Skip to main content

ExternalBackend

orch::backends

Trait ExternalBackend 

Source 
pub trait ExternalBackend: Send + Sync {

Show 28 methods    // Required methods
    fn name(&self) -> &str;
    fn create_task<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        title: &'life1 str,
        body: &'life2 str,
        labels: &'life3 [String],
    ) -> Pin<Box<dyn Future<Output = Result<ExternalId>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait;
    fn get_task<'life0, 'life1, 'async_trait>(
        &'life0 self,
        id: &'life1 ExternalId,
    ) -> Pin<Box<dyn Future<Output = Result<ExternalTask>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn list_by_status<'life0, 'async_trait>(
        &'life0 self,
        status: Status,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<ExternalTask>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn post_comment<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        id: &'life1 ExternalId,
        body: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn set_labels<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        id: &'life1 ExternalId,
        labels: &'life2 [String],
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn remove_label<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        id: &'life1 ExternalId,
        label: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn get_sub_issues<'life0, 'life1, 'async_trait>(
        &'life0 self,
        id: &'life1 ExternalId,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<ExternalId>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn health_check<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided methods
    fn update_status<'life0, 'life1, 'async_trait>(
        &'life0 self,
        id: &'life1 ExternalId,
        status: Status,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn list_all_tasks<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<ExternalTask>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn list_reconciliation_candidates<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<ExternalTask>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn list_routable<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<ExternalTask>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn list_active_open_issues<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _since: Option<&'life1 str>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<(ExternalTask, Option<Status>)>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn create_sub_task<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
        &'life0 self,
        parent_id: &'life1 ExternalId,
        title: &'life2 str,
        body: &'life3 str,
        labels: &'life4 [String],
    ) -> Pin<Box<dyn Future<Output = Result<ExternalId>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait,
             'life4: 'async_trait { ... }
    fn ensure_status_label<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _label: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn sync_to_project<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _id: &'life1 ExternalId,
        _status: Status,
    ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn reconcile_project_statuses<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn sync_estimate_to_project<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _id: &'life1 ExternalId,
        _estimate: u8,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn get_project_item_estimates<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _issue_node_ids: &'life1 [String],
    ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, u8>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn has_open_issue_with_title<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _title: &'life1 str,
        _label: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn is_pr_merged<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _branch: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn batch_is_pr_merged<'life0, 'life1, 'async_trait>(
        &'life0 self,
        branches: &'life1 [String],
    ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, bool>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn get_authenticated_user<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn get_mentions<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _since: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Mention>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn list_issue_comments<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _id: &'life1 ExternalId,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Mention>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn acknowledge_issue<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _id: &'life1 ExternalId,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn acknowledge_mention<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _comment_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }

}
Expand description

The core trait for external task backends.

Each implementation talks to a different issue tracker. The engine calls these methods without knowing which backend is active.

Required Methods§

Source

fn name(&self) -> &str

Human-readable name (e.g. “github”, “linear”, “jira”)

Source

fn create_task<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, title: &'life1 str, body: &'life2 str, labels: &'life3 [String], ) -> Pin<Box<dyn Future<Output = Result<ExternalId>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Create a task in the external system.

Source

fn get_task<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 ExternalId, ) -> Pin<Box<dyn Future<Output = Result<ExternalTask>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fetch a task by its external ID.

Source

fn list_by_status<'life0, 'async_trait>( &'life0 self, status: Status, ) -> Pin<Box<dyn Future<Output = Result<Vec<ExternalTask>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

List tasks by status.

Source

fn post_comment<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, id: &'life1 ExternalId, body: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Post a comment / activity note.

Source

fn set_labels<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, id: &'life1 ExternalId, labels: &'life2 [String], ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Add metadata labels / tags (additive — does not remove existing labels). The GitHub backend uses POST /repos/{repo}/issues/{number}/labels, which appends to the existing label set.

Source

fn remove_label<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, id: &'life1 ExternalId, label: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Remove a label / tag.

Source

fn get_sub_issues<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 ExternalId, ) -> Pin<Box<dyn Future<Output = Result<Vec<ExternalId>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get sub-issues (children) of a task.

Returns the list of external IDs for sub-issues. Empty list means no sub-issues or sub-issues not supported.

Source

fn health_check<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Check if connected and authenticated.

Provided Methods§

Source

fn update_status<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 ExternalId, status: Status, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Update task status using idempotent remove + add operations.

Default implementation retries up to 3 times with a fresh snapshot on each attempt to narrow the TOCTOU window. Backends that provide a native atomic status-update endpoint can override this.

The retry loop:

  1. Fetches a fresh label snapshot via get_task.
  2. Removes all status:* labels except the target via remove_label.
  3. Adds the target label via set_labels.

Note: labels removed in a previous attempt are already gone — the retry re-evaluates the current state rather than undoing prior work.

Source

fn list_all_tasks<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<ExternalTask>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

List all tasks (open and closed) in a single API call.

This is more efficient than calling list_by_status for each status when you need counts or details for all statuses.

Source

fn list_reconciliation_candidates<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<ExternalTask>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

List tasks for closed-issue reconciliation fallback.

