Filo.Socket (Filo v0.2.0)

Copy Markdown View Source

A WebSock handler that speaks Hrana over WebSocket. This is the binding the libSQL clients use over ws:///wss:///libsql:// — notably django-libsql (via libsql-client), which has no HTTP-pipeline path.

Mount it from the host's server by upgrading a WebSocket request to this handler (see Filo.Plug, which performs the upgrade). The handler is server agnostic: it only implements the WebSock behaviour.

Protocol

After the WebSocket opens (subprotocol hrana2/hrana3, or hrana3-protobuf for the binary Protobuf encoding), the client sends a hello and the server replies hello_ok. Thereafter every message is a request carrying a request_id, answered by a response_ok or response_error with the same id. Requests:

  • open_stream / close_stream — open and release a connection; the client allocates the stream_id. A connection lives for the life of its stream, so state (transactions, temp tables) persists across requests.
  • execute / batch / sequence / describe / get_autocommit — run against a stream.
  • store_sql / close_sql — cache SQL text under a sql_id for the connection, referenced by later statements.
  • open_cursor / fetch_cursor / close_cursor (Hrana 3) — run a batch and read its results incrementally as cursor entries.

The per-request payloads reuse the shared protocol core (Filo.Stmt, Filo.Batch, Filo.Request, …) — only the framing and stream bookkeeping are WebSocket specific. Unlike the HTTP binding there are no batons: the persistent socket plus the client-allocated stream_id identify a stream.

Summary

Functions

init(opts)

Initializes a connection's handler state.

Functions

init(opts)

Initializes a connection's handler state.

Options: :executor (required, the Filo.Executor module), :open_arg (host context passed to executor.open/1 for each stream), :encoding (:json (default) or :protobuf, set from the negotiated subprotocol), :authorize (optional 2-arity host callback fun(open_arg, token) — see Filo.Plug; checked at the hello handshake against the hello's jwt field), and :header_token (a bearer token the host extracted from the upgrade request, the fallback when the hello carries no jwt).