mod limit;
use std::fmt;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex, PoisonError};
use std::time::Duration;
use jmap_scene_types::{ObjectEventKind, SceneEvent, SceneInteractionEvent, SceneStreamEnable};
use jmap_types::{Id, JmapError};
use jmap_websocket::server::{ExtensionHandler, ExtensionMessage, ExtensionSender};
use tokio::sync::broadcast;
use tokio::task::JoinHandle;
use tokio::time::Instant;
use crate::SceneBackend;
use crate::SceneStreamFilter;
use crate::ephemeral::{
SceneEphemeralSubscription, observer_regions, should_deliver, validate_interaction,
};
use limit::{Limiter, Window, sleep_until};
const ENABLE: &str = "SceneStreamEnable";
const DISABLE: &str = "SceneStreamDisable";
const INTERACTION: &str = "SceneInteractionEvent";
type InteractionKey = (Id, Id, String);
#[derive(Clone)]
pub struct SceneEventHub {
tx: broadcast::Sender<SceneEvent>,
interactions: Arc<Mutex<Limiter<InteractionKey, ()>>>,
}
impl fmt::Debug for SceneEventHub {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("SceneEventHub")
.field("connections", &self.tx.receiver_count())
.finish_non_exhaustive()
}
}
impl SceneEventHub {
pub fn new(capacity: usize) -> Self {
Self::with_interaction_window(capacity, Some(Duration::from_secs(1)))
}
pub fn with_interaction_window(capacity: usize, window: Option<Duration>) -> Self {
let (tx, _) = broadcast::channel(capacity);
let rule = window.map(|per| Window {
max: 5,
per,
keep_latest: false,
});
Self {
tx,
interactions: Arc::new(Mutex::new(Limiter::new(rule))),
}
}
pub fn publish(&self, event: SceneEvent) {
let _ = self.tx.send(event);
}
fn admit_interaction(&self, key: InteractionKey) -> bool {
self.interactions
.lock()
.unwrap_or_else(PoisonError::into_inner)
.offer(key, (), Instant::now())
.is_some()
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SceneStreamLimits {
object_update: Option<Duration>,
}
impl Default for SceneStreamLimits {
fn default() -> Self {
Self {
object_update: Some(Duration::from_secs(1)),
}
}
}
impl SceneStreamLimits {
pub fn object_update_window(mut self, window: Option<Duration>) -> Self {
self.object_update = window;
self
}
pub fn object_update_window_value(&self) -> Option<Duration> {
self.object_update
}
}
#[derive(Debug, Clone, Default)]
pub struct SceneChatAlias {
on: Arc<AtomicBool>,
}
impl SceneChatAlias {
pub fn set(&self, on: bool) {
self.on.store(on, Ordering::SeqCst);
}
pub fn is_on(&self) -> bool {
self.on.load(Ordering::SeqCst)
}
}
struct Shared<B: SceneBackend> {
backend: Arc<B>,
caller: B::CallerCtx,
recipient_account_id: Id,
subscription: Mutex<SceneEphemeralSubscription>,
alias: SceneChatAlias,
every: SceneEphemeralSubscription,
observing: tokio::sync::Mutex<Vec<(Id, Id)>>,
}
impl<B: SceneBackend> Shared<B> {
fn subscription(&self) -> SceneEphemeralSubscription {
self.subscription
.lock()
.unwrap_or_else(PoisonError::into_inner)
.clone()
}
async fn admits(&self, event: &SceneEvent) -> bool {
let Some(hosting) = hosting_account(event) else {
return false;
};
let deliver = |subscription| {
should_deliver(
&*self.backend,
&self.caller,
hosting,
&self.recipient_account_id,
subscription,
event,
)
};
let own = self.subscription();
if self.alias.is_on() {
if deliver(&self.every).await.unwrap_or(false) {
return true;
}
if !own.filter().is_some_and(SceneStreamFilter::observes) {
return false;
}
}
deliver(&own).await.unwrap_or(false)
}
fn observer_covers(&self, region_id: &Id) -> bool {
self.subscription()
.filter()
.is_some_and(|f| f.observes() && f.region_ids().covers(region_id))
}
async fn observe(&self, listed: Vec<(Id, Id)>) {
let mut observing = self.observing.lock().await;
let mut next = listed;
for pair in observing.iter() {
if !next.contains(pair) && self.observer_covers(&pair.1) {
next.push(pair.clone());
}
}
let previous = std::mem::replace(&mut *observing, next);
for (account, region) in observing.iter().filter(|p| !previous.contains(p)) {
let _ = self
.backend
.set_observing(&self.caller, account, region, true)
.await;
}
for (account, region) in previous.iter().filter(|p| !observing.contains(p)) {
let _ = self
.backend
.set_observing(&self.caller, account, region, false)
.await;
}
}
async fn observe_event(&self, event: &SceneEvent) {
let (Some(account), Some(region)) = (hosting_account(event), event_region(event)) else {
return;
};
if !self.observer_covers(region) {
return;
}
let mut observing = self.observing.lock().await;
let pair = (account.clone(), region.clone());
if observing.contains(&pair) || !self.observer_covers(region) {
return;
}
let _ = self
.backend
.set_observing(&self.caller, account, region, true)
.await;
observing.push(pair);
}
}
fn event_region(event: &SceneEvent) -> Option<&Id> {
Some(match event {
SceneEvent::Avatar(e) => &e.region_id,
SceneEvent::Object(e) => &e.region_id,
SceneEvent::Interaction(e) => &e.region_id,
SceneEvent::Region(e) => &e.region_id,
_ => return None,
})
}
fn hosting_account(event: &SceneEvent) -> Option<&Id> {
Some(match event {
SceneEvent::Avatar(e) => &e.account_id,
SceneEvent::Object(e) => &e.account_id,
SceneEvent::Interaction(e) => &e.account_id,
SceneEvent::Region(e) => &e.account_id,
_ => return None,
})
}
pub struct SceneStreamHandler<B: SceneBackend> {
shared: Arc<Shared<B>>,
hub: SceneEventHub,
limits: SceneStreamLimits,
task: Option<JoinHandle<()>>,
}
impl<B: SceneBackend> fmt::Debug for SceneStreamHandler<B> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("SceneStreamHandler")
.field("recipient_account_id", &self.shared.recipient_account_id)
.field("subscription", &self.shared.subscription())
.field("chat_alias", &self.shared.alias.is_on())
.field("limits", &self.limits)
.finish_non_exhaustive()
}
}
impl<B: SceneBackend> SceneStreamHandler<B> {
pub fn new(
backend: Arc<B>,
caller: B::CallerCtx,
recipient_account_id: Id,
hub: &SceneEventHub,
) -> Self {
let mut every = SceneEphemeralSubscription::default();
every
.replace_with(&SceneStreamEnable::default())
.expect("a SceneStreamEnable with null eventTypes is always valid");
Self {
shared: Arc::new(Shared {
backend,
caller,
recipient_account_id,
subscription: Mutex::new(SceneEphemeralSubscription::default()),
alias: SceneChatAlias::default(),
every,
observing: tokio::sync::Mutex::new(Vec::new()),
}),
hub: hub.clone(),
limits: SceneStreamLimits::default(),
task: None,
}
}
pub fn with_limits(mut self, limits: SceneStreamLimits) -> Self {
self.limits = limits;
self
}
pub fn chat_alias(&self) -> SceneChatAlias {
self.shared.alias.clone()
}
pub fn subscription(&self) -> SceneEphemeralSubscription {
self.shared.subscription()
}
fn set(&self, subscription: SceneEphemeralSubscription) {
*self
.shared
.subscription
.lock()
.unwrap_or_else(PoisonError::into_inner) = subscription;
}
async fn enable(&self, message: &ExtensionMessage) -> Result<(), JmapError> {
let enable: SceneStreamEnable = message.deserialize()?;
let shared = &self.shared;
let backend = &*shared.backend;
let mut next = self.subscription();
let observing = backend.supports_observe(&shared.caller);
if observing {
next.replace_with_observe(&enable)?;
} else {
next.replace_with(&enable)?;
}
let mut listed = Vec::new();
if observing
&& enable.observe == Some(true)
&& let Some(region_ids) = &enable.region_ids
{
let fail = |e: B::Error| jmap_server::server_fail_from_backend(&e);
let accounts = backend
.observer_accounts(&shared.caller, &shared.recipient_account_id)
.await
.map_err(fail)?;
let refused = observer_regions(backend, &shared.caller, &accounts, region_ids)
.await
.map_err(fail)?;
if !refused.is_empty() {
let mut err = JmapError::forbidden();
err.description = Some("these regions do not admit observers".to_owned());
err.extra
.insert("regionIds".to_owned(), serde_json::json!(refused));
return Err(err);
}
for account in &accounts {
for region in region_ids {
let pair = (account.clone(), region.clone());
if !listed.contains(&pair) {
listed.push(pair);
}
}
}
}
self.set(next);
shared.observe(listed).await;
Ok(())
}
async fn interact(&self, message: &ExtensionMessage) {
let Ok(mut frame) = message.deserialize::<SceneInteractionEvent>() else {
return;
};
frame.extra.clear();
let shared = &self.shared;
let Ok(Some(relayed)) =
validate_interaction(&*shared.backend, &shared.caller, &frame.account_id, &frame).await
else {
return;
};
let key = (
relayed.account_id.clone(),
relayed.region_id.clone(),
relayed.user_id.clone(),
);
if self.hub.admit_interaction(key) {
self.hub.publish(SceneEvent::Interaction(relayed));
}
}
}
impl<B: SceneBackend> ExtensionHandler for SceneStreamHandler<B> {
fn message_types(&self) -> &[&str] {
&[ENABLE, DISABLE, INTERACTION]
}
fn start(&mut self, events: ExtensionSender) {
let rx = self.hub.tx.subscribe();
self.task = Some(tokio::spawn(forward(
Arc::clone(&self.shared),
self.limits,
rx,
events,
)));
}
async fn handle(&mut self, message: ExtensionMessage) -> Result<(), JmapError> {
match message.message_type.as_str() {
ENABLE => self.enable(&message).await,
INTERACTION => {
self.interact(&message).await;
Ok(())
}
_ => {
self.set(SceneEphemeralSubscription::default());
self.shared.observe(Vec::new()).await;
Ok(())
}
}
}
async fn close(&mut self) {
if let Some(task) = self.task.take() {
task.abort();
}
self.set(SceneEphemeralSubscription::default());
self.shared.observe(Vec::new()).await;
}
}
impl<B: SceneBackend> Drop for SceneStreamHandler<B> {
fn drop(&mut self) {
if let Some(task) = self.task.take() {
task.abort();
}
}
}
type ObjectKey = (Id, Id);
async fn forward<B: SceneBackend>(
shared: Arc<Shared<B>>,
limits: SceneStreamLimits,
mut rx: broadcast::Receiver<SceneEvent>,
events: ExtensionSender,
) {
let mut updates: Limiter<ObjectKey, SceneEvent> =
Limiter::new(limits.object_update.map(|per| Window {
max: 2,
per,
keep_latest: true,
}));
loop {
tokio::select! {
() = events.closed() => return,
() = sleep_until(updates.next_due()) => {
for (_, held) in updates.take_due(Instant::now()) {
if shared.admits(&held).await {
send(&events, &held);
}
}
}
received = rx.recv() => match received {
Ok(event) => {
shared.observe_event(&event).await;
if !shared.admits(&event).await {
continue;
}
let pass = match &event {
SceneEvent::Object(e) if e.event == ObjectEventKind::Updated => {
let key = (e.account_id.clone(), e.object_id.clone());
updates.offer(key, event.clone(), Instant::now()).is_some()
}
_ => true,
};
if pass {
send(&events, &event);
}
}
Err(broadcast::error::RecvError::Lagged(_)) => {}
Err(broadcast::error::RecvError::Closed) => return,
},
}
}
}
fn send(events: &ExtensionSender, event: &SceneEvent) {
let _ = events.try_send(event);
}
#[cfg(all(test, feature = "memory"))]
mod tests {
use super::*;
use crate::RegionScope;
use crate::memory::MemoryBackend;
use serde_json::{Value, json};
fn handler(hub: &SceneEventHub) -> SceneStreamHandler<MemoryBackend> {
SceneStreamHandler::new(
Arc::new(MemoryBackend::new()),
Id::from("user:alice@example.com"),
Id::from("a1"),
hub,
)
}
fn message(ty: &str, body: Value) -> ExtensionMessage {
let Value::Object(body) = body else {
panic!("object")
};
ExtensionMessage::new(ty, body)
}
#[test]
fn registers_the_control_messages_and_interactions() {
assert_eq!(
handler(&SceneEventHub::new(8)).message_types(),
[
"SceneStreamEnable",
"SceneStreamDisable",
"SceneInteractionEvent"
]
);
}
#[tokio::test]
async fn enable_replaces_and_disable_clears() {
let mut h = handler(&SceneEventHub::new(8));
h.handle(message(ENABLE, json!({"regionIds": ["r1"]})))
.await
.unwrap();
assert_eq!(
h.subscription().filter().unwrap().region_ids(),
&RegionScope::Only(vec![Id::from("r1")])
);
h.handle(message(ENABLE, json!({}))).await.unwrap();
assert_eq!(
h.subscription().filter().unwrap().region_ids(),
&RegionScope::All
);
h.handle(message(DISABLE, json!({}))).await.unwrap();
assert!(h.subscription().filter().is_none());
h.handle(message(DISABLE, json!({}))).await.unwrap();
}
#[tokio::test]
async fn invalid_event_types_and_unrecognized_observe() {
let mut h = handler(&SceneEventHub::new(8));
h.handle(message(ENABLE, json!({"eventTypes": ["SceneAvatarEvent"]})))
.await
.unwrap();
let err = h
.handle(message(ENABLE, json!({"eventTypes": ["SceneFooBarEvent"]})))
.await
.unwrap_err();
assert_eq!(err.error_type.as_str(), "invalidArguments");
assert!(
h.subscription()
.filter()
.unwrap()
.includes("SceneAvatarEvent")
);
h.handle(message(ENABLE, json!({"observe": true, "regionIds": null})))
.await
.unwrap();
assert_eq!(
h.subscription().filter().unwrap().region_ids(),
&RegionScope::All
);
}
#[tokio::test]
async fn failed_interactions_are_silent() {
let hub = SceneEventHub::new(8);
let mut rx = hub.tx.subscribe();
let mut h = handler(&hub);
h.handle(message(INTERACTION, json!({"action": 1})))
.await
.unwrap();
h.handle(message(
INTERACTION,
json!({"accountId": "a1", "regionId": "r1", "objectId": "o1", "action": "click", "data": null}),
))
.await
.unwrap();
assert!(rx.try_recv().is_err());
}
#[cfg(feature = "test-helpers")]
mod observing {
use super::*;
use jmap_scene_types::{SceneCapability, SceneRegion};
use jmap_server::JmapReads as _;
const OWN: &str = "a1";
const OTHER: &str = "a2";
const R1: &str = "r1";
const R2: &str = "r2";
const ALICE: &str = "user:alice@example.com";
const CAROL: &str = "user:carol@example.com";
fn backend() -> Arc<MemoryBackend> {
let backend = MemoryBackend::new();
let cap: SceneCapability = serde_json::from_value(json!({
"mayCreateRegion": true,
"mayCreateObject": true,
"supportedVisualTypes": ["model/gltf-binary"],
"maxRegionsPerAccount": null,
"maxObjectsPerRegion": null,
"maxAvatarsPerRegion": null,
"maxAssetSizeBytes": null
}))
.unwrap();
backend.register_account(&Id::from(OWN), cap.clone());
backend.register_account(&Id::from(OTHER), cap);
backend.set_supports_observe(true);
Arc::new(backend)
}
fn region(backend: &MemoryBackend, account: &str, id: &str, policy: &str) {
backend.insert_object_for_test(
"SceneRegion",
&Id::from(account),
id,
json!({
"id": id,
"accountId": account,
"ownerId": ALICE,
"name": id,
"description": null,
"bounds": {"min": [-20, 0, -20], "max": [20, 8, 20]},
"environment": null,
"simulationUri": null,
"spawnPosition": [0, 0, 5],
"spawnOrientation": [0, 0, 0, 1],
"activeAvatarCount": 0,
"viewHint": "3d",
"accessPolicy": policy,
"createdAt": "2026-06-01T10:00:00Z",
"updatedAt": "2026-06-01T10:00:00Z",
"allowObservers": true,
"observerCount": 0
}),
);
}
async fn count(backend: &MemoryBackend, account: &str, region: &str) -> u64 {
let (list, _) = backend
.get_objects::<SceneRegion>(
&Id::from(ALICE),
&Id::from(account),
Some(&[Id::from(region)]),
None,
)
.await
.unwrap();
list[0].observer_count.unwrap()
}
fn carol(backend: &Arc<MemoryBackend>) -> SceneStreamHandler<MemoryBackend> {
SceneStreamHandler::new(
Arc::clone(backend),
Id::from(CAROL),
Id::from(OWN),
&SceneEventHub::new(8),
)
}
async fn observe(h: &mut SceneStreamHandler<MemoryBackend>, regions: &[&str]) {
h.handle(message(
ENABLE,
json!({"regionIds": regions, "observe": true}),
))
.await
.unwrap();
}
fn round_start(account: &str, region: &str) -> SceneEvent {
serde_json::from_value(json!({
"@type": "SceneRegionEvent",
"accountId": account,
"regionId": region,
"event": "com.example.round-start",
"data": null
}))
.unwrap()
}
async fn reported(h: &SceneStreamHandler<MemoryBackend>) -> Vec<(Id, Id)> {
h.shared.observing.lock().await.clone()
}
#[tokio::test]
async fn a_region_the_user_gains_access_to_later_counts() {
let backend = backend();
region(&backend, OWN, R1, "invite");
let mut h = carol(&backend);
observe(&mut h, &[R1]).await;
assert_eq!(count(&backend, OWN, R1).await, 0);
assert!(reported(&h).await.contains(&(Id::from(OWN), Id::from(R1))));
backend.grant_region_access(R1, CAROL);
assert_eq!(count(&backend, OWN, R1).await, 1);
backend.revoke_region_access(R1, CAROL);
assert_eq!(count(&backend, OWN, R1).await, 0);
backend.grant_region_access(R1, CAROL);
h.close().await;
assert_eq!(count(&backend, OWN, R1).await, 0);
}
#[tokio::test]
async fn a_region_outside_the_observer_accounts_counts_from_its_first_event() {
let backend = backend();
backend.restrict_observer_accounts(&[OWN]);
region(&backend, OTHER, R1, "public");
region(&backend, OTHER, R2, "public");
let mut h = carol(&backend);
observe(&mut h, &[R1]).await;
assert_eq!(count(&backend, OTHER, R1).await, 0);
h.shared.observe_event(&round_start(OTHER, R2)).await;
assert_eq!(count(&backend, OTHER, R2).await, 0);
h.shared.observe_event(&round_start(OTHER, R1)).await;
assert!(h.shared.admits(&round_start(OTHER, R1)).await);
assert_eq!(count(&backend, OTHER, R1).await, 1);
h.shared.observe_event(&round_start(OTHER, R1)).await;
let pair = (Id::from(OTHER), Id::from(R1));
assert_eq!(reported(&h).await.iter().filter(|p| **p == pair).count(), 1);
observe(&mut h, &[R1, R2]).await;
assert_eq!(count(&backend, OTHER, R1).await, 1);
observe(&mut h, &[R2]).await;
assert_eq!(count(&backend, OTHER, R1).await, 0);
assert!(!reported(&h).await.contains(&pair));
h.shared.observe_event(&round_start(OTHER, R2)).await;
assert_eq!(count(&backend, OTHER, R2).await, 1);
h.handle(message(DISABLE, json!({}))).await.unwrap();
assert_eq!(count(&backend, OTHER, R2).await, 0);
assert!(reported(&h).await.is_empty());
}
#[tokio::test]
async fn a_plain_subscription_reports_nothing() {
let backend = backend();
region(&backend, OWN, R1, "public");
let mut h = carol(&backend);
h.handle(message(ENABLE, json!({"regionIds": [R1]})))
.await
.unwrap();
h.shared.observe_event(&round_start(OWN, R1)).await;
assert!(reported(&h).await.is_empty());
assert_eq!(count(&backend, OWN, R1).await, 0);
}
#[tokio::test]
async fn several_connections_count_once() {
let backend = backend();
backend.restrict_observer_accounts(&[OWN]);
region(&backend, OWN, R1, "public");
region(&backend, OTHER, R1, "public");
let mut first = carol(&backend);
let mut second = carol(&backend);
observe(&mut first, &[R1]).await;
observe(&mut second, &[R1]).await;
for h in [&first, &second] {
h.shared.observe_event(&round_start(OTHER, R1)).await;
}
assert_eq!(count(&backend, OWN, R1).await, 1);
assert_eq!(count(&backend, OTHER, R1).await, 1);
first.close().await;
assert_eq!(count(&backend, OWN, R1).await, 1);
assert_eq!(count(&backend, OTHER, R1).await, 1);
second.close().await;
assert_eq!(count(&backend, OWN, R1).await, 0);
assert_eq!(count(&backend, OTHER, R1).await, 0);
}
}
#[test]
fn the_hub_limits_interactions_per_user_per_region() {
let hub = SceneEventHub::new(8);
let key = |region: &str| (Id::from("a1"), Id::from(region), "u".to_owned());
for _ in 0..5 {
assert!(hub.admit_interaction(key("r1")));
}
assert!(!hub.admit_interaction(key("r1")));
assert!(hub.admit_interaction(key("r2")));
let unlimited = SceneEventHub::with_interaction_window(8, None);
for _ in 0..10 {
assert!(unlimited.admit_interaction(key("r1")));
}
}
#[test]
fn default_limits_are_the_drafts() {
let l = SceneStreamLimits::default();
assert_eq!(l.object_update_window_value(), Some(Duration::from_secs(1)));
assert_eq!(
l.object_update_window(None).object_update_window_value(),
None
);
}
}