jmap-tasks-server 0.3.0

JMAP Tasks method handlers — backend-agnostic, plugs into jmap-server Dispatcher
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
//! TasksBackend trait and supporting types for JMAP Tasks method handlers.
//!
//! Consumers implement [`TasksBackend`] for their storage system. The method
//! handlers in sibling modules call into the backend through this trait.
//!
//! The read-side operations (`get_objects`, `get_state`, `get_changes`,
//! `query_objects`, `query_changes`) are defined on the [`jmap_server::JmapBackend`]
//! supertrait. Only write operations and type-specific operations are here.

// ── Re-exports from jmap-server (the foundation crate) ────────────────────
//
// Every TasksBackend implementor needs these names. They are re-exported
// here so a consumer can write `use jmap_tasks_server::backend::*;` and get
// the full vocabulary in one import.

/// JMAP wire-format SetError; emitted by [`TasksBackend`] write methods
/// wrapped as [`BackendSetError::SetError`] and serialised into
/// `notCreated` / `notUpdated` / `notDestroyed` maps by the `/set` handlers
/// (RFC 8620 §5.3).
pub use jmap_server::SetError;

/// The standard wire-format SetError type tag (RFC 8620 §5.3 +
/// extension-specific types like `taskListHasTask` from
/// draft-ietf-jmap-tasks-06 §3.4).
pub use jmap_server::SetErrorType;

/// Backend-side wrapper around [`SetError`]; the trait's write methods
/// return `Result<…, BackendSetError<Self::Error>>`. The handler unwraps
/// `BackendSetError::SetError` into the per-target SetError map and
/// folds `BackendSetError::Other(e)` into a top-level `serverFail`.
pub use jmap_server::BackendSetError;

/// Backend-side error wrapper for `/changes` paths (RFC 8620 §5.2);
/// distinguished from [`BackendSetError`] because the `cannotCalculateChanges`
/// recovery is a `/changes`-specific contract.
pub use jmap_server::{BackendChangesError, BackendQueryError};

/// Result of [`JmapBackend::get_changes`] (RFC 8620 §5.2). Carries
/// `created`, `updated`, `destroyed`, the `hasMoreChanges` flag, and the
/// new state token.
pub use jmap_server::ChangesResult;

/// Result of [`JmapBackend::query_objects`] (RFC 8620 §5.5). Carries the
/// id list, anchor position, total count (when requested), and state.
pub use jmap_server::QueryResult;

/// Result of [`JmapBackend::query_changes`] (RFC 8620 §5.6). Carries
/// `added`, `removed`, optional total count, and the new state.
pub use jmap_server::QueryChangesResult;

/// One entry in the `added` array of a [`QueryChangesResult`]: a typed
/// `(index, id)` pair.
pub use jmap_server::AddedItem;

/// Foundation `JmapBackend` supertrait. [`TasksBackend`] extends this with
/// Task-specific methods; consumers must implement both.
pub use jmap_server::JmapBackend;

/// Marker trait identifying a JMAP object type (RFC 8620 §5). Used as a
/// bound on `get_state` / `get_changes` / `query_objects`.
pub use jmap_server::JmapObject;

/// Marker trait identifying a "gettable" JMAP object type. Adds the
/// property-projection contract on top of [`JmapObject`].
pub use jmap_server::GetObject;

/// Marker trait identifying a "settable" JMAP object type. Adds the
/// `Patch` associated type on top of [`JmapObject`].
pub use jmap_server::SetObject;

/// Marker trait identifying a "queryable" JMAP object type. Adds the
/// `Filter` and `Comparator` associated types on top of [`JmapObject`].
pub use jmap_server::QueryObject;

// ── Property selector enums from jmap-tasks-types ────────────────────────
//
// These let backends interpret the `properties` argument on /get without
// reparsing string literals.

/// `TaskList` property selector enum (draft-ietf-jmap-tasks-06 §3); used
/// in [`JmapBackend::get_objects::<TaskList>`] property projection.
pub use jmap_tasks_types::backend::TaskListProperty;

/// `Task` property selector enum (draft-ietf-jmap-tasks-06 §4); used in
/// [`JmapBackend::get_objects::<Task>`] property projection.
pub use jmap_tasks_types::backend::TaskProperty;

/// `TaskNotification` property selector enum
/// (draft-ietf-jmap-tasks-06 §5).
pub use jmap_tasks_types::backend::TaskNotificationProperty;

// ── Wire types from jmap-types ───────────────────────────────────────────

