Struct Engine 

pub struct Engine { /* private fields */ }

The sources a configuration resolved to, and the queries they answer.

Implementations

impl Engine

pub async fn task_detail( &self, id: &GlobalId, ) -> Result<TaskDetail, EngineError>

One task by its qualified id, with its comments when its source has them.

The task is read exactly as task reads it, and the comments are read only once the task was found — a source declaring no comments is never asked.

Errors

As task. A comment read that fails is not an error: it lands in the response’s errors beside the task that was read.

pub async fn comments( &self, task: &GlobalId, ) -> Result<CommentList, EngineError>

Every comment on one task, oldest first.

Errors

Returns EngineError::NoComments for a source whose tasks have none, before anything is read; EngineError::NoSuchTask when the source holds no such task; and EngineError::SourceFailed when the source could not answer.

pub async fn add_comment( &self, task: &GlobalId, comment: &NewComment, ) -> Result<Comment, EngineError>

Add one comment to a task, answering with the comment as its source now holds it.

Errors

As comments, plus EngineError::CommentsNotWritable for a source whose comments cannot be written, before anything is written.

pub async fn edit_comment( &self, task: &GlobalId, comment: &NativeId, body: &CommentBody, ) -> Result<Comment, EngineError>

Replace one comment’s body, answering with the comment as its source now holds it.

Errors

As add_comment, plus EngineError::NoSuchComment when the task has no comment under comment.

pub async fn delete_comment( &self, task: &GlobalId, comment: &NativeId, ) -> Result<DeletedComment, EngineError>

Remove one comment from a task, answering with the id it removed.

Errors

As edit_comment.

impl Engine

pub async fn copy( &self, request: &CopyRequest, ) -> Result<CopyReport, EngineError>

Copy every item a request names into one configured destination.

This is the whole of the verb, and the command line drives exactly this: a copy a Rust caller makes and a copy typed at a shell are the same call, so the two cannot answer the same copy differently.

Errors

Returns EngineError when the destination is not configured, cannot be built, cannot be written, or — for a document copy — declares it has no documents; when an id names nothing; when an origin names an item the destination no longer holds and --recreate was not given; and when the destination refuses the write — including a field or a metadata key it cannot carry, which it names rather than dropping.

impl Engine

pub async fn set_task_status( &self, id: &GlobalId, category: StatusCategory, ) -> Result<TaskStatusSet, EngineError>

Set one task’s status, and nothing else about it, then keep every task it delivers in step with it.

Errors

Returns EngineError::UnknownSource for a source nothing configures, EngineError::StatusNotWritable for one with no write side, EngineError::NoSuchTask when the task is not there, and EngineError::SourceFailed when the source refuses — a category it has disabled included. A delivered task that cannot be kept in step is not an error: it is reported failed beside the status that was set.

impl Engine

pub async fn set_task_metadata( &self, id: &GlobalId, key: &MetadataKey, value: &Value, ) -> Result<MetadataSet, EngineError>

Set one key of one task’s metadata, and nothing else about it.

Errors

Returns EngineError::UnknownSource for a source nothing configures, EngineError::MetadataNotWritable for one with no write side, EngineError::NoSuchTask when the task is not there, and EngineError::SourceFailed when the source refuses — a plugin that cannot write one key on its own included.

pub async fn set_project_metadata( &self, id: &GlobalId, key: &MetadataKey, value: &Value, ) -> Result<MetadataSet, EngineError>

Set one key of one project’s metadata, and nothing else about it.

Errors

As set_task_metadata, with EngineError::NoSuchProject when the project is not there.

pub async fn set_document_metadata( &self, id: &GlobalId, key: &MetadataKey, value: &Value, ) -> Result<MetadataSet, EngineError>

Set one key of one document’s metadata, and nothing else about it.

Errors

As set_task_metadata, with EngineError::NoDocuments for a source declaring it has none — which is never asked — and EngineError::NoSuchDocument when the document is not there.

impl Engine

pub fn build(config: &Config, secrets: &dyn SecretResolver) -> Self

Build every source a configuration names.

A source whose plugin refuses to build — a credential that is not there, a plugin whose implementation has not landed — is not fatal: it becomes an entry in every response’s errors, exactly as a source that fails mid-query does, and the other sources still answer. A user with three sources and one expired token gets the other two rather than nothing.

pub fn new(sources: Vec<ConfiguredSource>, selection: Vec<SourceName>) -> Self

Drive sources built elsewhere — the engine’s own tests, and any caller holding a source it did not resolve from a configuration document.

pub fn listing(&self) -> Vec<SourceListing>

Every configured source, whether or not it built, in name order.

pub fn has(&self, name: &SourceName) -> bool

Whether this configuration has a source called name, built or not.

A caller reading a --project argument needs this: urn:project:1 is a qualified id only if urn is a source here, and a native id full of colons otherwise. That rule cannot be applied without knowing what is configured.

pub async fn tasks( &self, request: &TaskRequest, ) -> Result<QueryResponse<Qualified<Task>>, EngineError>

One page of tasks.

Errors

Returns EngineError when the request names a source nothing configures, or carries a page token this engine did not issue. One source failing is not an error: it lands in the response’s errors.

pub async fn projects( &self, request: &ProjectRequest, ) -> Result<QueryResponse<Qualified<Project>>, EngineError>

One page of projects.

Errors

As tasks.

pub async fn documents( &self, request: &DocumentRequest, ) -> Result<QueryResponse<Qualified<Document>>, EngineError>

One page of documents.

A source declaring it has no documents is not asked: the declaration is read once here, that source contributes no rows, and the plan reports Predicate::Document unavailable for it. So a document list spanning a mixed set of sources answers with what the document-bearing ones hold and says nothing alarming about the others — the same shape a source with no project table takes.

Errors

As tasks.

pub async fn labels( &self, request: &LabelRequest, ) -> Result<QueryResponse<Qualified<Label>>, EngineError>

One page of labels.

Errors

As tasks.

pub async fn search( &self, request: &SearchRequest, ) -> Result<QueryResponse<SearchHit>, EngineError>

One page of search hits, over tasks, projects, or both.

Errors

As tasks.

pub async fn task( &self, id: &GlobalId, ) -> Result<QueryResponse<Qualified<Task>>, EngineError>

One task by its qualified id, or an empty page when there is no such task.

Errors

Returns EngineError::UnknownSource when the id names a source nothing configures.

pub async fn project( &self, id: &GlobalId, ) -> Result<QueryResponse<Qualified<Project>>, EngineError>

One project by its qualified id, or an empty page when there is no such project.

Errors

As task.

pub async fn document( &self, id: &GlobalId, ) -> Result<QueryResponse<Qualified<Document>>, EngineError>

One document by its qualified id, or an empty page when there is no such document.

A source declaring it has no documents holds none, so it is not asked and the answer is the empty page with Predicate::Document reported unavailable — the same answer the list verb gives, rather than a failure.

Errors

As task.

pub async fn task_dependencies( &self, request: &DependencyRequest, ) -> Result<QueryResponse<QualifiedEdge>, EngineError>

One page of a task’s dependency edges.

Errors

As task, plus EngineError::Token for a page token this engine did not issue.

pub async fn project_dependencies( &self, request: &DependencyRequest, ) -> Result<QueryResponse<QualifiedEdge>, EngineError>

One page of a project’s dependency edges.

Errors

As task_dependencies.