ProtoRune.Firehose.Transport behaviour (proto_rune v0.5.1)

Behaviour for the WebSocket transport used by ProtoRune.Firehose.

A transport owns the underlying connection and translates the BEAM messages it receives into firehose frames. The default implementation is ProtoRune.Firehose.Transport.Gun; a different implementation can be injected through the :transport and :transport_opts options of ProtoRune.Firehose.start_link/1, which is how the connection lifecycle is exercised in tests.

Summary

Types

conn()

Opaque transport connection state.

frame()

A decoded WebSocket frame: a binary or text payload, or a close signal.

Callbacks

close(conn)

Closes the connection.

connect(url, opts)

Opens a WebSocket connection to the given ws(s):// URL.

stream(conn, message)

Processes a message received by the connection owner.

Types

conn()

@type conn() :: term()

Opaque transport connection state.

frame()

@type frame() :: {:binary, binary()} | {:text, binary()} | :closed

A decoded WebSocket frame: a binary or text payload, or a close signal.

The CBOR firehose (ProtoRune.Firehose) uses binary frames; Jetstream (ProtoRune.Jetstream) uses text frames carrying JSON.

Callbacks

close(conn)

@callback close(conn()) :: :ok

Closes the connection.

connect(url, opts)

@callback connect(url :: String.t(), opts :: keyword()) ::
  {:ok, conn()} | {:error, term()}

Opens a WebSocket connection to the given ws(s):// URL.

The calling process becomes the connection owner and receives the socket-related messages that stream/2 understands.

stream(conn, message)

@callback stream(conn(), message :: term()) ::
  {:ok, conn(), [frame()]} | :unknown | {:error, conn(), term()}

Processes a message received by the connection owner.

Returns :unknown when the message does not belong to the transport, {:ok, conn, frames} with the decoded frames, or {:error, conn, reason} when the connection failed.