arizona_ws (arizona v0.4.0)

View Source

Transport-agnostic bootstrap for WebSocket handlers.

Factors out the upgrade-time logic common to every WebSocket transport adapter:

  1. Read the framework keys _az_path, _az_reconnect, and _az_fps_follow from the parsed upgrade query string.
  2. Strip framework keys to recover the user-page query string.
  3. Resolve the target route via the arizona_req adapter's resolve_route/3 callback.
  4. Apply any route middlewares against the synthesized az:request().
  5. Return either a halt signal (middleware blocked) or the state the transport should feed into arizona_socket:init/4.

The helper is transport-agnostic: callers pre-parse the query string into the standard [{binary(), binary() | true}] shape from their own transport APIs. On halt, callers unwrap the native transport request via arizona_req:raw/1.

Summary

Types

qs()
result()
state()
upgrade()

Functions

init(State)

Starts the Arizona socket for an upgraded connection, in the process that owns it, from the state upgrade/3 returned. The result is arizona_socket's, which the adapter maps onto its server's WebSocket replies.

prepare(QS, Adapter, AdapterState)

Prepares a WebSocket upgrade.

upgrade(QS, Adapter, AdapterState)

prepare/3 folded into the answer to the upgrade request. A halt becomes its arizona_req:halt_reply/1 and an unresolvable _az_path a 404, both with the adapter state the reply belongs to; otherwise the upgrade proceeds and arizona_req:flush/1's lines (cookies and headers the route's middlewares stashed, and a committed session write) ride the 101.

Types

qs()

-nominal qs() :: [{binary(), binary() | true}].

result()

-nominal result() :: {halt, az:request()} | {cont, state()} | not_found.

state()

-nominal state() ::
             #{handler := module(),
               bindings := map(),
               on_mount := arizona_live:on_mount(),
               layouts := [arizona_render:layout()],
               req := az:request(),
               reconnect := boolean(),
               fps_follow := boolean(),
               capabilities := map()}.

upgrade()

-nominal upgrade() ::
             {reply, arizona_req:resp_status(), [{binary(), binary()}], AdapterState :: term()} |
             {upgrade, [{binary(), binary()}], state()}.

Functions

init(State)

-spec init(State) -> arizona_socket:result() when State :: state().

Starts the Arizona socket for an upgraded connection, in the process that owns it, from the state upgrade/3 returned. The result is arizona_socket's, which the adapter maps onto its server's WebSocket replies.

prepare(QS, Adapter, AdapterState)

-spec prepare(QS, Adapter, AdapterState) -> result()
                 when QS :: qs(), Adapter :: module(), AdapterState :: term().

Prepares a WebSocket upgrade.

Reads _az_path / _az_reconnect / _az_fps_follow from QS, resolves the route against Adapter/AdapterState, and applies route middlewares.

Returns {halt, HaltReq} when middleware short-circuits; the transport extracts the native raw request via arizona_req:raw/1 and emits its own response. Returns not_found when the client-supplied _az_path does not resolve to a live route (no match, or a controller/asset/ws route); the transport rejects the upgrade with a 404 rather than crashing on an attacker-controllable path. Returns {cont, State} otherwise; the transport passes State (which carries handler, bindings, on_mount, layouts, req, reconnect, fps_follow) on through to arizona_socket:init/4.

upgrade(QS, Adapter, AdapterState)

-spec upgrade(QS, Adapter, AdapterState) -> upgrade()
                 when QS :: qs(), Adapter :: module(), AdapterState :: term().

prepare/3 folded into the answer to the upgrade request. A halt becomes its arizona_req:halt_reply/1 and an unresolvable _az_path a 404, both with the adapter state the reply belongs to; otherwise the upgrade proceeds and arizona_req:flush/1's lines (cookies and headers the route's middlewares stashed, and a committed session write) ride the 101.