/// JMAP wire-format `PatchObject` (RFC 8620 §5.3) — a JSON-Pointer-keyed
/// map of property paths to new values, used as the patch payload for
/// `update_object` and `update_task_per_user`.
pub use jmap_types::PatchObject;

// ---------------------------------------------------------------------------
// TasksBackend trait
// ---------------------------------------------------------------------------

/// Storage backend for JMAP Tasks method handlers (draft-ietf-jmap-tasks-06).
///
/// Implementors provide the actual data access; the method handler modules
/// in this crate translate between JMAP wire protocol and backend calls.
///
/// Read-side operations (`get_objects`, `get_state`, `get_changes`,
/// `query_objects`, `query_changes`) are defined on the [`JmapBackend`]
/// supertrait. Only write operations and type introspection are here.
///
/// This trait is not object-safe by design (generic methods). Use
/// `Arc<impl TasksBackend>` when sharing across tasks.
pub trait TasksBackend: JmapBackend {
    /// Create a new object (TaskList or Task).
    ///
    /// # Authorisation contract
    ///
    /// This method is the canonical enforcement point for caller authorisation
    /// per workspace AGENTS.md "Caller identity (foundation seam)" and per-crate
    /// AGENTS.md "Permission enforcement: backend canonical". Implementors MUST
    /// verify that the principal identified by
    /// [`JmapBackend::principal_id(caller)`](JmapBackend::principal_id) has write
    /// access to the target account / TaskList / Task before performing the
    /// mutation, and MUST return
    /// [`BackendSetError::SetError`] carrying
    /// [`SetErrorType::Forbidden`] otherwise. Handlers in this crate do NO
    /// permission checking; any handler-layer pre-check is defense-in-depth
    /// only and the backend MUST re-verify atomically with the mutation. A
    /// backend that trusts the handler is a bug; a backend that returns `None`
    /// from `principal_id` is signalling "single-user posture" and CANNOT
    /// correctly implement TaskList ACLs or per-user scoping.
    ///
    /// # Errors
    ///
    /// Reject a create that RFC 8620 §5.3 defines an error for with
    /// [`BackendSetError::SetError`] carrying the matching
    /// [`SetErrorType`]; the handler places it verbatim in `notCreated`.
    /// For create these are `forbidden`, `overQuota`, `tooLarge`,
    /// `rateLimit` and `invalidProperties`. An `invalidProperties` error
    /// SHOULD name in `properties` "*all* the properties that were
    /// invalid", for example `taskListId` when a Task names a TaskList that
    /// does not exist.
    ///
    /// Return [`BackendSetError::Other`] only for unexpected storage
    /// failures. The handler reports it as `serverFail` without the
    /// error's `Display` text, which tells the client to retry; a
    /// deterministic rejection returned as `Other` invites retries that
    /// cannot succeed.
    ///
    /// The `/set` handlers in this crate reject an unknown `account_id`
    /// with the method-level `accountNotFound` error before calling the
    /// backend.
    ///
    /// # State and change log
    ///
    /// RFC 8620 §5.1 defines the state string over "*all* the data of
    /// this type in the account": "If the data changes, this string MUST
    /// change." Every successful `create_object`,
    /// [`update_object`](Self::update_object) and
    /// [`destroy_object`](Self::destroy_object) MUST advance
    /// [`get_state`](JmapBackend::get_state) for `O` in `account_id` and
    /// record the id as created, updated or destroyed so
    /// [`get_changes`](JmapBackend::get_changes) reports it.
    ///
    /// The write, the state advance and the change record MUST be atomic
    /// with respect to other callers: the reference `MemoryBackend` does
    /// all three under one mutex acquisition, and a database backend uses
    /// one transaction. A call that returns `Err` MUST leave the stored
    /// data, the state and the change log unchanged.
    fn create_object<O: SetObject + Send + Sync>(
        &self,
        caller: &Self::CallerCtx,
        account_id: &jmap_types::Id,
        create_id: &str,
        obj: O,
    ) -> impl std::future::Future<Output = Result<(jmap_types::Id, O), BackendSetError<Self::Error>>>
           + Send;

