Skip to main content

TasksBackend

Trait TasksBackend 

Source
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§

Source

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,

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.

Source

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.

Source

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: true when the stored value is not true (false, or absent after a null patch) is invalidProperties naming isDraft: draft-tasks-06 §4 “This may only be set to true upon creation.” The Task/set handler does not pre-check this; the backend is the only enforcement point, in the same critical section that applies the patch.
  • A Task’s workflowStatus and progress follow decision 42 (crate::workflow::apply_workflow_status): a status not in the list’s workflowStatuses is invalidProperties when the patch sets it or moves the task; a progress value is mirrored into progress (return the Task as Some to echo it); a conflicting progress is invalidProperties. Run it in the same critical section, as create_object does 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.

Source

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”).

Source

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.

Source

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 with taskListHasTask.
  • Ok(false) — the task list is definitely empty. The handler forwards to destroy_object.
  • Err(_) — connectivity/transient failure. The handler maps this to serverFail so the client knows to retry. Returning Ok(false) for a transient backend failure is a bug: the destroy proceeds and any tasks that DID exist become silently orphaned.
§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.

Source

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.

Source

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 and before - after exceeds TasksLimits::max_expanded_query_duration_seconds (the account’s maxExpandedQueryDuration, 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”).
  • cannotCalculateOccurrences when a recurrence needed for the result cannot be expanded.
  • The RFC 8620 §5.5 errors (unsupportedFilter, unsupportedSort, anchorNotFound, …), as for query_objects.

BackendQueryError::Other becomes a redacted serverFail.

Provided Methods§

Source

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 whose start and due fields are to be converted.
  • tz_hint — the Task/get timeZone argument, None when 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 null timeZone): “Floating tasks will be interpreted as per the time zone given as a Task/get argument” (draft-tasks-06 §4). A task with a timeZone converts with its own zone. The crate does not check the value against the IANA Time Zone Database; an unknown zone converts to None.

Naming and signature mirror the canonical CalendarsBackend::compute_utc_times (bd:JMAP-ops7.25).

Source

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§

Source§

impl<C: MemoryCaller> TasksBackend for MemoryBackend<C>

Available on crate feature memory only.