arizona_cowboy_server (arizona_cowboy v0.1.0)
View SourceThe Cowboy arizona_server adapter: boots a Cowboy listener serving Arizona
routes.
Cowboy's router sees one catch-all route to arizona_cowboy_handler; the
Arizona routes are compiled by arizona_route_table into a table kept per
listener in a persistent_term, which the handler and
arizona_cowboy_req:resolve_route/3 read.
Mounting on a listener another framework owns
mount/2 serves Arizona routes on a Cowboy listener that something else
started (a Nova or plain Cowboy application): it compiles the routes under that
listener's ref without starting anything, and arizona_cowboy_middleware, placed
in the listener's middleware chain, serves the requests they match and passes the
rest on. It takes routes, compress, error_page, ws_opts and
max_content_length as below; the owner configures the listener itself, TLS
and enable_connect_protocol included. unmount/1 forgets the routes,
notify_drain/2 tells the live sessions to wind down, and drain/2 also waits
for the requests in flight, then unmounts, leaving the owner's listener running.
Options
routes-- the Arizona route list (required).transport_opts--[{port, Port}](default4040); other entries go to Ranch's socket options.scheme--http(default) orhttps.tls--[ssl:tls_server_option()], merged into the socket options of a TLS listener, which negotiates HTTP/2 or HTTP/1.1 by ALPN. Supplying it makes the listener HTTPS, soscheme => httpsis optional beside it;scheme => httpswithout it raiseshttps_requires_tls, and withscheme => httpit raisestls_with_http_scheme, rather than serving the certs' traffic in cleartext.max_content_length-- the largest request body a controller can read, in bytes (default10485760); a larger one reads as{error, too_large}.compress--true(default) compresses pages and assets (arizona_route:transforms/2).error_page--{Module, Function}rendered on a page crash.proto_opts-- merged into Cowboy's protocol options.enable_connect_protocolistrueby default, so a client may open a WebSocket over HTTP/2 (RFC 8441).ws_opts-- merged into thecowboy_websocketoptions of every live session (default#{idle_timeout => infinity, max_frame_size => 10485760}: the frame cap bounds what one client can make a session buffer).
Summary
Functions
Every controller reply kind, the MCP route and the dev reload route.
Drains the listener Name: stops accepting connections, tells every live
session {arizona_drain, Deadline} (through arizona_socket:drain/2), and waits
up to Timeout milliseconds for every request in flight -- a page, a controller
reply, a loop, a WebSocket session -- to finish, then stops it, closing the idle
keep-alive connections and killing what is left.
The compiled route table of the listener Ref, if it serves Arizona routes.
Renders this module's configuration errors.
The largest request body the listener Name lets a controller read.
Serves the Arizona routes in Opts on the Cowboy listener Ref someone else
started, through arizona_cowboy_middleware in its middleware chain. Refused
when Ref already serves Arizona routes.
Tells every live session of the listener Name {arizona_drain, Deadline}, as
drain/2 does, while the listener keeps accepting.
Recompiles every running listener's routes from the list it started with.
The pubsub group of the listener's requests in flight, every process answering one; a process leaves it when it exits.
The pubsub group of the listener's live WebSocket sessions.
Starts the Cowboy listener Name serving the Arizona routes in Opts.
Stops the listener Name and forgets its routes.
The compiled route table of the listener Name.
Stops serving Arizona routes on the listener Ref, which stays up.
The cowboy_websocket options of the listener Name's live sessions.
Functions
-spec capabilities() -> #{routes := [mcp | reload], replies := [stream | sendfile | loop]}.
Every controller reply kind, the MCP route and the dev reload route.
-spec drain(Name, Timeout) -> ok | {error, not_found} when Name :: atom(), Timeout :: non_neg_integer().
Drains the listener Name: stops accepting connections, tells every live
session {arizona_drain, Deadline} (through arizona_socket:drain/2), and waits
up to Timeout milliseconds for every request in flight -- a page, a controller
reply, a loop, a WebSocket session -- to finish, then stops it, closing the idle
keep-alive connections and killing what is left.
-spec find_table(Ref) -> {ok, arizona_route_table:table()} | error when Ref :: atom().
The compiled route table of the listener Ref, if it serves Arizona routes.
-spec format_error(Reason, Stacktrace) -> ErrorInfo when Reason :: term(), Stacktrace :: [tuple()], ErrorInfo :: #{general := iolist()}.
Renders this module's configuration errors.
-spec max_content_length(Name) -> non_neg_integer() when Name :: atom().
The largest request body the listener Name lets a controller read.
Serves the Arizona routes in Opts on the Cowboy listener Ref someone else
started, through arizona_cowboy_middleware in its middleware chain. Refused
when Ref already serves Arizona routes.
-spec notify_drain(Name, Timeout) -> ok | {error, not_found} when Name :: atom(), Timeout :: non_neg_integer().
Tells every live session of the listener Name {arizona_drain, Deadline}, as
drain/2 does, while the listener keeps accepting.
-spec recompile_routes() -> ok.
Recompiles every running listener's routes from the list it started with.
The pubsub group of the listener's requests in flight, every process answering one; a process leaves it when it exits.
The pubsub group of the listener's live WebSocket sessions.
Starts the Cowboy listener Name serving the Arizona routes in Opts.
-spec stop(Name) -> ok | {error, not_found} when Name :: atom().
Stops the listener Name and forgets its routes.
-spec table(Name) -> arizona_route_table:table() when Name :: atom().
The compiled route table of the listener Name.
-spec unmount(Ref) -> ok | {error, not_found} when Ref :: atom().
Stops serving Arizona routes on the listener Ref, which stays up.
The cowboy_websocket options of the listener Name's live sessions.