# jmap-scene-server
Method handlers for the `SceneAsset`, `SceneRegion`, `SceneObject` and
`SceneAvatar` data types of the
JMAP Scene extension (draft-atwood-jmap-scene-00), backend-agnostic, for a
`jmap-server` `Dispatcher`. You supply storage through the `SceneBackend`
trait.
## What it is
| `handle_scene_asset_get`, `handle_scene_asset_changes` | §SceneAsset/get, §SceneAsset/changes (RFC 8620 §5.1, §5.2) |
| `handle_scene_asset_set` | §SceneAsset/set and its §SetError Conditions |
| `handle_scene_asset_query`, `handle_scene_asset_query_changes` | §SceneAsset/query, §SceneAsset/queryChanges |
| `GLTF_BINARY` | §Preferred Asset Format: `model/gltf-binary` is mandatory to implement |
| `handle_scene_region_get`, `handle_scene_region_changes` | §SceneRegion/get, §SceneRegion/changes (RFC 8620 §5.1, §5.2) |
| `handle_scene_region_set` | §SceneRegion/set: create, update, destroy and §SetError Conditions |
| `handle_scene_region_query`, `handle_scene_region_query_changes` | §SceneRegion/query, §SceneRegion/queryChanges |
| `handle_scene_object_get`, `handle_scene_object_changes` | §SceneObject/get, §SceneObject/changes (RFC 8620 §5.1, §5.2) |
| `handle_scene_object_set` | §SceneObject/set: create, update, recursive destroy and §SetError Conditions |
| `handle_scene_object_query`, `handle_scene_object_query_changes` | §SceneObject/query, §Spatial Filters, §SceneObject/queryChanges |
| `handle_scene_object_interact` | §SceneObject/interact: `notFound`, `forbidden`, `rateLimit` and `invalidProperties`; accepted interactions go to `SceneBackend::accept_interaction` |
| `handle_scene_region_broadcast` | §SceneRegion/broadcast (jmap-chat-spec 93f2258): `unknownMethod` without `supportsRegionBroadcast`; `notFound`, `forbidden` (owner or admin only), `rateLimit` and `invalidProperties`; accepted events go to `SceneBackend::accept_region_event` |
| `handle_scene_avatar_get`, `handle_scene_avatar_changes` | §SceneAvatar/get, §SceneAvatar/changes (RFC 8620 §5.1, §5.2) |
| `handle_scene_avatar_set` | §SceneAvatar/set: enter, update, leave, re-enter, eject and §SetError Conditions |
| `handle_scene_avatar_query`, `handle_scene_avatar_query_changes` | §SceneAvatar/query, §SceneAvatar/queryChanges |
| `query::asset_matches`, `query::compare_assets` | §SceneAsset/query filter and sort |
| `query::region_matches`, `query::compare_regions` | §SceneRegion/query filter and sort |
| `query::object_matches`, `query::compare_objects`, `query::region_local_position` | §SceneObject/query filter, spatial filters and sort |
| `query::avatar_matches`, `query::compare_avatars` | §SceneAvatar/query filter, spatial filters and sort |
| `SceneBackend` | storage, capability objects, blob sizes, permission and binding hooks |
| `BindingTarget` | what a `chatId`/`spaceId`/`channelId`/`activeCallId` references |
| `AvatarView`, `AvatarRedaction` | §Avatar Visibility: what `SceneBackend::avatar_view` lets a caller see of another user's avatar |
| `memory::MemoryBackend` (`memory` feature) | in-memory reference backend; accounts with `with_account` / `register_account`, companion capabilities with `advertise` |
| `register_scene_handlers` | wires the `SceneAsset/*`, `SceneRegion/*`, `SceneObject/*` (including `SceneObject/interact`), `SceneAvatar/*` and `SceneRegion/broadcast` methods |
## What it's for
A JMAP server that offers spatial scenes wires these handlers next to its
other extensions. The crate depends on `jmap-types`, `jmap-server` and
`jmap-scene-types` only. Chat and VTC lookups for the region bindings
belong to binding crates, which implement `SceneBackend::has_capability`
and `SceneBackend::region_binding`.
## How to use
```rust,ignore
use std::sync::Arc;
use jmap_server::{Dispatcher, Id};
use jmap_scene_server::{memory::MemoryBackend, register_scene_handlers};
// `capability`: the account-level object the Session advertises.
let backend = Arc::new(MemoryBackend::new().with_account(&account_id, capability));
let mut dispatcher: Dispatcher<Id> = Dispatcher::new();
register_scene_handlers(&mut dispatcher, backend);
```
Advertise `urn:ietf:params:jmap:scene` in your Session with the same
account-level object that `SceneBackend::scene_capability` returns, and
list `model/gltf-binary` in its `supportedVisualTypes`.
### WebSocket ephemeral events (`websocket` feature)
`websocket::SceneStreamHandler` is a `jmap-websocket` extension handler
for `SceneStreamEnable`, `SceneStreamDisable` and client-sent
`SceneInteractionEvent` frames (draft-atwood-jmap-scene-wss-00). Keep one
`SceneEventHub`, publish every Scene event to it (the interactions
`SceneObject/interact` accepts and the region events `SceneRegion/broadcast`
accepts included), and register one handler per connection next to
advertising `urn:ietf:params:jmap:scene:websocket` as `{}`, or as
`{"supportsObserve": true}` when `SceneBackend::supports_observe` is
`true`:
```rust,ignore
use jmap_scene_server::websocket::{SceneEventHub, SceneStreamHandler};
let hub = SceneEventHub::new(256); // server-wide
let scene = SceneStreamHandler::new(Arc::clone(&backend), caller, own_account_id, &hub);
let connection = connection.with_extension(scene);
hub.publish(avatar_event); // accountId = the region's hosting account
```
- Each event goes through `should_deliver` with its `accountId` as the
hosting account.
- An interaction frame goes through `validate_interaction` and the hub's
limit of five per user per region per second, then to the hub; one
that fails is dropped without a `RequestError`.
- `SceneStreamLimits` (default: the draft's) keeps two `"updated"`
`SceneObjectEvent`s per object per second, sending the latest held one
when the window reopens.
- Observer subscriptions (`observe: true`, jmap-chat-spec 93f2258) are
recognized only when `SceneBackend::supports_observe` is `true`. They
need `regionIds` (else `invalidArguments`); a listed region the user can
access whose `allowObservers` is `false`, or that
`may_observe_region` declines, makes the whole message a `forbidden`
RequestError with a `regionIds` member, and the subscription stays as
it was. Inaccessible and missing regions are kept silently. The
observed regions are reported to `SceneBackend::set_observing` and
released on the next enable, disable or close, so the backend keeps
`observerCount`. `observer_accounts` names the accounts a `regionIds`
entry is looked up in (default: the connection's own).
- `chat_alias()` is the `ChatStreamEnable` `"scene"` switch;
`jmap-chat-scene-server::link_scene_stream` drives it. While it is on,
an event the alias path refuses still reaches the connection's own
observer subscription, once.
## How it works
A create must carry `blobId` and `mediaType` and must not carry the
server-set `id`, `accountId`, `size` or `createdAt`. `name`, `assetUri`
and `sha256` must be strings or `null`, and `sha256` must be lowercase
hex. `mediaType` must be `model/gltf-binary`, a type listed in
`supportedVisualTypes`, or any `audio/*` or `image/*` type. Any failure
of these rules is one `invalidProperties` naming every offending
property. The handler then asks `SceneBackend::blob_size`: a missing blob
is `invalidProperties` naming `blobId` and a blob larger than `maxAssetSizeBytes` is `overQuota`.
`SceneBackend::create_object` assigns the ULID and applies the
deployment's account storage quota and admin-only rule atomically. The
`created` entry holds the five server-set properties, with `ownerId` from
`SceneBackend::caller_user_id`. An update may patch only `name`,
`assetUri`, `sha256` and extension properties. Update and destroy return
`notFound` for an unknown id, and `forbidden` when
`SceneBackend::may_modify_asset` is `false`. `/query` defaults to
`createdAt` descending. The backend trait is not object-safe (generic
methods); every public type is `#[non_exhaustive]`.
A SceneRegion create needs `mayCreateRegion`, a non-empty `name` and
`bounds` with `min <= max` on every axis; `accessPolicy` must be
`public`, `invite` or `space`, and `spawnOrientation` a unit quaternion
(within 1e-6). `space` needs `urn:ietf:params:jmap:chat` and a `spaceId`.
A non-null `chatId`, `spaceId` or `channelId` needs the Chat capability
and a `BindingTarget::Usable` answer from `region_binding`; otherwise it
is `invalidProperties` naming the property. `activeCallId` is not a
create property. The backend applies `maxRegionsPerAccount` atomically
with the insert. An update is validated as the region the patch leaves.
A non-null `activeCallId` needs `urn:ietf:params:jmap:vtc`: a missing or
ended call is `invalidProperties`, an inaccessible one `forbidden`. The
`updated` entry echoes the new `updatedAt`. Update needs
`may_update_region` and destroy `may_destroy_region` (owner or admin in
`MemoryBackend`). On destroy the backend removes the region's SceneObjects
and SceneAvatars. `/query` defaults to `createdAt` descending, and an
`accessPolicy` filter value outside the three is `invalidArguments`, as
is a `worldStateEquals` filter that is not an object of String, Number
or Boolean values. With `SceneBackend::supports_observe`, a create
stores `allowObservers` (default `true`) and `observerCount` `0`;
without it, `allowObservers` is `invalidProperties`. `observerCount` is
server-set.
A SceneObject create needs `mayCreateObject`, a `regionId` naming an
existing region the caller can access (else `invalidProperties` naming
`regionId`, the same for both cases) and a finite `position`. `scale` must
be finite, `orientation` within 1e-3 of unit length (stored normalized;
an absent one is the identity), `physicsMode` one of `static`, `dynamic`,
`kinematic` or `none`, and `visualRef` and `visualType` come together.
`visualType` must be listed in `supportedVisualTypes` (or be
`model/gltf-binary`) and `visualRef` must name an uploaded blob (else
`invalidProperties` naming `visualRef`, on create and update). A `parentId` must name an existing object (else
`invalidProperties` naming `parentId`, on create and update) in the same
region, must not make the object its own ancestor, and must
keep every object within 16 levels; an update that re-parents counts the
moved subtree. The backend sets `ownerId` to the caller and applies
`maxObjectsPerRegion` atomically. `regionId` is immutable. Update and
destroy need `may_modify_object` (object owner, region owner or admin);
destroy removes the object's descendants too, and only the requested id
appears in `destroyed`. `/query` defaults to `createdAt` ascending and
returns `invalidArguments` without `regionId` in every condition, for an
unknown `physicsMode`, a `withinRadius.radius` <= 0 or a `withinBounds`
`max` below `min`. The spatial filters compare region-local positions:
a child's parent-relative `position` is mapped through its ancestors'
transforms, and the boundary is inclusive.
A SceneAvatar create enters a region. It needs a `regionId` naming an
existing region the caller has access to under `may_access_region`
(else `invalidProperties` naming `regionId`, the same error either way)
and `may_enter_region`, which bars banned users (else `forbidden`), and must not carry `id`, `joinedAt`, `leftAt` or another
user's `userId` (`forbidden`). The handler sets `userId` from
`caller_user_id`, `displayName` from `avatar_display_name` when absent,
and `position` and `orientation` from the region's spawn values when
absent. A supplied `position` must be finite, an `orientation` within
1e-3 of unit length (stored normalized), and `visualRef` and
`visualType` come together. In one atomic step `create_object` refuses
the create with `alreadyExists` and `existingId` when the user already
has an avatar in the region, present or departed, applies
`maxAvatarsPerRegion` to active avatars, sets `leftAt` on the user's
active avatar in any other region, and keeps every affected region's
`activeAvatarCount`. The `created` entry is the stored avatar. An update
of the caller's own avatar may change anything but `id`, `regionId`,
`userId` and `joinedAt`; setting `leftAt` leaves the region and a second
leave is `invalidProperties` naming `leftAt`. Setting `leftAt` to `null`
on a departed avatar re-enters the region (§Re-entering a Region): lost
region access is `notFound`, `may_enter_region` `false` is `forbidden`,
and a `position` or `orientation` in the same patch is
`invalidProperties`. The handler sets `joinedAt` to now and `position`
and `orientation` to the region's spawn point, and `update_object`
applies `maxAvatarsPerRegion` (`overQuota`), the auto-eject from other
regions and the `activeAvatarCount` update in the same atomic step. On
another user's avatar only an eject (`leftAt`) and, on accounts with
`supportsAvatarRegionState`, a change to `regionState` are allowed: the
eject when `may_eject_avatar` agrees, `regionState` when
`may_update_region` does (owner or admin); anything else is `forbidden`.
The avatar's own user cannot change `regionState` or create with a
non-null one unless they are the region owner or an admin; without the
capability `regionState` is `invalidProperties`. Another user's avatar
that `avatar_view` hides is `notFound` for `/get` and for an update. Destroy is always `forbidden`. `/query` defaults to
`joinedAt` ascending and returns `invalidArguments` without `regionId` in
every condition, for a `withinRadius.radius` <= 0 or a `withinBounds`
`max` below `min`.
### Conditional Foo/set (draft-ietf-jmap-conditional-02)
`register_scene_conditional(dispatcher, backend)`, called after
`register_scene_handlers`, attaches `SetSupport` to each registered `/set`
(SceneAsset, SceneRegion, SceneObject, SceneAvatar) and skips the rest; it
re-registers nothing, and a deployment that never calls it is unchanged
(docs/design/DECISIONS.md decisions 1 and 17). Advertise
`urn:ietf:params:jmap:conditional` only when `Dispatcher::conditional_ready()` is
true.
`SceneRegion/get` marks `invitedUserIds` unreadable for every caller who may not
update the region (the list it blanks to `[]`, empty or not), so a precondition on
it is `forbidden` (§9.1) and reveals nothing. `MemoryBackend`'s store is a
`jmap_server::ScopedState`: an atomic rollback restores objects, states and
derived counts. Under an atomic scope `maxAvatarsPerRegion` moves to the commit,
which checks the final state, so an admin can eject one avatar and enter at the
cap in one call; the one-record-per-user rule stays with the create, as records are
never destroyed.
## Object history (draft-ietf-jmap-object-history-03)
`register_scene_handlers_with_history(dispatcher, backend)`, for a backend
that also implements `jmap_server::ObjectHistoryBackend`, calls
`register_scene_handlers` and re-registers history-aware `/get`, `/set`,
`/query` and `/queryChanges` of SceneAsset, SceneRegion and SceneObject.
SceneAvatar keeps no history (decision 22). SceneRegion and SceneObject
history entries pass the same region-access and visibility checks as
current objects, and `invitedUserIds` is emptied for a caller who may not
update the region (§8.2); a destroyed query leaves out ids the caller may
not see and omits `total`. SceneObject restores run parent first and need
a current region. `SceneObject/interact` is not a `/set` and is
unchanged. The memory backend's `with_object_history(capability,
retention)` records region and object cascades and evaluates no filter or
sort over destroyed objects.
## Gotchas
- `SceneBackend::may_modify_asset` defaults to `Ok(true)` (fail-open,
bd:JMAP-bghk). Override it, or every caller can rename and delete
every asset.
- `may_update_region`, `may_destroy_region` and `region_binding` also
fail open: any caller may change any region, and every binding id is
accepted, until you override them.
- `may_modify_object` fails open too: any caller may move or delete any
SceneObject until you override it.
- `may_enter_region` and `may_eject_avatar` fail open too: no one is
banned from a region and anyone may eject anyone, until you override
them. Entry to an `invite` or `space` region is decided by
`may_access_region`.
- `caller_user_id` has no default. Avatar ownership is a spec rule, not
a policy hook.
- Re-parenting an object reads every SceneObject of the account to find
the moved subtree's height. A backend with a `parentId` index can
register a faster `SceneObject/set`.
- `has_capability` has no default. Return `true` only for the companion
capabilities you advertise on that account.
- Destroying a region does not end its `activeCallId` VTCCall, and this
crate sends no VTCCall StateChange. That belongs to the Scene/VTC
binding crate.
- `blob_size` has no default. Return `Err` for a storage failure, not
`Ok(None)`, or the client sees `invalidProperties` and does not retry.
- `model/gltf-binary` is accepted even if your capability object omits
it. The draft requires you to list it.
- "Recognized audio/image type" means any `audio/*` or `image/*` media
type; there is no registry lookup.
- The `name` filter is a case-insensitive substring match, as in the
draft's example. The `name` sort ignores `collation` and puts assets
without a name last.
- The `MemoryBackend` caller context is a `jmap_server::MemoryCaller`: the
caller's Principal `Id` (whose string is the userId), or `()` (the
account id is the userId); the creator owns an asset. `grant_region_access` admits a user to an
`invite` region. Its `/queryChanges` always returns
`cannotCalculateChanges`.
## References
- [draft-atwood-jmap-scene-00] — JMAP Scene
- [RFC 8620] — JMAP Core
- [RFC 6838] — Media Type Specifications and Registration Procedures
[draft-atwood-jmap-scene-00]: https://github.com/MarkAtwood/jmap-chat-spec
[RFC 8620]: https://www.rfc-editor.org/rfc/rfc8620
[RFC 6838]: https://www.rfc-editor.org/rfc/rfc6838