jmap-tasks-server 0.5.0

JMAP Tasks method handlers — backend-agnostic, plugs into jmap-server Dispatcher
Documentation

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 std::sync::Arc;
use jmap_tasks_server::{TasksBackend, register_tasks_handlers};
use jmap_server::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: Dispatcher<MyCallerCtx> = Dispatcher::new();
register_tasks_handlers(&mut dispatcher, Arc::new(my_backend));

// 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.

pub trait TasksBackend: JmapBackend {
    // --- Write operations ---

    /// Create a new object (TaskList or Task).
    /// `build` receives the backend-assigned id and returns the object
    /// to store. Returns (assigned_id, created_object). The implementor MUST
    /// authorise against `caller` before the mutation; see the rustdoc
    /// on the trait itself for the workspace-canonical contract.
    fn create_object<O, F>(
        &self,
        caller: &Self::CallerCtx,
        account_id: &Id,
        create_id: &str,
        build: F,
    ) -> impl Future<Output = Result<(Id, O), BackendSetError<Self::Error>>> + Send
    where
        O: SetObject + Send + Sync,
        F: FnOnce(&Id) -> O + Send;

    /// Apply a partial update (patch) to an existing object.
    /// Returns Some(updated_object) if the backend modified server-set fields beyond
    /// the patch (RFC 8620 §5.3 echo); None if the patch was applied verbatim.
    fn update_object<O: SetObject + Send + Sync>(
        &self, caller: &Self::CallerCtx, account_id: &Id, id: &Id, patch: O::Patch,
    ) -> impl Future<Output = Result<Option<O>, BackendSetError<Self::Error>>> + Send;

    /// Destroy an object by id.
    fn destroy_object<O: SetObject + Send + Sync>(
        &self, caller: &Self::CallerCtx, account_id: &Id, id: &Id,
    ) -> impl Future<Output = Result<(), BackendSetError<Self::Error>>> + Send;

    /// Returns `true` if this backend supports JMAP object type `O` for
    /// `account_id`, as seen by `caller`.
    fn supports_type<O: JmapObject>(&self, caller: &Self::CallerCtx, account_id: &Id) -> bool;

    /// Returns true if the given task list contains at least one task.
    ///
    /// Called by TaskList/set destroy when onDestroyRemoveTasks is false.
    /// If this returns true, the destroy is rejected with taskListHasTask.
    fn task_list_has_tasks(
        &self, caller: &Self::CallerCtx, account_id: &Id, task_list_id: &Id,
    ) -> impl Future<Output = bool> + Send;

    /// Apply a patch containing only per-user Task properties (§4.5.1).
    ///
    /// When only per-user properties are patched, the shared `updated` timestamp
    /// MUST NOT change (§4.5.1). No default: delegating to update_object is
    /// correct only for a single-user backend whose update_object leaves
    /// `updated` alone. Backends serving multiple users store the patch in a
    /// user-scoped path.
    fn update_task_per_user(
        &self, caller: &Self::CallerCtx, account_id: &Id, id: &Id, patch: PatchObject,
    ) -> impl Future<Output = Result<Option<Task>, BackendSetError<Self::Error>>> + Send;

    // --- Optional overrides (have default implementations) ---

    /// Compute utcStart and utcDue for a Task by converting local-time fields
    /// and time zone into UTC (draft-tasks-06 §4, utcStart/utcDue paragraphs).
    ///
    /// Returns (utc_start, utc_due) as `UTCDate` values, or None for each
    /// if the field is absent or the time zone is unknown.
    ///
    /// The default implementation returns (None, None). Backends with full
    /// time-zone support should override this.
    fn compute_utc_times(
        &self,
        caller: &Self::CallerCtx,
        account_id: &Id,
        task: &Task,
        tz_hint: Option<&str>,
    ) -> impl Future<Output = (Option<UTCDate>, Option<UTCDate>)> + Send {
        async { (None, None) }
    }
}

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 a serverFail response

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)

  1. Create requires the account's mayCreateTaskList (§1.6.1).

  2. shareWith write requires mayAdmin, 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).

  3. Destroy requires mayDelete, which "MUST be false if the account to which this task list belongs has the isReadOnly property set to true" (§3).

  4. isSubscribed policy hook (optional). "The server MAY forbid users from subscribing to certain task lists even though they have permission to see them" (§3.4).

  5. Per-user TaskList properties. name, color, sortOrder, timeZone, defaultAlertsWithoutTime and defaultAlertsWithTime "may be set by anyone who is subscribed to the task list, and are all stored per-user" (§3.4), keyed on principal_id.

Task/set and Task/copy (§3, §4.5.1)

  1. Create, update and destroy require mayWriteAll, or mayWriteOwn when 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/copy writes through copy_object in the destination account and treats a source the caller cannot read as notFound.

  2. Per-user Task properties. keywords, color, freeBusyStatus, useDefaultAlerts and alerts "MUST be stored per-user" (§4.5.1); mayUpdatePrivate lets the user modify them "even if they would not otherwise have permission to modify that task" (§3). The handler routes such patches to update_task_per_user.

  3. mayRSVP participant updates. Without write access the caller may change only participationStatus, participationComment and expectReply on its own Participant, and may add participants only as mayInviteSelf / mayInviteOthers allow (§3).

Reads (§3)

  1. Visibility. "The user may fetch the task if they have the mayReadItems right on any task list the task is in" (§3). get_objects and query_objects leave 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:

  1. Pick a CallerCtx type for your backend — e.g. () if no auth context is needed, or a struct like AuthCtx { user_id: Id, scopes: Vec<Scope> }.
  2. Implement JmapBackend with type CallerCtx = AuthCtx; (the bound is Clone + Send + Sync + 'static).
  3. Use the matching Dispatcher<AuthCtx> and pass the constructed auth context as the second argument to Dispatcher::dispatch(request, auth, …).
  4. Inside TasksBackend method bodies, read caller: &AuthCtx to 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-memory MemoryBackend (gated behind #[cfg(feature = "memory")] in src/memory.rs). Off by default; enable only for tests and demonstrations. Not production-grade. Server-assigned ids are uuid v4, as in jmap-mail-server.

Gotchas

  • compute_utc_times default returns (None, None) — utcStart/utcDue will be absent from all Task/get responses unless the backend overrides this method.
  • isDraft immutability is the backend's job: update_object MUST reject a patch that sets isDraft: true on a Task whose stored value is not true; the handler does not check it.
  • memory::MemoryBackend is a reference implementation, not production. Gated behind feature = "memory" (off by default). State is held in HashMaps behind a std::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 in src/memory.rs for the explicit non-production caveats. Server-assigned ids are uuid v4, as in jmap-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, /set response shape)