Trait RemoteHost 

pub trait RemoteHost {
    // Required methods
    fn authenticated_user(&self) -> Result<String>;
    fn open_change(&self, req: ChangeSpec) -> Result<ChangeRequest>;
    fn find_changes(&self, head: &str, base: &str) -> Result<Vec<ChangeRequest>>;
    fn change_checks(&self, cr: &ChangeRequest) -> Result<ChangeChecks>;
    fn check_log(&self, cr: &ChangeRequest, check: &Check) -> Result<ArtifactId>;
    fn merge(
        &self,
        cr: &ChangeRequest,
        policy: MergePolicy,
    ) -> Result<MergeOutcome>;

    // Provided methods
    fn merged_at(&self, _cr: &ChangeRequest) -> Result<Option<Sha>> { ... }
    fn merge_time(&self, _cr: &ChangeRequest) -> Result<Option<String>> { ... }
    fn mergeability(&self, _cr: &ChangeRequest) -> Result<Mergeability> { ... }
    fn ready_for_review(&self, _cr: &ChangeRequest) -> Result<()> { ... }
    fn is_draft(&self, _cr: &ChangeRequest) -> Result<bool> { ... }
    fn required_checks_on(&self, _base: &str) -> Result<RequiredChecks> { ... }
    fn describe_change(
        &self,
        _cr: &ChangeRequest,
        _title: Option<&str>,
        _body: &str,
    ) -> Result<()> { ... }
    fn change_description(&self, _cr: &ChangeRequest) -> Result<Description> { ... }
}

Everything onevcs asks of a repository’s remote host.

Required Methods

fn authenticated_user(&self) -> Result<String>

Who the host believes is calling.

fn open_change(&self, req: ChangeSpec) -> Result<ChangeRequest>

Open a change request.

fn find_changes(&self, head: &str, base: &str) -> Result<Vec<ChangeRequest>>

Every open change request from head into base.

fn change_checks(&self, cr: &ChangeRequest) -> Result<ChangeChecks>

The checks the host is reporting on a change request, and which of its sources that answer was read from.

fn check_log(&self, cr: &ChangeRequest, check: &Check) -> Result<ArtifactId>

Store one check’s log as an artifact and return its id.

fn merge(&self, cr: &ChangeRequest, policy: MergePolicy) -> Result<MergeOutcome>

Merge a change request under a policy.

Provided Methods

fn merged_at(&self, _cr: &ChangeRequest) -> Result<Option<Sha>>

The commit a change request reached its base at, or None while the host has not merged it.

What a publication under change-auto watches. The host performs that merge on its own clock — merge arms it and answers MergeOutcome::Queued — so the only way to learn that it happened, and at which commit, is to ask again. None is “not yet” and never “somewhere else”: an implementation that cannot say must refuse rather than answer it.

Defaulted so that an implementation written against the earlier surface still compiles, and defaulted to the refusal this crate reserves for a seam with no body rather than to None — a host that was never taught to answer this has not said a change is unmerged, and a publication that read it that way would watch until its bound and then report checks that were never the reason.

fn merge_time(&self, _cr: &ChangeRequest) -> Result<Option<String>>

When the host says a merged change request reached its base, as the host spelled it, or None while it has not merged it.

What the record of a landing carries as landed_at, and the one way to learn it for a merge the host performed on its own clock — above all one this crate reconciles on a later read, whose landing time is the host’s and never the moment somebody asked.

Defaulted for the reason merged_at is — the seam stays additive — and to the same refusal. A caller reads that refusal as a host that cannot say, and records the landing’s time as unknown.

fn mergeability(&self, _cr: &ChangeRequest) -> Result<Mergeability>

Whether a change request can still merge into its base, as the host has computed it.

What a publication under change-auto reads beside merged_at while it waits for the merge it armed: a base that moved under the change so that it conflicts is a merge the host can never perform, and Mergeability::Conflicting ends that wait at once as a sync conflict rather than at the bound. Mergeability::Unknown is “not computed yet” and is never read as a conflict.

Defaulted for the reason merged_at is — the seam stays additive — and to the same refusal. A publication reads that refusal as a host that said nothing, which is no conflict, so a host written before this method watches exactly as it did.

fn ready_for_review(&self, _cr: &ChangeRequest) -> Result<()>

Take a change request out of its draft state, so the host will let it land.

What lifts a draft: a publication whose required checks came back green on it (or whose grace window elapsed with none run), onevcs change ready, and a publication adopting a draft with the lifecycle off. It is always asked before the host is asked to merge or arm a merge, because a host does neither to a draft.

Defaulted for the reason merged_at is — the seam stays additive — and to the same refusal: a host that was never taught to lift a draft has not lifted one, and answering Ok(()) would report a change as ready for review while the host goes on holding it.

fn is_draft(&self, _cr: &ChangeRequest) -> Result<bool>

Whether the host is holding this change request as a draft.

Asked on both sides of a draft’s life: after one is opened, because a host that ignored the request would otherwise leave a landable change reported as held back; and before one is lifted, so a change nobody drafted is asked for nothing and a second lift changes nothing.

Defaulted to the refusal, never to false: “this host was never taught to answer” and “this change is not a draft” are different facts, and only the second is a reason to go on and merge — which is what the Result around the answer carries, rather than a third value inside it.

The answer is a bool because the approved amendment in docs/contract.md declares this seam verbatim as -> Result<bool>: a named domain type here would be a public item the contract does not name, which this repository reports rather than takes. Nothing is lost to the shape — the third state a caller must not confuse with “not a draft” is “this host would not say”, and that is the Err arm rather than a value inside the Ok. Both call sites read it as one of three, and they are hold_as_draft and lift_any_draft in publish.rs.

fn required_checks_on(&self, _base: &str) -> Result<RequiredChecks>

The checks the repository requires before anything merges into base, asked of the branch itself rather than of a change request targeting it.

What onevcs repos --audit-gates names per identity. Which checks a repository requires is a setting on that repository, and a consumer that sequences its own work behind another repository’s merge path had to keep a copy of that list — which drifted the day the repository renamed a check, and cost a whole gate to discover. The host holds the list; this is how it is read.

The answer says which protection source it could not consult, because “this source found nothing” and “this merge path requires nothing” are opposite facts and only the second is safe to act on: an answer with a source in RequiredChecks::unconsulted is incomplete, and an empty one is unknown rather than none. A host that could read no source at all must refuse rather than answer, for the reason change_checks may not answer with an empty source list.

Defaulted for the reason merged_at is — the seam stays additive — and to the same refusal, which the audit reports as the list being unreadable rather than as no check being required.

fn describe_change( &self, _cr: &ChangeRequest, _title: Option<&str>, _body: &str, ) -> Result<()>

Replace a change request’s description: its body, and its title when one is given.

The one write to a change request’s prose after it exists. It writes exactly the caller’s bytes — nothing is composed around the body and nothing of a draft’s reason is rendered into it — because a body is what a reviewer reads and what a drafting caller may rewrite, and onevcs change describe is where a session’s own evidence reaches it.

Defaulted for the reason merged_at is — the seam stays additive — and to the same refusal: a host that was never taught to describe a change has not described one.

fn change_description(&self, _cr: &ChangeRequest) -> Result<Description>

What a change request’s description is now: its title and its body, as the host holds them.

The read beside describe_change, and what onevcs change show answers with: a caller that wrote a description needs to see what it wrote, and a caller finishing one off needs to see what it starts from.

Defaulted to the refusal for the reason every other added method is.

Dyn Compatibility

This trait is dyn compatible.

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

Implementors

impl RemoteHost for GitHub