LlmCall.WS behaviour (llm_call v0.1.0)

Copy Markdown View Source

The WebSocket transport contract.

A session at this layer is synchronous: connect/3 performs the HTTP upgrade and returns a connection, send_frame/2 writes one frame, and recv/2 blocks for one frame. A caller that needs concurrency (a realtime session) runs the connection in its own process and owns the socket from connect/3 onward.

Only data frames cross the contract. recv/2 answers pings itself, ignores pongs, and reports a peer close as {:close, code, reason}.

The library ships LlmCall.WS.Mint as the default implementation.

Summary

Callbacks

Sends a close frame and closes the socket.

Opens a connection to url (ws:// or wss://) with the given headers.

Decodes one socket message delivered to the process that called connect/3.

Waits up to timeout milliseconds for one data frame or a peer close.

Writes one data frame.

Types

conn()

@type conn() :: term()

error()

@type error() :: term()

frame()

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

received()

@type received() :: frame() | {:close, non_neg_integer(), binary()}

url()

@type url() :: String.t()

Callbacks

close(conn, non_neg_integer, binary)

@callback close(conn(), non_neg_integer(), binary()) :: :ok

Sends a close frame and closes the socket.

connect(url, list, keyword)

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

Opens a connection to url (ws:// or wss://) with the given headers.

Options are implementation-specific; LlmCall.WS.Mint accepts :timeout (connect and upgrade, default 15 seconds), :transport_opts, :proxy, :proxy_headers and :log. It requires an active socket: mode: :active is accepted and anything else is {:error, {:unsupported_mode, mode}}.

feed(conn, term)

@callback feed(conn(), term()) :: {:ok, [received()], conn()} | {:error, error()}

Decodes one socket message delivered to the process that called connect/3.

A session that owns the connection in active mode calls this from its message loop; recv/2 is the blocking alternative. The function also answers pings and reports a close as {:close, code, reason}.

recv(conn, timeout)

@callback recv(conn(), timeout()) :: {:ok, received(), conn()} | {:error, error()}

Waits up to timeout milliseconds for one data frame or a peer close.

send_frame(conn, frame)

@callback send_frame(conn(), frame()) :: {:ok, conn()} | {:error, error()}

Writes one data frame.