crates/gunnar-proto/src/lib.rs
//! # gunnar-proto: the control-plane surface
//!
//! The `.proto` files in `proto/gunnar/v1/` and their `tonic-build` output.
//! This crate is generated code plus a small amount of hand-written glue; it
//! holds no behaviour. The service implementations live in `gunnar-grpc`.
//!
//! ## What is here
//!
//! Seven services:
//!
//! | service | what it owns |
//! |---|---|
//! | [`repos_client`] / [`repos_server`] | namespaces and repositories, i.e. the catalogue |
//! | [`refs_client`] / [`refs_server`] | refs, commit log, object reads, diffs. READ ONLY |
//! | [`access_client`] / [`access_server`] | principals, public keys, grants |
//! | [`policy_client`] / [`policy_server`] | branch protection, ref-name policy, gates |
//! | [`events_client`] / [`events_server`] | `Watch`, the server-streaming event feed |
//! | [`admin_client`] / [`admin_server`] | health, stats, storage backend info |
//! | [`mirror_client`] / [`mirror_server`] | pull-mirroring a remote forge |
//! | [`bootstrap_client`] / [`bootstrap_server`] | first-boot enrolment; the ONE unauthenticated service |
//! | [`forge_client`] / [`forge_server`] | issues, change proposals and review, as signed events |
//! | [`webhooks_client`] / [`webhooks_server`] | outbound webhook delivery to external URLs |
//!
//! ## Two invariants that hold across the whole surface
//!
//! **Namespaces are first class.** Every repo-scoped request and every
//! repo-scoped event carries a [`RepoPath`] of `<namespace>/<repo>`, matching
//! the SSH path `git@host:<namespace>/<repo>.git`. Multi-tenancy is in from
//! day 1 because adding it later would mean migrating every stored path and
//! every ACL row; adding it now costs one field.
//!
//! **No `google.protobuf.Any`.** [`Event`] carries an explicit `oneof` of named
//! payloads. A UI must be able to render an event without a type registry.
//!
//! ## What is deliberately absent
//!
//! There is no RPC that moves a ref. Refs move through `git-receive-pack` on
//! the SSH listener, behind the policy gate. A `Refs.Set` would route a
//! push around every gate, so it does not exist — see [`refs_server`].
#![doc(
html_logo_url = "https://gunnar.rs/download/gunnar.webp",
html_favicon_url = "https://gunnar.rs/download/favicon.svg"
)]
// Generated by `build.rs`. Both halves are built: dwarves and korp consume the
// client, `gunnar-grpc` implements the server.
#[allow(clippy::doc_overindented_list_items, clippy::doc_lazy_continuation)]
mod generated {
tonic::include_proto!("gunnar.v1");
}
pub use generated::*;
/// `gunnar/<version>`, the agent string reported by `Admin.Health`, written
/// into every [`PushAttestation`], and advertised as `agent=` on the git wire.
pub const AGENT: &str = concat!("gunnar/", env!("CARGO_PKG_VERSION"));
/// `HealthResponse.status` of a box with nothing to act on.
pub const HEALTH_SERVING: &str = "serving";
/// `HealthResponse.status` of a box that serves and needs an operator (see its alarms).
pub const HEALTH_MAINTENANCE: &str = "maintenance";
/// The all-zeroes oid: git's "this ref did not exist" / "this ref is being
/// deleted" sentinel. Length differs per hash kind, so use [`null_oid`].
pub fn null_oid(kind: HashKind) -> &'static str {
match kind {
HashKind::Sha256 => "0000000000000000000000000000000000000000000000000000000000000000",
// Unspecified is treated as sha1 here on purpose: an unspecified hash
// kind on the wire comes from an older peer, and sha1 is what those
// speak. Nothing writes an unspecified kind.
HashKind::Sha1 | HashKind::Unspecified => "0000000000000000000000000000000000000000",
}
}
/// Most components a repository path may have: up to three namespace levels
/// plus the repository name.
///
/// **This must equal `gunnar_core::sandbox::MAX_COMPONENTS`**, and there is no
/// construction that keeps it so: the two crates cannot depend on each other
/// (see `tests/nested_namespace.rs`). `the_component_bound_is_the_sandboxs_and_
/// not_a_second_number` is the guard that says they still agree; it reads the
/// real constant, so it goes red the day either side moves.
pub const MAX_COMPONENTS: usize = 4;
/// Why a `<namespace>/<repo>` string was rejected.
///
/// This is a *shape* check, not the SSH path sandbox. That one guards a
/// resolved filesystem-ish path and lives in `gunnar-core`. This one exists so
/// a malformed path is rejected at the edge of the control plane with a
/// specific reason rather than becoming a confusing NotFound. It is
/// deliberately the **laxer** of the two: everything the sandbox accepts must
/// pass here, and the sandbox itself is what refuses the rest one layer
/// down.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RepoPathError {
Empty,
/// No `/` at all, or a `/` in the repository half, which is one component
/// by definition however deeply the namespace nests.
NotTwoSegments,
EmptyNamespace,
EmptyRepo,
/// `.`, `..`, a NUL, a control character, a backslash or a colon.
IllegalCharacter(&'static str),
/// More than [`MAX_COMPONENTS`] components: namespace levels plus the
/// repository name.
TooManyComponents,
}
impl std::fmt::Display for RepoPathError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Empty => f.write_str("repository path is empty"),
Self::NotTwoSegments => {
f.write_str("repository path must be exactly `<namespace>/<repo>`")
}
Self::EmptyNamespace => f.write_str("namespace is empty"),
Self::EmptyRepo => f.write_str("repository name is empty"),
Self::IllegalCharacter(what) => write!(f, "illegal in a repository path: {what}"),
Self::TooManyComponents => write!(
f,
"repository path has more than {MAX_COMPONENTS} components"
),
}
}
}
impl std::error::Error for RepoPathError {}
/// **The one renderer of `gunnar issuer show`.**
///
/// Both halves of the verb print through this: the offline one, which builds
/// this message out of the data root under its feet, and the `--at` one, which
/// receives it over `Admin.IssuerInfo`. The lines are therefore identical by
/// construction rather than by two people keeping two `println!` blocks in
/// step — and "the box answers something different over the wire than it says
/// on its own disk" is not a state this verb can reach.
///
/// It lives in `gunnar-proto` because that is the one crate both the server
/// and the control client already depend on, and because the wire message IS
/// the shape of the answer; a renderer beside it in either crate would make
/// the other one the copy.
impl IssuerInfoResponse {
/// The `issuer show` report, ending in a newline.
///
/// `pem` additionally prints the issuer certificate itself, so it can be
/// piped straight to a client that needs to pin it.
pub fn render(&self, pem: bool) -> String {
let mut out = String::new();
if self.has_issuer {
out.push_str(&format!(
"issuer\t{}\t{}\t{}\n",
self.subject, self.fingerprint, self.origin
));
if pem {
out.push_str(&self.cert_pem);
if !self.cert_pem.ends_with('\n') {
out.push('\n');
}
}
} else {
out.push_str("no issuer. `gunnar issuer create` mints one\n");
}
// Printed even when it holds only the issuer, because "which CAs does
// this server verify against" is a different question from "which one
// does it mint with", and an operator mid-rotation is asking the first.
for ca in &self.trusted {
out.push_str(&format!(
"trusted\t{}\t{}\t{}\n",
ca.fingerprint,
if ca.is_issuer { "issuer" } else { "ca" },
ca.label
));
}
out
}
}
impl RepoPath {
pub fn new(namespace: impl Into<String>, repo: impl Into<String>) -> Self {
Self {
namespace: namespace.into(),
repo: repo.into(),
}
}
/// Parse `"<namespace>/<repo>"`, tolerating a trailing `.git` because that
/// is how the same repo is spelled over SSH.
///
/// **The split is at the LAST `/`.** A namespace may itself be nested, so
/// `team/sub/repo.git` is `team/sub` and `repo`. Nested
/// namespaces are first class and the SSH sandbox already serves them. A
/// `RepoPath` that could not spell one made those repositories invisible to
/// every gRPC consumer while `git` cloned them happily.
///
/// Rejects: empty halves, no `/` at all, more than [`MAX_COMPONENTS`]
/// components, `.`/`..`, NUL, control characters, `\` and `:`.
pub fn parse(s: &str) -> Result<Self, RepoPathError> {
let s = s.strip_suffix(".git").unwrap_or(s);
if s.is_empty() {
return Err(RepoPathError::Empty);
}
let Some((namespace, repo)) = s.rsplit_once('/') else {
return Err(RepoPathError::NotTwoSegments);
};
if namespace.is_empty() {
return Err(RepoPathError::EmptyNamespace);
}
if repo.is_empty() {
return Err(RepoPathError::EmptyRepo);
}
let path = Self::new(namespace, repo);
path.validate()?;
Ok(path)
}
/// The same checks [`RepoPath::parse`] applies, against an already-split
/// path, which is the form every request carries.
pub fn validate(&self) -> Result<(), RepoPathError> {
if self.namespace.is_empty() {
return Err(RepoPathError::EmptyNamespace);
}
if self.repo.is_empty() {
return Err(RepoPathError::EmptyRepo);
}
// The repository half is exactly one component, however deeply the
// namespace nests. A `/` here is a path that was split in the wrong
// place; `parse` splits at the last one for precisely this reason.
if self.repo.contains('/') {
return Err(RepoPathError::NotTwoSegments);
}
// Content before count, matching `gunnar_core::sandbox`: a traversal is
// reported as a traversal rather than as "too many components", because
// the reason ends up in a log line an operator has to act on.
let mut components = 0usize;
for segment in self.namespace.split('/').chain([self.repo.as_str()]) {
components += 1;
// A leading, trailing or doubled `/` in the namespace. The repo
// half was ruled out above, so this can only be a namespace level.
if segment.is_empty() {
return Err(RepoPathError::EmptyNamespace);
}
if segment == "." || segment == ".." {
return Err(RepoPathError::IllegalCharacter("`.` or `..`"));
}
if segment.contains('\0') {
return Err(RepoPathError::IllegalCharacter("a NUL byte"));
}
if segment.chars().any(char::is_control) {
return Err(RepoPathError::IllegalCharacter("a control character"));
}
if segment.contains('\\') {
return Err(RepoPathError::IllegalCharacter("a backslash"));
}
if segment.contains(':') {
return Err(RepoPathError::IllegalCharacter("a colon"));
}
}
if components > MAX_COMPONENTS {
return Err(RepoPathError::TooManyComponents);
}
Ok(())
}
}
impl std::fmt::Display for RepoPath {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}/{}", self.namespace, self.repo)
}
}
impl Event {
/// The [`EventKind`] a payload belongs to.
///
/// `Event.kind` is a separate field from the `oneof` so that a subscriber
/// can filter without matching, but two sources of truth is exactly the
/// shape that drifts. This is the one writer both go through (one
/// implementation), and [`Event::kind_matches_payload`] is the guard that
/// says they agree.
pub fn kind_of(payload: &event::Payload) -> EventKind {
match payload {
event::Payload::RefUpdated(_) => EventKind::RefUpdated,
event::Payload::RefDeleted(_) => EventKind::RefDeleted,
event::Payload::PushRejected(_) => EventKind::PushRejected,
event::Payload::RepoCreated(_) => EventKind::RepoCreated,
event::Payload::RepoDeleted(_) => EventKind::RepoDeleted,
event::Payload::MirrorSynced(_) => EventKind::MirrorSynced,
event::Payload::KeyUsed(_) => EventKind::KeyUsed,
event::Payload::PushAttestation(_) => EventKind::PushAttestation,
event::Payload::Gap(_) => EventKind::Gap,
event::Payload::ReplicationFailed(_) => EventKind::ReplicationFailed,
event::Payload::PullRequestOpened(_) => EventKind::PullRequestOpened,
event::Payload::PullRequestMerged(_) => EventKind::PullRequestMerged,
event::Payload::PullRequestClosed(_) => EventKind::PullRequestClosed,
event::Payload::StreamOpened(_) => EventKind::StreamOpened,
event::Payload::VisibilityChanged(_) => EventKind::VisibilityChanged,
event::Payload::EncryptedChanged(_) => EventKind::EncryptedChanged,
}
}
/// Build an event whose `kind` cannot disagree with its payload.
pub fn new(seq: u64, at_unix_ms: i64, payload: event::Payload) -> Self {
Self {
seq,
at_unix_ms,
kind: Self::kind_of(&payload) as i32,
payload: Some(payload),
}
}
/// False when `kind` and the payload variant disagree, or when the payload
/// is missing. Used by tests and by the bus as a cheap self-check.
pub fn kind_matches_payload(&self) -> bool {
match &self.payload {
Some(payload) => self.kind == Self::kind_of(payload) as i32,
None => false,
}
}
/// The repository this event is about, when it is about one. `KeyUsed` may
/// have none (an auth event is not repo-scoped), and neither `EventGap` nor
/// `StreamOpened` ever has: both are facts about the STREAM, not about a
/// repository.
pub fn repo_path(&self) -> Option<&RepoPath> {
match self.payload.as_ref()? {
event::Payload::RefUpdated(e) => e.repo.as_ref(),
event::Payload::RefDeleted(e) => e.repo.as_ref(),
event::Payload::PushRejected(e) => e.repo.as_ref(),
event::Payload::RepoCreated(e) => e.repo.as_ref()?.path.as_ref(),
event::Payload::RepoDeleted(e) => e.repo.as_ref(),
event::Payload::MirrorSynced(e) => e.repo.as_ref(),
event::Payload::KeyUsed(e) => e.repo.as_ref(),
event::Payload::PushAttestation(e) => e.repo.as_ref(),
event::Payload::Gap(_) => None,
event::Payload::ReplicationFailed(e) => e.repo.as_ref(),
event::Payload::PullRequestOpened(e) => e.repo.as_ref(),
event::Payload::PullRequestMerged(e) => e.repo.as_ref(),
event::Payload::PullRequestClosed(e) => e.repo.as_ref(),
event::Payload::StreamOpened(_) => None,
event::Payload::VisibilityChanged(e) => e.repo.as_ref(),
event::Payload::EncryptedChanged(e) => e.repo.as_ref(),
}
}
}
/// **The most of a peer's CLAIMED length this process reserves before the bytes arrive**
/// (2026-09-16, lane AUDIT-TWIN).
///
/// `LogChunk.blob_len` is a number the other end sent. Every reassembler in the tree used it
/// directly — `Vec::with_capacity(chunk.blob_len as usize)` — in `Bootstrap.Restore`'s handler,
/// in the twin's `Mirror.LogFetch` client and in the CLI's replay pump. A frame's blob is a
/// whole pack and may legitimately be gigabytes, so there is no honest ceiling on the VALUE;
/// there is one on what may be reserved on the strength of it, because the claim is checked
/// only after the item ends (`{} of {} blob bytes arrived`) — which is after the allocator has
/// already been asked.
///
/// What that cost, on the two shapes that matter:
///
/// * `u64::MAX` — `Vec::with_capacity` panics `capacity overflow` (over `isize::MAX`), and the
/// panic is inside a tonic handler, so the call dies and takes its connection with it;
/// * a merely impossible number, say 1 TiB on a 1 GiB appliance — no overflow, so the allocator
/// is asked for it, Linux's default overcommit heuristic refuses an obviously impossible
/// request, and a Rust allocation failure is not catchable: the PROCESS ABORTS.
///
/// `Bootstrap.Restore` is served WITHOUT a credential while a box is fresh — which is exactly
/// when it is sitting on the network waiting to be enrolled — so that abort is unauthenticated.
///
/// 8 MiB is eight `CHUNK_BYTES` pieces: the common case still reserves its blob in one go, and
/// a lie costs 8 MiB and a few `Vec` growths before the length check refuses it by name.
pub const TRUSTED_PREALLOC_BYTES: u64 = 8 << 20;
/// The tunnel answer as `key value` lines — what the SSH door prints and
/// `gunnar control tunnel` parses back ([`parse_tunnel_answer`]): the output of the
/// SSH door's `gunnar-tunnel-address` (2026-09-21, T17). One writer, one reader, both here.
pub fn render_tunnel_answer(a: &AssignTunnelAddressResponse) -> String {
format!(
"wg_public_key {}\naddress {}\nchanged {}\ntunnel_up {}\ndetail {}\n",
a.wg_public_key,
if a.address.is_empty() {
"-"
} else {
&a.address
},
a.changed,
a.tunnel_up,
a.detail.replace('\n', " ")
)
}
/// The inverse of [`render_tunnel_answer`]; `error: …` lines are the door's
/// refusal and come back as `Err`.
pub fn parse_tunnel_answer(text: &str) -> std::result::Result<AssignTunnelAddressResponse, String> {
if let Some(why) = text.lines().find_map(|l| l.strip_prefix("error: ")) {
return Err(why.to_string());
}
let mut a = AssignTunnelAddressResponse::default();
for line in text.lines() {
let (k, v) = line.split_once(' ').unwrap_or((line, ""));
match k {
"wg_public_key" => a.wg_public_key = v.to_string(),
"address" => {
a.address = if v == "-" {
String::new()
} else {
v.to_string()
}
}
"changed" => a.changed = v == "true",
"tunnel_up" => a.tunnel_up = v == "true",
"detail" => a.detail = v.to_string(),
_ => {}
}
}
if a.wg_public_key.is_empty() {
return Err(format!("not a tunnel answer: {text:?}"));
}
Ok(a)
}
/// How much to reserve for a blob the other end says is `claimed` bytes long. Never more than
/// [`TRUSTED_PREALLOC_BYTES`]; the rest is grown as the bytes actually arrive.
pub fn reserve_for(claimed: u64) -> usize {
claimed.min(TRUSTED_PREALLOC_BYTES) as usize
}
/// `812 MB/s` / `1.9 GB/s` — a `disk_seq_*_bps` field read as a human reads
/// it, in decimal units, as disks are sold.
///
/// It lives HERE, beside the fields, because two callers need the same
/// spelling and they are in different crates: the server's own
/// `disktest::fmt_rate` writes the console row, and `gunnar control capacity`
/// prints the wire field. A second spelling of a unit is a drift with no
/// symptom until two numbers that are equal read differently.
pub fn fmt_rate_bps(bps: u64) -> String {
let v = bps as f64;
if v >= 1e9 {
format!("{:.1} GB/s", v / 1e9)
} else if v >= 1e6 {
format!("{:.0} MB/s", v / 1e6)
} else {
format!("{:.0} kB/s", v / 1e3)
}
}
#[cfg(test)]
mod rate_tests {
/// The same three cases `gunnar_server::disktest::fmt_rate` is asserted
/// on, so the two spellings cannot drift apart unnoticed.
#[test]
fn a_rate_reads_in_the_units_disks_are_sold_in() {
assert_eq!(super::fmt_rate_bps(812_000_000), "812 MB/s");
assert_eq!(super::fmt_rate_bps(1_900_000_000), "1.9 GB/s");
assert_eq!(super::fmt_rate_bps(512_000), "512 kB/s");
}
}
#[cfg(test)]
mod prealloc_tests {
use super::*;
/// **A length a peer sent is not a length to allocate.**
///
/// Red with the old expression (`claimed as usize`): `u64::MAX` reaches
/// `Vec::with_capacity` and panics `capacity overflow` inside whatever handler is
/// reassembling — and `Bootstrap.Restore`'s handler needs no credential on a fresh box.
#[test]
fn a_claimed_length_never_becomes_a_reservation_on_its_own() {
for claimed in [u64::MAX, u64::MAX / 2, 1 << 40, (8 << 20) + 1] {
let reserved = reserve_for(claimed);
assert!(
reserved as u64 <= TRUSTED_PREALLOC_BYTES,
"{claimed} reserved {reserved}"
);
// The reservation is one the allocator will actually take.
let v: Vec<u8> = Vec::with_capacity(reserved);
assert!(v.capacity() >= reserved);
}
// An honest small length is still reserved exactly, so the common case allocates once.
for claimed in [0u64, 1, 4096, 8 << 20] {
assert_eq!(reserve_for(claimed) as u64, claimed);
}
}
}