Skip to main content

Module memory

Module memory 

Source
Available on crate feature memory only.
Expand description

In-memory reference implementation of SceneBackend.

Gated behind feature = "memory". Not production. In-memory reference implementation of SceneBackend.

§This is a reference implementation, not production

MemoryBackend backs this crate’s integration tests and is a readable example for anyone writing a real backend. All state lives in HashMaps behind a std::sync::Mutex; nothing is persisted. Blobs are registered by size only, with add_blob.

§Caller context

CallerCtx is a type implementing MemoryCaller: the caller’s Principal id (Id, the default), whose string is the caller’s userId, or () for a deployment without identity, whose every caller acts as the user named by the account id. The owner of an asset or a region is its ownerId; SceneBackend::may_modify_asset and SceneBackend::may_update_region allow the owner and the users registered with add_admin, and so does SceneBackend::may_destroy_region. SceneBackend::may_modify_object allows the object’s owner, its region’s owner and the admins; a created object’s ownerId is the caller.

§Accounts

An account exists once MemoryBackend::with_account (or MemoryBackend::register_account) registers it with the Scene capability object it advertises; every call naming any other account is accountNotFound (RFC 8620 §3.6.2).

§Avatars

SceneBackend::caller_user_id is the caller. SceneBackend::may_enter_region refuses the users barred from a region with ban_from_region. SceneBackend::may_eject_avatar allows the avatar’s region owner and the admins. Each region’s activeAvatarCount is recomputed from its avatars with leftAt null whenever an avatar enters or leaves.

§Interactions

SceneBackend::accept_interaction refuses the interactions of users registered with rate_limit_interactions and records the rest, read back with accepted_interactions. SceneBackend::accept_region_event does the same for region events with rate_limit_region_events and accepted_region_events.

§Visibility

SceneBackend::may_access_region refuses an "invite" region to everyone but its owner, the admins, the users in its invitedUserIds, the users given access with grant_region_access (one of the “other mechanisms” an "invite" region MAY admit by) and the users with an active avatar in it; other policies, and a region that is not stored, admit everyone (there are no Spaces here). hide_object takes an object out of one user’s visibility set, for SceneBackend::is_object_visible; block makes one user blocked by another, for SceneBackend::is_user_blocked; hide_region_avatars hides a region’s avatars from one user, as for a region bound to an E2EE call, for SceneBackend::may_see_region_avatars. reserve_display_name adds a name to the list SceneBackend::reserved_display_names returns for every account. /query omits the regions, objects and avatars those hooks hide from the caller; activeAvatarCount stays the true count.

SceneBackend::avatar_view follows per-account rules: hide_avatar hides one avatar from one viewer, withhold_avatar withholds an AvatarRedaction’s properties, and reveal_avatar undoes either. Each advances the account’s SceneAvatar state. The avatar’s own user, the region owner and the admins always see it in full. SceneAvatar/query leaves hidden avatars out and matches the redacted values. Once an account has a rule, SceneAvatar/changes answers from the caller’s view, from snapshots kept per state; a state from before the first rule is cannotCalculateChanges.

§Observers

set_supports_observe turns on SceneBackend::supports_observe. SceneBackend::observer_accounts is every registered account (or the list given to restrict_observer_accounts), SceneBackend::may_observe_region declines the regions registered with decline_observers (until admit_observers), and SceneBackend::set_observing counts each user’s observing connections per region. A region’s observerCount is the users observing it who have access and no active avatar there, or 0 while allowObservers is false or the region declines observers. It is recomputed, advancing the SceneRegion state when it changes, whenever any of those inputs changes: an observer starts or stops, an avatar enters or leaves, the region is updated, and the knobs that change access or the observer policy from outside the region (grant_region_access, revoke_region_access, add_admin, decline_observers, admit_observers). There are no Spaces here, so no other access change exists.

§Companion capabilities and bindings

advertise records a capability URI for an account, for SceneBackend::has_capability. set_region_binding records what a binding id references; SceneBackend::region_binding answers BindingTarget::Missing for any id not recorded. set_channel_space records that a channel belongs to a Space; SceneBackend::channel_in_space answers false for any pair not recorded.

§Quota

set_storage_quota sets an account’s total asset storage in bytes; SceneBackend::create_object refuses a SceneAsset that would exceed it, a SceneRegion beyond the capability’s maxRegionsPerAccount, and a SceneObject beyond its maxObjectsPerRegion, with overQuota.

§Region destroy

Destroying a SceneRegion also destroys the stored SceneObject and SceneAvatar records whose regionId names it. Destroying a SceneObject also destroys its descendants, in the same state step.

§Query

SceneAsset/query, SceneRegion/query, SceneObject/query and SceneAvatar/query evaluate the filter and sort with the crate::query functions. /queryChanges is not implemented: results say canCalculateChanges: false and /queryChanges returns cannotCalculateChanges (RFC 8620 §5.6).

§Concurrency

The await_holding_lock lint is denied module-wide: no guard is held across an .await.

Structs§

MemoryBackend
A fully in-memory implementation of SceneBackend.
MemoryError
Opaque storage-layer error returned by MemoryBackend.