Struct SubprocessSource 

pub struct SubprocessSource { /* private fields */ }

A source served by a spawned program speaking docs/plugin-protocol.md.

Implementations

impl SubprocessSource

pub fn connect( program: &str, args: &[String], name: &SourceName, config: &Value, secrets: BTreeMap<String, String>, ) -> Result<Self, SourceError>

Spawn program, complete the handshake, and adopt the connection.

Errors

Returns SourceError::Unavailable when the program cannot be run or stops answering, the plugin’s own error when it refuses the handshake, and SourceError::Config when the two sides do not speak the same protocol version — refused by name, never guessed at (§6.1).

pub fn connect_with_deadline( program: &str, args: &[String], name: &SourceName, config: &Value, secrets: BTreeMap<String, String>, deadline: RequestDeadline, ) -> Result<Self, SourceError>

Spawn a plugin with a deadline applying independently to every exchange.

Errors

What connect returns.

pub fn connect_with_deadlines( program: &str, args: &[String], name: &SourceName, config: &Value, secrets: BTreeMap<String, String>, handshake: RequestDeadline, requests: RequestDeadline, ) -> Result<Self, SourceError>

Spawn a plugin, bounding the initialization handshake and every later request separately.

handshake bounds the one initialize exchange of §3, and a newly spawned child does its own starting up inside that exchange: whatever a runtime loads before it can read its first line is counted against this bound. requests bounds every exchange after the handshake succeeded, each on its own, against a child that is by then already running. They are the same bound in connect_with_deadline and in every configured source, because one deadline_ms is what docs/plugin-protocol.md §1 gives a user to set. Separating them is for a caller that means to hold a request to a span shorter than a program takes to start — the engine’s own probe of what a silent child’s expired request reports — where one bound would fail the handshake on a loaded host instead of reaching the behaviour it was after.

Errors

What connect returns.

pub fn connect_from_document( program: &str, args: &[String], name: &SourceName, config: &Value, secrets: BTreeMap<String, String>, deadline: RequestDeadline, document_dir: Option<&Path>, ) -> Result<Self, SourceError>

Spawn a plugin, telling it which document’s directory its settings are measured from — document_dir in docs/plugin-protocol.md §3, sent only when there is one.

Errors

What connect returns, and SourceError::Config when document_dir is not an absolute directory whose name is valid UTF-8, and so cannot be written into the handshake — refused rather than dropped, because dropping it would silently measure the child’s paths from its working directory instead.

pub fn over( to_plugin: impl Write + Send + 'static, from_plugin: impl Read + Send + 'static, name: &SourceName, config: &Value, secrets: BTreeMap<String, String>, ) -> Result<Self, SourceError>

Connect to a plugin that is already running, over streams somebody else owns.

The handshake, the framing and every refusal are the same as connect’s, because they are the protocol’s rather than the process’s. What this constructor adds is the ability to hold the other end: it is how the engine’s own tests drive this half against serve over a real pipe, including the answers a well-behaved program would never give.

Errors

Returns what connect returns, minus the failures that belong to spawning a program.

pub fn over_with_request_deadline( to_plugin: impl Write + Send + 'static, from_plugin: impl Read + Send + 'static, name: &SourceName, config: &Value, secrets: BTreeMap<String, String>, deadline: RequestDeadline, ) -> Result<Self, SourceError>

Connect over existing streams with a deadline for requests after initialization.

Unlike connect_with_deadline, this engine does not own a process it can interrupt while the synchronous handshake is blocked. The supplied deadline therefore begins only after initialization succeeds.

Trait Implementations

impl Debug for SubprocessSource

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Named without its connection, which holds a live child and a credential the handshake forwarded — neither belongs in a diagnostic.

impl TaskSource for SubprocessSource

fn kind(&self) -> &'static str

The plugin kind that built this source, for display and for plan output.

fn capabilities(&self) -> Capabilities

What this source applies itself. Read once per query by the engine.

fn health<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Health, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Whether the source is answering right now.

fn get_task<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 NativeId, ) -> Pin<Box<dyn Future<Output = Result<Option<Task>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fetch one task by its native id, or None when there is no such task.

