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

```rust
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](#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
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:

```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 — 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)

[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