crates/hub-api/src/lib.rs at 16cb2b3aa947 · andymccall/oxygenhub

# 16cb2b3aa947 oxygenhub / crates / hub-api / src / lib.rs

18.8 KiB · Rust · last changed Milestone 0.6: releases, Git mirror, code search, anchored API comments 1 month ago source blame history raw

//! Types of the Oxygenhub JSON API (hub spec §12.1). Everything here is
//! `serde` data with no behaviour, so clients in other languages can be
//! generated from it and the server can never drift from them.
//!
//! Shapes reuse `oxy --json`'s where one exists (hashes as lowercase hex,
//! times as milliseconds since the epoch), so tools written against the
//! command line work against the hub.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

/// A repository as the API lists it.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Repository {
    pub owner: String,
    pub name: String,
    pub description: String,
    pub default_bookmark: String,
    pub visibility: Visibility,
    /// Milliseconds since the epoch.
    pub created_ms: i64,
    pub updated_ms: i64,
    /// `https://…/{owner}/{name}`, what `oxy clone` takes.
    pub clone_url: String,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum Visibility {
    Public,
    Internal,
    Private,
}

impl Visibility {
    pub fn as_str(self) -> &'static str {
        match self {
            Visibility::Public => "public",
            Visibility::Internal => "internal",
            Visibility::Private => "private",
        }
    }

    pub fn parse(s: &str) -> Option<Visibility> {
        Some(match s {
            "public" => Visibility::Public,
            "internal" => Visibility::Internal,
            "private" => Visibility::Private,
            _ => return None,
        })
    }
}

/// A bookmark: a name for a set of heads (spec §10.1).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Bookmark {
    pub name: String,
    pub heads: Vec<String>,
    /// Number of changes in the bookmark's state.
    pub changes: usize,
    pub default: bool,
}

/// A tag: a name for one state, with its attestation when signed.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Tag {
    pub name: String,
    pub heads: Vec<String>,
    pub message: String,
    pub signer: Option<String>,
}

/// One change in a history listing.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ChangeSummary {
    pub hash: String,
    pub message: String,
    pub author: Author,
    pub when_ms: u64,
    pub deps: Vec<String>,
    pub head: bool,
    pub signature: Signature,
}

/// Who wrote a change: the linked account when the signing key is linked,
/// else the key alone.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Author {
    pub name: String,
    pub email: String,
    pub key: String,
    /// The hub account this key is linked to, when any.
    pub account: Option<String>,
}

/// Signature status of a change as `oxy verify` reports it.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "status", rename_all = "lowercase")]
pub enum Signature {
    Unsigned,
    Valid { key: String, sealed: bool, revoked: bool },
    Invalid { reason: String },
}

/// An RFC 7807 problem response.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Problem {
    pub status: u16,
    pub title: String,
    pub detail: String,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn visibility_round_trips() {
        for v in [Visibility::Public, Visibility::Internal, Visibility::Private] {
            assert_eq!(Visibility::parse(v.as_str()), Some(v));
        }
        assert_eq!(Visibility::parse("secret"), None);
    }
}

// ---------------------------------------------------------------- proposals

/// A proposal: a request to add changes to a target bookmark (hub spec §7).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Proposal {
    pub number: i64,
    pub title: String,
    pub body: String,
    pub author: String,
    pub state: ProposalState,
    pub target: String,
    pub source: ProposalSource,
    /// The changes the proposal adds, dependency order, newest last.
    pub changes: Vec<ChangeSummary>,
    /// Heads of the projected state (target plus the changes), when computed.
    pub projected_heads: Vec<String>,
    pub projected_state: Option<String>,
    pub conflicted: bool,
    pub approvals: Vec<Approval>,
    pub landable: bool,
    pub blockers: Vec<String>,
    pub created_ms: i64,
    pub updated_ms: i64,
    /// `https://hub/{owner}/{name}/proposal/{number}`.
    pub url: String,
    /// Where `oxy` fetches the changes from.
    pub repository_url: String,
    /// The fork's clone URL when the source is a fork.
    pub source_url: Option<String>,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum ProposalState {
    Draft,
    Open,
    Landed,
    Closed,
}

