bookclerk_player_api::socket

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Engine.IO (v4) and Socket.IO (v5) framing of /player/socket.io.

The endpoint speaks websocket only: an app opens /player/socket.io/?EIO=4&transport=websocket, the host sends the Engine.IO open packet, the app connects to the default namespace and then sends auth with its access token, as apps written for an Audiobookshelf server do. After that the host pushes events (user_item_progress_updated, user_updated, item_updated, ...) and pings; the app answers pings and may send its own.

Everything here is sans-IO: parse_client_frame reads one text frame an app sent and the *_frame functions build the frames the host sends. Binary frames and polling are refused by the host before they reach this module.

Item Kind Summary
SocketError enum Why a frame an app sent was refused. The host closes the socket.
ClientFrame enum One text frame an app sent, read.
ClientEvent enum An event an app sends.
parse_client_frame function Reads one text frame an app sent.
open_frame function The Engine.IO open packet (0{...}), the first frame the host sends.
connect_frame function The Socket.IO connect answer (40{"sid":...}) on the default namespace.
connect_error_frame function The Socket.IO connect error (44{"message":...}) for a namespace the endpoint does not serve.
event_frame function A Socket.IO event (42["name",data]) on the default namespace.
bare_event_frame function A Socket.IO event with no argument (42["name"]), such as pong.
MAX_CLIENT_FRAME_BYTES constant The longest text frame an app may send, in bytes. An auth event with a token is under a hundred bytes; nothing an app sends is near this.
MAX_EVENT_NAME_BYTES constant The longest event name read back, in bytes.
PING_INTERVAL_MS constant How often the host pings, in milliseconds (Engine.IO's default).
PING_TIMEOUT_MS constant How long the host waits for a pong before closing, in milliseconds.
ENGINE_IO_REVISION constant The Engine.IO protocol revision the endpoint speaks (EIO=4).
PING_FRAME constant The Engine.IO ping (2) the host sends every PING_INTERVAL_MS.
PONG_FRAME constant The Engine.IO pong (3) answering an app's ping.
CLOSE_FRAME constant The Engine.IO close (1).

Enums

SocketError

pub enum SocketError {
    TooLong,
    UnknownPacket,
    Malformed,
}

Why a frame an app sent was refused. The host closes the socket.

Variants

  • TooLong: The frame is longer than MAX_CLIENT_FRAME_BYTES.
  • UnknownPacket: The frame is empty or its packet type is not one an app sends.
  • Malformed: A Socket.IO packet whose namespace, ack id or payload is malformed.

Implements: Clone, Copy, Debug, Display, Eq, Error, PartialEq

ClientFrame

pub enum ClientFrame {
    Close,
    Ping,
    Pong,
    Noop,
    Connect { default_namespace: bool, token: Option<String> },
    Disconnect,
    Event { event: ClientEvent, ack: Option<u64> },
}

One text frame an app sent, read.

Variants

  • Close: Engine.IO close (1): the app is leaving.
  • Ping: Engine.IO ping (2), answered with a pong.
  • Pong: Engine.IO pong (3), the answer to the host's ping.
  • Noop: Engine.IO upgrade or noop (5, 6): nothing to do.
  • Connect: Socket.IO connect (40) to a namespace.
    • default_namespace: True when the namespace is the default one (/), the only one the endpoint serves.
    • token: The token field of the connect payload, when the app sent one.
  • Disconnect: Socket.IO disconnect (41).
  • Event: Socket.IO event (42) on the default namespace.
    • event: The event the app sent.
    • ack: The ack id the app asked to be answered on, if any.

Implements: Clone, Debug, Eq, PartialEq

ClientEvent

pub enum ClientEvent {
    Auth(String),
    Ping,
    Other(String),
}

An event an app sends.

Variants

  • Auth: auth with an access token: ties the socket to a patron.
  • Ping: The application-level ping event, answered with pong.
  • Other: Any other event (scans, cover search, log listeners): ignored.

Implements: Clone, Debug, Eq, PartialEq

Functions

parse_client_frame

pub fn parse_client_frame(frame: &str) -> Result<ClientFrame, SocketError>

Reads one text frame an app sent.

Arguments

  • frame - The websocket text frame.

Returns

The frame.

Errors

SocketError when the frame is too long, empty, of a packet type an app does not send, or malformed.

open_frame

pub fn open_frame(sid: &str) -> String

The Engine.IO open packet (0{...}), the first frame the host sends.

Arguments

  • sid - A fresh, unguessable session id for this socket.

connect_frame

pub fn connect_frame(sid: &str) -> String

The Socket.IO connect answer (40{"sid":...}) on the default namespace.

connect_error_frame

pub fn connect_error_frame(namespace_message: &str) -> String

The Socket.IO connect error (44{"message":...}) for a namespace the endpoint does not serve.

event_frame

pub fn event_frame<T: Serialize>(name: &str, data: &T) -> String

A Socket.IO event (42["name",data]) on the default namespace.

Arguments

  • name - The event name, such as user_item_progress_updated.
  • data - Its one argument.

bare_event_frame

pub fn bare_event_frame(name: &str) -> String

A Socket.IO event with no argument (42["name"]), such as pong.

Constants

MAX_CLIENT_FRAME_BYTES

pub const MAX_CLIENT_FRAME_BYTES: usize = _;

The longest text frame an app may send, in bytes. An auth event with a token is under a hundred bytes; nothing an app sends is near this.

MAX_EVENT_NAME_BYTES

pub const MAX_EVENT_NAME_BYTES: usize = 64;

The longest event name read back, in bytes.

PING_INTERVAL_MS

pub const PING_INTERVAL_MS: u64 = 25_000;

How often the host pings, in milliseconds (Engine.IO's default).

PING_TIMEOUT_MS

pub const PING_TIMEOUT_MS: u64 = 20_000;

How long the host waits for a pong before closing, in milliseconds.

ENGINE_IO_REVISION

pub const ENGINE_IO_REVISION: &str = "4";

The Engine.IO protocol revision the endpoint speaks (EIO=4).

PING_FRAME

pub const PING_FRAME: &str = "2";

The Engine.IO ping (2) the host sends every PING_INTERVAL_MS.

PONG_FRAME

pub const PONG_FRAME: &str = "3";

The Engine.IO pong (3) answering an app's ping.

CLOSE_FRAME

pub const CLOSE_FRAME: &str = "1";

The Engine.IO close (1).

Generated from crates/bookclerk-player-api at main · View as Markdown