    /// Apply a partial update (patch) to an existing object.
    ///
    /// Returns `Some(updated_object)` if the backend modified any properties
    /// beyond what the client requested (RFC 8620 §5.3 server-set field echo),
    /// or `None` if the patch was applied verbatim.
    ///
    /// # Authorisation contract
    ///
    /// Implementors MUST verify caller write-access to the target object before
    /// applying the patch and MUST return [`BackendSetError::SetError`] with
    /// [`SetErrorType::Forbidden`] otherwise. See [`Self::create_object`] for
    /// the workspace-canonical rationale; the same rule applies here.
    ///
    /// # Patch format
    ///
    /// `patch` is an RFC 8620 §5.3 PatchObject, not an RFC 7396 JSON
    /// Merge Patch: "The keys are a path in JSON Pointer format
    /// \[RFC6901\], with an implicit leading "/"". So `{"a/b": null}`
    /// removes member `b` of property `a`; it does not touch a top-level
    /// property literally named `a/b`. A `null` value sets the
    /// property's default if it has one, otherwise removes it. A pointer
    /// into an array, a pointer whose parent does not exist, or two keys
    /// where one pointer is a prefix of the other "MUST be rejected with
    /// an "invalidPatch" error".
    ///
    /// Implementors SHOULD apply `patch` with
    /// [`jmap_server::apply_patch_object`], which enforces these rules
    /// all-or-nothing, and map any [`jmap_server::PatchPathError`] to
    /// [`jmap_server::SetErrorType::InvalidPatch`], as the reference
    /// `MemoryBackend` does.
    ///
    /// # Errors
    ///
    /// As for [`create_object`](Self::create_object), plus these RFC 8620
    /// §5.3 rules for update:
    ///
    /// - "If an id given cannot be found, the update or destroy MUST be
    ///   rejected with a "notFound" set error."
    /// - A patch that breaks the rules under "Patch format" is
    ///   `invalidPatch`.
    /// - A patched record that is invalid is `invalidProperties`. That
    ///   includes changing a server-set property, though "it is not an
    ///   error to include a server-set property in an update as long as
    ///   the value is identical to the current value on the server."
    ///
    /// # Atomicity
    ///
    /// RFC 8620 §5.3: the server "MUST NOT only commit part of an update
    /// to a single record". Apply the whole patch and validate the result
    /// before writing it, so that on any error the stored record is
    /// unchanged. State and change log follow
    /// [`create_object`](Self::create_object) ("State and change log"); an
    /// `Ok(None)` return still advances the state.
    fn update_object<O: SetObject + Send + Sync>(
        &self,
        caller: &Self::CallerCtx,
        account_id: &jmap_types::Id,
        id: &jmap_types::Id,
        patch: O::Patch,
    ) -> impl std::future::Future<Output = Result<Option<O>, BackendSetError<Self::Error>>> + Send;

    /// Destroy an object by id.
    ///
    /// # Authorisation contract
    ///
    /// Implementors MUST verify caller write-access to the target object before
    /// destroying it and MUST return [`BackendSetError::SetError`] with
    /// [`SetErrorType::Forbidden`] otherwise. See [`Self::create_object`] for
    /// the workspace-canonical rationale; the same rule applies here.
    ///
    /// # Errors
    ///
    /// As for [`create_object`](Self::create_object), plus these RFC 8620
    /// §5.3 rules for destroy: an unknown id, including one already
    /// destroyed, is `notFound`, and a destroy that "would violate an ACL
    /// or other permissions policy" is `forbidden`.
    ///
    /// # Cascades
    ///
    /// The handlers perform the cross-record effects the client chooses,
    /// through explicit backend calls, and the backend does not repeat
    /// them. `TaskList/set` `onDestroyRemoveTasks` does not yet destroy
    /// the list's Tasks (bd:JMAP-ji1v).
    ///
    /// If the backend itself changes another record because of the
    /// destroy, it MUST advance that record type's state and record the
    /// change in the same atomic step, so `/changes` on that type sees it.
    /// State and change log for `O` follow
    /// [`create_object`](Self::create_object) ("State and change log").
    fn destroy_object<O: SetObject + Send + Sync>(
        &self,
        caller: &Self::CallerCtx,
        account_id: &jmap_types::Id,
        id: &jmap_types::Id,
    ) -> impl std::future::Future<Output = Result<(), BackendSetError<Self::Error>>> + Send;

    /// Returns true if this account supports the given JMAP object type.
    ///
    /// # Per-account semantics
    ///
    /// Capabilities are per account (RFC 8620 §1.6.2, §2
    /// `accountCapabilities`), so the answer may vary with `caller` and
    /// `account_id`. Backends that support every type in this trait for
    /// every account can ignore both arguments and return `true`.
    fn supports_type<O: JmapObject>(
        &self,
        caller: &Self::CallerCtx,
        account_id: &jmap_types::Id,
    ) -> bool;