impl ProposalState {
    pub fn as_str(self) -> &'static str {
        match self {
            ProposalState::Draft => "draft",
            ProposalState::Open => "open",
            ProposalState::Landed => "landed",
            ProposalState::Closed => "closed",
        }
    }

    pub fn parse(s: &str) -> Option<ProposalState> {
        Some(match s {
            "draft" => ProposalState::Draft,
            "open" => ProposalState::Open,
            "landed" => ProposalState::Landed,
            "closed" => ProposalState::Closed,
            _ => return None,
        })
    }
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "kind", rename_all = "lowercase")]
pub enum ProposalSource {
    /// A bookmark of the same repository.
    Bookmark { bookmark: String },
    /// A bookmark of a fork.
    Fork { owner: String, name: String, bookmark: String },
    /// An explicit list of change hashes.
    Changes { hashes: Vec<String> },
}

/// A reviewer's approval, counted only when backed by a seal over every
/// change of the proposal signed with a key linked to the reviewer.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Approval {
    pub account: String,
    pub sealed: bool,
    pub key: Option<String>,
}

// ------------------------------------------------------------------ issues

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Issue {
    pub number: i64,
    pub title: String,
    pub body: String,
    pub author: String,
    pub state: String,
    pub reason: String,
    pub labels: Vec<Label>,
    pub assignees: Vec<String>,
    pub milestone: Option<String>,
    pub comments: i64,
    pub locked: bool,
    pub pinned: bool,
    pub created_ms: i64,
    pub updated_ms: i64,
    pub closed_ms: Option<i64>,
    pub url: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Label {
    pub name: String,
    pub colour: String,
    pub description: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Milestone {
    pub title: String,
    pub description: String,
    pub due_ms: Option<i64>,
    pub state: String,
    pub open: i64,
    pub closed: i64,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Comment {
    pub id: i64,
    pub author: String,
    pub body: String,
    pub created_ms: i64,
    /// For proposal comments: the file and the atom the comment anchors to.
    pub path: Option<String>,
    pub anchor: Option<Atom>,
    pub resolved: bool,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Atom {
    pub change: String,
    pub index: u32,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Review {
    pub id: i64,
    pub author: String,
    pub verdict: String,
    pub body: String,
    pub sealed: bool,
    pub created_ms: i64,
}

// ------------------------------------------------------------- repository

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct TreeEntry {
    pub name: String,
    pub path: String,
    pub kind: String,
    pub exec: bool,
    pub size: Option<u64>,
    pub conflicted: bool,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct BlameLine {
    pub line: usize,
    pub change: String,
    pub index: u32,
    pub author: String,
    pub when_ms: u64,
    pub text: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct FileChange {
    pub path: String,
    pub kind: String,
    pub from: Option<String>,
    pub added: usize,
    pub removed: usize,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ChangeDetail {
    pub change: ChangeSummary,
    pub body: String,
    pub dependents: Vec<String>,
    pub in_bookmarks: Vec<String>,
    pub in_tags: Vec<String>,
    pub files: Vec<FileChange>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct History {
    pub reference: String,
    pub heads: Vec<String>,
    pub total: usize,
    pub offset: usize,
    pub changes: Vec<ChangeSummary>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Conflict {
    pub bookmark: String,
    pub path: String,
    pub kind: String,
    pub contributors: Vec<String>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Push {
    pub at_ms: i64,
    pub pusher: String,
    pub reference: String,
    pub ok: bool,
    pub reason: String,
    pub old_state: String,
    pub new_state: String,
    pub heads: i64,
    pub changes: i64,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Trust {
    pub policy: Option<Policy>,
    pub signed: usize,
    pub sealed: usize,
    pub unsigned: usize,
    pub invalid: Vec<String>,
    pub hub_key: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Policy {
    pub serial: u64,
    pub expires_ms: u64,
    pub roots: Vec<String>,
    pub root_threshold: u32,
    pub rules: Vec<Rule>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Rule {
    pub pattern: String,
    pub keys: Vec<String>,
    pub threshold: u32,
    pub require: String,
    pub allow_conflicts: bool,
}

// ---------------------------------------------------------- hooks, checks

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Hook {
    pub id: i64,
    pub url: String,
    pub events: String,
    pub active: bool,
    pub created_ms: i64,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewHook {
    pub url: String,
    pub secret: String,
    #[serde(default = "star")]
    pub events: String,
}

fn star() -> String {
    "*".into()
}

/// A check on a state hash (hub spec §13.1).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Check {
    pub state: String,
    pub name: String,
    pub status: CheckStatus,
    pub summary: String,
    pub url: String,
    pub reporter: String,
    /// The seal attestation's reference when the checker sealed the changes.
    pub seal: Option<String>,
    pub started_ms: i64,
    pub finished_ms: Option<i64>,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum CheckStatus {
    Queued,
    Running,
    Passed,
    Failed,
    Cancelled,
    Skipped,
}

impl CheckStatus {
    pub fn as_str(self) -> &'static str {
        match self {
            CheckStatus::Queued => "queued",
            CheckStatus::Running => "running",
            CheckStatus::Passed => "passed",
            CheckStatus::Failed => "failed",
            CheckStatus::Cancelled => "cancelled",
            CheckStatus::Skipped => "skipped",
        }
    }

    pub fn parse(s: &str) -> Option<CheckStatus> {
        Some(match s {
            "queued" => CheckStatus::Queued,
            "running" => CheckStatus::Running,
            "passed" => CheckStatus::Passed,
            "failed" => CheckStatus::Failed,
            "cancelled" => CheckStatus::Cancelled,
            "skipped" => CheckStatus::Skipped,
            _ => return None,
        })
    }
}

/// What a checker posts.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewCheck {
    pub state: String,
    pub name: String,
    pub status: CheckStatus,
    #[serde(default)]
    pub summary: String,
    #[serde(default)]
    pub url: String,
    /// Hex of a seal attestation reference the checker pushed, if any.
    #[serde(default)]
    pub seal: Option<String>,
}

// ------------------------------------------------------------- accounts

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct User {
    pub username: String,
    pub display_name: String,
    pub is_admin: bool,
    pub keys: Vec<String>,
    pub created_ms: i64,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Organisation {
    pub name: String,
    pub display_name: String,
    pub description: String,
    pub members: Vec<String>,
}

/// Forms accepted by the write endpoints.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewRepository {
    pub owner: String,
    pub name: String,
    #[serde(default)]
    pub description: String,
    #[serde(default = "public")]
    pub visibility: Visibility,
}

fn public() -> Visibility {
    Visibility::Public
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewIssue {
    pub title: String,
    #[serde(default)]
    pub body: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewComment {
    pub body: String,
    /// For a proposal: anchor the comment to this file's line (1-based) of
    /// the projected state; the hub records the line's atom.
    #[serde(default)]
    pub path: Option<String>,
    #[serde(default)]
    pub line: Option<usize>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewProposal {
    pub title: String,
    #[serde(default)]
    pub body: String,
    pub target: String,
    /// A bookmark here, or `owner/name:bookmark` of a fork.
    pub source: String,
    #[serde(default)]
    pub draft: bool,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewReview {
    pub verdict: String,
    #[serde(default)]
    pub body: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct IssueStateChange {
    /// `open` or `closed`.
    pub state: String,
    #[serde(default)]
    pub reason: String,
}

/// A webhook payload's envelope (hub spec §12.2).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct WebhookEnvelope {
    pub event: String,
    pub delivery: String,
    pub repository: Option<Repository>,
    pub actor: String,
    pub at_ms: i64,
    pub data: serde_json::Value,
}

/// A server-sent event on a proposal's stream.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProposalEvent {
    pub number: i64,
    pub kind: String,
    pub check: Option<Check>,
}

// --------------------------------------------------------------- releases

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Release {
    pub tag: String,
    pub title: String,
    pub notes: String,
    pub prerelease: bool,
    pub latest: bool,
    pub author: String,
    pub heads: Vec<String>,
    pub signer: Option<String>,
    pub assets: Vec<ReleaseAsset>,
    pub archives: Vec<String>,
    pub created_ms: i64,
    pub url: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ReleaseAsset {
    pub name: String,
    pub size: i64,
    /// BLAKE3 of the content, hex.
    pub hash: String,
    pub content_type: String,
    pub downloads: i64,
    pub url: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewRelease {
    pub tag: String,
    pub title: String,
    #[serde(default)]
    pub notes: Option<String>,
    #[serde(default)]
    pub prerelease: bool,
}

/// Every type of the API, for schema generation.
pub fn schemas() -> Vec<(&'static str, schemars::Schema)> {
    vec![
        ("Repository", schemars::schema_for!(Repository)),
        ("Visibility", schemars::schema_for!(Visibility)),
        ("Bookmark", schemars::schema_for!(Bookmark)),
        ("Tag", schemars::schema_for!(Tag)),
        ("ChangeSummary", schemars::schema_for!(ChangeSummary)),
        ("Author", schemars::schema_for!(Author)),
        ("Signature", schemars::schema_for!(Signature)),
        ("Problem", schemars::schema_for!(Problem)),
        ("Proposal", schemars::schema_for!(Proposal)),
        ("ProposalState", schemars::schema_for!(ProposalState)),
        ("ProposalSource", schemars::schema_for!(ProposalSource)),
        ("Approval", schemars::schema_for!(Approval)),
        ("Issue", schemars::schema_for!(Issue)),
        ("Label", schemars::schema_for!(Label)),
        ("Milestone", schemars::schema_for!(Milestone)),
        ("Comment", schemars::schema_for!(Comment)),
        ("Atom", schemars::schema_for!(Atom)),
        ("Review", schemars::schema_for!(Review)),
        ("TreeEntry", schemars::schema_for!(TreeEntry)),
        ("BlameLine", schemars::schema_for!(BlameLine)),
        ("FileChange", schemars::schema_for!(FileChange)),
        ("ChangeDetail", schemars::schema_for!(ChangeDetail)),
        ("History", schemars::schema_for!(History)),
        ("Conflict", schemars::schema_for!(Conflict)),
        ("Push", schemars::schema_for!(Push)),
        ("Trust", schemars::schema_for!(Trust)),
        ("Policy", schemars::schema_for!(Policy)),
        ("Rule", schemars::schema_for!(Rule)),
        ("Hook", schemars::schema_for!(Hook)),
        ("NewHook", schemars::schema_for!(NewHook)),
        ("Check", schemars::schema_for!(Check)),
        ("CheckStatus", schemars::schema_for!(CheckStatus)),
        ("NewCheck", schemars::schema_for!(NewCheck)),
        ("User", schemars::schema_for!(User)),
        ("Organisation", schemars::schema_for!(Organisation)),
        ("NewRepository", schemars::schema_for!(NewRepository)),
        ("NewIssue", schemars::schema_for!(NewIssue)),
        ("NewComment", schemars::schema_for!(NewComment)),
        ("NewProposal", schemars::schema_for!(NewProposal)),
        ("NewReview", schemars::schema_for!(NewReview)),
        ("IssueStateChange", schemars::schema_for!(IssueStateChange)),
        ("WebhookEnvelope", schemars::schema_for!(WebhookEnvelope)),
        ("ProposalEvent", schemars::schema_for!(ProposalEvent)),
        ("Release", schemars::schema_for!(Release)),
        ("ReleaseAsset", schemars::schema_for!(ReleaseAsset)),
        ("NewRelease", schemars::schema_for!(NewRelease)),
    ]
}

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

1	//! Types of the Oxygenhub JSON API (hub spec §12.1). Everything here is
2	//! `serde` data with no behaviour, so clients in other languages can be
3	//! generated from it and the server can never drift from them.
4	//!
5	//! Shapes reuse `oxy --json`'s where one exists (hashes as lowercase hex,
6	//! times as milliseconds since the epoch), so tools written against the
7	//! command line work against the hub.
8
9	use schemars::JsonSchema;
10	use serde::{Deserialize, Serialize};
11
12	/// A repository as the API lists it.
13	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
14	pub struct Repository {
15	pub owner: String,
16	pub name: String,
17	pub description: String,
18	pub default_bookmark: String,
19	pub visibility: Visibility,
20	/// Milliseconds since the epoch.
21	pub created_ms: i64,
22	pub updated_ms: i64,
23	/// `https://…/{owner}/{name}`, what `oxy clone` takes.
24	pub clone_url: String,
25	}
26
27	#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
28	#[serde(rename_all = "lowercase")]
29	pub enum Visibility {
30	Public,
31	Internal,
32	Private,
33	}
34
35	impl Visibility {
36	pub fn as_str(self) -> &'static str {
37	match self {
38	Visibility::Public => "public",
39	Visibility::Internal => "internal",
40	Visibility::Private => "private",
41	}
42	}
43
44	pub fn parse(s: &str) -> Option<Visibility> {
45	Some(match s {
46	"public" => Visibility::Public,
47	"internal" => Visibility::Internal,
48	"private" => Visibility::Private,
49	_ => return None,
50	})
51	}
52	}
53
54	/// A bookmark: a name for a set of heads (spec §10.1).
55	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
56	pub struct Bookmark {
57	pub name: String,
58	pub heads: Vec<String>,
59	/// Number of changes in the bookmark's state.
60	pub changes: usize,
61	pub default: bool,
62	}
63
64	/// A tag: a name for one state, with its attestation when signed.
65	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
66	pub struct Tag {
67	pub name: String,
68	pub heads: Vec<String>,
69	pub message: String,
70	pub signer: Option<String>,
71	}
72
73	/// One change in a history listing.
74	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
75	pub struct ChangeSummary {
76	pub hash: String,
77	pub message: String,
78	pub author: Author,
79	pub when_ms: u64,
80	pub deps: Vec<String>,
81	pub head: bool,
82	pub signature: Signature,
83	}
84
85	/// Who wrote a change: the linked account when the signing key is linked,
86	/// else the key alone.
87	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
88	pub struct Author {
89	pub name: String,
90	pub email: String,
91	pub key: String,
92	/// The hub account this key is linked to, when any.
93	pub account: Option<String>,
94	}
95
96	/// Signature status of a change as `oxy verify` reports it.
97	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
98	#[serde(tag = "status", rename_all = "lowercase")]
99	pub enum Signature {
100	Unsigned,
101	Valid { key: String, sealed: bool, revoked: bool },
102	Invalid { reason: String },
103	}
104
105	/// An RFC 7807 problem response.
106	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
107	pub struct Problem {
108	pub status: u16,
109	pub title: String,
110	pub detail: String,
111	}
112
113	#[cfg(test)]
114	mod tests {
115	use super::*;
116
117	#[test]
118	fn visibility_round_trips() {
119	for v in [Visibility::Public, Visibility::Internal, Visibility::Private] {
120	assert_eq!(Visibility::parse(v.as_str()), Some(v));
121	}
122	assert_eq!(Visibility::parse("secret"), None);
123	}
124	}
125
126	// ---------------------------------------------------------------- proposals
127
128	/// A proposal: a request to add changes to a target bookmark (hub spec §7).
129	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
130	pub struct Proposal {
131	pub number: i64,
132	pub title: String,
133	pub body: String,
134	pub author: String,
135	pub state: ProposalState,
136	pub target: String,
137	pub source: ProposalSource,
138	/// The changes the proposal adds, dependency order, newest last.
139	pub changes: Vec<ChangeSummary>,
140	/// Heads of the projected state (target plus the changes), when computed.
141	pub projected_heads: Vec<String>,
142	pub projected_state: Option<String>,
143	pub conflicted: bool,
144	pub approvals: Vec<Approval>,
145	pub landable: bool,
146	pub blockers: Vec<String>,
147	pub created_ms: i64,
148	pub updated_ms: i64,
149	/// `https://hub/{owner}/{name}/proposal/{number}`.
150	pub url: String,
151	/// Where `oxy` fetches the changes from.
152	pub repository_url: String,
153	/// The fork's clone URL when the source is a fork.
154	pub source_url: Option<String>,
155	}
156
157	#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
158	#[serde(rename_all = "lowercase")]
159	pub enum ProposalState {
160	Draft,
161	Open,
162	Landed,
163	Closed,
164	}
165
166	impl ProposalState {
167	pub fn as_str(self) -> &'static str {
168	match self {
169	ProposalState::Draft => "draft",
170	ProposalState::Open => "open",
171	ProposalState::Landed => "landed",
172	ProposalState::Closed => "closed",
173	}
174	}
175
176	pub fn parse(s: &str) -> Option<ProposalState> {
177	Some(match s {
178	"draft" => ProposalState::Draft,
179	"open" => ProposalState::Open,
180	"landed" => ProposalState::Landed,
181	"closed" => ProposalState::Closed,
182	_ => return None,
183	})
184	}
185	}
186
187	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
188	#[serde(tag = "kind", rename_all = "lowercase")]
189	pub enum ProposalSource {
190	/// A bookmark of the same repository.
191	Bookmark { bookmark: String },
192	/// A bookmark of a fork.
193	Fork { owner: String, name: String, bookmark: String },
194	/// An explicit list of change hashes.
195	Changes { hashes: Vec<String> },
196	}
197
198	/// A reviewer's approval, counted only when backed by a seal over every
199	/// change of the proposal signed with a key linked to the reviewer.
200	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
201	pub struct Approval {
202	pub account: String,
203	pub sealed: bool,
204	pub key: Option<String>,
205	}
206
207	// ------------------------------------------------------------------ issues
208
209	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
210	pub struct Issue {
211	pub number: i64,
212	pub title: String,
213	pub body: String,
214	pub author: String,
215	pub state: String,
216	pub reason: String,
217	pub labels: Vec<Label>,
218	pub assignees: Vec<String>,
219	pub milestone: Option<String>,
220	pub comments: i64,
221	pub locked: bool,
222	pub pinned: bool,
223	pub created_ms: i64,
224	pub updated_ms: i64,
225	pub closed_ms: Option<i64>,
226	pub url: String,
227	}
228
229	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
230	pub struct Label {
231	pub name: String,
232	pub colour: String,
233	pub description: String,
234	}
235
236	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
237	pub struct Milestone {
238	pub title: String,
239	pub description: String,
240	pub due_ms: Option<i64>,
241	pub state: String,
242	pub open: i64,
243	pub closed: i64,
244	}
245
246	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
247	pub struct Comment {
248	pub id: i64,
249	pub author: String,
250	pub body: String,
251	pub created_ms: i64,
252	/// For proposal comments: the file and the atom the comment anchors to.
253	pub path: Option<String>,
254	pub anchor: Option<Atom>,
255	pub resolved: bool,
256	}
257
258	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
259	pub struct Atom {
260	pub change: String,
261	pub index: u32,
262	}
263
264	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
265	pub struct Review {
266	pub id: i64,
267	pub author: String,
268	pub verdict: String,
269	pub body: String,
270	pub sealed: bool,
271	pub created_ms: i64,
272	}
273
274	// ------------------------------------------------------------- repository
275
276	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
277	pub struct TreeEntry {
278	pub name: String,
279	pub path: String,
280	pub kind: String,
281	pub exec: bool,
282	pub size: Option<u64>,
283	pub conflicted: bool,
284	}
285
286	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
287	pub struct BlameLine {
288	pub line: usize,
289	pub change: String,
290	pub index: u32,
291	pub author: String,
292	pub when_ms: u64,
293	pub text: String,
294	}
295
296	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
297	pub struct FileChange {
298	pub path: String,
299	pub kind: String,
300	pub from: Option<String>,
301	pub added: usize,
302	pub removed: usize,
303	}
304
305	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
306	pub struct ChangeDetail {
307	pub change: ChangeSummary,
308	pub body: String,
309	pub dependents: Vec<String>,
310	pub in_bookmarks: Vec<String>,
311	pub in_tags: Vec<String>,
312	pub files: Vec<FileChange>,
313	}
314
315	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
316	pub struct History {
317	pub reference: String,
318	pub heads: Vec<String>,
319	pub total: usize,
320	pub offset: usize,
321	pub changes: Vec<ChangeSummary>,
322	}
323
324	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
325	pub struct Conflict {
326	pub bookmark: String,
327	pub path: String,
328	pub kind: String,
329	pub contributors: Vec<String>,
330	}
331
332	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
333	pub struct Push {
334	pub at_ms: i64,
335	pub pusher: String,
336	pub reference: String,
337	pub ok: bool,
338	pub reason: String,
339	pub old_state: String,
340	pub new_state: String,
341	pub heads: i64,
342	pub changes: i64,
343	}
344
345	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
346	pub struct Trust {
347	pub policy: Option<Policy>,
348	pub signed: usize,
349	pub sealed: usize,
350	pub unsigned: usize,
351	pub invalid: Vec<String>,
352	pub hub_key: String,
353	}
354
355	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
356	pub struct Policy {
357	pub serial: u64,
358	pub expires_ms: u64,
359	pub roots: Vec<String>,
360	pub root_threshold: u32,
361	pub rules: Vec<Rule>,
362	}
363
364	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
365	pub struct Rule {
366	pub pattern: String,
367	pub keys: Vec<String>,
368	pub threshold: u32,
369	pub require: String,
370	pub allow_conflicts: bool,
371	}
372
373	// ---------------------------------------------------------- hooks, checks
374
375	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
376	pub struct Hook {
377	pub id: i64,
378	pub url: String,
379	pub events: String,
380	pub active: bool,
381	pub created_ms: i64,
382	}
383
384	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
385	pub struct NewHook {
386	pub url: String,
387	pub secret: String,
388	#[serde(default = "star")]
389	pub events: String,
390	}
391
392	fn star() -> String {
393	"*".into()
394	}
395
396	/// A check on a state hash (hub spec §13.1).
397	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
398	pub struct Check {
399	pub state: String,
400	pub name: String,
401	pub status: CheckStatus,
402	pub summary: String,
403	pub url: String,
404	pub reporter: String,
405	/// The seal attestation's reference when the checker sealed the changes.
406	pub seal: Option<String>,
407	pub started_ms: i64,
408	pub finished_ms: Option<i64>,
409	}
410
411	#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
412	#[serde(rename_all = "lowercase")]
413	pub enum CheckStatus {
414	Queued,
415	Running,
416	Passed,
417	Failed,
418	Cancelled,
419	Skipped,
420	}
421
422	impl CheckStatus {
423	pub fn as_str(self) -> &'static str {
424	match self {
425	CheckStatus::Queued => "queued",
426	CheckStatus::Running => "running",
427	CheckStatus::Passed => "passed",
428	CheckStatus::Failed => "failed",
429	CheckStatus::Cancelled => "cancelled",
430	CheckStatus::Skipped => "skipped",
431	}
432	}
433
434	pub fn parse(s: &str) -> Option<CheckStatus> {
435	Some(match s {
436	"queued" => CheckStatus::Queued,
437	"running" => CheckStatus::Running,
438	"passed" => CheckStatus::Passed,
439	"failed" => CheckStatus::Failed,
440	"cancelled" => CheckStatus::Cancelled,
441	"skipped" => CheckStatus::Skipped,
442	_ => return None,
443	})
444	}
445	}
446
447	/// What a checker posts.
448	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
449	pub struct NewCheck {
450	pub state: String,
451	pub name: String,
452	pub status: CheckStatus,
453	#[serde(default)]
454	pub summary: String,
455	#[serde(default)]
456	pub url: String,
457	/// Hex of a seal attestation reference the checker pushed, if any.
458	#[serde(default)]
459	pub seal: Option<String>,
460	}
461
462	// ------------------------------------------------------------- accounts
463
464	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
465	pub struct User {
466	pub username: String,
467	pub display_name: String,
468	pub is_admin: bool,
469	pub keys: Vec<String>,
470	pub created_ms: i64,
471	}
472
473	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
474	pub struct Organisation {
475	pub name: String,
476	pub display_name: String,
477	pub description: String,
478	pub members: Vec<String>,
479	}
480
481	/// Forms accepted by the write endpoints.
482	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
483	pub struct NewRepository {
484	pub owner: String,
485	pub name: String,
486	#[serde(default)]
487	pub description: String,
488	#[serde(default = "public")]
489	pub visibility: Visibility,
490	}
491
492	fn public() -> Visibility {
493	Visibility::Public
494	}
495
496	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
497	pub struct NewIssue {
498	pub title: String,
499	#[serde(default)]
500	pub body: String,
501	}
502
503	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
504	pub struct NewComment {
505	pub body: String,
506	/// For a proposal: anchor the comment to this file's line (1-based) of
507	/// the projected state; the hub records the line's atom.
508	#[serde(default)]
509	pub path: Option<String>,
510	#[serde(default)]
511	pub line: Option<usize>,
512	}
513
514	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
515	pub struct NewProposal {
516	pub title: String,
517	#[serde(default)]
518	pub body: String,
519	pub target: String,
520	/// A bookmark here, or `owner/name:bookmark` of a fork.
521	pub source: String,
522	#[serde(default)]
523	pub draft: bool,
524	}
525
526	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
527	pub struct NewReview {
528	pub verdict: String,
529	#[serde(default)]
530	pub body: String,
531	}
532
533	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
534	pub struct IssueStateChange {
535	/// `open` or `closed`.
536	pub state: String,
537	#[serde(default)]
538	pub reason: String,
539	}
540
541	/// A webhook payload's envelope (hub spec §12.2).
542	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
543	pub struct WebhookEnvelope {
544	pub event: String,
545	pub delivery: String,
546	pub repository: Option<Repository>,
547	pub actor: String,
548	pub at_ms: i64,
549	pub data: serde_json::Value,
550	}
551
552	/// A server-sent event on a proposal's stream.
553	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
554	pub struct ProposalEvent {
555	pub number: i64,
556	pub kind: String,
557	pub check: Option<Check>,
558	}
559
560	// --------------------------------------------------------------- releases
561
562	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
563	pub struct Release {
564	pub tag: String,
565	pub title: String,
566	pub notes: String,
567	pub prerelease: bool,
568	pub latest: bool,
569	pub author: String,
570	pub heads: Vec<String>,
571	pub signer: Option<String>,
572	pub assets: Vec<ReleaseAsset>,
573	pub archives: Vec<String>,
574	pub created_ms: i64,
575	pub url: String,
576	}
577
578	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
579	pub struct ReleaseAsset {
580	pub name: String,
581	pub size: i64,
582	/// BLAKE3 of the content, hex.
583	pub hash: String,
584	pub content_type: String,
585	pub downloads: i64,
586	pub url: String,
587	}
588
589	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
590	pub struct NewRelease {
591	pub tag: String,
592	pub title: String,
593	#[serde(default)]
594	pub notes: Option<String>,
595	#[serde(default)]
596	pub prerelease: bool,
597	}
598
599	/// Every type of the API, for schema generation.
600	pub fn schemas() -> Vec<(&'static str, schemars::Schema)> {
601	vec![
602	("Repository", schemars::schema_for!(Repository)),
603	("Visibility", schemars::schema_for!(Visibility)),
604	("Bookmark", schemars::schema_for!(Bookmark)),
605	("Tag", schemars::schema_for!(Tag)),
606	("ChangeSummary", schemars::schema_for!(ChangeSummary)),
607	("Author", schemars::schema_for!(Author)),
608	("Signature", schemars::schema_for!(Signature)),
609	("Problem", schemars::schema_for!(Problem)),
610	("Proposal", schemars::schema_for!(Proposal)),
611	("ProposalState", schemars::schema_for!(ProposalState)),
612	("ProposalSource", schemars::schema_for!(ProposalSource)),
613	("Approval", schemars::schema_for!(Approval)),
614	("Issue", schemars::schema_for!(Issue)),
615	("Label", schemars::schema_for!(Label)),
616	("Milestone", schemars::schema_for!(Milestone)),
617	("Comment", schemars::schema_for!(Comment)),
618	("Atom", schemars::schema_for!(Atom)),
619	("Review", schemars::schema_for!(Review)),
620	("TreeEntry", schemars::schema_for!(TreeEntry)),
621	("BlameLine", schemars::schema_for!(BlameLine)),
622	("FileChange", schemars::schema_for!(FileChange)),
623	("ChangeDetail", schemars::schema_for!(ChangeDetail)),
624	("History", schemars::schema_for!(History)),
625	("Conflict", schemars::schema_for!(Conflict)),
626	("Push", schemars::schema_for!(Push)),
627	("Trust", schemars::schema_for!(Trust)),
628	("Policy", schemars::schema_for!(Policy)),
629	("Rule", schemars::schema_for!(Rule)),
630	("Hook", schemars::schema_for!(Hook)),
631	("NewHook", schemars::schema_for!(NewHook)),
632	("Check", schemars::schema_for!(Check)),
633	("CheckStatus", schemars::schema_for!(CheckStatus)),
634	("NewCheck", schemars::schema_for!(NewCheck)),
635	("User", schemars::schema_for!(User)),
636	("Organisation", schemars::schema_for!(Organisation)),
637	("NewRepository", schemars::schema_for!(NewRepository)),
638	("NewIssue", schemars::schema_for!(NewIssue)),
639	("NewComment", schemars::schema_for!(NewComment)),
640	("NewProposal", schemars::schema_for!(NewProposal)),
641	("NewReview", schemars::schema_for!(NewReview)),
642	("IssueStateChange", schemars::schema_for!(IssueStateChange)),
643	("WebhookEnvelope", schemars::schema_for!(WebhookEnvelope)),
644	("ProposalEvent", schemars::schema_for!(ProposalEvent)),
645	("Release", schemars::schema_for!(Release)),
646	("ReleaseAsset", schemars::schema_for!(ReleaseAsset)),
647	("NewRelease", schemars::schema_for!(NewRelease)),
648	]
649	}

Keyboard