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. The impl must also
// satisfy the JmapBackend supertrait (account_exists, get_objects,
// get_state, get_changes, query_objects, query_changes) and declare
// `type Error` and `type CallerCtx`. See the TasksBackend trait
// section below for the full surface.
// 2. Construct a dispatcher parameterised on your CallerCtx type, then
// register all 14 Tasks methods in one call.
let mut dispatcher: = new;
register_tasks_handlers;
// 3. Dispatch JMAP requests (in your HTTP handler).
// let response = dispatcher.dispatch(request, caller_ctx, session_state).await;
Dispatcher<C> requires B::CallerCtx = C; register_tasks_handlers
enforces the match at the type level. For a single-user dev server use
Dispatcher<()> with a backend whose CallerCtx = (). For
multi-tenant production, define a typed caller context (e.g. a
principal-id newtype) and parameterise both sides on that type.
For a runnable, type-checked variant of this example, see the
crate-level documentation — the
doctest in lib.rs is verified by cargo test --doc.
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
Permission enforcement responsibilities
The handlers in this crate do no permission checking. Per the
workspace AGENTS.md "Caller identity (foundation seam)" rule, backends
are canonical for authorization: the handler computes the candidate
mutation and the backend's /set impl is the canonical point of
enforcement. Caller identity is read via
JmapBackend::principal_id on the caller: &Self::CallerCtx
parameter every backend method receives.
The reference memory::MemoryBackend does not implement any of
the checks below — it returns None from principal_id and stores
whatever the handler hands it. Production backends MUST implement each
of the following or they will silently accept JMAP requests that
draft-ietf-jmap-tasks-06 mandates the server to reject. ACL denials
are forbidden SetErrors. The rights are the TaskRights of the
TaskList (§3).
TaskList/set (draft-ietf-jmap-tasks-06 §1.6.1, §3, §3.4)
-
Create requires the account's
mayCreateTaskList(§1.6.1). -
shareWithwrite requiresmayAdmin, and "the user cannot give a right to a principal if the principal did not already have that right and the user making the change also does not have that right" (§3.4). -
Destroy requires
mayDelete, which "MUST be false if the account to which this task list belongs has the isReadOnly property set to true" (§3). -
isSubscribedpolicy hook (optional). "The server MAY forbid users from subscribing to certain task lists even though they have permission to see them" (§3.4). -
Per-user TaskList properties.
name,color,sortOrder,timeZone,defaultAlertsWithoutTimeanddefaultAlertsWithTime"may be set by anyone who is subscribed to the task list, and are all stored per-user" (§3.4), keyed onprincipal_id.
Task/set and Task/copy (§3, §4.5.1)
-
Create, update and destroy require
mayWriteAll, ormayWriteOwnwhen the caller is an owner of the task or it has no owner (§3). Moving a task between lists needs the right on both.Task/copywrites throughcopy_objectin the destination account and treats a source the caller cannot read asnotFound. -
Per-user Task properties.
keywords,color,freeBusyStatus,useDefaultAlertsandalerts"MUST be stored per-user" (§4.5.1);mayUpdatePrivatelets the user modify them "even if they would not otherwise have permission to modify that task" (§3). The handler routes such patches toupdate_task_per_user. -
mayRSVPparticipant updates. Without write access the caller may change onlyparticipationStatus,participationCommentandexpectReplyon its own Participant, and may add participants only asmayInviteSelf/mayInviteOthersallow (§3).
Reads (§3)
- Visibility. "The user may fetch the task if they have the
mayReadItems right on any task list the task is in" (§3).
get_objectsandquery_objectsleave out the others.
TaskNotification create and update are rejected with forbidden by
the handler itself (§5.4); the backend sees only destroys.
Caller-identity-less backends
The reference MemoryBackend returns None from principal_id and
is intentionally permissive (fail-open, bd:JMAP-bghk) — it is suitable
for single-user dev servers, fixtures, and the workspace's own
integration tests, but NOT for any deployment where more than one
principal can reach the JMAP dispatcher. A deployment that needs ACL
enforcement MUST override JmapBackend::principal_id and implement
each of the checks above; the workspace ships no production-grade
reference impl.
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 not true, it cannot be set to true (draft-tasks-06
§4: "This may only be set to true upon creation"). The backend enforces this in
update_object, atomically with the write, and rejects the patch with
invalidProperties: ["isDraft"]; the Task/set handler does not pre-check it (the
workspace-canonical posture — see AGENTS.md "Permission enforcement: backend
canonical"). Transitions from isDraft: true to isDraft: false (publishing a draft)
are always allowed. 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,
which the closure body then passes by reference (&ctx) into the standard
handle_* handler. The handler in turn forwards caller: &B::CallerCtx into
every TasksBackend (and inherited JmapBackend) method call.
To use this:
- Pick a
CallerCtxtype for your backend — e.g.()if no auth context is needed, or a struct likeAuthCtx { user_id: Id, scopes: Vec<Scope> }. - Implement
JmapBackendwithtype CallerCtx = AuthCtx;(the bound isClone + Send + Sync + 'static). - Use the matching
Dispatcher<AuthCtx>and pass the constructed auth context as the second argument toDispatcher::dispatch(request, auth, …). - Inside
TasksBackendmethod bodies, readcaller: &AuthCtxto apply per-user visibility rules, rate limits, etc.
Backends that don't need an auth identity use type CallerCtx = (); and a
Dispatcher<()>. Both shapes register the same way.
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 is the backend's job:update_objectMUST reject a patch that setsisDraft: trueon a Task whose stored value is nottrue; the handler does not check it.memory::MemoryBackendis a reference implementation, not production. Gated behindfeature = "memory"(off by default). State is held inHashMaps behind astd::sync::Mutex; persistence is not implemented; a number of draft-ietf-jmap-tasks-06 edge cases are simplified. Intended for integration tests, smoke tests, examples, and as source-readable study material for downstream contributors writing a real (database-backed) backend. See the module docs insrc/memory.rsfor the explicit non-production caveats. Server-assigned ids are uuid v4, as injmap-mail-server.
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)