ws_transport behaviour (ws v0.3.0)

View Source

Transport behaviour — a thin abstraction the session uses to exchange bytes on the stream handle supplied by the embedder.

Inbound bytes reach the session as plain Erlang messages; the transport module is responsible for turning adapter-specific messages ({tcp, ...}, {ssl, ...}, {h2_stream, ...}) into the canonical shapes below:

{ws_data, Handle, Bin} {ws_closed, Handle} {ws_error, Handle, Reason}

The session calls activate/1 when it wants the next batch of bytes. Transports that deliver continuously (e.g. ssl in active, true mode) may simply return ok.

Summary

Callbacks

activate/1
classify/2
close/1
controlling_process/2
peername/1
recv/2
send/2

Callbacks

activate/1

-callback activate(Handle :: term()) -> ok | {error, term()}.

classify/2

-callback classify(Msg :: term(), Handle :: term()) ->
                      {ws_data, term(), binary()} |
                      {ws_closed, term()} |
                      {ws_error, term(), term()} |
                      ignore.
Synchronous read used by the client while driving the HTTP/1.1 handshake (when the session has not yet taken ownership of the stream). Transports whose handshake happens elsewhere (e.g. an HTTP/2 stream handle) may omit this and only be used server-side.

close/1

-callback close(Handle :: term()) -> ok.

controlling_process/2

-callback controlling_process(Handle :: term(), pid()) -> ok | {error, term()}.
Classify an arbitrary Erlang message against this transport's handle. Returning ignore hands the message back to the session to dispatch as an out-of-band info to the user handler.

peername/1

(optional) 
-callback peername(Handle :: term()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, term()}.

recv/2

(optional) 
-callback recv(Handle :: term(), timeout()) -> {ok, binary()} | {error, term()}.

send/2

-callback send(Handle :: term(), iodata()) -> ok | {error, term()}.