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 — JmapAccounts::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
JmapAccounts::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 JmapAccounts::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.
A requested one is null when the task has no start / due (jmapio/jmap PR #464). A
floating task is read in the Task/get timeZone argument (default Etc/UTC). The default
compute_utc_times returns (None, None), so for a task that has a start / due both
fields are absent unless the backend overrides this method.
Task/query — filter, expandRecurrences, timeZone
The FilterCondition is jmapio/jmap #456's: inTaskLists (replacing a single taskListId),
workflowStatus, progress, text, title, and after / before read as on
CalendarEvent/query over the span start..due (after tests the due, before the start).
expandRecurrences needs a single FilterCondition with both bounds (invalidArguments)
and a window within TasksLimits::max_expanded_query_duration_seconds
(expandDurationTooLarge); both arguments reach TasksBackend::query_tasks.
Task owners (mayWriteOwn)
A task's owner is a participant with the owner role matching one of the user's
ParticipantIdentity calendarAddress values, as Calendars defines it (jmapio/jmap #461);
use jmap_tasks_types::is_task_owner / task_has_owner in the backend's write checks.
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.
Conditional Foo/set (draft-ietf-jmap-conditional-02)
register_tasks_conditional(dispatcher, backend), called after
register_tasks_handlers, attaches SetSupport to each registered /set
(TaskList, Task, TaskNotification) and skips the rest; it re-registers nothing,
and a deployment that never calls it is unchanged (docs/design/DECISIONS.md
decisions 1 and 17). Advertise urn:ietf:params:jmap:conditional only when
Dispatcher::conditional_ready() is true.
The dispatcher evaluates ifUnchangedBy through each type's /get and runs the
call inside the backend's ConditionalBackend::begin_set scope, which must roll
back onDestroyRemoveTasks cascades under atomic. MemoryBackend's store is a
jmap_server::ScopedState; its commit checks nothing extra, because
taskListHasTask is judged within one TaskList/set, draft-ietf-jmap-tasks-06 sets
no uniqueness rule for role, and there are no cross-object caps. A deployment
that hides a Task's chatId reports it from hidden_properties, with
jmap_chat_tasks_server::task_hidden_properties.
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.
Object history (draft-ietf-jmap-object-history-03)
register_tasks_handlers_with_history(dispatcher, backend), for a backend
that also implements jmap_server::ObjectHistoryBackend, calls
register_tasks_handlers and re-registers the history-aware TaskList
/get, /set and Task /get, /set, /query, /queryChanges (the
jmap-mail-server pattern). Task and TaskList have history through
their registry rows from crate-jmap's local Tasks profile
(docs/specs/jmap-tasks-local.md, docs/design/DECISIONS.md decisions 23
and 52); TaskNotification has none (decision 22), so the
dispatcher answers a history argument for it with invalidArguments.
The memory backend's with_object_history(capability, retention) keeps
the history: onDestroyRemoveTasks cascades are recorded, a restored Task
needs a current TaskList and counts toward it again, and destroyed Task
queries support what Task/query here does (inTaskLists, workflowStatus, progress, after, before, metadata; no
sort). A deployment with chat-tasks redacts chatId on history entries
as on current Tasks.
Gotchas
compute_utc_timesdefault returns(None, None)— a requestedutcStart/utcDuewill be absent fromTask/getresponses for tasks that have astart/dueunless the backend overrides this method (a task without them still getsnull).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.workflowStatusandprogress(decision 42, jmapio/jmap #465) are the backend's job too:create_objectandupdate_objectrunworkflow::apply_workflow_statusunder the lock. It mirrors an RFC 8984 progress value intoprogress, rejects a status outside the list'sworkflowStatusesand a conflictingprogress, and checks a move. This replaces -06's "If set,progressMUST be null".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)