fn get_project<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 NativeId, ) -> Pin<Box<dyn Future<Output = Result<Option<Project>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fetch one project by its native id, or None when there is no such project.

fn query_tasks<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, query: &'life1 TaskQuery, page: &'life2 PageRequest, ) -> Pin<Box<dyn Future<Output = Result<Page<Task>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

One page of the tasks matching query.

fn query_projects<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, query: &'life1 ProjectQuery, page: &'life2 PageRequest, ) -> Pin<Box<dyn Future<Output = Result<Page<Project>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

One page of the projects matching query.

fn labels<'life0, 'life1, 'async_trait>( &'life0 self, page: &'life1 PageRequest, ) -> Pin<Box<dyn Future<Output = Result<Page<Label>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

One page of every label this source knows.

fn task_dependencies<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, id: &'life1 NativeId, direction: Direction, page: &'life2 PageRequest, ) -> Pin<Box<dyn Future<Output = Result<Page<DependencyEdge>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

One page of the task dependency edges at id, in direction.

fn project_dependencies<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, id: &'life1 NativeId, direction: Direction, page: &'life2 PageRequest, ) -> Pin<Box<dyn Future<Output = Result<Page<DependencyEdge>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

One page of the project dependency edges at id, in direction.

fn writes(&self) -> WriteSupport

Whether this source can be written through at all.

fn write_task<'life0, 'life1, 'async_trait>( &'life0 self, write: &'life1 ItemWrite<Task>, ) -> Pin<Box<dyn Future<Output = Result<NativeId, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Create or update one task, answering with the native id the destination holds it under.

fn write_project<'life0, 'life1, 'async_trait>( &'life0 self, write: &'life1 ItemWrite<Project>, ) -> Pin<Box<dyn Future<Output = Result<NativeId, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Create or update one project, on exactly the terms of write_task.

fn set_task_status<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 NativeId, category: StatusCategory, ) -> Pin<Box<dyn Future<Output = Result<Option<Status>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Set the status of one task this source holds, and change nothing else about it, answering with the status as this source now reads it — or None when this source holds no such task.

fn set_task_priority<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 NativeId, priority: Priority, ) -> Pin<Box<dyn Future<Output = Result<Option<Priority>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Set the priority of one task this source holds, and change nothing else about it, answering with the priority as this source now reads it — or None when this source holds no such task.

fn set_task_content<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, id: &'life1 NativeId, content: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Option<()>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Replace the content of one task this source holds with content, byte for byte, and change nothing else about it — or answer None when this source holds no such task.

fn set_delivered_by<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, id: &'life1 NativeId, delivered_by: &'life2 [TaskRef], ) -> Pin<Box<dyn Future<Output = Result<Option<()>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Replace the Task::delivered_by of one task this source holds, and change nothing else about it — or answer None when this source holds no such task.

fn set_task_metadata<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, id: &'life1 NativeId, key: &'life2 MetadataKey, value: &'life3 Value, ) -> Pin<Box<dyn Future<Output = Result<Option<Task>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Set one key of the metadata of one task this source holds, and change nothing else about it, answering with the task as this source reads it back after the write — or None when this source holds no such task.

fn set_project_metadata<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, id: &'life1 NativeId, key: &'life2 MetadataKey, value: &'life3 Value, ) -> Pin<Box<dyn Future<Output = Result<Option<Project>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Set one key of the metadata of one project this source holds, on exactly the terms of set_task_metadata.

fn set_document_metadata<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, id: &'life1 NativeId, key: &'life2 MetadataKey, value: &'life3 Value, ) -> Pin<Box<dyn Future<Output = Result<Option<Document>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Set one key of the metadata of one document this source holds, on exactly the terms of set_task_metadata.

fn task_template_answers<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 NativeId, ) -> Pin<Box<dyn Future<Output = Result<Option<BTreeMap<String, Value>>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

The template answers the task id was last rendered from, as this source keeps them beside the task — or None when it keeps none for it, or holds no such task.

