pub trait TasksBackend: JmapBackend {
// Required methods
fn create_object<O, F>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
create_id: &str,
build: F,
) -> impl Future<Output = Result<(Id, O), BackendSetError<Self::Error>>> + Send
where O: SetObject + Send + Sync,
F: FnOnce(&Id) -> O + Send;
fn copy_object<O: SetObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
from_account_id: &Id,
to_account_id: &Id,
obj: O,
create: &Value,
) -> impl Future<Output = Result<(Id, O), BackendSetError<Self::Error>>> + Send;
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;
fn destroy_object<O: SetObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
id: &Id,
) -> impl Future<Output = Result<(), BackendSetError<Self::Error>>> + Send;
fn supports_type<O: JmapObject>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
) -> bool;
fn task_list_has_tasks(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
task_list_id: &Id,
) -> impl Future<Output = Result<bool, Self::Error>> + Send;
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;
fn query_tasks(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
params: QueryParams<'_, Task>,
args: &TaskQueryArgs,
) -> impl Future<Output = Result<QueryResult, BackendQueryError<Self::Error>>> + Send;
// Provided methods
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 { ... }
fn limits(&self, caller: &Self::CallerCtx, account_id: &Id) -> TasksLimits { ... }
}Expand description
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.
Required Methods§
Sourcefn create_object<O, F>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
create_id: &str,
build: F,
) -> impl Future<Output = Result<(Id, O), BackendSetError<Self::Error>>> + Send
fn create_object<O, F>( &self, caller: &Self::CallerCtx, account_id: &Id, create_id: &str, build: F, ) -> impl Future<Output = Result<(Id, O), BackendSetError<Self::Error>>> + Send
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
JmapAccounts::principal_id(caller) 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 whose
principal_id returns None permits every write (fail-open,
bd:JMAP-bghk) and CANNOT correctly implement TaskList ACLs or
per-user scoping.
§mayWriteOwn and task owners
For a Task, write access is the TaskList’s mayWriteAll right, or
its mayWriteOwn right when the caller is an owner of the task or
the task has no owner (draft-ietf-jmap-tasks-06 §3 mayWriteOwn).
Who the owner is follows JMAP Calendars (jmapio/jmap #461, PR #462;
draft-ietf-jmap-calendars-34 §4), not -06’s “participant”/“chair”
text: decide it with jmap_tasks_types::is_task_owner and
jmap_tasks_types::task_has_owner, passing the calendarAddress
of each of the caller’s ParticipantIdentity objects in the account.
A participant with the "owner" role whose calendarAddress is one
of those makes the caller an owner; a task whose participants is
null or omitted, or has no "owner" participant, has no owner.
Check a create against the new task, and an update or destroy against the stored one: “This means the user may also transfer ownership by updating a task so they are no longer an owner” (-06 §3), so the patched result need not leave the caller an owner.
§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 and
destroy_object MUST advance
get_state for O in account_id and
record the id as created, updated or destroyed so
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.
Sourcefn copy_object<O: SetObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
from_account_id: &Id,
to_account_id: &Id,
obj: O,
create: &Value,
) -> impl Future<Output = Result<(Id, O), BackendSetError<Self::Error>>> + Send
fn copy_object<O: SetObject + Send + Sync>( &self, caller: &Self::CallerCtx, from_account_id: &Id, to_account_id: &Id, obj: O, create: &Value, ) -> impl Future<Output = Result<(Id, O), BackendSetError<Self::Error>>> + Send
Store obj, a record read from from_account_id, as a new record in
to_account_id, for /copy (RFC 8620 §5.4).
Called by Task/copy after the handler fetched the Task from
from_account_id and applied the request’s overrides, including any
metadata and privateMetadata it supplies
(draft-ietf-jmap-metadata-05 §3.4). create is the request’s create
object for this copy (RFC 8620 §5.4). -05 §3.4 says its metadata
and privateMetadata follow “the same rules as a create in
Foo/set”, so the backend validates them as
create_object does (-05 §3.2 rules 1 to 4,
maxDepth only on these supplied values) and leaves the copied
values unvalidated (“Copied values are not revalidated against the
destination account”). Every other rule of
create_object applies to the copy. The
backend assigns the new id, stores the record in to_account_id
and records the create in the state and change log as
create_object does. Returns the new id and
the stored record.
§Authorisation contract
Implementors MUST verify caller read access to obj in
from_account_id and write access to to_account_id before storing the
copy, 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: a
BackendSetError::SetError is reported for that copy.
Sourcefn 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
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
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. For a
Task, write access includes mayWriteOwn on a task the caller owns
or that has no owner, judged on the stored task (see
Self::create_object, “mayWriteOwn and task owners”).
§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, 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.” - A Task patch whose result has
isDraft: truewhen the stored value is nottrue(false, or absent after anullpatch) isinvalidPropertiesnamingisDraft: draft-tasks-06 §4 “This may only be set to true upon creation.” TheTask/sethandler does not pre-check this; the backend is the only enforcement point, in the same critical section that applies the patch. - A Task’s
workflowStatusandprogressfollow decision 42 (crate::workflow::apply_workflow_status): a status not in the list’sworkflowStatusesisinvalidPropertieswhen the patch sets it or moves the task; a progress value is mirrored intoprogress(return the Task asSometo echo it); a conflictingprogressisinvalidProperties. Run it in the same critical section, ascreate_objectdoes for a create.
§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 (“State and change log”); an
Ok(None) return still advances the state.
Sourcefn destroy_object<O: SetObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
id: &Id,
) -> impl Future<Output = Result<(), BackendSetError<Self::Error>>> + Send
fn destroy_object<O: SetObject + Send + Sync>( &self, caller: &Self::CallerCtx, account_id: &Id, id: &Id, ) -> impl Future<Output = Result<(), 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. For a
Task, write access includes mayWriteOwn on a task the caller owns
or that has no owner (see Self::create_object, “mayWriteOwn
and task owners”).
§Errors
As for 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 destroys the list’s
Tasks through Self::destroy_object calls the handler makes.
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 (“State and change log”).
Sourcefn supports_type<O: JmapObject>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
) -> bool
fn supports_type<O: JmapObject>( &self, caller: &Self::CallerCtx, account_id: &Id, ) -> bool
Returns true if this backend supports JMAP object type O for
account_id, as seen by caller.
§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.
Sourcefn task_list_has_tasks(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
task_list_id: &Id,
) -> impl Future<Output = Result<bool, Self::Error>> + Send
fn task_list_has_tasks( &self, caller: &Self::CallerCtx, account_id: &Id, task_list_id: &Id, ) -> impl Future<Output = Result<bool, Self::Error>> + Send
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 withtaskListHasTask.Ok(false)— the task list is definitely empty. The handler forwards todestroy_object.Err(_)— connectivity/transient failure. The handler maps this toserverFailso the client knows to retry. ReturningOk(false)for a transient backend failure is a bug: the destroy proceeds and any tasks that DID exist become silently orphaned.
§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.
Sourcefn 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
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
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)).
There is no default: delegating to Self::update_object is correct
only for a single-user backend whose update_object leaves updated
alone. A backend serving multiple users stores the patch in a
user-scoped path.
§Authorisation contract
Implementors MUST verify that the caller may modify per-user properties
on the target Task and MUST return BackendSetError::SetError with
SetErrorType::Forbidden otherwise. That is the TaskList’s
mayUpdatePrivate right, which covers exactly the per-user properties
of draft-ietf-jmap-tasks-06 §4.5.1
(jmap_tasks_types::PER_USER_TASK_PROPERTIES), as jmapio/jmap
#468 / PR #469 words it: “The user may modify the per-user properties
(see the “Per-user properties” section) on all tasks in the task list,
even if they would not otherwise have permission to modify that task.“
(-06 §3 says “the following properties” and gives no list.) The
handler sends only patches whose every key is one of those here, so a
patch that also touches a shared property goes to
Self::update_object and needs write access. The write-access rule
of Self::update_object does NOT apply here. See
Self::create_object for the workspace-canonical rationale on
backend-as-enforcement-point.
Sourcefn query_tasks(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
params: QueryParams<'_, Task>,
args: &TaskQueryArgs,
) -> impl Future<Output = Result<QueryResult, BackendQueryError<Self::Error>>> + Send
fn query_tasks( &self, caller: &Self::CallerCtx, account_id: &Id, params: QueryParams<'_, Task>, args: &TaskQueryArgs, ) -> impl Future<Output = Result<QueryResult, BackendQueryError<Self::Error>>> + Send
Run a Task/query request with its Task/query arguments
(expandRecurrences, timeZone; jmapio/jmap #456, following
CalendarEvent/query, draft-ietf-jmap-calendars-34 §5.11).
params holds the RFC 8620 §5.5 arguments. args.time_zone (or
"Etc/UTC" when None) is the zone for the after / before
conditions and for the local times of floating tasks, both when
filtering and when sorting; a start sort orders by absolute time.
The conditions are documented on
TaskFilterCondition: after
tests the task’s due (or start when it has no due), before its
start (or due).
When args.expand_recurrences is true, return one id per
instance of a recurring task inside the filter’s after / before
window; the handler has checked the filter is one FilterCondition
with both. A synthetic instance id is opaque to the client and must
resolve in Task/get and Task/set (calendars-34 §5.11). With
expand_recurrences false, a recurring task is one id.
There is no default: one that ignored args would answer an
expansion request with unexpanded ids and read floating tasks in the
wrong zone (workspace AGENTS.md, “Default bodies on spec-semantic
backend methods”). A backend that cannot expand says so with
cannotCalculateOccurrences.
§Errors
BackendQueryError::Method
is returned to the client unchanged:
expandDurationTooLarge(JmapError::custom) when expansion is requested andbefore - afterexceedsTasksLimits::max_expanded_query_duration_seconds(the account’smaxExpandedQueryDuration, draft-tasks-06 §1.6.2). The handler checks this first, but the backend is canonical and MUST check it again (workspace AGENTS.md “Backend caps and limits”).cannotCalculateOccurrenceswhen a recurrence needed for the result cannot be expanded.- The RFC 8620 §5.5 errors (
unsupportedFilter,unsupportedSort,anchorNotFound, …), as forquery_objects.
BackendQueryError::Other
becomes a redacted serverFail.
Provided Methods§
Sourcefn compute_utc_times(
&self,
_caller: &Self::CallerCtx,
_account_id: &Id,
_task: &Task,
_tz_hint: Option<&str>,
) -> impl Future<Output = (Option<UTCDate>, Option<UTCDate>)> + Send
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
Compute utcStart and utcDue for a 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 values,
or None for each if the corresponding field is absent or the time zone
is unknown.
Task/get sends null for a requested utcStart / utcDue when the
task has no start / due (jmapio/jmap PR #464), whatever this
returns; when the local time is set and this returns None, the key
is left out, because null would say the local time is unset.
The default implementation returns (None, None) — backends that do not
support time-zone conversion can accept this behaviour, and Task/get
then omits the two properties for tasks that have a start / due.
Backends with full tz support should override this.
§Parameters
caller— the caller context. The default implementation ignores it.account_id— the target account. The default implementation ignores it, but backends MAY use it to look up an account-scoped tz database.task— the task whosestartandduefields are to be converted.tz_hint— the Task/gettimeZoneargument,Nonewhen the request has none, which means"Etc/UTC"(the CalendarEvent/get default, draft-ietf-jmap-calendars-34 §5.7). It applies only to a floating task (a nulltimeZone): “Floating tasks will be interpreted as per the time zone given as a Task/get argument” (draft-tasks-06 §4). A task with atimeZoneconverts with its own zone. The crate does not check the value against the IANA Time Zone Database; an unknown zone converts toNone.
Naming and signature mirror the canonical
CalendarsBackend::compute_utc_times
(bd:JMAP-ops7.25).
Sourcefn limits(&self, caller: &Self::CallerCtx, account_id: &Id) -> TasksLimits
fn limits(&self, caller: &Self::CallerCtx, account_id: &Id) -> TasksLimits
Implementation-defined caps for account_id as seen by caller
(workspace AGENTS.md “Backend caps and limits”). The default is
TasksLimits::default; override it to vary caps per account.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".
Implementors§
impl<C: MemoryCaller> TasksBackend for MemoryBackend<C>
memory only.