# 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:
| `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