jmap-tasks-server 0.1.2

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 (see trait section below).
struct MyBackend { /* db pool, etc. */ }
impl TasksBackend for MyBackend { /* ... */ }

// 2. Wire all 14 Tasks methods into a Dispatcher in one call.
let mut dispatcher: Dispatcher<()> = Dispatcher::new();
register_tasks_handlers(&mut dispatcher, Arc::new(MyBackend { /* ... */ }));

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

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

    /// Create a new object (TaskList or Task).
    /// 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: SetObject + Send + Sync>(
        &self, caller: &Self::CallerCtx, account_id: &Id, create_id: &str, obj: O,
    ) -> impl Future<Output = Result<(Id, O), BackendSetError<Self::Error>>> + 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 account supports the given JMAP object type.
    fn supports_type<O: JmapObject>(&self) -> 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;

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

    /// Returns true if `prop` is a per-user Task property (draft-tasks-06 §4.5.1).
    ///
    /// Per-user properties: "keywords", "color", "freeBusyStatus",
    /// "useDefaultAlerts", "alerts". The default implementation matches exactly
    /// these five names.
    fn is_per_user_property(prop: &str) -> bool { /* ... */ }

    /// 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). The default implementation delegates to
    /// update_object, which is correct for single-user scenarios. Backends
    /// serving multiple users SHOULD override this to route to a user-scoped
    /// patch 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 {
        self.update_object::<Task>(caller, account_id, id, patch)
    }

    /// Returns `true` if the backend enforces the `isDraft` immutability
    /// invariant atomically inside `update_object`. When `true`, the
    /// `Task/set` handler skips its pre-fetch fast-path. See the
    /// "isDraft immutability" subsection under "How it works" below.
    /// Default: `false`.
    fn enforce_is_draft_atomically(&self) -> bool { false }

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

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). When every non-null 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-memory MemoryBackend (gated behind #[cfg(feature = "memory")] in src/memory.rs). Off by default; enable only for tests and demonstrations. Not production-grade — see the cargo-cult warning on MemoryBackend::demo_next_id.
  • realistic-demo-ids — when combined with memory, switches demo_next_id from the deterministic <type><n:016x> form to a process-start-nanos + atomic-counter form matching the canonical jmap-mail-server shape at email.rs:1748. Still not production.

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 check requires one extra get_objects call per updated task where the patch includes isDraft: true, unless the backend overrides enforce_is_draft_atomically() to return true and emits the invalidProperties SetError from update_object itself.
  • No storage backend ships with this crate. The memory feature 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, /set response shape)