use std::collections::BTreeMap;
use jmap_scene_types::SceneAvatarComparator;
use jmap_scene_types::{SceneAvatar, SceneRegion};
use jmap_types::{Id, JmapError, PatchObject, SetObject};
use serde_json::{Map, Value, json};
use crate::helpers::{
SetAccumulators, check_region_filter, default_sort, enforce_max_objects_in_set,
extract_account_id, fetch_one, finalize_set_response, finite3, forbidden, handle_get_visible,
invalid, normalized_quaternion, not_found, orientation_ok, reject_unsupported_sort,
};
use crate::helpers::{avatar_view, resolve_refs};
use crate::{AvatarView, SceneBackend};
use jmap_server::{
HandlerOutput, SetError, SetErrorType, apply_patch_object, backend_set_error_value,
now_utc_string, reject_server_set, server_fail_from_backend, server_fail_value_from_backend,
strip_read_only_patch,
};
const SET_BY_SERVER_ON_CREATE: &[&str] = &["position", "orientation", "leftAt"];
const EJECT_PROPERTIES: &[&str] = &["leftAt"];
const REGION_STATE: &str = "regionState";
pub async fn handle_scene_avatar_get<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
args: Value,
) -> Result<HandlerOutput, JmapError> {
handle_get_visible::<SceneAvatar, B>(backend, caller, args).await
}
pub async fn handle_scene_avatar_changes<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
args: Value,
) -> Result<HandlerOutput, JmapError> {
jmap_server::handle_changes::<SceneAvatar, B>(backend, caller, args, &[]).await
}
pub async fn handle_scene_avatar_query<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
args: Value,
) -> Result<HandlerOutput, JmapError> {
jmap_server::handle_query::<SceneAvatar, B>(backend, caller, prepare_query(args)?).await
}
pub async fn handle_scene_avatar_query_changes<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
args: Value,
) -> Result<HandlerOutput, JmapError> {
jmap_server::handle_query_changes::<SceneAvatar, B>(backend, caller, prepare_query(args)?).await
}
fn prepare_query(mut args: Value) -> Result<Value, JmapError> {
if let Value::Object(map) = &mut args {
default_sort(
map,
json!([{ "property": "joinedAt", "isAscending": true }]),
);
}
reject_unsupported_sort::<SceneAvatarComparator>(args.get("sort"))?;
match args.get("filter") {
None | Some(Value::Null) => {
Err(JmapError::invalid_arguments("filter.regionId is required"))
}
Some(filter) => check_region_filter(filter, &|_| Ok(())),
}?;
Ok(args)
}
const AVATAR_ID_PROPERTIES: &[&str] = &["regionId"];
pub async fn handle_scene_avatar_set<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
created_ids: &BTreeMap<Id, Id>,
args: Value,
) -> Result<HandlerOutput, JmapError> {
let (account_id, mut args) = extract_account_id(args)?;
if !backend
.account_exists(caller, &account_id)
.await
.map_err(|e| server_fail_from_backend(&e))?
{
return Err(JmapError::account_not_found());
}
enforce_max_objects_in_set(&args, backend.max_objects_in_set(caller, &account_id))?;
let old_state = backend
.get_state::<SceneAvatar>(caller, &account_id)
.await
.map_err(|e| server_fail_from_backend(&e))?;
if let Some(if_in_state) = args.get("ifInState").and_then(Value::as_str)
&& if_in_state != old_state.as_ref()
{
return Err(JmapError::state_mismatch());
}
let ctx = SetCtx {
backend,
caller,
account_id: &account_id,
created_ids,
};
let mut acc = SetAccumulators::default();
let mut mutated = set_create(&ctx, &mut args, &mut acc).await?;
jmap_server::resolve_set_id_refs(&mut args, created_ids, &acc.created);
mutated |= set_update(&ctx, &mut args, &mut acc).await?;
set_destroy(&mut args, &mut acc)?;
finalize_set_response::<B, SceneAvatar>(backend, caller, &account_id, old_state, mutated, acc)
.await
}
struct SetCtx<'a, B: SceneBackend> {
backend: &'a B,
caller: &'a B::CallerCtx,
account_id: &'a Id,
created_ids: &'a BTreeMap<Id, Id>,
}
async fn set_create<B: SceneBackend>(
ctx: &SetCtx<'_, B>,
args: &mut Map<String, Value>,
acc: &mut SetAccumulators,
) -> Result<bool, JmapError> {
let mut mutated = false;
if let Some(Value::Object(create_map)) = args.remove("create") {
for (create_id, mut obj) in create_map {
if let Err(err) = resolve_refs(&mut obj, AVATAR_ID_PROPERTIES, ctx.created_ids) {
acc.not_created
.insert(create_id, serde_json::Value::from(&*err));
continue;
}
match enter_region(ctx.backend, ctx.caller, ctx.account_id, &create_id, obj).await {
Ok(created) => {
mutated = true;
acc.created.insert(create_id, created);
}
Err(e) => {
acc.not_created.insert(create_id, e);
}
}
}
}
Ok(mutated)
}
async fn set_update<B: SceneBackend>(
ctx: &SetCtx<'_, B>,
args: &mut Map<String, Value>,
acc: &mut SetAccumulators,
) -> Result<bool, JmapError> {
let mut mutated = false;
if let Some(Value::Object(update_map)) = args.remove("update") {
for (id_str, mut patch) in update_map {
let id = match jmap_server::parse_wire_id(&id_str, "id") {
Ok(id) => id,
Err(err) => {
acc.not_updated
.insert(id_str, serde_json::Value::from(&*err));
continue;
}
};
if let Err(err) = resolve_refs(&mut patch, AVATAR_ID_PROPERTIES, ctx.created_ids) {
acc.not_updated
.insert(id_str, serde_json::Value::from(&*err));
continue;
}
match update_avatar(ctx.backend, ctx.caller, ctx.account_id, &id, patch).await {
Ok(echo) => {
mutated = true;
acc.updated.insert(id_str, echo);
}
Err(e) => {
acc.not_updated.insert(id_str, e);
}
}
}
}
Ok(mutated)
}
fn set_destroy(args: &mut Map<String, Value>, acc: &mut SetAccumulators) -> Result<(), JmapError> {
if let Some(Value::Array(destroy_arr)) = args.remove("destroy") {
let ids: Vec<&str> = destroy_arr
.iter()
.map(|v| v.as_str().ok_or(v))
.collect::<Result<_, _>>()
.map_err(|bad| {
JmapError::invalid_arguments(format!(
"destroy: every element must be a string Id; got {}",
jmap_server::json_type_name(bad)
))
})?;
for id_str in ids {
acc.not_destroyed.insert(
id_str.to_owned(),
forbidden("SceneAvatar records are not destroyed; set leftAt to leave"),
);
}
}
Ok(())
}
fn utc_date_shaped(s: &str) -> bool {
let b = s.as_bytes();
let digits =
|r: std::ops::Range<usize>| b.get(r).is_some_and(|d| d.iter().all(u8::is_ascii_digit));
let at = |i: usize, c: u8| b.get(i) == Some(&c);
let fraction = match b.get(19..b.len().saturating_sub(1)) {
Some([]) => true,
Some([b'.', rest @ ..]) => !rest.is_empty() && rest.iter().all(u8::is_ascii_digit),
_ => false,
};
digits(0..4)
&& at(4, b'-')
&& digits(5..7)
&& at(7, b'-')
&& digits(8..10)
&& at(10, b'T')
&& digits(11..13)
&& at(13, b':')
&& digits(14..16)
&& at(16, b':')
&& digits(17..19)
&& fraction
&& s.ends_with('Z')
}
fn malformed(m: &Map<String, Value>) -> Vec<&'static str> {
let mut bad = Vec::new();
let mut check = |key: &'static str, ok: bool| {
if !ok {
bad.push(key);
}
};
let optional = |key: &str, ok: fn(&Value) -> bool| m.get(key).is_none_or(ok);
check("regionId", m.get("regionId").is_some_and(Value::is_string));
check("position", optional("position", finite3));
check("orientation", optional("orientation", orientation_ok));
check("displayName", optional("displayName", Value::is_string));
for key in ["visualRef", "visualType"] {
check(key, optional(key, |v| v.is_null() || v.is_string()));
}
for key in ["worldState", "regionState"] {
check(key, optional(key, |v| v.is_null() || v.is_object()));
}
let present = |key: &str| m.get(key).is_some_and(|v| !v.is_null());
if present("visualRef") != present("visualType") {
bad.extend(["visualRef", "visualType"]);
}
bad
}
fn refuse_malformed(mut bad: Vec<&'static str>) -> Result<(), Value> {
if bad.is_empty() {
return Ok(());
}
bad.sort_unstable();
bad.dedup();
Err(invalid(
&bad,
"regionId is required, position finite, orientation a unit quaternion, visualRef and \
visualType together",
))
}
async fn refuse_reserved_name<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
account_id: &Id,
m: &Map<String, Value>,
) -> Result<(), Value> {
let Some(name) = m.get("displayName").and_then(Value::as_str) else {
return Ok(());
};
let reserved = backend
.reserved_display_names(caller, account_id)
.await
.map_err(|e| server_fail_value_from_backend(&e))?;
if reserved.iter().any(|r| r == name) {
return Err(forbidden("This displayName is reserved."));
}
Ok(())
}
async fn region_state_supported<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
account_id: &Id,
) -> Result<bool, Value> {
Ok(backend
.scene_capability(caller, account_id)
.await
.map_err(|e| server_fail_value_from_backend(&e))?
.supports_avatar_region_state)
}
async fn may_manage_region_state<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
account_id: &Id,
region: &SceneRegion,
) -> Result<bool, Value> {
backend
.may_update_region(caller, account_id, region)
.await
.map_err(|e| server_fail_value_from_backend(&e))
}
fn present_in<'a>(keys: impl Iterator<Item = &'a str>, set: &[&str]) -> Vec<&'a str> {
let mut found: Vec<&str> = keys.filter(|k| set.contains(k)).collect();
found.sort_unstable();
found.dedup();
found
}
async fn enter_region<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
account_id: &Id,
create_id: &str,
obj: Value,
) -> Result<Value, Value> {
let Value::Object(mut m) = obj else {
return Err(invalid(&[], "a SceneAvatar create must be a JSON object"));
};
let user_id = backend
.caller_user_id(caller, account_id)
.await
.map_err(|e| server_fail_value_from_backend(&e))?;
reject_create_server_set(&mut m, &user_id)?;
refuse_malformed(malformed(&m))?;
let region_state = region_state_supported(backend, caller, account_id).await?;
if m.contains_key("regionState") && !region_state {
return Err(invalid(
&["regionState"],
"regionState needs supportsAvatarRegionState",
));
}
let region = region_to_enter(backend, caller, account_id, &m).await?;
refuse_reserved_name(backend, caller, account_id, &m).await?;
if region_state {
m.entry("regionState").or_insert(Value::Null);
}
if !m.contains_key("displayName") {
let name = backend
.avatar_display_name(caller, account_id, &user_id)
.await
.map_err(|e| server_fail_value_from_backend(&e))?;
m.insert("displayName".to_owned(), json!(name));
}
fill_entry_fields(&mut m, ®ion, &user_id);
let mut avatar: SceneAvatar = serde_json::from_value(Value::Object(m))
.map_err(|e| invalid(&[], &format!("invalid SceneAvatar: {e}")))?;
let (_, stored) = backend
.create_object(caller, account_id, create_id, move |id: &Id| {
avatar.id = id.clone();
avatar
})
.await
.map_err(backend_set_error_value)?;
jmap_server::serialize_value(stored)
.map_err(|e| jmap_server::server_fail_value_from_backend(&e))
}
fn reject_create_server_set(m: &mut Map<String, Value>, user_id: &str) -> Result<(), Value> {
if m.get("userId").is_some_and(|u| u.as_str() != Some(user_id)) {
return Err(forbidden("Users MUST only create their own avatar."));
}
m.remove("userId");
if let Some(e) = reject_server_set::<SceneAvatar>(m) {
return Err(serde_json::Value::from(
&e.with_description("these properties are set by the server"),
));
}
let fixed = present_in(m.keys().map(String::as_str), SET_BY_SERVER_ON_CREATE);
if !fixed.is_empty() {
return Err(invalid(&fixed, "these properties are set by the server"));
}
Ok(())
}
async fn region_to_enter<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
account_id: &Id,
m: &Map<String, Value>,
) -> Result<SceneRegion, Value> {
let region_id = Id::new_validated(m["regionId"].as_str().unwrap_or_default())
.map_err(|e| invalid(&["regionId"], &e.to_string()))?;
let inaccessible = || invalid(&["regionId"], "regionId is not an accessible SceneRegion");
let region: SceneRegion = fetch_one(backend, caller, account_id, ®ion_id)
.await?
.ok_or_else(inaccessible)?;
if !backend
.may_access_region(caller, account_id, ®ion_id)
.await
.map_err(|e| server_fail_value_from_backend(&e))?
{
return Err(inaccessible());
}
if !backend
.may_enter_region(caller, account_id, ®ion)
.await
.map_err(|e| server_fail_value_from_backend(&e))?
{
return Err(forbidden("The caller may not enter this region."));
}
if m.get("regionState").is_some_and(|v| !v.is_null())
&& !may_manage_region_state(backend, caller, account_id, ®ion).await?
{
return Err(forbidden(
"regionState is kept by the region; only its owner or an admin may set it",
));
}
Ok(region)
}
fn fill_entry_fields(m: &mut Map<String, Value>, region: &SceneRegion, user_id: &str) {
m.insert("position".to_owned(), json!(region.spawn_position));
m.insert("orientation".to_owned(), json!(region.spawn_orientation));
if let Some(q) = normalized_quaternion(m, "orientation") {
m.insert("orientation".to_owned(), q);
}
for key in ["visualRef", "visualType", "worldState"] {
m.entry(key).or_insert(Value::Null);
}
m.insert("id".to_owned(), json!(jmap_server::CREATE_ID_PLACEHOLDER));
m.insert("userId".to_owned(), json!(user_id));
m.insert("joinedAt".to_owned(), json!(now_utc_string()));
m.insert("leftAt".to_owned(), Value::Null);
}
async fn update_avatar<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
account_id: &Id,
id: &Id,
patch: Value,
) -> Result<Value, Value> {
let mut patch: PatchObject = serde_json::from_value(patch).map_err(|e| {
serde_json::Value::from(
&SetError::new(SetErrorType::InvalidPatch).with_description(e.to_string()),
)
})?;
let avatar = visible_avatar(backend, caller, account_id, id).await?;
let Value::Object(mut result) = jmap_server::serialize_value(&avatar)
.map_err(|e| jmap_server::server_fail_value_from_backend(&e))?
else {
unreachable!("a SceneAvatar serializes as a JSON object")
};
let patched = patched_properties(&patch, &result);
let touched = |k: &str| patched.iter().any(|p| p == k);
let left_to = patch.as_map().get("leftAt").cloned();
check_avatar_update_permission(
backend,
caller,
account_id,
&avatar,
&patched,
left_to.as_ref(),
)
.await?;
strip_read_only_patch::<SceneAvatar>(patch.as_map_mut(), Some(&result)).map_err(|e| {
serde_json::Value::from(
&(*e).with_description("these properties are immutable or set by the server"),
)
})?;
if patch.as_map().is_empty() {
return Ok(Value::Null);
}
let mut echo = Map::new();
if left_to.as_ref().is_some_and(Value::is_null) {
let set = reentry_fields(backend, caller, account_id, &avatar, &patched).await?;
patch.as_map_mut().extend(set.clone());
echo = set;
} else if touched("leftAt") {
let now = leave_stamp(&avatar, left_to.as_ref())?;
patch.as_map_mut().insert("leftAt".to_owned(), now.clone());
echo.insert("leftAt".to_owned(), now);
}
apply_patch_object(&mut result, patch.as_map()).map_err(|e| {
serde_json::Value::from(
&SetError::new(SetErrorType::InvalidPatch).with_description(e.to_string()),
)
})?;
refuse_malformed(malformed(&result))?;
if touched("displayName") {
refuse_reserved_name(backend, caller, account_id, &result).await?;
}
if touched("orientation")
&& let Some(q) = normalized_quaternion(&result, "orientation")
{
let map = patch.as_map_mut();
map.retain(|k, _| top_level(k) != "orientation");
map.insert("orientation".to_owned(), q.clone());
echo.insert("orientation".to_owned(), q);
}
match backend
.update_object::<SceneAvatar>(caller, account_id, id, patch)
.await
.map_err(backend_set_error_value)?
{
Some(avatar) => Ok(jmap_server::serialize_value(avatar)
.map_err(|e| jmap_server::server_fail_value_from_backend(&e))?),
None if echo.is_empty() => Ok(Value::Null),
None => Ok(Value::Object(echo)),
}
}
fn top_level(k: &str) -> String {
k.split('/').next().unwrap_or(k).to_owned()
}
async fn visible_avatar<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
account_id: &Id,
id: &Id,
) -> Result<SceneAvatar, Value> {
let avatar: SceneAvatar = fetch_one(backend, caller, account_id, id)
.await?
.ok_or_else(not_found)?;
if !backend
.may_access_region(caller, account_id, &avatar.region_id)
.await
.map_err(|e| server_fail_value_from_backend(&e))?
{
return Err(not_found());
}
if avatar_view(backend, caller, account_id, &avatar)
.await
.map_err(|e| server_fail_value_from_backend(&e))?
== AvatarView::Hidden
{
return Err(not_found());
}
Ok(avatar)
}
fn patched_properties(patch: &PatchObject, stored: &Map<String, Value>) -> Vec<String> {
let read_only =
|k: &str| SceneAvatar::SERVER_SET.contains(&k) || SceneAvatar::IMMUTABLE.contains(&k);
patch
.as_map()
.iter()
.filter(|(k, v)| !(read_only(k) && stored.get(*k).unwrap_or(&Value::Null) == *v))
.map(|(k, _)| top_level(k))
.collect()
}
async fn manages_region_state<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
account_id: &Id,
avatar: &SceneAvatar,
) -> Result<bool, Value> {
let region: SceneRegion = fetch_one(backend, caller, account_id, &avatar.region_id)
.await?
.ok_or_else(not_found)?;
may_manage_region_state(backend, caller, account_id, ®ion).await
}
async fn check_avatar_update_permission<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
account_id: &Id,
avatar: &SceneAvatar,
patched: &[String],
left_to: Option<&Value>,
) -> Result<(), Value> {
let touched = |k: &str| patched.iter().any(|p| p == k);
let touches_region_state = touched(REGION_STATE);
if touches_region_state && !region_state_supported(backend, caller, account_id).await? {
return Err(invalid(
&[REGION_STATE],
"regionState needs supportsAvatarRegionState",
));
}
let user_id = backend
.caller_user_id(caller, account_id)
.await
.map_err(|e| server_fail_value_from_backend(&e))?;
if avatar.user_id != user_id {
let touches_left = touched("leftAt");
let shape = (touches_left || touches_region_state)
&& patched
.iter()
.all(|p| EJECT_PROPERTIES.contains(&&**p) || p == REGION_STATE)
&& (!touches_left || left_to.is_some_and(|v| !v.is_null()));
let allowed = shape
&& (!touches_left
|| backend
.may_eject_avatar(caller, account_id, avatar)
.await
.map_err(|e| server_fail_value_from_backend(&e))?)
&& (!touches_region_state
|| manages_region_state(backend, caller, account_id, avatar).await?);
if !allowed {
return Err(forbidden("Users MUST NOT update other users' avatars."));
}
} else if touches_region_state
&& !manages_region_state(backend, caller, account_id, avatar).await?
{
return Err(forbidden(
"regionState is kept by the region; only its owner or an admin may change it",
));
}
Ok(())
}
async fn reentry_fields<B: SceneBackend>(
backend: &B,
caller: &B::CallerCtx,
account_id: &Id,
avatar: &SceneAvatar,
patched: &[String],
) -> Result<Map<String, Value>, Value> {
if avatar.left_at.is_none() {
return Err(invalid(
&["leftAt"],
"the avatar is present; only a departed avatar re-enters",
));
}
let spawn = present_in(
patched.iter().map(String::as_str),
&["position", "orientation"],
);
if !spawn.is_empty() {
return Err(invalid(
&spawn,
"re-entry sets position and orientation from the region's spawn point",
));
}
let region: SceneRegion = fetch_one(backend, caller, account_id, &avatar.region_id)
.await?
.ok_or_else(not_found)?;
if !backend
.may_enter_region(caller, account_id, ®ion)
.await
.map_err(|e| server_fail_value_from_backend(&e))?
{
return Err(forbidden("The caller may not enter this region."));
}
let mut set = Map::new();
set.insert("joinedAt".to_owned(), json!(now_utc_string()));
set.insert("position".to_owned(), json!(region.spawn_position));
set.insert("orientation".to_owned(), json!(region.spawn_orientation));
if let Some(q) = normalized_quaternion(&set, "orientation") {
set.insert("orientation".to_owned(), q);
}
Ok(set)
}
fn leave_stamp(avatar: &SceneAvatar, left_to: Option<&Value>) -> Result<Value, Value> {
if avatar.left_at.is_some() {
return Err(invalid(&["leftAt"], "the avatar has already left"));
}
if !left_to.and_then(Value::as_str).is_some_and(utc_date_shaped) {
return Err(invalid(&["leftAt"], "leftAt must be a UTCDate or null"));
}
Ok(json!(now_utc_string()))
}
#[cfg(test)]
mod tests {
use super::utc_date_shaped;
#[test]
fn utc_date_shape() {
assert!(utc_date_shaped("2026-06-05T15:45:00Z"));
assert!(utc_date_shaped("2026-06-05T15:45:00.123Z"));
for bad in [
"",
"2026-06-05T15:45:00",
"2026-06-05T15:45:00+00:00",
"2026-06-05 15:45:00Z",
"2026-06-05T15:45:00.Z",
"yesterday",
] {
assert!(!utc_date_shaped(bad), "{bad}");
}
}
}