jmap-tasks-server 0.4.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

```rust,ignore
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](https://docs.rs/jmap-tasks-server) — 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](#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.

```rust,ignore
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)

6. **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`.

7. **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`.

8. **`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)

9. **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:

```rust
// 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
  `HashMap`s 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)

[draft-ietf-jmap-tasks-06]: https://datatracker.ietf.org/doc/draft-ietf-jmap-tasks/
[RFC 8984]: https://www.rfc-editor.org/rfc/rfc8984
[RFC 8620]: https://www.rfc-editor.org/rfc/rfc8620
[`jmap-server`]: ../crate-jmap-server