Skip to main content

Module websocket

Module websocket 

Source
Available on crate feature websocket only.
Expand description

SceneStreamEnable / SceneStreamDisable, the Scene ephemeral events they turn on, and client-sent SceneInteractionEvent frames, as a jmap_websocket extension (draft-atwood-jmap-scene-wss-00).

  • The deployment keeps one SceneEventHub and publishes every Scene event to it with SceneEventHub::publish: avatar and object events, the interactions accepted by SceneObject/interact, and the region events accepted by SceneRegion/broadcast or originated by the server. Every event carries accountId, “the id of the region’s hosting account” (§Ephemeral Event Types).
  • For each WebSocket connection it builds a SceneStreamHandler with the connection’s caller and the caller’s own account, and registers it with Connection::with_extension next to advertising urn:ietf:params:jmap:scene:websocket.

For each published event the handler asks should_deliver, at delivery time, with the event’s accountId as the hosting account, applies the draft’s rate limit on object updates (SceneStreamLimits), and queues the frame with ExtensionSender::try_send, which drops it if the client is too slow.

A SceneInteractionEvent frame from the client goes through validate_interaction and the hub’s per-user rate limit, and is then published to the hub for every connection, the sender’s included, to decide on. A frame that fails any check, or does not parse, is discarded: “the server discards the frame and returns no error to the sender” (§Submitting Interactions).

ChatStreamEnable with "scene" in dataTypes is a second path to the same events (§Interoperability with JMAP Chat WebSocket). The Chat handler switches it through the SceneChatAlias of this handler (jmap-chat-scene-server wires the two), so both paths are decided here, once per event: the union is delivered without duplicates.

Observer subscriptions (observe: true, jmap-chat-spec 93f2258) are recognized when SceneBackend::supports_observe is true, the server advertising {"supportsObserve": true}; otherwise observe is ignored, as the draft requires. An observing SceneStreamEnable needs regionIds (invalidArguments without), looks each listed region up in SceneBackend::observer_accounts, and fails with a forbidden RequestError whose regionIds member lists the accessible regions that refuse observers (allowObservers false, or SceneBackend::may_observe_region), leaving the subscription as it was.

For observerCount the handler reports to SceneBackend::set_observing every (account, region) pair its observer subscription covers: each listed region in each of the SceneBackend::observer_accounts when the subscription is enabled, whether or not the user has access to it then, and, from the first event for it that reaches the handler, each listed region of any other account (“delivery is not limited to those accounts”). It releases a pair when a later SceneStreamEnable, SceneStreamDisable or the connection’s close stops covering it. Which of the reported users count (access, allowObservers, policy, an active avatar) the backend decides, as delivery does, so the count follows delivery.

Credential expiry is the deployment’s (§Credential Expiry): the handler does not know when credentials expire; close the connection then.

use std::sync::Arc;
use jmap_scene_server::SceneBackend;
use jmap_scene_server::websocket::{SceneEventHub, SceneStreamHandler};
use jmap_types::Id;
use jmap_websocket::server::{Connection, DispatcherHandler};

/// Called once per accepted connection; `hub` is the server's.
fn wire<B: SceneBackend<CallerCtx = ()>>(
    backend: Arc<B>,
    hub: &SceneEventHub,
    connection: Connection<DispatcherHandler<()>>,
) -> Connection<DispatcherHandler<()>> {
    let scene = SceneStreamHandler::new(backend, (), Id::from("acct-alice"), hub);
    connection.with_extension(scene)
}

Structs§

SceneChatAlias
The "scene" switch of one connection’s ChatStreamEnable subscription, shared with that connection’s SceneStreamHandler.
SceneEventHub
The server-wide source of Scene ephemeral events: the deployment publishes each event here, and every connection’s SceneStreamHandler decides whether its client receives it.
SceneStreamHandler
The SceneStreamEnable / SceneStreamDisable / SceneInteractionEvent handler of one WebSocket connection; see the module docs.
SceneStreamLimits
The outbound rate limit a SceneStreamHandler applies, per connection. The default is the draft’s (§Rate Limiting): “SceneObjectEvent with event: "updated": no more than two events per object per second. Events above this rate MAY be silently dropped; the most recent state SHOULD be delivered when the rate window reopens.” The latest one over the limit is held and sent when the window reopens, after the delivery checks run again.