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

# c0fac31d36fd oxygenhub / crates / hub-api / src / lib.rs

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

Keyboard