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
SceneEventHuband publishes every Scene event to it withSceneEventHub::publish: avatar and object events, the interactions accepted bySceneObject/interact, and the region events accepted bySceneRegion/broadcastor originated by the server. Every event carriesaccountId, “the id of the region’s hosting account” (§Ephemeral Event Types). - For each WebSocket connection it builds a
SceneStreamHandlerwith the connection’s caller and the caller’s own account, and registers it withConnection::with_extensionnext to advertisingurn: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§
- Scene
Chat Alias - The
"scene"switch of one connection’sChatStreamEnablesubscription, shared with that connection’sSceneStreamHandler. - Scene
Event Hub - The server-wide source of Scene ephemeral events: the deployment
publishes each event here, and every connection’s
SceneStreamHandlerdecides whether its client receives it. - Scene
Stream Handler - The
SceneStreamEnable/SceneStreamDisable/SceneInteractionEventhandler of one WebSocket connection; see the module docs. - Scene
Stream Limits - The outbound rate limit a
SceneStreamHandlerapplies, per connection. The default is the draft’s (§Rate Limiting): “SceneObjectEventwithevent: "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.