crates/hub-api/src/lib.rs at 3f02e5ea4f2d · andymccall/oxygenhub

# 3f02e5ea4f2d oxygenhub / crates / hub-api / src / lib.rs

18.0 KiB · Rust · last changed API: a proposal's files and each side's bytes 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,
}

/// A file a proposal changes, between the target's state and the
/// projected state (hub spec §7.2). Fetch either side's bytes from
/// `/proposals/{number}/content/{base|head}/{path}`.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProposalFile {
    pub path: String,
    /// For a rename, the path in the target's state.
    pub from: Option<String>,
    /// `added`, `removed`, `modified`, `renamed`, `mode` or `replaced`.
    pub kind: String,
    pub added: usize,
    pub removed: usize,
}

#[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,
}

#[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>,
}

/// 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)),
        ("ProposalFile", schemars::schema_for!(ProposalFile)),
        ("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)),
    ]
}

`/`	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	/// A file a proposal changes, between the target's state and the
259	/// projected state (hub spec §7.2). Fetch either side's bytes from
260	/// `/proposals/{number}/content/{base\|head}/{path}`.
261	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
262	pub struct ProposalFile {
263	pub path: String,
264	/// For a rename, the path in the target's state.
265	pub from: Option<String>,
266	/// `added`, `removed`, `modified`, `renamed`, `mode` or `replaced`.
267	pub kind: String,
268	pub added: usize,
269	pub removed: usize,
270	}
271
272	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
273	pub struct Atom {
274	pub change: String,
275	pub index: u32,
276	}
277
278	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
279	pub struct Review {
280	pub id: i64,
281	pub author: String,
282	pub verdict: String,
283	pub body: String,
284	pub sealed: bool,
285	pub created_ms: i64,
286	}
287
288	// ------------------------------------------------------------- repository
289
290	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
291	pub struct TreeEntry {
292	pub name: String,
293	pub path: String,
294	pub kind: String,
295	pub exec: bool,
296	pub size: Option<u64>,
297	pub conflicted: bool,
298	}
299
300	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
301	pub struct BlameLine {
302	pub line: usize,
303	pub change: String,
304	pub index: u32,
305	pub author: String,
306	pub when_ms: u64,
307	pub text: String,
308	}
309
310	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
311	pub struct FileChange {
312	pub path: String,
313	pub kind: String,
314	pub from: Option<String>,
315	pub added: usize,
316	pub removed: usize,
317	}
318
319	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
320	pub struct ChangeDetail {
321	pub change: ChangeSummary,
322	pub body: String,
323	pub dependents: Vec<String>,
324	pub in_bookmarks: Vec<String>,
325	pub in_tags: Vec<String>,
326	pub files: Vec<FileChange>,
327	}
328
329	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
330	pub struct History {
331	pub reference: String,
332	pub heads: Vec<String>,
333	pub total: usize,
334	pub offset: usize,
335	pub changes: Vec<ChangeSummary>,
336	}
337
338	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
339	pub struct Conflict {
340	pub bookmark: String,
341	pub path: String,
342	pub kind: String,
343	pub contributors: Vec<String>,
344	}
345
346	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
347	pub struct Push {
348	pub at_ms: i64,
349	pub pusher: String,
350	pub reference: String,
351	pub ok: bool,
352	pub reason: String,
353	pub old_state: String,
354	pub new_state: String,
355	pub heads: i64,
356	pub changes: i64,
357	}
358
359	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
360	pub struct Trust {
361	pub policy: Option<Policy>,
362	pub signed: usize,
363	pub sealed: usize,
364	pub unsigned: usize,
365	pub invalid: Vec<String>,
366	pub hub_key: String,
367	}
368
369	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
370	pub struct Policy {
371	pub serial: u64,
372	pub expires_ms: u64,
373	pub roots: Vec<String>,
374	pub root_threshold: u32,
375	pub rules: Vec<Rule>,
376	}
377
378	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
379	pub struct Rule {
380	pub pattern: String,
381	pub keys: Vec<String>,
382	pub threshold: u32,
383	pub require: String,
384	pub allow_conflicts: bool,
385	}
386
387	// ---------------------------------------------------------- hooks, checks
388
389	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
390	pub struct Hook {
391	pub id: i64,
392	pub url: String,
393	pub events: String,
394	pub active: bool,
395	pub created_ms: i64,
396	}
397
398	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
399	pub struct NewHook {
400	pub url: String,
401	pub secret: String,
402	#[serde(default = "star")]
403	pub events: String,
404	}
405
406	fn star() -> String {
407	"*".into()
408	}
409
410	/// A check on a state hash (hub spec §13.1).
411	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
412	pub struct Check {
413	pub state: String,
414	pub name: String,
415	pub status: CheckStatus,
416	pub summary: String,
417	pub url: String,
418	pub reporter: String,
419	/// The seal attestation's reference when the checker sealed the changes.
420	pub seal: Option<String>,
421	pub started_ms: i64,
422	pub finished_ms: Option<i64>,
423	}
424
425	#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
426	#[serde(rename_all = "lowercase")]
427	pub enum CheckStatus {
428	Queued,
429	Running,
430	Passed,
431	Failed,
432	Cancelled,
433	Skipped,
434	}
435
436	impl CheckStatus {
437	pub fn as_str(self) -> &'static str {
438	match self {
439	CheckStatus::Queued => "queued",
440	CheckStatus::Running => "running",
441	CheckStatus::Passed => "passed",
442	CheckStatus::Failed => "failed",
443	CheckStatus::Cancelled => "cancelled",
444	CheckStatus::Skipped => "skipped",
445	}
446	}
447
448	pub fn parse(s: &str) -> Option<CheckStatus> {
449	Some(match s {
450	"queued" => CheckStatus::Queued,
451	"running" => CheckStatus::Running,
452	"passed" => CheckStatus::Passed,
453	"failed" => CheckStatus::Failed,
454	"cancelled" => CheckStatus::Cancelled,
455	"skipped" => CheckStatus::Skipped,
456	_ => return None,
457	})
458	}
459	}
460
461	/// What a checker posts.
462	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
463	pub struct NewCheck {
464	pub state: String,
465	pub name: String,
466	pub status: CheckStatus,
467	#[serde(default)]
468	pub summary: String,
469	#[serde(default)]
470	pub url: String,
471	/// Hex of a seal attestation reference the checker pushed, if any.
472	#[serde(default)]
473	pub seal: Option<String>,
474	}
475
476	// ------------------------------------------------------------- accounts
477
478	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
479	pub struct User {
480	pub username: String,
481	pub display_name: String,
482	pub is_admin: bool,
483	pub keys: Vec<String>,
484	pub created_ms: i64,
485	}
486
487	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
488	pub struct Organisation {
489	pub name: String,
490	pub display_name: String,
491	pub description: String,
492	pub members: Vec<String>,
493	}
494
495	/// Forms accepted by the write endpoints.
496	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
497	pub struct NewRepository {
498	pub owner: String,
499	pub name: String,
500	#[serde(default)]
501	pub description: String,
502	#[serde(default = "public")]
503	pub visibility: Visibility,
504	}
505
506	fn public() -> Visibility {
507	Visibility::Public
508	}
509
510	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
511	pub struct NewIssue {
512	pub title: String,
513	#[serde(default)]
514	pub body: String,
515	}
516
517	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
518	pub struct NewComment {
519	pub body: String,
520	}
521
522	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
523	pub struct NewProposal {
524	pub title: String,
525	#[serde(default)]
526	pub body: String,
527	pub target: String,
528	/// A bookmark here, or `owner/name:bookmark` of a fork.
529	pub source: String,
530	#[serde(default)]
531	pub draft: bool,
532	}
533
534	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
535	pub struct NewReview {
536	pub verdict: String,
537	#[serde(default)]
538	pub body: String,
539	}
540
541	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
542	pub struct IssueStateChange {
543	/// `open` or `closed`.
544	pub state: String,
545	#[serde(default)]
546	pub reason: String,
547	}
548
549	/// A webhook payload's envelope (hub spec §12.2).
550	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
551	pub struct WebhookEnvelope {
552	pub event: String,
553	pub delivery: String,
554	pub repository: Option<Repository>,
555	pub actor: String,
556	pub at_ms: i64,
557	pub data: serde_json::Value,
558	}
559
560	/// A server-sent event on a proposal's stream.
561	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
562	pub struct ProposalEvent {
563	pub number: i64,
564	pub kind: String,
565	pub check: Option<Check>,
566	}
567
568	/// Every type of the API, for schema generation.
569	pub fn schemas() -> Vec<(&'static str, schemars::Schema)> {
570	vec![
571	("Repository", schemars::schema_for!(Repository)),
572	("Visibility", schemars::schema_for!(Visibility)),
573	("Bookmark", schemars::schema_for!(Bookmark)),
574	("Tag", schemars::schema_for!(Tag)),
575	("ChangeSummary", schemars::schema_for!(ChangeSummary)),
576	("Author", schemars::schema_for!(Author)),
577	("Signature", schemars::schema_for!(Signature)),
578	("Problem", schemars::schema_for!(Problem)),
579	("Proposal", schemars::schema_for!(Proposal)),
580	("ProposalState", schemars::schema_for!(ProposalState)),
581	("ProposalSource", schemars::schema_for!(ProposalSource)),
582	("Approval", schemars::schema_for!(Approval)),
583	("Issue", schemars::schema_for!(Issue)),
584	("Label", schemars::schema_for!(Label)),
585	("Milestone", schemars::schema_for!(Milestone)),
586	("Comment", schemars::schema_for!(Comment)),
587	("ProposalFile", schemars::schema_for!(ProposalFile)),
588	("Atom", schemars::schema_for!(Atom)),
589	("Review", schemars::schema_for!(Review)),
590	("TreeEntry", schemars::schema_for!(TreeEntry)),
591	("BlameLine", schemars::schema_for!(BlameLine)),
592	("FileChange", schemars::schema_for!(FileChange)),
593	("ChangeDetail", schemars::schema_for!(ChangeDetail)),
594	("History", schemars::schema_for!(History)),
595	("Conflict", schemars::schema_for!(Conflict)),
596	("Push", schemars::schema_for!(Push)),
597	("Trust", schemars::schema_for!(Trust)),
598	("Policy", schemars::schema_for!(Policy)),
599	("Rule", schemars::schema_for!(Rule)),
600	("Hook", schemars::schema_for!(Hook)),
601	("NewHook", schemars::schema_for!(NewHook)),
602	("Check", schemars::schema_for!(Check)),
603	("CheckStatus", schemars::schema_for!(CheckStatus)),
604	("NewCheck", schemars::schema_for!(NewCheck)),
605	("User", schemars::schema_for!(User)),
606	("Organisation", schemars::schema_for!(Organisation)),
607	("NewRepository", schemars::schema_for!(NewRepository)),
608	("NewIssue", schemars::schema_for!(NewIssue)),
609	("NewComment", schemars::schema_for!(NewComment)),
610	("NewProposal", schemars::schema_for!(NewProposal)),
611	("NewReview", schemars::schema_for!(NewReview)),
612	("IssueStateChange", schemars::schema_for!(IssueStateChange)),
613	("WebhookEnvelope", schemars::schema_for!(WebhookEnvelope)),
614	("ProposalEvent", schemars::schema_for!(ProposalEvent)),
615	]
616	}

Keyboard