Trait Provider 

pub trait Provider: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn capabilities(&self) -> Capabilities;
    fn search(&self, query: &str) -> ProviderResult<Vec<SearchItem>>;
    fn org_repos(&self, org: &str) -> ProviderResult<Vec<RepoInfo>>;
    fn fetch_tree(
        &self,
        repo: &RepoId,
        ref_: Option<&GitRef>,
    ) -> ProviderResult<TreeResult>;
    fn fetch_blob(&self, repo: &RepoId, sha: &Sha) -> ProviderResult<Vec<u8>>;
    fn search_code(&self, q: &str) -> ProviderResult<SearchCodeResult>;
    fn clone_url(&self, repo: &RepoId) -> ProviderResult<String>;
    fn web_url(
        &self,
        repo: &RepoId,
        path: &str,
        branch: Option<&GitRef>,
        line: Option<u32>,
        end: Option<u32>,
        is_file: bool,
    ) -> ProviderResult<String>;
    fn org_url(&self, org: &str) -> ProviderResult<String>;

    // Provided methods
    fn source_tarball(&self, repo: &RepoId) -> ProviderResult<Vec<u8>> { ... }
    fn refs(&self, repo: &RepoId) -> ProviderResult<RepoRefs> { ... }
    fn log(
        &self,
        repo: &RepoId,
        path: Option<&str>,
        ref_: Option<&GitRef>,
        limit: Option<usize>,
    ) -> ProviderResult<(Vec<LogEntry>, bool)> { ... }
    fn blob_at(
        &self,
        repo: &RepoId,
        path: &str,
        ref_: Option<&GitRef>,
    ) -> ProviderResult<(Vec<u8>, Sha)> { ... }
    fn blame(
        &self,
        repo: &RepoId,
        path: &str,
        ref_: Option<&GitRef>,
    ) -> ProviderResult<Vec<BlameRange>> { ... }
    fn commit(&self, repo: &RepoId, sha: &Sha) -> ProviderResult<CommitDetail> { ... }
    fn icon(&self) -> Option<String> { ... }
    fn search_code_progressive(
        &self,
        q: &str,
        on_hits: &(dyn Fn(&[CodeMatch]) + Send + Sync),
    ) -> ProviderResult<SearchCodeResult> { ... }
    fn advise_cancel(&self) { ... }
    fn take_notice(&self) -> Option<String> { ... }
    fn cache_usage(&self) -> Option<u64> { ... }
}

The backend contract. Blocking; calls run on worker threads.

Required Methods

fn name(&self) -> &str

fn capabilities(&self) -> Capabilities

fn search(&self, query: &str) -> ProviderResult<Vec<SearchItem>>

Repo + org search for the launch popup (orgs first).

fn org_repos(&self, org: &str) -> ProviderResult<Vec<RepoInfo>>

Repo names of an org/group, with listing metadata when the backend reports it (v1.4).

fn fetch_tree( &self, repo: &RepoId, ref_: Option<&GitRef>, ) -> ProviderResult<TreeResult>

Full recursive tree of a repo — at ref (branch/tag/sha) when given (v1.5), else the default branch.

fn fetch_blob(&self, repo: &RepoId, sha: &Sha) -> ProviderResult<Vec<u8>>

Blob bytes by content id.

fn search_code(&self, q: &str) -> ProviderResult<SearchCodeResult>

Code search; q is the full query string with qualifiers.

fn clone_url(&self, repo: &RepoId) -> ProviderResult<String>

URL git clone accepts for a repo (clone wizard, plans/0004).

fn web_url( &self, repo: &RepoId, path: &str, branch: Option<&GitRef>, line: Option<u32>, end: Option<u32>, is_file: bool, ) -> ProviderResult<String>

Browser URL for yank (␣ y): repo root, or a path inside it. is_file picks the grammar (GitHub: blob vs tree); line adds a fragment when Some. branch is None for the default branch (the provider resolves it).

fn org_url(&self, org: &str) -> ProviderResult<String>

Browser URL for an org/group page.

Provided Methods

fn source_tarball(&self, repo: &RepoId) -> ProviderResult<Vec<u8>>

The repo’s default-branch source as a gzip tarball — fuel for the local-grep fallback when a repo-scoped code search returns nothing (GitHub’s index does not cover young/low-activity repos; the tree can’t lie, the index can). Optional: the default refuses and the fallback is simply unavailable — external providers grow it when the wire protocol does.

fn refs(&self, repo: &RepoId) -> ProviderResult<RepoRefs>

fn log( &self, repo: &RepoId, path: Option<&str>, ref_: Option<&GitRef>, limit: Option<usize>, ) -> ProviderResult<(Vec<LogEntry>, bool)>

v1.5: commit log, newest first; limit rides the bounded- compute contract — stop at ~N, the bool is truncated (capability log).

fn blob_at( &self, repo: &RepoId, path: &str, ref_: Option<&GitRef>, ) -> ProviderResult<(Vec<u8>, Sha)>

v1.5: file bytes + content id at a path and ref — the open-at-commit call (capability log’s companion).

fn blame( &self, repo: &RepoId, path: &str, ref_: Option<&GitRef>, ) -> ProviderResult<Vec<BlameRange>>

v1.5: blame ranges, 1-based inclusive, coalesced (capability blame).

fn commit(&self, repo: &RepoId, sha: &Sha) -> ProviderResult<CommitDetail>

v1.6 (plans/0028): one commit’s detail — message, changed files, unified hunks (capability commit).

fn icon(&self) -> Option<String>

Modeline icon: a builtin name (“github”, “gitlab”, “bitbucket”, “folder” — rendered as its Nerd Font glyph when nerd_font is on) or a single literal glyph the terminal can render. The provider declares its own (handshake icon, protocol v1.3); the in-tree github provider owns the one rootle hardcodes.

fn search_code_progressive( &self, q: &str, on_hits: &(dyn Fn(&[CodeMatch]) + Send + Sync), ) -> ProviderResult<SearchCodeResult>

Progressive code search (protocol v1.3, plans/0011): on_hits may fire from any thread, any number of times, strictly before this call returns. When the provider streamed, the result is metadata-only — hits empty, truncated authoritative. Default: one search_code call, one on_hits batch — every provider streams; page-shaped backends stream page-by-page.

fn advise_cancel(&self)

Advisory cancellation (protocol v1.1): tells the backend the caller no longer needs the in-flight request. Best-effort — replies may still arrive and are always handled. Default: nothing to cancel (in-process providers drop work via generations).

fn take_notice(&self) -> Option<String>

One-shot UI notice for the status line (plans/0008 §5) — e.g. a stdio child’s successful restart. Drained once per route. Default: nothing to say.

fn cache_usage(&self) -> Option<u64>

Cache usage the provider reported at initialize (bytes), when it participates in the advisory cache budget (protocol v1.2) — surfaced in :settings next to the provider row.

Dyn Compatibility

This trait is dyn compatible.

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

Implementors