# Filo v0.2.0 - Table of Contents

> A Hrana (libSQL) protocol server and client for Elixir — speak libSQL's wire protocol from any Plug app, backed by the SQLite engine of your choice.

## Pages

- [Filo](readme.md)
- [Changelog](changelog.md)
- [Contributing to Filo](contributing.md)

## Modules

- [Filo](Filo.md): Filo — a Hrana (libSQL) protocol **server** for Elixir.
- [Filo.Batch](Filo.Batch.md): A decoded Hrana batch: an ordered list of steps, each a statement with an
optional condition. `run/3` executes the steps in order, gating each on its
condition, and collects a `Filo.BatchResult`.

- [Filo.BatchCond](Filo.BatchCond.md): Hrana batch step conditions.
- [Filo.BatchResult](Filo.BatchResult.md): The result of executing a batch, encoded to a Hrana `BatchResult`.
- [Filo.Cursor](Filo.Cursor.md): Turns a `Filo.BatchResult` into the sequence of Hrana cursor entries.
- [Filo.Describe](Filo.Describe.md): The result of a Hrana `describe` request: the parameters and columns of a
prepared statement, plus whether it is an `EXPLAIN` and whether it is
read-only. The libSQL client uses this to learn a statement's shape (e.g. how
many parameters to bind) before executing it.
- [Filo.Protobuf](Filo.Protobuf.md): Protobuf codec for the Hrana 3 shared structures.
- [Filo.Protobuf.Http](Filo.Protobuf.Http.md): Protobuf codec for the Hrana 3 *over HTTP* message envelopes: the pipeline and
cursor request/response bodies and the per-request `StreamRequest` /
`StreamResponse` / `StreamResult` types. Maps to and from the same Hrana maps
the JSON pipeline uses (`%{"baton" => ..., "requests" => [...]}`, request maps
tagged by `"type"`), so `Filo.Plug` can serve the `v3-protobuf` routes by
swapping only the body codec. Shared structures come from `Filo.Protobuf`.

- [Filo.Protobuf.Wire](Filo.Protobuf.Wire.md): Protobuf wire-format primitives (proto3): varints, zigzag, `fixed64`, tags, and
length-delimited fields — just enough of the encoding to (de)serialize the
Hrana 3 messages. The message-level codecs live in `Filo.Protobuf`.
- [Filo.Protobuf.Ws](Filo.Protobuf.Ws.md): Protobuf codec for the Hrana 3 *over WebSocket* messages: `ClientMsg`
(hello / request) and `ServerMsg` (hello_ok / hello_error / response_ok /
response_error), plus the `RequestMsg` / `ResponseOkMsg` request- and
response-oneofs. Maps to and from the same message maps `Filo.Socket` already
dispatches on, so the socket only swaps text-JSON framing for binary-protobuf
framing. Shared structures come from `Filo.Protobuf`.

- [Filo.Request](Filo.Request.md): Dispatch of a single Hrana stream request against a host `Filo.Executor`.

- Server
  - [Filo.Executor](Filo.Executor.md): Behaviour a host application implements to back a Hrana stream with a real
database connection.
  - [Filo.Plug](Filo.Plug.md): A `Plug` that speaks Hrana over HTTP (versions 1, 2, and 3) and upgrades
WebSocket requests to `Filo.Socket` (Hrana over WebSocket). Mount it in any Plug
or Phoenix app to accept libSQL clients (`django-libsql` over ws, `libsql-client`,
`libsql-experimental`, the libSQL SDKs).
  - [Filo.Socket](Filo.Socket.md): 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.
  - [Filo.Stream](Filo.Stream.md): A single Hrana-over-HTTP stream: one `GenServer` owning one executor
connection and the stream's baton sequence number.
  - [Filo.Streams](Filo.Streams.md): Registry of live `Filo.Stream` processes — the find-or-start layer between the
HTTP plug and the per-stream processes.

- Client
  - [Filo.Client](Filo.Client.md): A Hrana **client** — the mirror of `Filo.Plug`.
  - [Filo.Client.Transport](Filo.Client.Transport.md): The HTTP transport a `Filo.Client` drives — a behaviour, so Filo ships the Hrana
protocol without pinning a concrete HTTP client on hosts (the same posture the
server keeps with `Plug`/`WebSock`).
  - [Filo.Client.Transport.Mint](Filo.Client.Transport.Mint.md): The default `Filo.Client.Transport`, over [Mint](https://hex.pm/packages/mint).

- Protocol
  - [Filo.Baton](Filo.Baton.md): Hrana-over-HTTP baton — an opaque, server-signed token that identifies a stream
and enforces single-use, serial access.
  - [Filo.Error](Filo.Error.md): A Hrana error: a human-readable `message` and a SQLite error `code`
(e.g. `"SQLITE_CONSTRAINT"`).
  - [Filo.Stmt](Filo.Stmt.md): A decoded Hrana statement.
  - [Filo.StmtResult](Filo.StmtResult.md): The result of executing a single statement, encoded to a Hrana `StmtResult`.
  - [Filo.Value](Filo.Value.md): Hrana value codec.

