Skip to main content

jmap_tasks_server/
backend.rs

1//! [`TasksBackend`] trait and supporting types for JMAP Tasks method handlers.
2//!
3//! Consumers implement [`TasksBackend`] for their storage system. The method
4//! handlers in sibling modules call into the backend through this trait.
5//!
6//! The read-side operations (`get_objects`, `get_state`, `get_changes`,
7//! `query_objects`, `query_changes`) are defined on the [`jmap_server::JmapBackend`]
8//! supertrait. Only write operations and type-specific operations are here.
9
10use jmap_server::{
11    BackendQueryError, BackendSetError, JmapBackend, JmapObject, QueryParams, QueryResult,
12    SetObject,
13};
14use jmap_types::PatchObject;
15
16// ---------------------------------------------------------------------------
17// TasksBackend trait
18// ---------------------------------------------------------------------------
19
20/// Storage backend for JMAP Tasks method handlers (draft-ietf-jmap-tasks-06).
21///
22/// Implementors provide the actual data access; the method handler modules
23/// in this crate translate between JMAP wire protocol and backend calls.
24///
25/// Read-side operations (`get_objects`, `get_state`, `get_changes`,
26/// `query_objects`, `query_changes`) are defined on the [`JmapBackend`]
27/// supertrait. Only write operations and type introspection are here.
28///
29/// This trait is not object-safe by design (generic methods). Use
30/// `Arc<impl TasksBackend>` when sharing across tasks.
31pub trait TasksBackend: JmapBackend {
32    /// Create a new object (`TaskList` or Task).
33    ///
34    /// # Authorisation contract
35    ///
36    /// This method is the canonical enforcement point for caller authorisation
37    /// per workspace AGENTS.md "Caller identity (foundation seam)" and per-crate
38    /// AGENTS.md "Permission enforcement: backend canonical". Implementors MUST
39    /// verify that the principal identified by
40    /// [`JmapAccounts::principal_id(caller)`](jmap_server::JmapAccounts::principal_id) has write
41    /// access to the target account / `TaskList` / Task before performing the
42    /// mutation, and MUST return
43    /// [`BackendSetError::SetError`] carrying
44    /// [`SetErrorType::Forbidden`](jmap_server::SetErrorType::Forbidden) otherwise. Handlers in this crate do NO
45    /// permission checking; any handler-layer pre-check is defense-in-depth
46    /// only and the backend MUST re-verify atomically with the mutation. A
47    /// backend that trusts the handler is a bug. A backend whose
48    /// `principal_id` returns `None` permits every write (fail-open,
49    /// bd:JMAP-bghk) and CANNOT correctly implement `TaskList` ACLs or
50    /// per-user scoping.
51    ///
52    /// ## `mayWriteOwn` and task owners
53    ///
54    /// For a Task, write access is the `TaskList`'s `mayWriteAll` right, or
55    /// its `mayWriteOwn` right when the caller is an owner of the task or
56    /// the task has no owner (draft-ietf-jmap-tasks-06 §3 `mayWriteOwn`).
57    /// Who the owner is follows JMAP Calendars (jmapio/jmap #461, PR #462;
58    /// draft-ietf-jmap-calendars-34 §4), not -06's "participant"/"chair"
59    /// text: decide it with [`jmap_tasks_types::is_task_owner`] and
60    /// [`jmap_tasks_types::task_has_owner`], passing the `calendarAddress`
61    /// of each of the caller's `ParticipantIdentity` objects in the account.
62    /// A participant with the `"owner"` role whose `calendarAddress` is one
63    /// of those makes the caller an owner; a task whose `participants` is
64    /// null or omitted, or has no `"owner"` participant, has no owner.
65    ///
66    /// Check a create against the new task, and an update or destroy
67    /// against the stored one: "This means the user may also transfer
68    /// ownership by updating a task so they are no longer an owner" (-06
69    /// §3), so the patched result need not leave the caller an owner.
70    ///
71    /// # Errors
72    ///
73    /// Reject a create that RFC 8620 §5.3 defines an error for with
74    /// [`BackendSetError::SetError`] carrying the matching
75    /// [`SetErrorType`](jmap_server::SetErrorType); the handler places it verbatim in `notCreated`.
76    /// For create these are `forbidden`, `overQuota`, `tooLarge`,
77    /// `rateLimit` and `invalidProperties`. An `invalidProperties` error
78    /// SHOULD name in `properties` "*all* the properties that were
79    /// invalid", for example `taskListId` when a Task names a `TaskList` that
80    /// does not exist.
81    ///
82    /// Return [`BackendSetError::Other`] only for unexpected storage
83    /// failures. The handler reports it as `serverFail` without the
84    /// error's `Display` text, which tells the client to retry; a
85    /// deterministic rejection returned as `Other` invites retries that
86    /// cannot succeed.
87    ///
88    /// The `/set` handlers in this crate reject an unknown `account_id`
89    /// with the method-level `accountNotFound` error before calling the
90    /// backend.
91    ///
92    /// # State and change log
93    ///
94    /// RFC 8620 §5.1 defines the state string over "*all* the data of
95    /// this type in the account": "If the data changes, this string MUST
96    /// change." Every successful `create_object`,
97    /// [`update_object`](Self::update_object) and
98    /// [`destroy_object`](Self::destroy_object) MUST advance
99    /// [`get_state`](jmap_server::JmapReads::get_state) for `O` in `account_id` and
100    /// record the id as created, updated or destroyed so
101    /// [`get_changes`](jmap_server::JmapReads::get_changes) reports it.
102    ///
103    /// The write, the state advance and the change record MUST be atomic
104    /// with respect to other callers: the reference `MemoryBackend` does
105    /// all three under one mutex acquisition, and a database backend uses
106    /// one transaction. A call that returns `Err` MUST leave the stored
107    /// data, the state and the change log unchanged.
108    fn create_object<O, F>(
109        &self,
110        caller: &Self::CallerCtx,
111        account_id: &jmap_types::Id,
112        create_id: &str,
113        build: F,
114    ) -> impl std::future::Future<Output = Result<(jmap_types::Id, O), BackendSetError<Self::Error>>>
115    + Send
116    where
117        O: SetObject + Send + Sync,
118        F: FnOnce(&jmap_types::Id) -> O + Send;
119
120    /// Store `obj`, a record read from `from_account_id`, as a new record in
121    /// `to_account_id`, for `/copy` (RFC 8620 §5.4).
122    ///
123    /// Called by `Task/copy` after the handler fetched the Task from
124    /// `from_account_id` and applied the request's overrides, including any
125    /// `metadata` and `privateMetadata` it supplies
126    /// (draft-ietf-jmap-metadata-05 §3.4). `create` is the request's create
127    /// object for this copy (RFC 8620 §5.4). -05 §3.4 says its `metadata`
128    /// and `privateMetadata` follow "the same rules as a create in
129    /// Foo/set", so the backend validates them as
130    /// [`create_object`](Self::create_object) does (-05 §3.2 rules 1 to 4,
131    /// `maxDepth` only on these supplied values) and leaves the copied
132    /// values unvalidated ("Copied values are not revalidated against the
133    /// destination account"). Every other rule of
134    /// [`create_object`](Self::create_object) applies to the copy. The
135    /// backend assigns the new `id`, stores the record in `to_account_id`
136    /// and records the create in the state and change log as
137    /// [`create_object`](Self::create_object) does. Returns the new id and
138    /// the stored record.
139    ///
140    /// # Authorisation contract
141    ///
142    /// Implementors MUST verify caller read access to `obj` in
143    /// `from_account_id` and write access to `to_account_id` before storing the
144    /// copy, and MUST return [`BackendSetError::SetError`] with
145    /// [`SetErrorType::Forbidden`](jmap_server::SetErrorType::Forbidden) otherwise. See [`Self::create_object`] for
146    /// the workspace-canonical rationale; the same rule applies here.
147    ///
148    /// # Errors
149    ///
150    /// As for [`create_object`](Self::create_object): a
151    /// [`BackendSetError::SetError`] is reported for that copy.
152    fn copy_object<O: SetObject + Send + Sync>(
153        &self,
154        caller: &Self::CallerCtx,
155        from_account_id: &jmap_types::Id,
156        to_account_id: &jmap_types::Id,
157        obj: O,
158        create: &serde_json::Value,
159    ) -> impl std::future::Future<Output = Result<(jmap_types::Id, O), BackendSetError<Self::Error>>>
160    + Send;
161
162    /// Apply a partial update (patch) to an existing object.
163    ///
164    /// Returns `Some(updated_object)` if the backend modified any properties
165    /// beyond what the client requested (RFC 8620 §5.3 server-set field echo),
166    /// or `None` if the patch was applied verbatim.
167    ///
168    /// # Authorisation contract
169    ///
170    /// Implementors MUST verify caller write-access to the target object before
171    /// applying the patch and MUST return [`BackendSetError::SetError`] with
172    /// [`SetErrorType::Forbidden`](jmap_server::SetErrorType::Forbidden) otherwise. See [`Self::create_object`] for
173    /// the workspace-canonical rationale; the same rule applies here. For a
174    /// Task, write access includes `mayWriteOwn` on a task the caller owns
175    /// or that has no owner, judged on the stored task (see
176    /// [`Self::create_object`], "`mayWriteOwn` and task owners").
177    ///
178    /// # Patch format
179    ///
180    /// `patch` is an RFC 8620 §5.3 [`PatchObject`], not an RFC 7396 JSON
181    /// Merge Patch: "The keys are a path in JSON Pointer format
182    /// \[RFC6901\], with an implicit leading "/"". So `{"a/b": null}`
183    /// removes member `b` of property `a`; it does not touch a top-level
184    /// property literally named `a/b`. A `null` value sets the
185    /// property's default if it has one, otherwise removes it. A pointer
186    /// into an array, a pointer whose parent does not exist, or two keys
187    /// where one pointer is a prefix of the other "MUST be rejected with
188    /// an "invalidPatch" error".
189    ///
190    /// Implementors SHOULD apply `patch` with
191    /// [`jmap_server::apply_patch_object`], which enforces these rules
192    /// all-or-nothing, and map any [`jmap_server::PatchPathError`] to
193    /// [`jmap_server::SetErrorType::InvalidPatch`], as the reference
194    /// `MemoryBackend` does.
195    ///
196    /// # Errors
197    ///
198    /// As for [`create_object`](Self::create_object), plus these RFC 8620
199    /// §5.3 rules for update:
200    ///
201    /// - "If an id given cannot be found, the update or destroy MUST be
202    ///   rejected with a "notFound" set error."
203    /// - A patch that breaks the rules under "Patch format" is
204    ///   `invalidPatch`.
205    /// - A patched record that is invalid is `invalidProperties`. That
206    ///   includes changing a server-set property, though "it is not an
207    ///   error to include a server-set property in an update as long as
208    ///   the value is identical to the current value on the server."
209    /// - A Task patch whose result has `isDraft: true` when the stored
210    ///   value is not `true` (false, or absent after a `null` patch) is
211    ///   `invalidProperties` naming `isDraft`: draft-tasks-06 §4 "This may
212    ///   only be set to true upon creation." The `Task/set` handler does
213    ///   not pre-check this; the backend is the only enforcement point, in
214    ///   the same critical section that applies the patch.
215    /// - A Task's `workflowStatus` and `progress` follow decision 42
216    ///   ([`crate::workflow::apply_workflow_status`]): a status not in the
217    ///   list's `workflowStatuses` is `invalidProperties` when the patch sets
218    ///   it or moves the task; a progress value is mirrored into `progress`
219    ///   (return the Task as `Some` to echo it); a conflicting `progress` is
220    ///   `invalidProperties`. Run it in the same critical section, as
221    ///   `create_object` does for a create.
222    ///
223    /// # Atomicity
224    ///
225    /// RFC 8620 §5.3: the server "MUST NOT only commit part of an update
226    /// to a single record". Apply the whole patch and validate the result
227    /// before writing it, so that on any error the stored record is
228    /// unchanged. State and change log follow
229    /// [`create_object`](Self::create_object) ("State and change log"); an
230    /// `Ok(None)` return still advances the state.
231    fn update_object<O: SetObject + Send + Sync>(
232        &self,
233        caller: &Self::CallerCtx,
234        account_id: &jmap_types::Id,
235        id: &jmap_types::Id,
236        patch: O::Patch,
237    ) -> impl std::future::Future<Output = Result<Option<O>, BackendSetError<Self::Error>>> + Send;
238
239    /// Destroy an object by id.
240    ///
241    /// # Authorisation contract
242    ///
243    /// Implementors MUST verify caller write-access to the target object before
244    /// destroying it and MUST return [`BackendSetError::SetError`] with
245    /// [`SetErrorType::Forbidden`](jmap_server::SetErrorType::Forbidden) otherwise. See [`Self::create_object`] for
246    /// the workspace-canonical rationale; the same rule applies here. For a
247    /// Task, write access includes `mayWriteOwn` on a task the caller owns
248    /// or that has no owner (see [`Self::create_object`], "`mayWriteOwn`
249    /// and task owners").
250    ///
251    /// # Errors
252    ///
253    /// As for [`create_object`](Self::create_object), plus these RFC 8620
254    /// §5.3 rules for destroy: an unknown id, including one already
255    /// destroyed, is `notFound`, and a destroy that "would violate an ACL
256    /// or other permissions policy" is `forbidden`.
257    ///
258    /// # Cascades
259    ///
260    /// The handlers perform the cross-record effects the client chooses,
261    /// through explicit backend calls, and the backend does not repeat
262    /// them. `TaskList/set` `onDestroyRemoveTasks` destroys the list's
263    /// Tasks through [`Self::destroy_object`] calls the handler makes.
264    ///
265    /// If the backend itself changes another record because of the
266    /// destroy, it MUST advance that record type's state and record the
267    /// change in the same atomic step, so `/changes` on that type sees it.
268    /// State and change log for `O` follow
269    /// [`create_object`](Self::create_object) ("State and change log").
270    fn destroy_object<O: SetObject + Send + Sync>(
271        &self,
272        caller: &Self::CallerCtx,
273        account_id: &jmap_types::Id,
274        id: &jmap_types::Id,
275    ) -> impl std::future::Future<Output = Result<(), BackendSetError<Self::Error>>> + Send;
276
277    /// Returns `true` if this backend supports JMAP object type `O` for
278    /// `account_id`, as seen by `caller`.
279    ///
280    /// # Per-account semantics
281    ///
282    /// Capabilities are per account (RFC 8620 §1.6.2, §2
283    /// `accountCapabilities`), so the answer may vary with `caller` and
284    /// `account_id`. Backends that support every type in this trait for
285    /// every account can ignore both arguments and return `true`.
286    fn supports_type<O: JmapObject>(
287        &self,
288        caller: &Self::CallerCtx,
289        account_id: &jmap_types::Id,
290    ) -> bool;
291
292    /// Returns true if the given task list contains at least one task.
293    ///
294    /// Called by `TaskList/set` destroy handler when `onDestroyRemoveTasks`
295    /// is false: if this returns `Ok(true)`, the destroy is rejected with
296    /// `taskListHasTask` (draft-ietf-jmap-tasks-06 §3.4).
297    ///
298    /// # Three-way result
299    ///
300    /// The return type is `Result<bool, Self::Error>` to distinguish
301    /// three states that callers actually need to tell apart
302    /// (mirrors [`CalendarsBackend::calendar_has_events`]):
303    ///
304    /// - `Ok(true)` — the task list is definitely non-empty. The
305    ///   handler rejects the destroy with `taskListHasTask`.
306    /// - `Ok(false)` — the task list is definitely empty. The handler
307    ///   forwards to `destroy_object`.
308    /// - `Err(_)` — connectivity/transient failure. The handler maps
309    ///   this to `serverFail` so the client knows to retry. Returning
310    ///   `Ok(false)` for a transient backend failure is a bug: the
311    ///   destroy proceeds and any tasks that DID exist become silently
312    ///   orphaned.
313    ///
314    /// [`CalendarsBackend::calendar_has_events`]: https://docs.rs/jmap-calendars-server/latest/jmap_calendars_server/trait.CalendarsBackend.html#tymethod.calendar_has_events
315    ///
316    /// # Authorisation contract
317    ///
318    /// This is a read-side probe that informs a destroy decision the caller is
319    /// already authorised to attempt; implementors MAY assume the caller has at
320    /// least read access to the target `TaskList` (the surrounding `/set` flow
321    /// re-validates write access in [`Self::destroy_object`]). Backends that
322    /// scope task visibility per-principal MUST filter by the caller's effective
323    /// access — a counter that includes tasks the caller cannot see leaks
324    /// existence information.
325    fn task_list_has_tasks(
326        &self,
327        caller: &Self::CallerCtx,
328        account_id: &jmap_types::Id,
329        task_list_id: &jmap_types::Id,
330    ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send;
331
332    /// Apply a patch that contains only per-user Task properties
333    /// (draft-tasks-06 §4.5.1 — `keywords`, `color`, `freeBusyStatus`,
334    /// `useDefaultAlerts`, `alerts`).
335    ///
336    /// The handler routes here when every patch key's leading segment
337    /// satisfies [`jmap_tasks_types::is_per_user_task_property`]; that
338    /// classification is fixed by the spec and is not a backend hook.
339    ///
340    /// When only per-user properties are patched, the shared `updated`
341    /// timestamp MUST NOT change (§4.5.1 (per-user updated paragraph)).
342    /// There is no default: delegating to [`Self::update_object`] is correct
343    /// only for a single-user backend whose `update_object` leaves `updated`
344    /// alone. A backend serving multiple users stores the patch in a
345    /// user-scoped path.
346    ///
347    /// # Authorisation contract
348    ///
349    /// Implementors MUST verify that the caller may modify per-user properties
350    /// on the target Task and MUST return [`BackendSetError::SetError`] with
351    /// [`SetErrorType::Forbidden`](jmap_server::SetErrorType::Forbidden) otherwise. That is the `TaskList`'s
352    /// `mayUpdatePrivate` right, which covers exactly the per-user properties
353    /// of draft-ietf-jmap-tasks-06 §4.5.1
354    /// ([`jmap_tasks_types::PER_USER_TASK_PROPERTIES`]), as jmapio/jmap
355    /// #468 / PR #469 words it: "The user may modify the per-user properties
356    /// (see the "Per-user properties" section) on all tasks in the task list,
357    /// even if they would not otherwise have permission to modify that task."
358    /// (-06 §3 says "the following properties" and gives no list.) The
359    /// handler sends only patches whose every key is one of those here, so a
360    /// patch that also touches a shared property goes to
361    /// [`Self::update_object`] and needs write access. The write-access rule
362    /// of [`Self::update_object`] does NOT apply here. See
363    /// [`Self::create_object`] for the workspace-canonical rationale on
364    /// backend-as-enforcement-point.
365    fn update_task_per_user(
366        &self,
367        caller: &Self::CallerCtx,
368        account_id: &jmap_types::Id,
369        id: &jmap_types::Id,
370        patch: PatchObject,
371    ) -> impl std::future::Future<
372        Output = Result<Option<jmap_tasks_types::Task>, BackendSetError<Self::Error>>,
373    > + Send;
374
375    /// Compute `utcStart` and `utcDue` for a [`Task`](jmap_tasks_types::Task) by converting the task's
376    /// `start`/`due` local-time fields and time zone into UTC (draft-tasks-06 §4,
377    /// utcStart/utcDue paragraphs).
378    ///
379    /// Returns `(utc_start, utc_due)` as [`UTCDate`](jmap_types::UTCDate) values,
380    /// or `None` for each if the corresponding field is absent or the time zone
381    /// is unknown.
382    ///
383    /// `Task/get` sends `null` for a requested `utcStart` / `utcDue` when the
384    /// task has no `start` / `due` (jmapio/jmap PR #464), whatever this
385    /// returns; when the local time is set and this returns `None`, the key
386    /// is left out, because `null` would say the local time is unset.
387    ///
388    /// The default implementation returns `(None, None)` — backends that do not
389    /// support time-zone conversion can accept this behaviour, and `Task/get`
390    /// then omits the two properties for tasks that have a `start` / `due`.
391    /// Backends with full tz support should override this.
392    ///
393    /// # Parameters
394    /// - `caller` — the caller context. The default implementation ignores it.
395    /// - `account_id` — the target account. The default implementation ignores
396    ///   it, but backends MAY use it to look up an account-scoped tz database.
397    /// - `task` — the task whose `start` and `due` fields are to be converted.
398    /// - `tz_hint` — the Task/get `timeZone` argument, `None` when the
399    ///   request has none, which means `"Etc/UTC"` (the CalendarEvent/get
400    ///   default, draft-ietf-jmap-calendars-34 §5.7). It applies only to a
401    ///   floating task (a null `timeZone`): "Floating tasks will be
402    ///   interpreted as per the time zone given as a Task/get argument"
403    ///   (draft-tasks-06 §4). A task with a `timeZone` converts with its own
404    ///   zone. The crate does not check the value against the IANA Time
405    ///   Zone Database; an unknown zone converts to `None`.
406    ///
407    /// Naming and signature mirror the canonical
408    /// [`CalendarsBackend::compute_utc_times`](https://docs.rs/jmap-calendars-server/latest/jmap_calendars_server/trait.CalendarsBackend.html#method.compute_utc_times)
409    /// (bd:JMAP-ops7.25).
410    fn compute_utc_times(
411        &self,
412        _caller: &Self::CallerCtx,
413        _account_id: &jmap_types::Id,
414        _task: &jmap_tasks_types::Task,
415        _tz_hint: Option<&str>,
416    ) -> impl std::future::Future<
417        Output = (Option<jmap_types::UTCDate>, Option<jmap_types::UTCDate>),
418    > + Send {
419        // Default: no UTC conversion capability; callers omit utcStart/utcDue.
420        async { (None, None) }
421    }
422
423    /// Run a `Task/query` request with its Task/query arguments
424    /// (`expandRecurrences`, `timeZone`; jmapio/jmap #456, following
425    /// CalendarEvent/query, draft-ietf-jmap-calendars-34 §5.11).
426    ///
427    /// `params` holds the RFC 8620 §5.5 arguments. `args.time_zone` (or
428    /// `"Etc/UTC"` when `None`) is the zone for the `after` / `before`
429    /// conditions and for the local times of floating tasks, both when
430    /// filtering and when sorting; a `start` sort orders by absolute time.
431    /// The conditions are documented on
432    /// [`TaskFilterCondition`](jmap_tasks_types::TaskFilterCondition): `after`
433    /// tests the task's `due` (or `start` when it has no `due`), `before` its
434    /// `start` (or `due`).
435    ///
436    /// When `args.expand_recurrences` is `true`, return one id per
437    /// instance of a recurring task inside the filter's `after` / `before`
438    /// window; the handler has checked the filter is one `FilterCondition`
439    /// with both. A synthetic instance id is opaque to the client and must
440    /// resolve in `Task/get` and `Task/set` (calendars-34 §5.11). With
441    /// `expand_recurrences` `false`, a recurring task is one id.
442    ///
443    /// There is no default: one that ignored `args` would answer an
444    /// expansion request with unexpanded ids and read floating tasks in the
445    /// wrong zone (workspace AGENTS.md, "Default bodies on spec-semantic
446    /// backend methods"). A backend that cannot expand says so with
447    /// `cannotCalculateOccurrences`.
448    ///
449    /// # Errors
450    ///
451    /// [`BackendQueryError::Method`]
452    /// is returned to the client unchanged:
453    ///
454    /// - `expandDurationTooLarge` (`JmapError::custom`) when expansion is
455    ///   requested and `before - after` exceeds
456    ///   [`TasksLimits::max_expanded_query_duration_seconds`] (the account's
457    ///   `maxExpandedQueryDuration`, draft-tasks-06 §1.6.2). The handler
458    ///   checks this first, but the backend is canonical and MUST check it
459    ///   again (workspace AGENTS.md "Backend caps and limits").
460    /// - `cannotCalculateOccurrences` when a recurrence needed for the
461    ///   result cannot be expanded.
462    /// - The RFC 8620 §5.5 errors (`unsupportedFilter`, `unsupportedSort`,
463    ///   `anchorNotFound`, ...), as for
464    ///   [`query_objects`](jmap_server::JmapReads::query_objects).
465    ///
466    /// [`BackendQueryError::Other`]
467    /// becomes a redacted `serverFail`.
468    fn query_tasks(
469        &self,
470        caller: &Self::CallerCtx,
471        account_id: &jmap_types::Id,
472        params: QueryParams<'_, jmap_tasks_types::Task>,
473        args: &TaskQueryArgs,
474    ) -> impl std::future::Future<Output = Result<QueryResult, BackendQueryError<Self::Error>>> + Send;
475
476    /// Implementation-defined caps for `account_id` as seen by `caller`
477    /// (workspace AGENTS.md "Backend caps and limits"). The default is
478    /// [`TasksLimits::default`]; override it to vary caps per account.
479    fn limits(&self, caller: &Self::CallerCtx, account_id: &jmap_types::Id) -> TasksLimits {
480        let _ = (caller, account_id);
481        TasksLimits::default()
482    }
483}
484
485/// Per-call `Task/query` arguments beyond RFC 8620 §5.5
486/// (jmapio/jmap #456, following CalendarEvent/query,
487/// draft-ietf-jmap-calendars-34 §5.11).
488///
489/// `#[non_exhaustive]` so a later revision can add arguments; build one
490/// with [`TaskQueryArgs::default`] and the setters.
491#[non_exhaustive]
492#[derive(Debug, Clone, Default, PartialEq, Eq)]
493pub struct TaskQueryArgs {
494    /// `expandRecurrences` (default `false`): return one id per instance
495    /// of a recurring task. The handler has checked that the filter is one
496    /// `FilterCondition` with both `before` and `after`.
497    pub expand_recurrences: bool,
498    /// `timeZone` (default `"Etc/UTC"` when `None`): the zone for the
499    /// `after` / `before` conditions and for floating tasks when filtering
500    /// and sorting. The crate does not check it against the IANA Time Zone
501    /// Database; that is the backend's job.
502    pub time_zone: Option<String>,
503}
504
505impl TaskQueryArgs {
506    /// Set [`Self::expand_recurrences`].
507    #[must_use]
508    pub fn with_expand_recurrences(mut self, expand: bool) -> Self {
509        self.expand_recurrences = expand;
510        self
511    }
512
513    /// Set [`Self::time_zone`].
514    #[must_use]
515    pub fn with_time_zone(mut self, time_zone: Option<String>) -> Self {
516        self.time_zone = time_zone;
517        self
518    }
519}
520
521/// Implementation-defined caps of a [`TasksBackend`], returned by
522/// [`TasksBackend::limits`] (workspace AGENTS.md "Backend caps and limits";
523/// mirrors `CalendarsLimits`).
524///
525/// | Field | Default | Rationale |
526/// |---|---|---|
527/// | `max_expanded_query_duration_seconds` | `31_536_000` (365 days) | As `CalendarsLimits`: a year is the range clients commonly ask for, and longer windows multiply recurrence expansion. |
528#[non_exhaustive]
529#[derive(Debug, Clone, PartialEq, Eq)]
530pub struct TasksLimits {
531    /// Longest `before - after` window, in seconds, that `Task/query`
532    /// expands recurrences over: the account's `maxExpandedQueryDuration`
533    /// (draft-tasks-06 §1.6.2, "The maximum duration the user may query
534    /// over when asking the server to expand recurrences"). A longer window
535    /// is the `expandDurationTooLarge` method error.
536    pub max_expanded_query_duration_seconds: u64,
537}
538
539impl Default for TasksLimits {
540    fn default() -> Self {
541        Self {
542            max_expanded_query_duration_seconds: 31_536_000,
543        }
544    }
545}
546
547impl TasksLimits {
548    /// Limits with the given [`Self::max_expanded_query_duration_seconds`].
549    #[must_use]
550    pub fn new(max_expanded_query_duration_seconds: u64) -> Self {
551        Self {
552            max_expanded_query_duration_seconds,
553        }
554    }
555}