pub struct RoutingLabels { /* private fields */ }Expand description
A policy’s routing label set: the token runs-on targets.
04-subsystem-contracts.md types this as Option<NonEmpty<Label>>. This
type is the NonEmpty<Label> half, and it is deliberately stronger than a
non-empty vector, because the contract has two separate requirements that a
bare NonEmpty only covers one of:
- Non-empty. Guaranteed by
RoutingLabels::host_labelalways existing.generate-jitconfigrejectslabels: []with422(docs/spikes/d18-org-jit-verification.md, Point 3), so an empty set is not a case to handle downstream. - The derived host label may not be dropped.
b1: “Optional descriptive labels may be added to the set; the derived host label may not be dropped from it.” AVec<Label>cannot express that. Here the host label is a separate field with no removal path, so dropping it is not a rule anyone has to remember.
The Option half of Option<NonEmpty<Label>> is carried by PolicyMode:
MonitorOnly has no routing labels because the variant has no field for
them, not because the field happens to be None.
Why the default is host-scoped. With no AcquireJobs, nothing reserves a
queued job for one host. Two hosts whose policies carry the same label will
both start a runner for the same job, and the loser pays a capacity slot and
a cold start (01-current-architecture.md, edge case 6). The host identity
baked into the derived label is the only control that prevents that by
default — the capacity ceilings only bound it once it happens.
Implementations§
Source§impl RoutingLabels
impl RoutingLabels
Sourcepub fn derive(host_label: &HostLabel, os: Os, arch: Arch) -> Self
pub fn derive(host_label: &HostLabel, os: Os, arch: Arch) -> Self
Derive the host-scoped default label, rm-<host>-<os>-<arch>.
02-target-architecture.md: “The label set … encodes the product, host
identity, and host OS — for example rm-home-win-x64.” Read against that
sentence the four segments are product / host identity / OS /
architecture, so --host-label home on a Windows x64 host derives
rm-home-win-x64.
Note that the worked command in 03-control-flows.md step 3 passes
--host-label home-win, which under this rule derives
rm-home-win-win-x64. That is a redundant example rather than a
different rule — b1’s Scope names the three inputs explicitly — but it
is recorded here because it is the obvious thing for a reader to trip on.
Sourcepub fn from_parts(
host_label: Label,
additional: impl IntoIterator<Item = Label>,
) -> Self
pub fn from_parts( host_label: Label, additional: impl IntoIterator<Item = Label>, ) -> Self
Build from an explicit host label, for the operator override f2
supports, and for b2 reloading a stored set.
This accepts any Label as the host label, including one that is not
host-scoped at all. “Host-scoped by construction” is a property of
Self::derive, not of this type: f2 deliberately supports an
operator override, so a hard rejection here would break a supported
workflow, and this is also the serde path, so b2 reaches it for every
stored row. A hand-edited row can therefore set host_label to
self-hosted, and Self::remove will then defend that as immovable
while two hosts happily serve each other’s jobs. Ask
Self::is_derived_shape before trusting the collision control.
Sourcepub fn from_host_label(host_label: Label) -> Self
pub fn from_host_label(host_label: Label) -> Self
Build from an explicit host label with no optional labels.
Sourcepub fn host_label(&self) -> &Label
pub fn host_label(&self) -> &Label
The one label that carries host identity and cannot be removed.
Sourcepub fn is_derived_shape(&self) -> bool
pub fn is_derived_shape(&self) -> bool
Whether the host label still has the shape Self::derive produces:
rm-<host>-<os>-<arch>, with the OS and architecture segments being
tokens this crate actually emits.
This is a warning predicate, not a validation rule. It is false for
an operator override, and an override is supported — f2 offers one on
purpose. What it detects is that the collision control has been turned
off: the derived shape is what keeps two hosts from answering each
other’s jobs, so a policy whose host label is self-hosted or
ubuntu-latest will route work that belongs to another machine, and
Self::remove will refuse to remove that label because it cannot tell
the difference. f2 and g2 should say so rather than fail; nothing
here rejects it.
Matching is structural rather than a check against a known host label, because the host label this was derived from is not stored — only the concatenation is.
The middle segments are not inspected, only counted. An earlier
version also required every one of them to be non-empty, meaning to
reject an empty host segment — but a HostLabel cannot be empty, so
that condition never rejected anything Self::derive could produce and
only ever produced false negatives: HostLabel::new("home--pc") is legal
(only a leading or trailing - is refused), derives
rm-home--pc-win-x64, and was reported as not derived. The consequence
was f2/g2 warning an operator that their collision control was off
when they had done nothing wrong, which is worse than the residual it
leaves: a hand-edited rm--win-x64 now reads as derived. That row is
still host-scoped in shape, so it does not mislead in the direction this
predicate exists to catch.
Sourcepub fn additional(&self) -> impl Iterator<Item = &Label>
pub fn additional(&self) -> impl Iterator<Item = &Label>
The optional descriptive labels, in sorted order.
Sourcepub fn add(&mut self, label: Label) -> bool
pub fn add(&mut self, label: Label) -> bool
Add an optional descriptive label. Returns false if it was already in
the set (including as the host label).
Sourcepub fn remove(&mut self, label: &Label) -> Result<bool, PolicyError>
pub fn remove(&mut self, label: &Label) -> Result<bool, PolicyError>
Remove an optional descriptive label.
§Errors
PolicyError::HostLabelNotRemovable when asked to remove the host
label. There is deliberately no override: this is the routing identity
that keeps two hosts from serving each other’s jobs.
pub fn contains(&self, label: &Label) -> bool
Sourcepub fn count(&self) -> NonZeroUsize
pub fn count(&self) -> NonZeroUsize
Never zero.
Sourcepub fn to_non_empty(&self) -> NonEmpty<Label>
pub fn to_non_empty(&self) -> NonEmpty<Label>
The same set in the shape 04-subsystem-contracts.md names.
Sourcepub fn as_registration_labels(&self) -> Vec<String>
pub fn as_registration_labels(&self) -> Vec<String>
The labels array for generate-jitconfig
(04-subsystem-contracts.md, “Generate JIT configuration”).
c4 sends exactly this. It matters that it is exactly this: the v1
spike established that no labels are added implicitly — the 201
carries the requested labels and nothing else, so a runner registered
from this array does not answer runs-on: self-hosted unless
self-hosted is in it (docs/spikes/d18-org-jit-verification.md,
Point 3, findings 1 and 2).
Sourcepub fn matches(&self, runs_on: &RunsOn) -> RunsOnMatch
pub fn matches(&self, runs_on: &RunsOn) -> RunsOnMatch
Decide whether this policy should serve a queued job.
GitHub assigns a job to a runner whose label set is a superset of the job’s required labels, so the predicate is subset-in-the-other-direction: the job’s required labels must all be present here.
Sourcepub fn tally<'a>(
&self,
jobs: impl IntoIterator<Item = &'a RunsOn>,
) -> DemandTally
pub fn tally<'a>( &self, jobs: impl IntoIterator<Item = &'a RunsOn>, ) -> DemandTally
Tally a poll’s worth of queued jobs into a demand signal.
The three counts are kept apart on purpose. An unresolvable runs-on is
neither counted as demand nor dropped: b1 requires it be “reported as
unresolvable rather than silently counted or silently dropped”, because
counting it would start a runner for a job that may not be ours and
dropping it would hide a workflow this host can never serve.
Trait Implementations§
Source§impl Clone for RoutingLabels
impl Clone for RoutingLabels
Source§fn clone(&self) -> RoutingLabels
fn clone(&self) -> RoutingLabels
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more