    /// Returns true if the given task list contains at least one task.
    ///
    /// Called by `TaskList/set` destroy handler when `onDestroyRemoveTasks`
    /// is false: if this returns `Ok(true)`, the destroy is rejected with
    /// `taskListHasTask` (draft-ietf-jmap-tasks-06 §3.4).
    ///
    /// # Three-way result
    ///
    /// The return type is `Result<bool, Self::Error>` to distinguish
    /// three states that callers actually need to tell apart
    /// (mirrors [`CalendarsBackend::calendar_has_events`]):
    ///
    /// - `Ok(true)` — the task list is definitely non-empty. The
    ///   handler rejects the destroy with `taskListHasTask`.
    /// - `Ok(false)` — the task list is definitely empty. The handler
    ///   forwards to `destroy_object`.
    /// - `Err(_)` — connectivity/transient failure. The handler maps
    ///   this to `serverFail` so the client knows to retry. Returning
    ///   `Ok(false)` for a transient backend failure is a bug: the
    ///   destroy proceeds and any tasks that DID exist become silently
    ///   orphaned.
    ///
    /// [`CalendarsBackend::calendar_has_events`]: https://docs.rs/jmap-calendars-server/latest/jmap_calendars_server/trait.CalendarsBackend.html#tymethod.calendar_has_events
    ///
    /// # Authorisation contract
    ///
    /// This is a read-side probe that informs a destroy decision the caller is
    /// already authorised to attempt; implementors MAY assume the caller has at
    /// least read access to the target TaskList (the surrounding `/set` flow
    /// re-validates write access in [`Self::destroy_object`]). Backends that
    /// scope task visibility per-principal MUST filter by the caller's effective
    /// access — a counter that includes tasks the caller cannot see leaks
    /// existence information.
    fn task_list_has_tasks(
        &self,
        caller: &Self::CallerCtx,
        account_id: &jmap_types::Id,
        task_list_id: &jmap_types::Id,
    ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send;

    /// Apply a patch that contains only per-user Task properties
    /// (draft-tasks-06 §4.5.1 — `keywords`, `color`, `freeBusyStatus`,
    /// `useDefaultAlerts`, `alerts`).
    ///
    /// The handler routes here when every patch key's leading segment
    /// satisfies [`jmap_tasks_types::is_per_user_task_property`]; that
    /// classification is fixed by the spec and is not a backend hook.
    ///
    /// When only per-user properties are patched, the shared `updated`
    /// timestamp MUST NOT change (§4.5.1 (per-user updated paragraph)).  The default
    /// implementation delegates to [`Self::update_object`], which is correct
    /// for single-user scenarios but backends serving multiple users SHOULD
    /// override this method to route to a user-scoped patch path.
    ///
    /// # Authorisation contract
    ///
    /// Implementors MUST verify caller read access to the target Task (per-user
    /// properties are still scoped to the user, but only users who can see the
    /// Task can have per-user state on it) and MUST return
    /// [`BackendSetError::SetError`] with [`SetErrorType::Forbidden`] otherwise.
    /// The shared-property write-access rule from [`Self::update_object`] does
    /// NOT apply here — a user with only read access to the shared Task may
    /// still mutate their own per-user state. See [`Self::create_object`] for
    /// the workspace-canonical rationale on backend-as-enforcement-point.
    fn update_task_per_user(
        &self,
        caller: &Self::CallerCtx,
        account_id: &jmap_types::Id,
        id: &jmap_types::Id,
        patch: PatchObject,
    ) -> impl std::future::Future<
        Output = Result<Option<jmap_tasks_types::Task>, BackendSetError<Self::Error>>,
    > + Send {
        // Task::Patch = PatchObject (see jmap_tasks_types backend.rs).
        self.update_object::<jmap_tasks_types::Task>(caller, account_id, id, patch)
    }

    /// Declares which side of the draft-tasks-06 §4 (`isDraft` paragraph)
    /// immutability invariant enforcement contract this backend honours.
    ///
    /// This is a **correctness-handover contract**, not a performance flag.
    /// The invariant is: once a Task transitions to `isDraft: false`, the
    /// value MUST NOT be updated back to `true`. Exactly one of the handler
    /// or the backend is responsible for rejecting such a revert with
    /// [`SetErrorType::InvalidProperties`] (`properties: ["isDraft"]`); this
    /// method tells the handler which side owns enforcement on this backend.
    ///
    /// # Returning `false` (default)
    ///
    /// The handler in `Task/set` performs a `get_objects` pre-fetch on every
    /// update that contains `isDraft: true`, inspects the current value, and
    /// rejects the revert before calling [`Self::update_object`]. The backend
    /// is then free to apply the patch verbatim — it will never receive a
    /// spec-violating patch.
    ///
    /// # Returning `true`
    ///
    /// Implementor commits to **atomically rejecting** any update whose
    /// post-patch `isDraft` is `true` when the stored value is not `true`
    /// (including a `null` reset followed by `true`) inside
    /// [`Self::update_object`] (and
    /// [`Self::update_task_per_user`] if applicable), in the same critical
    /// section as the read-and-write that applies the patch. The handler
    /// skips its pre-fetch and forwards the raw patch.
    ///
    /// **Returning `true` without actually performing the atomic re-check is
    /// a spec violation that silently corrupts data.** The pre-fetch
    /// fast-path is removed under the assumption the backend will catch
    /// the revert; if it does not, draft-tasks-06 §4 immutability is broken
    /// with no client-visible signal. Workspace test-integrity rules
    /// (`AGENTS.md` "Permission enforcement: backend canonical") make the
    /// backend the canonical enforcement point regardless of which value
    /// is returned here — a `true` return value is opting OUT of the
    /// handler's defense-in-depth pre-check, not opting INTO enforcement
    /// the handler would otherwise do alone.
    ///
    /// # Performance is a side effect
    ///
    /// The handler's pre-fetch costs one extra `get_objects` round-trip per
    /// update that contains `isDraft: true`. Returning `true` eliminates
    /// that round-trip. This is real, but the reason to return `true` is
    /// that the backend genuinely enforces the invariant atomically — the
    /// round-trip saving alone is not a sufficient reason to flip the flag.
    ///
    /// # Reference impl
    ///
    /// The `memory` feature's `MemoryBackend` returns `true` and enforces
    /// the revert atomically in [`Self::update_object`] under the same lock
    /// that applies the patch. See `memory.rs` for the shape a production
    /// backend should mirror.
    ///
    /// # Default
    ///
    /// `false` — pre-fetch is always performed. Safe default for backends
    /// that have not yet wired atomic isDraft re-checking.
    fn enforce_is_draft_atomically(&self) -> bool {
        false
    }

    /// Compute `utcStart` and `utcDue` for a [`Task`](jmap_tasks_types::Task) by converting the task's
    /// `start`/`due` local-time fields and time zone into UTC (draft-tasks-06 §4,
    /// utcStart/utcDue paragraphs).
    ///
    /// Returns `(utc_start, utc_due)` as [`UTCDate`](jmap_types::UTCDate) values,
    /// or `None` for each if the corresponding field is absent or the time zone
    /// is unknown.
    ///
    /// The default implementation returns `(None, None)` — backends that do not
    /// support time-zone conversion can accept this behaviour and the caller will
    /// omit both fields.  Backends with full tz support should override this.
    ///
    /// # Parameters
    /// - `caller` — the caller context. The default implementation ignores it,
    ///   but backends MAY use [`JmapBackend::principal_id`] to resolve the
    ///   caller's preferred default time zone when `tz_hint` is `None`.
    /// - `account_id` — the target account. The default implementation ignores
    ///   it, but backends MAY use it to look up an account-scoped tz database
    ///   or per-account default time zone.
    /// - `task` — the task whose `start` and `due` fields are to be converted.
    /// - `tz_hint` — an optional IANA time-zone override; if `None`, the task's
    ///   own `time_zone` field (if any) is used.
    ///
    /// Naming and signature mirror the canonical
    /// [`CalendarsBackend::compute_utc_times`](https://docs.rs/jmap-calendars-server/latest/jmap_calendars_server/trait.CalendarsBackend.html#method.compute_utc_times)
    /// (bd:JMAP-ops7.25).
    ///
    /// [`JmapBackend::principal_id`]: jmap_server::JmapBackend::principal_id
    fn compute_utc_times(
        &self,
        _caller: &Self::CallerCtx,
        _account_id: &jmap_types::Id,
        _task: &jmap_tasks_types::Task,
        _tz_hint: Option<&str>,
    ) -> impl std::future::Future<Output = (Option<jmap_types::UTCDate>, Option<jmap_types::UTCDate>)>
           + Send {
        // Default: no UTC conversion capability; callers omit utcStart/utcDue.
        async { (None, None) }
    }
}