Used when list_all_tasks fails (e.g., transient API issues). Default implementation returns an empty list, meaning no fallback data.

Source

fn list_routable<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<ExternalTask>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

List open tasks that are routable — no status:* label yet, or status:new.

Default implementation falls back to list_by_status(New).

Source

fn list_active_open_issues<'life0, 'life1, 'async_trait>( &'life0 self, _since: Option<&'life1 str>, ) -> Pin<Box<dyn Future<Output = Result<Vec<(ExternalTask, Option<Status>)>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fetch all open issues for ingest in a single logical call, returning each issue paired with its detected status (None = unlabeled/routable, Some(s) = has status label s).

When since is Some(ts), only returns issues updated after that ISO 8601 timestamp. This is more efficient for periodic syncs. Use None for full sync.

The default implementation calls list_routable() followed by list_by_status() for each active non-new status, deduplicating by ID. Backends that support bulk listing (e.g. GitHub) should override this to fetch all open issues in one API call and partition locally, eliminating the 1 + N fan-out.

Source

fn create_sub_task<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, parent_id: &'life1 ExternalId, title: &'life2 str, body: &'life3 str, labels: &'life4 [String], ) -> Pin<Box<dyn Future<Output = Result<ExternalId>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,

Create a child task and link it as a sub-issue of the parent.

Creates the task via create_task, then attempts to establish a native sub-issue relationship. Falls back to parent:{id} label if the native link fails.

Source

fn ensure_status_label<'life0, 'life1, 'async_trait>( &'life0 self, _label: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Ensure a status label exists in the backend system.

Called by the default update_status before applying labels. GitHub overrides this to auto-create labels on the repo. Default is a no-op.

Source

fn sync_to_project<'life0, 'life1, 'async_trait>( &'life0 self, _id: &'life1 ExternalId, _status: Status, ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Sync a task to the project board (if configured).

Called when a task is first ingested to ensure it appears on the project board immediately, not just when status changes later. Returns Some(node_id) if the item was added/updated on the project board, or None if project sync is not configured or failed. Default is a no-op returning None; GitHub backend implements project board sync.

Source

fn reconcile_project_statuses<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Repair project display state from authoritative external labels. Called by periodic and webhook-triggered sync, independent of ingestion. Does not transition tasks or dispatch agents. Default is a no-op.

Source

fn sync_estimate_to_project<'life0, 'life1, 'async_trait>( &'life0 self, _id: &'life1 ExternalId, _estimate: u8, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Sync a task’s estimate to the project board Estimate field.

Called after the router assigns an estimate to a task (via store_route). Writes the estimate value to GitHub Projects V2 so humans can see it on the board. Default is a no-op; GitHub backend implements estimate project sync.

Source

fn get_project_item_estimates<'life0, 'life1, 'async_trait>( &'life0 self, _issue_node_ids: &'life1 [String], ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, u8>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Batch-fetch project item estimates for a list of issue node IDs.

Returns a map from issue node ID → estimate value (0 if not set). Used during ingestion to populate tasks.estimate from GitHub Projects when the orch estimate is still 0. Default returns an empty map; GitHub backend implements batch estimate fetch.

Source

fn has_open_issue_with_title<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _title: &'life1 str, _label: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Check if an open issue with the given title already exists.

Used for deduplication before creating issues. The label parameter narrows the search to issues with a specific label. Default returns false (no dedup for backends that don’t support it).

Source

fn is_pr_merged<'life0, 'life1, 'async_trait>( &'life0 self, _branch: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Check if a PR/merge request for the given branch has been merged.

Returns false by default (backends that don’t track PRs).

Source

fn batch_is_pr_merged<'life0, 'life1, 'async_trait>( &'life0 self, branches: &'life1 [String], ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, bool>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Check if PRs for the given branches have been merged, in a single batch.

Returns a map of branch → merged. Backends that support batch queries (e.g. via GraphQL) should override this; the default falls back to serial is_pr_merged calls.

Source

fn get_authenticated_user<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Get the authenticated user’s username.

Returns None by default (backends that don’t support user identity).

Source

fn get_mentions<'life0, 'life1, 'async_trait>( &'life0 self, _since: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<Mention>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get recent mentions/comments since a given timestamp.

Returns empty by default (backends that don’t support mention scanning).

Source

fn list_issue_comments<'life0, 'life1, 'async_trait>( &'life0 self, _id: &'life1 ExternalId, ) -> Pin<Box<dyn Future<Output = Result<Vec<Mention>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get all comments for a specific task/issue.

Returns empty by default (backends that don’t support per-issue comment listing).

Source

fn acknowledge_issue<'life0, 'life1, 'async_trait>( &'life0 self, _id: &'life1 ExternalId, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Acknowledge a newly detected issue (e.g., add a reaction emoji).

Called when an issue is first ingested into the store. Default is a no-op; GitHub backend adds an eyes emoji reaction.

Source

fn acknowledge_mention<'life0, 'life1, 'async_trait>( &'life0 self, _comment_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Acknowledge a mention (comment) by reacting with the eyes emoji.

Called when a new @mention is detected in an issue or PR comment. Default is a no-op; GitHub backend adds an eyes emoji reaction to the comment.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§