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`](jmap_server::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`](jmap_server::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}