fn document_template_answers<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 NativeId, ) -> Pin<Box<dyn Future<Output = Result<Option<BTreeMap<String, Value>>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

The template answers the document id was last rendered from, on exactly the terms of task_template_answers.

fn write_task_rendered<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, write: &'life1 ItemWrite<Task>, answers: &'life2 BTreeMap<String, Value>, ) -> Pin<Box<dyn Future<Output = Result<NativeId, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Create or update one task exactly as write_task does, keeping answers — the answers its content was rendered from — beside it in the same write where this source keeps answers at all.

fn write_document_rendered<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, write: &'life1 ItemWrite<Document>, answers: &'life2 BTreeMap<String, Value>, ) -> Pin<Box<dyn Future<Output = Result<NativeId, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Create or update one document, on exactly the terms of write_task_rendered.

fn set_task_rendering<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, id: &'life1 NativeId, content: &'life2 str, provenance: &'life3 Value, answers: &'life4 BTreeMap<String, Value>, ) -> Pin<Box<dyn Future<Output = Result<Option<()>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,

Replace one task’s rendering — its content, byte for byte, its MetadataKey::TEMPLATE_KEY entry, set to provenance, and the answers it keeps beside the task where it keeps any — in one write, and change nothing else about it; or answer None when this source holds no such task.

fn set_document_rendering<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, id: &'life1 NativeId, content: &'life2 str, provenance: &'life3 Value, answers: &'life4 BTreeMap<String, Value>, ) -> Pin<Box<dyn Future<Output = Result<Option<()>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,

Replace one document’s rendering, on exactly the terms of set_task_rendering. A source declaring Capabilities::documents unsupported is never asked.

fn delete_task<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 NativeId, ) -> Pin<Box<dyn Future<Output = Result<(), SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Remove one task this destination holds, so a copy that could not finish can put the destination back the way it found it.

fn delete_project<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 NativeId, ) -> Pin<Box<dyn Future<Output = Result<(), SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Remove one project this destination holds, on exactly the terms of delete_task.

fn get_document<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 NativeId, ) -> Pin<Box<dyn Future<Output = Result<Option<Document>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fetch one document by its native id, or None when there is no such document.

fn query_documents<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, query: &'life1 DocumentQuery, page: &'life2 PageRequest, ) -> Pin<Box<dyn Future<Output = Result<Page<Document>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

One page of the documents matching query.

fn write_document<'life0, 'life1, 'async_trait>( &'life0 self, write: &'life1 ItemWrite<Document>, ) -> Pin<Box<dyn Future<Output = Result<NativeId, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Create or update one document, on exactly the terms of write_task.

fn delete_document<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 NativeId, ) -> Pin<Box<dyn Future<Output = Result<(), SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Remove one document this destination holds, on exactly the terms of delete_task.

fn task_comments<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, task: &'life1 NativeId, page: &'life2 PageRequest, ) -> Pin<Box<dyn Future<Output = Result<Option<Page<Comment>>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

One page of the comments on task, oldest first, or None when this source holds no such task.

fn add_comment<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, task: &'life1 NativeId, comment: &'life2 NewComment, ) -> Pin<Box<dyn Future<Output = Result<Option<Comment>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Add one comment to task, answering with the comment as the source now holds it, or None when this source holds no such task.

fn edit_comment<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, task: &'life1 NativeId, comment: &'life2 NativeId, body: &'life3 CommentBody, ) -> Pin<Box<dyn Future<Output = Result<Option<Comment>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Replace the body of the comment comment on task, answering with the comment as the source now holds it, or None when this source holds no such task or that task has no such comment.

fn delete_comment<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, task: &'life1 NativeId, comment: &'life2 NativeId, ) -> Pin<Box<dyn Future<Output = Result<Option<NativeId>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Remove the comment comment from task, answering with the id it removed, or None when this source holds no such task or that task has no such comment.

fn metering<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Option<Metering>, SourceError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

What this source has sent to its backend since it was built and what that spent, or None when it does not meter its own requests.

fn keeps_template_answers(&self) -> bool

Whether this source keeps template answers beside its items at all.