SendList Protocol

Overview

SendList is HFS’s streaming protocol for delivering live-updating lists (directory entries, connections, logs, notifications, and similar data). It uses Server-Sent Events (SSE) to send incremental commands so the client can build and keep a list in sync without re-fetching it.

Establishing the Stream

The client issues a GET request to the API with the header Accept: text/event-stream.

The server replies with Content-Type: text/event-stream and keeps the connection open.

Without that header, the same API in some case may fall back to a JSON snapshot.

Example request:

Message Format

Each SSE event carries one data: line containing a JSON array.
The array is a batch of SendList commands accumulated during the buffering window (200 ms by default). The client must read events in sequence and apply each command in order.

Generic command schema:

[operation, parameter, (extraData)]

operation: string code for the command.

parameter: object or value tied to the command.

extraData: used only by certain commands (for example update and error).

Standard Commands

Operation	Code	Message form	Description
Add	`+`	`['+', record]`	Inserts a new record. Payload is the full object.
Remove	`-`	`['-', filter]`	Removes records matching the filter (partial key/value match).
Update	`=`	`['=', filter, patch]`	Applies the patch to matching records. Fields set to `null` must be removed client-side.
Props	`props`	`['props', attributes]`	Updates list-level properties (permissions, metadata, and so on).
Ready	`ready`	`['ready']`	Signals the end of the initial bootstrap. The stream stays open for further updates.
Error	`e`	`['e', codeOrMessage, extra?]`	Reports an error. The optional `extra` contains additional details; the server may close the stream afterwards.

Custom Events

With custom(), the producer emits arrays like [eventName, payload?]. These names do not collide with the standard codes and are API-specific (for example notifications). Clients should handle or ignore them as appropriate.

Buffering and Diff Mode

SendList queues commands and flushes them as a group roughly every 200 ms (bufferTime is configurable). When the queue exceeds 10 000 entries, it forces an immediate flush.

When diff: true is enabled, the server tracks the sent state and automatically converts updates into minimal patches, omitting unchanged fields and marking removed fields with null.

Client Handling

Create an EventSource pointing to the endpoint.

On each message, parse event.data as JSON.

Iterate through the batch of commands and apply them sequentially.

Treat ready as the signal that the initial list is complete.

Handle error by showing the message or triggering a reconnection routine.

Close the EventSource when the list is no longer needed.

Example SSE Event

data: [["props",{"can_upload":true}],
       ["+",{"n":"report.pdf","s":123456,"m":"2024-05-01T08:15:00.000Z"}],
       ["ready"]]

Processing order:

Update list-level properties (can_upload).

Add report.pdf.

Mark the list as ready.

Best Practices

Match records using partial filters (for example _.matches) supplied in each command.

Make reconnection resilient: EventSource auto-reconnects, but refreshing the full list after long outages is recommended.

Ignore or log unknown commands without failing, to remain compatible with future extensions.

After ready, expect real-time +, -, =, and custom commands until the server closes the stream.

SendList over SSE

SendList Protocol#

Overview#

Establishing the Stream#

Message Format#

Standard Commands#

Custom Events#

Buffering and Diff Mode#

Client Handling#

Example SSE Event#

Best Practices#