jmap-tasks-server
What it is
JMAP Tasks (draft-ietf-jmap-tasks-06) method handlers and the TasksBackend
trait. Plugs into jmap-server's Dispatcher. Implements all 14 method names
from the Tasks extension. Storage-agnostic — consumers implement the
TasksBackend trait for their own data layer.
What it's for
Implements draft-ietf-jmap-tasks-06 — TaskList, Task, and TaskNotification
objects with Task/copy, per-user property routing, and isDraft
immutability — so consumers can wire JMAP Tasks method dispatch into their
HTTP transport. Sibling to jmap-mail-server (the canonical extension-server
template) and the other jmap-*-server crates; all of them inter-depend
through the workspace JmapHandler trait in jmap-server. The consumer
supplies a TasksBackend impl (storage), a CallerCtx type (auth identity),
and wires the dispatcher into HTTP / SSE / WebSocket transport themselves.
How to use
use Arc;
use ;
use Dispatcher;
// 1. Implement TasksBackend for your storage layer (see trait section below).
// 2. Wire all 14 Tasks methods into a Dispatcher in one call.
let mut dispatcher: = new;
register_tasks_handlers;
// 3. Dispatch JMAP requests (in your HTTP handler).
// let response = dispatcher.dispatch(request, (), session_state).await;
After register_tasks_handlers returns, the dispatcher handles every method name listed in
the Registered methods section below. The same Arc<MyBackend> can
be shared with other parts of your application.
Registered methods
All 14 method names from draft-ietf-jmap-tasks-06 are registered:
| Object | Methods |
|---|---|
TaskList |
get, changes, set |
Task |
get, changes, set, copy, query, queryChanges |
TaskNotification |
get, changes, set, query, queryChanges |
TasksBackend trait
Implement this trait to connect the handlers to your storage system. The read-side methods
(get_objects, get_state, get_changes, query_objects, query_changes) are defined on
the JmapBackend supertrait (from jmap-server). TasksBackend adds write operations and
Tasks-specific operations.
Every mutating method takes caller: &Self::CallerCtx. The workspace
"Caller identity (foundation seam)" contract — JmapBackend::principal_id
identifies the principal; the backend MUST authorise against it before
mutating — is documented per-method on the trait itself (backend.rs).
BackendSetError<E> is an enum over two variants:
BackendSetError::SetError(SetError)— a semantic RFC 8620 SetError (notFound,invalidProperties,forbidden,taskListHasTask, etc.)BackendSetError::Other(E)— a storage-layer error that becomes aserverFailresponse
How it works
Registration
register_tasks_handlers uses ClosureHandler (provided by
jmap-server) to wrap each handler function and Arc<B> into a
JmapHandler<C> and registers it with the dispatcher. The dispatcher's
CallerCtx value is forwarded into each closure as _ctx; the standard
handle_* handler bodies receive (Arc<B>, call_id, args) only. One
Arc::clone per method name; no heap allocation per request.
Task/set — isDraft immutability
Once a Task's isDraft is set to false, it cannot be reverted to true. The
Task/set handler enforces this defensively: when the patch contains isDraft: true,
it first fetches the current task via get_objects and rejects the patch with
invalidProperties: ["isDraft"] if the current value is already false. This costs
one extra get_objects call per updated task that includes isDraft: true in the patch.
Transitions from isDraft: true to isDraft: false (publishing a draft) are always allowed.
Backends that enforce this invariant atomically inside update_object (the
workspace-canonical posture — see AGENTS.md "Permission enforcement:
backend canonical") can override enforce_is_draft_atomically() to return
true. The handler then skips the pre-fetch and trusts the backend to emit
the invalidProperties SetError. The reference MemoryBackend does this.
Task/set — per-user property routing
keywords, color, freeBusyStatus, useDefaultAlerts, and alerts are per-user
properties (§4.5.1), listed in jmap_tasks_types::PER_USER_TASK_PROPERTIES and
classified by jmap_tasks_types::is_per_user_task_property (fixed by the spec, not a
backend hook). When every key in a patch is in this set, the handler routes
the update to update_task_per_user instead of update_object. This allows backends to
store per-user data separately without changing the shared updated timestamp.
Task/get — utcStart and utcDue
utcStart and utcDue are computed on-demand via compute_utc_times. They are only
included in the response when the client explicitly requests them in the properties list.
The default implementation returns (None, None), so both fields are absent unless the
backend overrides this method.
TaskList/set — onDestroyRemoveTasks cascade
When onDestroyRemoveTasks: false (the default) and the task list being destroyed contains
tasks, task_list_has_tasks is called. If it returns true, the destroy is rejected with
taskListHasTask. When onDestroyRemoveTasks: true, the handler cascades the destroy to
all tasks in the list before destroying the list itself.
CallerCtx
register_tasks_handlers registers each method as a ClosureHandler that
forwards the dispatcher's CallerCtx value into the closure as _ctx. The standard
handle_* handler bodies ignore _ctx and receive only (Arc<B>, call_id, args);
the value is still available for backends that register handlers individually via
ClosureHandler.
If you need per-request context — auth identity, tenant id, rate-limit token —
inside one of the standard handle_* functions, implement JmapHandler<C> directly
and register with dispatcher.register(method_name, Arc::new(your_handler)).
Capability URIs
Include these in your Session object's capabilities map:
// Re-exported from jmap-tasks-types:
pub const JMAP_TASKS_URI: &str = "urn:ietf:params:jmap:tasks";
// Sub-extension URIs (also from jmap-tasks-types):
// JMAP_TASKS_RECURRENCES_URI, JMAP_TASKS_ASSIGNEES_URI,
// JMAP_TASKS_ALERTS_URI, JMAP_TASKS_MULTILINGUAL_URI,
// JMAP_TASKS_CUSTOMTIMEZONES_URI
Crate family
jmap-types
├── jmap-server Dispatcher this plugs into
└── jmap-tasks-types domain types (TaskList, Task, TaskNotification, etc.)
└── jmap-tasks-server ← this crate
Path dependencies between crates use path = "../crate-jmap-*" and will remain that way
until the family is published to crates.io.
Cargo features
memory— enables the reference in-memoryMemoryBackend(gated behind#[cfg(feature = "memory")]insrc/memory.rs). Off by default; enable only for tests and demonstrations. Not production-grade. Server-assigned ids are uuid v4, as injmap-mail-server.
Gotchas
compute_utc_timesdefault returns(None, None)—utcStart/utcDuewill be absent from allTask/getresponses unless the backend overrides this method.isDraftimmutability check requires one extraget_objectscall per updated task where the patch includesisDraft: true, unless the backend overridesenforce_is_draft_atomically()to returntrueand emits theinvalidPropertiesSetError fromupdate_objectitself.- No storage backend ships with this crate. The
memoryfeature is for tests/demos only.
References
- draft-ietf-jmap-tasks-06 — JMAP Tasks (normative for all method semantics)
- RFC 8984 — JSCalendar (Task property definitions)
- RFC 8620 — JMAP Core (request format, SetError, ResultReference,
/setresponse shape)