Crate ably_chat 

Unofficial, ergonomic Rust client for the Ably Chat REST API (v4).

Not affiliated with or endorsed by Ably.

Overview

Build a Client with an Auth credential, scope it to a room with Client::room, then chain into Messages, Reactions, or OccupancyHandle. Each operation is a builder that terminates in a bare .await (via IntoFuture); every fallible call returns Result<T>. Handles are cheap to Clone (Arc-backed) and Send + Sync.

History and versions are paginated: .await a query for the first Page, or call .into_stream() to follow the next links to exhaustion.

Example

use ably_chat::prelude::*;
use futures::StreamExt;

// Build a client and scope it to a room (rooms are implicit — this creates
// nothing server-side).
let client = Client::builder(Auth::api_key("appId.keyId:keySecret")).build();
let room = client.room("my-room");

// Send a message.
let sent = room.messages().send("hello, world").await?;
println!("sent message {}", sent.serial);

// Stream history (newest first by default), following pagination. The
// stream is `!Unpin`, so pin it before polling with `.next()`.
let mut history = std::pin::pin!(room.messages().history().into_stream());
while let Some(message) = history.next().await {
    let message = message?;
    println!("{}: {}", message.client_id, message.text);
}

Permissions & token issuance

Build the capability string for a TokenRequest or JWT with Capability (feature capabilities), mint the JWT itself with mint_ably_jwt (feature jwt; server-side only — it signs with your API secret), and let the client refresh Bearer credentials automatically by building Auth with Auth::provider instead of a static token (ADR-0012, SPEC §13).

Prefer not to sign requests yourself? KeyTokenProvider (feature token-issuance, off by default) mints Ably Tokens through the platform requestToken endpoint instead — also server-side only. Pair it with Auth::provider the same way (ADR-0012 item 5, SPEC §13).

Modules

prelude

Convenience re-exports for common usage.

raw

Low-level generated bindings. Escape hatch; NOT covered by the pre-1.0 stability guarantee and may change on regeneration.

Structs

Capability

A capability document: resource pattern → set of allowed operation strings. Operation strings are stored (not the enum) so the BTreeSet sorts lexicographically by wire value, matching Ably’s canonicalization.

Client

The entry point to the Ably Chat REST API.

ClientBuilder

Builder for Client. Requires credentials; host, timeout, retry budget, and a caller-supplied reqwest::Client are optional.

ClientIdCounts

Aggregated per-client counts for a multiple reaction.

ClientIdList

Aggregated set of client IDs for a unique/distinct reaction.

ClientReactions

Builder for Reactions::for_client; .await it to fetch a ReactionSummary. Without client_id, the server defaults to the authenticated caller’s client ID.

DeleteMessage

Builder for Messages::delete; .await it to soft-delete the message and receive the resulting Message (action message.delete).

DeleteReaction

Builder for Reactions::delete; .await it to remove the reaction. Resolves to () on success (the endpoint returns 204 with no body).

ErrorInfo

The Ably error envelope carried by a non-2xx API response.

GetMessage

Builder for Messages::get; .await it to fetch a Message.

GetOccupancy

Builder for OccupancyHandle::get; .await it to fetch Occupancy.

History

Builder for Messages::history. .await yields the first Page<Message>; into_stream follows all pages.

KeyTokenProvider

Mints Ably Tokens by calling POST /keys/{keyName}/requestToken with an unsigned TokenParams body under HTTP Basic auth. Pair with Auth::provider for automatic use + refresh.

Message

A chat message in the V4 REST representation.

MessageVersion

Details of the latest create/update/delete version of a message.

Messages

Message operations for a room.

Occupancy

Occupancy metrics for a room.

OccupancyHandle

Occupancy operations for a room.

Page

One page of a paginated collection: the decoded items plus the parsed rel="next" cursor (ADR-0009).

ReactionSummary

Summary of reactions on a message, grouped by reaction type. Each map is keyed by the reaction name (e.g. an emoji). Absent groups default to empty.

Reactions

Reaction operations on messages in a room.

Room

A handle to a single chat room, scoped by RoomName.

RoomName

The name of a chat room.

SendMessage

Builder for Messages::send; .await it to publish the message and receive the created Message.

SendReaction

Builder for Reactions::send; .await it to add the reaction. Resolves to () on success (the endpoint returns 201 with no body).

Serial

A message’s unique, region-scoped identifier.

SigningKey

An Ably API key split into its name (appId.keyId) and secret, for signing Ably JWTs. Debug redacts the secret.

Timestamp

Milliseconds since the Unix epoch.

TokenParams

Inputs for minting an Ably JWT. capability is the capability JSON string (with the capabilities feature, produce it via Capability::to_capability_string).

UpdateMessage

Builder for Messages::update; .await it to apply the edit and receive the updated Message.

Versions

Builder for Messages::versions. .await yields the first Page<Message>; into_stream follows all pages.

Enums

Auth

Static credentials supplied to the client.

Direction

History/versions ordering. Query-only; serialized as a lowercase string by the dispatch layer, never via serde.

Error

The single error type surfaced by this crate.

MessageAction

The action that produced a message version.

Operation

An Ably capability operation. #[non_exhaustive]; unknown wire values map to Other (ADR-0007) so parsing never fails.

ReactionType

The reaction aggregation model.

Traits

TokenProvider

Supplies a currently-valid Bearer credential (Ably Token string or Ably JWT), refreshed on demand. The returned string is the raw token — the client adds the Bearer prefix. Implementations MUST be cheap to call when cached.

Functions

mint_ably_jwt

Mint an HS256 Ably JWT signed with the key secret. No network call.

Type Aliases

Metadata

Opaque, user-defined JSON metadata. Not interpreted by Ably; treat as untrusted input when reading.

Result

The result type returned by every fallible operation in this crate.