bookclerk_player_api::request

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

Last updated View as Markdown

Sans-IO parsers for what player apps send the /player API.

Every parser takes bytes or text exactly as they arrived (a body, a header value, a raw query string) and answers a typed, bounded value or a RequestError. The routes call these and nothing else on app input, and the player_request fuzz target drives the same functions against an independent oracle.

Apps send more fields than are read here (device details, cached copies of objects the server sent); unknown fields are ignored, as an Audiobookshelf server ignores them. A field that is read must have the documented type and range, or the whole request is refused.

Item Kind Summary
LoginRequest struct POST /player/login: a username and a player password.
DeviceInfo struct What a player reported about the device it plays on, kept for the session list and history.
PlayRequest struct POST /player/api/items/{id}/play: what the app can play.
SyncRequest struct POST /player/api/session/{id}/sync and .../close: where the player is, in milliseconds.
LocalSession struct A session a player kept while offline, sent later (POST /player/api/session/local, one entry of .../local-all).
ProgressPatch struct A change to the caller's progress in one item (PATCH /player/api/me/progress/{id} and each batch entry).
BookmarkRequest struct A bookmark as an app sends it (POST/PATCH /player/api/me/item/{id}/bookmark).
ListQuery struct The query of a list route (/player/api/libraries/{id}/items and the other paged lists).
DetailQuery struct The query of a single-entity or small-list route (GET /api/items/{id}, /api/authors/{id}, /api/libraries/{id}, /search, /me/listening-sessions).
RequestError enum Why a request was refused.
ListSort enum How a list is ordered (sort).
ListFilter enum Which part of a library a list shows (filter=<group>.<base64 value>).
parse_login_request function Parses a sign-in body: a JSON object with string username and password.
parse_card_token function A card token as an app sends it (Authorization: Bearer, ?token=, x-refresh-token, the socket's auth event).
parse_bearer function The token of an Authorization: Bearer <token> value.
parse_play_request function Parses a play request. An empty body counts as {}.
parse_sync_request function Parses a sync or close body. An empty body counts as {} (a close with nothing to report).
parse_local_session function Parses POST /player/api/session/local: one offline session.
parse_local_sessions function Parses POST /player/api/session/local-all: {"sessions": [...]}.
parse_progress_patch function Parses a progress change body.
parse_progress_batch function Parses PATCH /player/api/me/progress/batch/update: an array of progress changes, each naming its item in libraryItemId.
parse_bookmark_request function Parses a bookmark body: a number time in seconds and an optional string title.
parse_bookmark_time function The bookmark a DELETE /player/api/me/item/{id}/bookmark/{time} path names, by its time in seconds.
parse_batch_get function Parses POST /player/api/items/batch/get: {"libraryItemIds": [...]}.
parse_list_filter function Parses a filter value (group.base64).
parse_list_query function Parses a list route's raw query string.
parse_detail_query function Parses the query of a single-entity or small-list route.
LocalSessionEntry type alias One entry of a batch of local sessions: the session, or why it was refused together with the id the app gave it (when it gave one), so the answer can name the entry it refuses.
MAX_LOGIN_BODY_BYTES constant Largest sign-in body (POST /player/login).
MAX_USERNAME_BYTES constant Longest username a sign-in may carry, in bytes.
MAX_PASSWORD_BYTES constant Longest password a sign-in may carry, in bytes.
MAX_BODY_BYTES constant Largest body of a play, sync, progress or bookmark request. Apps send a device description with a play request, so this is larger than the fields read need.
MAX_BATCH_BODY_BYTES constant Largest body of a request that carries several items or sessions (/api/me/progress/batch/update, /api/session/local-all, /api/items/batch/get). An offline session as the apps send it holds a copy of the item, so each can be several kilobytes.
MAX_BATCH_ENTRIES constant Most entries a batch request may carry.
MAX_BOOKMARK_TITLE_BYTES constant Longest bookmark title read, in bytes.
MAX_QUERY_BYTES constant Longest raw query string read, in bytes.
MAX_SEARCH_BYTES constant Longest search term read, in bytes.
MAX_PAGE_LIMIT constant Most items one list page may ask for.
CARD_TOKEN_LEN constant Length of a card token: base64url without padding of 32 random bytes.
MAX_DEVICE_NAME_BYTES constant Longest player name kept from a play request's device details.

Structs

LoginRequest

pub struct LoginRequest {
    pub username: String,
    pub password: String,
}

POST /player/login: a username and a player password.

Fields

  • username: The patron's login name or email, trimmed.
  • password: The player password as typed.

Implements: Clone, Debug, Eq, PartialEq

DeviceInfo

pub struct DeviceInfo {
    pub name: String,
}

What a player reported about the device it plays on, kept for the session list and history.

Fields

  • name: A name for the player, built from the app's client name and the device's model, at most MAX_DEVICE_NAME_BYTES bytes.

Implements: Clone, Debug, Default, Eq, PartialEq

PlayRequest

pub struct PlayRequest {
    pub device: DeviceInfo,
    pub force_direct_play: bool,
    pub force_transcode: bool,
}

POST /player/api/items/{id}/play: what the app can play.

Fields

  • device: The player's device details.
  • force_direct_play: True when the app asked for the stored file even if it might not play it (forceDirectPlay).
  • force_transcode: True when the app asked for a transcode (forceTranscode); the library has none, so this is answered as not playable.

Implements: Clone, Debug, Default, Eq, PartialEq

SyncRequest

pub struct SyncRequest {
    pub position_ms: Option<u64>,
    pub listened_ms: u64,
    pub duration_ms: Option<u64>,
}

POST /player/api/session/{id}/sync and .../close: where the player is, in milliseconds.

Fields

  • position_ms: The position (currentTime); None when the report leaves it out, which a close may.
  • listened_ms: Time listened since the last report (timeListened).
  • duration_ms: The recording's runtime as the player knows it (duration).

Implements: Clone, Copy, Debug, Default, Eq, PartialEq

LocalSession

pub struct LocalSession {
    pub id: String,
    pub item_id: String,
    pub position_ms: u64,
    pub listened_ms: u64,
    pub duration_ms: Option<u64>,
    pub updated_at_ms: Option<i64>,
}

A session a player kept while offline, sent later (POST /player/api/session/local, one entry of .../local-all).

Fields

  • id: The app's own id for the session, echoed in the answer.
  • item_id: The item it played (libraryItemId).
  • position_ms: Where it stopped.
  • listened_ms: Time listened in it (timeListening).
  • duration_ms: The recording's runtime as the player knew it.
  • updated_at_ms: When it was last reported, epoch milliseconds (updatedAt).

Implements: Clone, Debug, Eq, PartialEq

ProgressPatch

pub struct ProgressPatch {
    pub position_ms: Option<u64>,
    pub duration_ms: Option<u64>,
    pub is_finished: Option<bool>,
    pub hide: Option<bool>,
}

A change to the caller's progress in one item (PATCH /player/api/me/progress/{id} and each batch entry).

Fields

  • position_ms: The new position (currentTime).
  • duration_ms: The runtime the app knows (duration).
  • is_finished: Finished or not (isFinished).
  • hide: True to take the item off Continue listening (hideFromContinueListening).

Implements: Clone, Copy, Debug, Default, Eq, PartialEq

BookmarkRequest

pub struct BookmarkRequest {
    pub position_ms: u64,
    pub title: String,
}

A bookmark as an app sends it (POST/PATCH /player/api/me/item/{id}/bookmark).

Fields

  • position_ms: The marked place (time).
  • title: The note (title), trimmed; may be empty.

Implements: Clone, Debug, Eq, PartialEq

ListQuery

pub struct ListQuery {
    pub limit: u64,
    pub page: u64,
    pub sort: ListSort,
    pub descending: bool,
    pub filter: Option<ListFilter>,
    pub collapse_series: bool,
    pub include_progress: bool,
    pub minified: bool,
    pub search: Option<String>,
}

The query of a list route (/player/api/libraries/{id}/items and the other paged lists).

Fields

  • limit: Rows per page; 0 asks for every row (bounded by MAX_PAGE_LIMIT).
  • page: Page number, from 0.
  • sort: The order.
  • descending: True to reverse it (desc=1).
  • filter: The filter, when one was given.
  • collapse_series: True to fold works of one series into one row (collapseseries=1).
  • include_progress: True when the caller's progress should ride along on each item (include=progress).
  • minified: True when the minified item shape was asked for (minified=1).
  • search: A search term (q), trimmed.

Implements: Clone, Debug, Default, Eq, PartialEq

DetailQuery

pub struct DetailQuery {
    pub expanded: bool,
    pub include_progress: bool,
    pub include_filterdata: bool,
    pub include_items: bool,
    pub include_series: bool,
    pub limit: Option<u64>,
    pub page: u64,
    pub search: Option<String>,
}

The query of a single-entity or small-list route (GET /api/items/{id}, /api/authors/{id}, /api/libraries/{id}, /search, /me/listening-sessions).

Fields

  • expanded: expanded=1: the item with its tracks and files.
  • include_progress: include=progress: the patron's progress rides along.
  • include_filterdata: include=filterdata: a library with its filter values.
  • include_items: include=items: an author with their items.
  • include_series: include=series: an author with their series.
  • limit: limit or itemsPerPage, at most MAX_PAGE_LIMIT.
  • page: page, from 0.
  • search: q, trimmed; None when empty.

Implements: Clone, Debug, Default, Eq, PartialEq

Enums

RequestError

pub enum RequestError {
    TooLong(usize),
    NotJson,
    Shape(&'static str),
    OutOfRange(&'static str),
}

Why a request was refused.

Variants

  • TooLong: The body is longer than its limit.
  • NotJson: The body is not a JSON value of the expected kind.
  • Shape: A field is missing or has the wrong type.
  • OutOfRange: A field is outside its range.

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

ListSort

pub enum ListSort {
    Title,
    Author,
    Added,
    Duration,
    Series,
}

How a list is ordered (sort).

Variants

  • Title: By title (media.metadata.title, and anything not listed here).
  • Author: By author (media.metadata.authorName, ...authorNameLF).
  • Added: By when the library got it (addedAt, birthtimeMs, mtimeMs).
  • Duration: By runtime (media.duration, size).
  • Series: By place in a series (sequence).

Implements: Clone, Copy, Debug, Default, Eq, PartialEq

ListFilter

pub enum ListFilter {
    Author(String),
    Series(String),
    NoSeries,
    Genre(String),
    Tag(String),
    Narrator(String),
    Publisher(String),
    Finished,
    NotFinished,
    InProgress,
    NotStarted,
    Unsupported,
}

Which part of a library a list shows (filter=<group>.<base64 value>).

Variants

  • Author: Works by this author: an author id (crate::ids::facet_id).
  • Series: Works in this series: a series id (crate::ids::facet_id).
  • NoSeries: Works in no series (series.no-series).
  • Genre: Works with this genre.
  • Tag: Works the caller tagged with this tag.
  • Narrator: Works with this narrator.
  • Publisher: Works from this publisher.
  • Finished: Works the caller finished.
  • NotFinished: Works the caller has not finished.
  • InProgress: Works the caller has started and not finished.
  • NotStarted: Works the caller has not started.
  • Unsupported: A filter group this library does not keep (languages, ebooks, missing metadata, feeds, ...): nothing matches.

Implements: Clone, Debug, Eq, PartialEq

Functions

parse_login_request

pub fn parse_login_request(body: &[u8]) -> Result<LoginRequest, RequestError>

Parses a sign-in body: a JSON object with string username and password.

Errors

RequestError::TooLong past MAX_LOGIN_BODY_BYTES, RequestError::NotJson for anything but an object, RequestError::Shape when a field is missing or not a string, and RequestError::OutOfRange for an empty or overlong field or a control character.

parse_card_token

pub fn parse_card_token(value: &str) -> Option<&str>

A card token as an app sends it (Authorization: Bearer, ?token=, x-refresh-token, the socket's auth event).

Arguments

  • value - The token text, trimmed of surrounding spaces.

Returns

None unless it is exactly CARD_TOKEN_LEN base64url characters, the only shape this library mints; anything else is refused without a lookup.

parse_bearer

pub fn parse_bearer(value: &[u8]) -> Option<&str>

The token of an Authorization: Bearer <token> value.

Returns

None unless the scheme is Bearer (any case) and the token passes parse_card_token.

parse_play_request

pub fn parse_play_request(body: &[u8]) -> Result<PlayRequest, RequestError>

Parses a play request. An empty body counts as {}.

Errors

RequestError::TooLong past MAX_BODY_BYTES, RequestError::NotJson for anything but an object, and RequestError::Shape when a flag is not a boolean.

parse_sync_request

pub fn parse_sync_request(body: &[u8]) -> Result<SyncRequest, RequestError>

Parses a sync or close body. An empty body counts as {} (a close with nothing to report).

Errors

RequestError::TooLong past MAX_BODY_BYTES, RequestError::NotJson for anything but an object, RequestError::Shape for a field that is not a number, and RequestError::OutOfRange for a negative or overlong length.

parse_local_session

pub fn parse_local_session(body: &[u8]) -> Result<LocalSession, RequestError>

Parses POST /player/api/session/local: one offline session.

Errors

RequestError::TooLong past MAX_BATCH_BODY_BYTES, and the field errors of an offline session.

parse_local_sessions

pub fn parse_local_sessions(body: &[u8]) -> Result<Vec<LocalSessionEntry>, RequestError>

Parses POST /player/api/session/local-all: {"sessions": [...]}.

Returns

One result per entry, in order: an entry that does not parse is its own error, so one bad session does not refuse the rest.

Errors

RequestError::TooLong past MAX_BATCH_BODY_BYTES, RequestError::NotJson for anything but an object, RequestError::Shape when sessions is not an array, and RequestError::OutOfRange past MAX_BATCH_ENTRIES entries.

parse_progress_patch

pub fn parse_progress_patch(body: &[u8]) -> Result<ProgressPatch, RequestError>

Parses a progress change body.

Errors

RequestError::TooLong past MAX_BODY_BYTES, RequestError::NotJson for anything but an object, and the field errors.

parse_progress_batch

pub fn parse_progress_batch(
    body: &[u8],
) -> Result<Vec<(String, ProgressPatch)>, RequestError>

Parses PATCH /player/api/me/progress/batch/update: an array of progress changes, each naming its item in libraryItemId.

Errors

RequestError::TooLong past MAX_BATCH_BODY_BYTES, RequestError::NotJson for anything but an array of objects, RequestError::OutOfRange past MAX_BATCH_ENTRIES entries, and the field errors of any entry.

parse_bookmark_request

pub fn parse_bookmark_request(body: &[u8]) -> Result<BookmarkRequest, RequestError>

Parses a bookmark body: a number time in seconds and an optional string title.

Errors

RequestError::TooLong past MAX_BODY_BYTES, RequestError::NotJson for anything but an object, RequestError::Shape when time is missing or a field has the wrong type, and RequestError::OutOfRange for a length out of range or a title over MAX_BOOKMARK_TITLE_BYTES bytes or with a control character.

parse_bookmark_time

pub fn parse_bookmark_time(time: &str) -> Option<u64>

The bookmark a DELETE /player/api/me/item/{id}/bookmark/{time} path names, by its time in seconds.

Returns

None unless time is a plain non-negative decimal number in range.

parse_batch_get

pub fn parse_batch_get(body: &[u8]) -> Result<Vec<String>, RequestError>

Parses POST /player/api/items/batch/get: {"libraryItemIds": [...]}.

Errors

RequestError::TooLong past MAX_BODY_BYTES, RequestError::NotJson for anything but an object, RequestError::Shape when the list is missing or holds a non-string, and RequestError::OutOfRange past MAX_BATCH_ENTRIES ids or for an id of the wrong shape.

parse_list_filter

pub fn parse_list_filter(raw: &str) -> Option<ListFilter>

Parses a filter value (group.base64).

Returns

None for a value of the wrong shape; ListFilter::Unsupported for a well-formed filter on a group this library does not keep.

parse_list_query

pub fn parse_list_query(raw: &str) -> Result<ListQuery, RequestError>

Parses a list route's raw query string.

Unknown keys are ignored; a known key with a bad value refuses the query.

Errors

RequestError::TooLong past MAX_QUERY_BYTES, and RequestError::OutOfRange naming the first bad value.

parse_detail_query

pub fn parse_detail_query(raw: &str) -> Result<DetailQuery, RequestError>

Parses the query of a single-entity or small-list route.

Unknown keys are ignored; a known key with a bad value refuses the query.

Errors

RequestError::TooLong past MAX_QUERY_BYTES, and RequestError::OutOfRange naming the first bad value.

Type aliases

LocalSessionEntry

pub type LocalSessionEntry = Result<LocalSession, (Option<String>, RequestError)>;

One entry of a batch of local sessions: the session, or why it was refused together with the id the app gave it (when it gave one), so the answer can name the entry it refuses.

Constants

MAX_LOGIN_BODY_BYTES

pub const MAX_LOGIN_BODY_BYTES: usize = _;

Largest sign-in body (POST /player/login).

MAX_USERNAME_BYTES

pub const MAX_USERNAME_BYTES: usize = 256;

Longest username a sign-in may carry, in bytes.

MAX_PASSWORD_BYTES

pub const MAX_PASSWORD_BYTES: usize = 256;

Longest password a sign-in may carry, in bytes.

MAX_BODY_BYTES

pub const MAX_BODY_BYTES: usize = _;

Largest body of a play, sync, progress or bookmark request. Apps send a device description with a play request, so this is larger than the fields read need.

MAX_BATCH_BODY_BYTES

pub const MAX_BATCH_BODY_BYTES: usize = _;

Largest body of a request that carries several items or sessions (/api/me/progress/batch/update, /api/session/local-all, /api/items/batch/get). An offline session as the apps send it holds a copy of the item, so each can be several kilobytes.

MAX_BATCH_ENTRIES

pub const MAX_BATCH_ENTRIES: usize = 100;

Most entries a batch request may carry.

MAX_BOOKMARK_TITLE_BYTES

pub const MAX_BOOKMARK_TITLE_BYTES: usize = 200;

Longest bookmark title read, in bytes.

MAX_QUERY_BYTES

pub const MAX_QUERY_BYTES: usize = _;

Longest raw query string read, in bytes.

MAX_SEARCH_BYTES

pub const MAX_SEARCH_BYTES: usize = 256;

Longest search term read, in bytes.

MAX_PAGE_LIMIT

pub const MAX_PAGE_LIMIT: u64 = 1000;

Most items one list page may ask for.

CARD_TOKEN_LEN

pub const CARD_TOKEN_LEN: usize = 43;

Length of a card token: base64url without padding of 32 random bytes.

MAX_DEVICE_NAME_BYTES

pub const MAX_DEVICE_NAME_BYTES: usize = 64;

Longest player name kept from a play request's device details.

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