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;
// Provided method
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 { ... }
}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
JmapBackend::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.
§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-04 §3.4). create is the request’s create
object for this copy (RFC 8620 §5.4). -04 §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 (-04 §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.
§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.
§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.
§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 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 (“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 draft-ietf-jmap-tasks-06 §3 defines as:
“The user may modify the following properties on all tasks in the task
list, even if they would not otherwise have permission to modify that
task.” 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.
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.
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 useJmapBackend::principal_idto resolve the caller’s preferred default time zone whentz_hintisNone.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 whosestartandduefields are to be converted.tz_hint— an optional IANA time-zone override; ifNone, the task’s owntime_zonefield (if any) is used.
Naming and signature mirror the canonical
CalendarsBackend::compute_utc_times
(bd:JMAP-ops7.25).
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".