Ace.HTTP.Service (ace v0.19.0) View Source

Run a Raxx.Server application for HTTP/1.x and HTTP/2 clients

NOTE: Ace services are served over a secure transport layer TLS(SSL), therefore :cert + :key or :certfile + :keyfile are required options.

Starting a service will start and manage a cohort of endpoint process. The number of awaiting endpoint processes is set by the :acceptors option.

Each endpoint process manages communicate to a single connected client. Using HTTP/1.1 pipelining of HTTP/2 multiplexing one connection may be used for multiple HTTP exchanges. An HTTP exchange consisting of one request from the client and one response from the server.

Each exchange is isolated in a dedicated worker process. Raxx specifies early abortion of an exchange can be achieved by causing the worker process to exit.

Link to this section Summary

Types

service()

Process to manage a HTTP service.

Functions

count_connections(service)

Returns a number of connected clients for a given service.

port(service)

Fetch the port number of a running service.

start_link(app, options)

Start a HTTP web service.

Link to this section Types

service()

Specs

service() :: pid()

Process to manage a HTTP service.

This process should be added to a supervision tree as a supervisor.

Link to this section Functions

count_connections(service)

Specs

count_connections(service()) :: non_neg_integer()

Returns a number of connected clients for a given service.

port(service)

Specs

port(service()) :: {:ok, :inet.port_number()}

Fetch the port number of a running service.

OS assigned ports: If an endpoint is started with port number 0 it will be assigned a port by the underlying system. This can be used to start many endpoints simultaneously. It can be useful running parallel tests.

start_link(app, options)

Specs

start_link({module(), any()}, [{atom(), any()}]) :: {:ok, service()}

Start a HTTP web service.

Options

:cleartext - Serve over TCP rather than TLS(ssl), will not support HTTP/2.
:certfile - the certificate.
:keyfile - the private key used to sign the certificate request.
:cert - the certificate.
:key - the private key used to sign the certificate request.
:port - the port to run the server on. Defaults to port 8443.
:name - name to register the spawned endpoint under. The supported values are the same as GenServers.
:acceptors - The number of servers simultaneously waiting for a connection. Defaults to 100.
:error_response - The response that Ace will send if a request handler crashes. Useful for setting custom headers, e.g. for CORS.

Internal socket options can also be specified, most notably:

:alpn_preferred_protocols - which protocols should be negotiated for the https traffic. Defaults to ["h2", "http/1.1"]

The additional options will be passed to :gen_tcp.listen/2 and :ssl.listen/2 as appropriate.