use std::collections::BTreeMap;
use jmap_scene_types::SceneAvatarComparator;
use jmap_scene_types::{SceneAvatar, SceneRegion};
use jmap_types::{Id, JmapError, PatchObject};
use serde_json::{Map, Value, json};
use crate::SceneBackend;
use crate::helpers::resolve_refs;
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 jmap_server::{
HandlerOutput, SetError, SetErrorType, apply_patch_object, backend_set_error_value,
now_utc_string, reject_read_only_patch, reject_server_set, server_fail_from_backend,
server_fail_value_from_backend,
};
const SET_BY_SERVER_ON_CREATE: &[&str] = &["position", "orientation", "leftAt"];
const EJECT_PROPERTIES: &[&str] = &["leftAt"];
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 mut acc = SetAccumulators::default();
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, created_ids) {
acc.not_created
.insert(create_id, serde_json::Value::from(&*err));
continue;
}
match enter_region(backend, caller, &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);
}
}
}
}
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, created_ids) {
acc.not_updated
.insert(id_str, serde_json::Value::from(&*err));
continue;
}
match update_avatar(backend, caller, &account_id, &id, patch).await {
Ok(echo) => {
mutated = true;
acc.updated.insert(id_str, echo);
}
Err(e) => {
acc.not_updated.insert(id_str, e);
}
}
}
}
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"),
);
}
}
finalize_set_response::<B, SceneAvatar>(backend, caller, &account_id, old_state, mutated, acc)
.await
}
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()));
}
check(
"worldState",
optional("worldState", |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(())
}
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))?;
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"));
}
refuse_malformed(malformed(&m))?;
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."));
}
refuse_reserved_name(backend, caller, account_id, &m).await?;
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));
}
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);
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))
}
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: 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());
}
let top = |k: &str| k.split('/').next().unwrap_or(k).to_owned();
let patched: Vec<String> = patch.as_map().keys().map(|k| top(k)).collect();
let touched = |k: &str| patched.iter().any(|p| p == k);
let left_to = patch.as_map().get("leftAt").cloned();
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 eject = left_to.as_ref().is_some_and(|v| !v.is_null())
&& patched.iter().all(|p| EJECT_PROPERTIES.contains(&&**p));
if !eject
|| !backend
.may_eject_avatar(caller, account_id, &avatar)
.await
.map_err(|e| server_fail_value_from_backend(&e))?
{
return Err(forbidden("Users MUST NOT update other users' avatars."));
}
}
if let Some(e) = reject_read_only_patch::<SceneAvatar>(patch.as_map(), None) {
return Err(serde_json::Value::from(&e.with_description(
"these properties are immutable or set by the server",
)));
}
let mut echo = Map::new();
if left_to.as_ref().is_some_and(Value::is_null) {
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);
}
patch.as_map_mut().extend(set.clone());
echo = set;
} else if touched("leftAt") {
if avatar.left_at.is_some() {
return Err(invalid(&["leftAt"], "the avatar has already left"));
}
if !left_to
.as_ref()
.and_then(Value::as_str)
.is_some_and(utc_date_shaped)
{
return Err(invalid(&["leftAt"], "leftAt must be a UTCDate or null"));
}
let now = json!(now_utc_string());
patch.as_map_mut().insert("leftAt".to_owned(), now.clone());
echo.insert("leftAt".to_owned(), now);
}
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")
};
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(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)),
}
}
#[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}");
}
}
}