OXYGENHUB
# f28389bd6aab oxygenhub / crates / hub-api / src / lib.rs
32.3 KiB · Rust · last changed Milestones over the API, and oh milestone 1 month ago source blame history raw
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 
    /// Set when the change is signed by a key no account has linked, and
95 
    /// says how its owner links it.
96 
    #[serde(default, skip_serializing_if = "Option::is_none")]
97 
    pub note: Option<String>,
98 
}
99
100 
impl Author {
101 
    /// What `note` says for a key that no account has linked.
102 
    pub const UNLINKED: &'static str =
103 
        "signed by a key not linked to any account; its owner links it under Settings → Keys (/settings/keys)";
104
105 
    /// The note for an author with this key and account.
106 
    pub fn note_for(key: &str, account: &Option<String>) -> Option<String> {
107 
        (!key.is_empty() && account.is_none()).then(|| Self::UNLINKED.to_string())
108 
    }
109 
}
110
111 
/// Signature status of a change as `oxy verify` reports it.
112 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
113 
#[serde(tag = "status", rename_all = "lowercase")]
114 
pub enum Signature {
115 
    Unsigned,
116 
    Valid { key: String, sealed: bool, revoked: bool },
117 
    Invalid { reason: String },
118 
}
119
120 
/// An RFC 7807 problem response.
121 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
122 
pub struct Problem {
123 
    pub status: u16,
124 
    pub title: String,
125 
    pub detail: String,
126 
}
127
128 
#[cfg(test)]
129 
mod tests {
130 
    use super::*;
131
132 
    #[test]
133 
    fn visibility_round_trips() {
134 
        for v in [Visibility::Public, Visibility::Internal, Visibility::Private] {
135 
            assert_eq!(Visibility::parse(v.as_str()), Some(v));
136 
        }
137 
        assert_eq!(Visibility::parse("secret"), None);
138 
    }
139 
}
140
141 
// ---------------------------------------------------------------- proposals
142
143 
/// A proposal: a request to add changes to a target bookmark (hub spec §7).
144 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
145 
pub struct Proposal {
146 
    pub number: i64,
147 
    pub title: String,
148 
    pub body: String,
149 
    pub author: String,
150 
    pub state: ProposalState,
151 
    pub target: String,
152 
    pub source: ProposalSource,
153 
    /// The changes the proposal adds, dependency order, newest last.
154 
    pub changes: Vec<ChangeSummary>,
155 
    /// Heads of the projected state (target plus the changes), when computed.
156 
    pub projected_heads: Vec<String>,
157 
    pub projected_state: Option<String>,
158 
    pub conflicted: bool,
159 
    pub approvals: Vec<Approval>,
160 
    pub landable: bool,
161 
    pub blockers: Vec<String>,
162 
    pub created_ms: i64,
163 
    pub updated_ms: i64,
164 
    /// `https://hub/{owner}/{name}/proposal/{number}`.
165 
    pub url: String,
166 
    /// Where `oxy` fetches the changes from.
167 
    pub repository_url: String,
168 
    /// The fork's clone URL when the source is a fork.
169 
    pub source_url: Option<String>,
170 
    /// Who landed it, how and when, once landed.
171 
    #[serde(default)]
172 
    pub landed: Option<Landed>,
173 
    /// Asked to review and not yet reviewing, in the order asked.
174 
    #[serde(default)]
175 
    pub requested_reviewers: Vec<String>,
176 
    #[serde(default)]
177 
    pub labels: Vec<Label>,
178 
}
179
180 
/// How a proposal was landed.
181 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
182 
pub struct Landed {
183 
    pub by: String,
184 
    /// `web`, or `api (token NAME)`.
185 
    pub via: String,
186 
    pub when_ms: i64,
187 
}
188
189 
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
190 
#[serde(rename_all = "lowercase")]
191 
pub enum ProposalState {
192 
    Draft,
193 
    Open,
194 
    Landed,
195 
    Closed,
196 
}
197
198 
impl ProposalState {
199 
    pub fn as_str(self) -> &'static str {
200 
        match self {
201 
            ProposalState::Draft => "draft",
202 
            ProposalState::Open => "open",
203 
            ProposalState::Landed => "landed",
204 
            ProposalState::Closed => "closed",
205 
        }
206 
    }
207
208 
    pub fn parse(s: &str) -> Option<ProposalState> {
209 
        Some(match s {
210 
            "draft" => ProposalState::Draft,
211 
            "open" => ProposalState::Open,
212 
            "landed" => ProposalState::Landed,
213 
            "closed" => ProposalState::Closed,
214 
            _ => return None,
215 
        })
216 
    }
217 
}
218
219 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
220 
#[serde(tag = "kind", rename_all = "lowercase")]
221 
pub enum ProposalSource {
222 
    /// A bookmark of the same repository.
223 
    Bookmark { bookmark: String },
224 
    /// A bookmark of a fork.
225 
    Fork { owner: String, name: String, bookmark: String },
226 
    /// An explicit list of change hashes.
227 
    Changes { hashes: Vec<String> },
228 
}
229
230 
/// A reviewer's approval, counted only when backed by a seal over every
231 
/// change of the proposal signed with a key linked to the reviewer.
232 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
233 
pub struct Approval {
234 
    pub account: String,
235 
    pub sealed: bool,
236 
    pub key: Option<String>,
237 
}
238
239 
// ------------------------------------------------------------------ issues
240
241 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
242 
pub struct Issue {
243 
    pub number: i64,
244 
    pub title: String,
245 
    pub body: String,
246 
    pub author: String,
247 
    pub state: String,
248 
    pub reason: String,
249 
    pub labels: Vec<Label>,
250 
    pub assignees: Vec<String>,
251 
    pub milestone: Option<String>,
252 
    pub comments: i64,
253 
    pub locked: bool,
254 
    pub pinned: bool,
255 
    pub created_ms: i64,
256 
    pub updated_ms: i64,
257 
    pub closed_ms: Option<i64>,
258 
    pub url: String,
259 
}
260
261 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
262 
pub struct Label {
263 
    pub name: String,
264 
    pub colour: String,
265 
    pub description: String,
266 
}
267
268 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
269 
pub struct Milestone {
270 
    pub title: String,
271 
    pub description: String,
272 
    pub due_ms: Option<i64>,
273 
    pub state: String,
274 
    pub open: i64,
275 
    pub closed: i64,
276 
}
277
278 
/// `POST /repos/{o}/{n}/milestones`: create a milestone, or change the
279 
/// description and due date of the one with that title (triage).
280 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
281 
pub struct NewMilestone {
282 
    pub title: String,
283 
    #[serde(default)]
284 
    pub description: String,
285 
    /// `YYYY-MM-DD`, UTC; absent for no due date.
286 
    #[serde(default)]
287 
    pub due: Option<String>,
288 
}
289
290 
/// `PATCH /repos/{o}/{n}/milestones/{title}`: only the fields given change
291 
/// (triage).
292 
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
293 
pub struct MilestoneEdit {
294 
    #[serde(default)]
295 
    pub title: Option<String>,
296 
    #[serde(default)]
297 
    pub description: Option<String>,
298 
    /// `YYYY-MM-DD`; the empty string clears the due date.
299 
    #[serde(default)]
300 
    pub due: Option<String>,
301 
    /// `open` or `closed`.
302 
    #[serde(default)]
303 
    pub state: Option<String>,
304 
}
305
306 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
307 
pub struct Comment {
308 
    pub id: i64,
309 
    pub author: String,
310 
    pub body: String,
311 
    pub created_ms: i64,
312 
    /// For proposal comments: the file and the atom the comment anchors to.
313 
    pub path: Option<String>,
314 
    pub anchor: Option<Atom>,
315 
    pub resolved: bool,
316 
}
317
318 
/// One entry in the caller's inbox (hub spec §10).
319 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
320 
pub struct Notification {
321 
    pub id: i64,
322 
    pub at_ms: i64,
323 
    /// `issue.opened`, `proposal.comment`, `mention`, `review`, …
324 
    pub kind: String,
325 
    pub title: String,
326 
    /// The page on the hub, absolute.
327 
    pub url: String,
328 
    pub actor: String,
329 
    pub read: bool,
330 
}
331
332 
/// `GET /notifications`: the unread count and the newest entries, unread first.
333 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
334 
pub struct Inbox {
335 
    pub unread: i64,
336 
    pub items: Vec<Notification>,
337 
}
338
339 
/// A file a proposal changes, between the target's state and the
340 
/// projected state (hub spec §7.2). Fetch either side's bytes from
341 
/// `/proposals/{number}/content/{base|head}/{path}`.
342 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
343 
pub struct ProposalFile {
344 
    pub path: String,
345 
    /// For a rename, the path in the target's state.
346 
    pub from: Option<String>,
347 
    /// `added`, `removed`, `modified`, `renamed`, `mode` or `replaced`.
348 
    pub kind: String,
349 
    pub added: usize,
350 
    pub removed: usize,
351 
}
352
353 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
354 
pub struct Atom {
355 
    pub change: String,
356 
    pub index: u32,
357 
}
358
359 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
360 
pub struct Review {
361 
    pub id: i64,
362 
    pub author: String,
363 
    pub verdict: String,
364 
    pub body: String,
365 
    pub sealed: bool,
366 
    pub created_ms: i64,
367 
}
368
369 
// ------------------------------------------------------------- repository
370
371 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
372 
pub struct TreeEntry {
373 
    pub name: String,
374 
    pub path: String,
375 
    pub kind: String,
376 
    pub exec: bool,
377 
    pub size: Option<u64>,
378 
    pub conflicted: bool,
379 
}
380
381 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
382 
pub struct BlameLine {
383 
    pub line: usize,
384 
    pub change: String,
385 
    pub index: u32,
386 
    pub author: String,
387 
    pub when_ms: u64,
388 
    pub text: String,
389 
}
390
391 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
392 
pub struct FileChange {
393 
    pub path: String,
394 
    pub kind: String,
395 
    pub from: Option<String>,
396 
    pub added: usize,
397 
    pub removed: usize,
398 
}
399
400 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
401 
pub struct ChangeDetail {
402 
    pub change: ChangeSummary,
403 
    pub body: String,
404 
    pub dependents: Vec<String>,
405 
    pub in_bookmarks: Vec<String>,
406 
    pub in_tags: Vec<String>,
407 
    pub files: Vec<FileChange>,
408 
}
409
410 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
411 
pub struct History {
412 
    pub reference: String,
413 
    pub heads: Vec<String>,
414 
    pub total: usize,
415 
    pub offset: usize,
416 
    pub changes: Vec<ChangeSummary>,
417 
}
418
419 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
420 
pub struct Conflict {
421 
    pub bookmark: String,
422 
    pub path: String,
423 
    pub kind: String,
424 
    pub contributors: Vec<String>,
425 
}
426
427 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
428 
pub struct Push {
429 
    pub at_ms: i64,
430 
    pub pusher: String,
431 
    pub reference: String,
432 
    pub ok: bool,
433 
    pub reason: String,
434 
    pub old_state: String,
435 
    pub new_state: String,
436 
    pub heads: i64,
437 
    pub changes: i64,
438 
}
439
440 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
441 
pub struct Trust {
442 
    pub policy: Option<Policy>,
443 
    pub signed: usize,
444 
    pub sealed: usize,
445 
    pub unsigned: usize,
446 
    pub invalid: Vec<String>,
447 
    pub hub_key: String,
448 
}
449
450 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
451 
pub struct Policy {
452 
    pub serial: u64,
453 
    pub expires_ms: u64,
454 
    pub roots: Vec<String>,
455 
    pub root_threshold: u32,
456 
    pub rules: Vec<Rule>,
457 
}
458
459 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
460 
pub struct Rule {
461 
    pub pattern: String,
462 
    pub keys: Vec<String>,
463 
    pub threshold: u32,
464 
    pub require: String,
465 
    pub allow_conflicts: bool,
466 
}
467
468 
// ---------------------------------------------------------- hooks, checks
469
470 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
471 
pub struct Hook {
472 
    pub id: i64,
473 
    pub url: String,
474 
    pub events: String,
475 
    pub active: bool,
476 
    pub created_ms: i64,
477 
}
478
479 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
480 
pub struct NewHook {
481 
    pub url: String,
482 
    pub secret: String,
483 
    #[serde(default = "star")]
484 
    pub events: String,
485 
}
486
487 
fn star() -> String {
488 
    "*".into()
489 
}
490
491 
/// An OxygenFlow run (hub spec §13.2).
492 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
493 
pub struct FlowRun {
494 
    /// The run's number within its repository.
495 
    pub number: i64,
496 
    pub bookmark: String,
497 
    /// The state's hash, as checks are keyed.
498 
    pub state: String,
499 
    /// Its heads, full change hashes.
500 
    pub heads: Vec<String>,
501 
    /// `queued`, `running`, `passed`, `failed` or `error` (an invalid pipeline).
502 
    pub status: String,
503 
    /// `push`, `manual` or `rerun:N`.
504 
    pub trigger: String,
505 
    pub actor: String,
506 
    pub pipeline_hash: String,
507 
    /// An invalid pipeline's problems.
508 
    pub error: String,
509 
    pub created_ms: i64,
510 
    pub finished_ms: Option<i64>,
511 
    pub url: String,
512 
    /// For a run waiting for a runner, its first queued job's 1-based
513 
    /// place among all queued jobs.
514 
    #[serde(default, skip_serializing_if = "Option::is_none")]
515 
    pub queue_position: Option<i64>,
516 
    /// Filled by the single-run endpoint.
517 
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
518 
    pub jobs: Vec<FlowJob>,
519 
}
520
521 
/// A job of a run.
522 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
523 
pub struct FlowJob {
524 
    pub name: String,
525 
    /// `queued`, `running`, `passed`, `failed`, `skipped` or `error`.
526 
    pub status: String,
527 
    pub depends_on: Vec<String>,
528 
    pub runner: String,
529 
    pub exit_code: Option<i64>,
530 
    pub error: String,
531 
    pub started_ms: Option<i64>,
532 
    pub finished_ms: Option<i64>,
533 
    /// Log lines stored so far.
534 
    pub log_lines: i64,
535 
}
536
537 
/// A line of a job's log.
538 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
539 
pub struct FlowLogLine {
540 
    /// Increasing within the job; pass the last one as `after` for more.
541 
    pub seq: i64,
542 
    /// Milliseconds since the job started.
543 
    pub t: i64,
544 
    /// `stdout`, `stderr` or `flow` (the runner's own notes).
545 
    pub stream: String,
546 
    pub text: String,
547 
}
548
549 
/// A check on a state hash (hub spec §13.1).
550 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
551 
pub struct Check {
552 
    pub state: String,
553 
    pub name: String,
554 
    pub status: CheckStatus,
555 
    pub summary: String,
556 
    pub url: String,
557 
    pub reporter: String,
558 
    /// The seal attestation's reference when the checker sealed the changes.
559 
    pub seal: Option<String>,
560 
    pub started_ms: i64,
561 
    pub finished_ms: Option<i64>,
562 
}
563
564 
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
565 
#[serde(rename_all = "lowercase")]
566 
pub enum CheckStatus {
567 
    Queued,
568 
    Running,
569 
    Passed,
570 
    Failed,
571 
    Cancelled,
572 
    Skipped,
573 
}
574
575 
impl CheckStatus {
576 
    pub fn as_str(self) -> &'static str {
577 
        match self {
578 
            CheckStatus::Queued => "queued",
579 
            CheckStatus::Running => "running",
580 
            CheckStatus::Passed => "passed",
581 
            CheckStatus::Failed => "failed",
582 
            CheckStatus::Cancelled => "cancelled",
583 
            CheckStatus::Skipped => "skipped",
584 
        }
585 
    }
586
587 
    pub fn parse(s: &str) -> Option<CheckStatus> {
588 
        Some(match s {
589 
            "queued" => CheckStatus::Queued,
590 
            "running" => CheckStatus::Running,
591 
            "passed" => CheckStatus::Passed,
592 
            "failed" => CheckStatus::Failed,
593 
            "cancelled" => CheckStatus::Cancelled,
594 
            "skipped" => CheckStatus::Skipped,
595 
            _ => return None,
596 
        })
597 
    }
598 
}
599
600 
/// What a checker posts.
601 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
602 
pub struct NewCheck {
603 
    pub state: String,
604 
    pub name: String,
605 
    pub status: CheckStatus,
606 
    #[serde(default)]
607 
    pub summary: String,
608 
    #[serde(default)]
609 
    pub url: String,
610 
    /// Hex of a seal attestation reference the checker pushed, if any.
611 
    #[serde(default)]
612 
    pub seal: Option<String>,
613 
}
614
615 
// ------------------------------------------------------------- accounts
616
617 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
618 
pub struct User {
619 
    pub username: String,
620 
    pub display_name: String,
621 
    pub is_admin: bool,
622 
    pub keys: Vec<String>,
623 
    pub created_ms: i64,
624 
}
625
626 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
627 
pub struct Organisation {
628 
    pub name: String,
629 
    pub display_name: String,
630 
    pub description: String,
631 
    pub members: Vec<String>,
632 
}
633
634 
/// Forms accepted by the write endpoints.
635 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
636 
pub struct NewRepository {
637 
    pub owner: String,
638 
    pub name: String,
639 
    #[serde(default)]
640 
    pub description: String,
641 
    #[serde(default = "public")]
642 
    pub visibility: Visibility,
643 
}
644
645 
fn public() -> Visibility {
646 
    Visibility::Public
647 
}
648
649 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
650 
pub struct NewIssue {
651 
    pub title: String,
652 
    #[serde(default)]
653 
    pub body: String,
654 
    /// Label names; each must exist. Needs triage.
655 
    #[serde(default)]
656 
    pub labels: Vec<String>,
657 
    /// Usernames. Needs triage.
658 
    #[serde(default)]
659 
    pub assignees: Vec<String>,
660 
    /// A milestone's title. Needs triage.
661 
    #[serde(default)]
662 
    pub milestone: Option<String>,
663 
}
664
665 
/// `PATCH /repos/{o}/{n}/issues/{number}`: only the fields given change.
666 
/// Title and body: the author or triage. The rest: triage.
667 
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
668 
pub struct IssueEdit {
669 
    #[serde(default)]
670 
    pub title: Option<String>,
671 
    #[serde(default)]
672 
    pub body: Option<String>,
673 
    /// The whole set of labels.
674 
    #[serde(default)]
675 
    pub labels: Option<Vec<String>>,
676 
    /// The whole set of assignees.
677 
    #[serde(default)]
678 
    pub assignees: Option<Vec<String>>,
679 
    /// A milestone's title; the empty string clears it.
680 
    #[serde(default)]
681 
    pub milestone: Option<String>,
682 
}
683
684 
/// The checks a proposal needs, passed, to land on the repository's
685 
/// default bookmark (hub spec §13.1). `GET` and `PUT
686 
/// /repos/{o}/{n}/checks/required`.
687 
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
688 
pub struct RequiredChecks {
689 
    pub names: Vec<String>,
690 
}
691
692 
/// A project (hub spec §8.2).
693 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
694 
pub struct Project {
695 
    pub owner: String,
696 
    pub number: i64,
697 
    pub title: String,
698 
    pub description: String,
699 
    pub public: bool,
700 
    pub closed: bool,
701 
    pub updated_ms: i64,
702 
    /// The board on the hub, absolute.
703 
    pub url: String,
704 
}
705
706 
/// A card as the caller may see it.
707 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
708 
pub struct ProjectCard {
709 
    pub id: i64,
710 
    /// `issue`, `proposal` or `note`.
711 
    pub kind: String,
712 
    /// `owner/name#N`; empty for a note.
713 
    pub reference: String,
714 
    /// The issue's or proposal's title, or the note.
715 
    pub title: String,
716 
    /// The issue's or proposal's state; empty for a note.
717 
    pub state: String,
718 
}
719
720 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
721 
pub struct ProjectColumn {
722 
    pub id: i64,
723 
    pub name: String,
724 
    pub cards: Vec<ProjectCard>,
725 
}
726
727 
/// `GET /projects/{owner}/{n}`.
728 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
729 
pub struct Board {
730 
    pub project: Project,
731 
    pub columns: Vec<ProjectColumn>,
732 
}
733
734 
/// `POST /projects/{owner}`.
735 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
736 
pub struct NewProject {
737 
    pub title: String,
738 
    #[serde(default)]
739 
    pub description: String,
740 
    #[serde(default)]
741 
    pub private: bool,
742 
}
743
744 
/// `PATCH /projects/{owner}/{n}`: only the fields given change.
745 
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
746 
pub struct ProjectEdit {
747 
    #[serde(default)]
748 
    pub title: Option<String>,
749 
    #[serde(default)]
750 
    pub description: Option<String>,
751 
    #[serde(default)]
752 
    pub private: Option<bool>,
753 
    #[serde(default)]
754 
    pub closed: Option<bool>,
755 
}
756
757 
/// `POST /projects/{owner}/{n}/cards`: a reference (`repo#12`) or a note,
758 
/// into the column named (by id or name; the first column when absent).
759 
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
760 
pub struct NewCard {
761 
    #[serde(default)]
762 
    pub column: Option<String>,
763 
    #[serde(default)]
764 
    pub reference: String,
765 
    #[serde(default)]
766 
    pub note: String,
767 
}
768
769 
/// `PATCH /projects/{owner}/{n}/cards/{id}`: move to a column (id or name).
770 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
771 
pub struct CardMove {
772 
    pub column: String,
773 
}
774
775 
/// `POST /repos/{o}/{n}/labels`: create a label, or change one of that name.
776 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
777 
pub struct NewLabel {
778 
    pub name: String,
779 
    /// `#rrggbb`; a default when absent.
780 
    #[serde(default)]
781 
    pub colour: Option<String>,
782 
    #[serde(default)]
783 
    pub description: String,
784 
}
785
786 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
787 
pub struct NewComment {
788 
    pub body: String,
789 
    /// For a proposal: anchor the comment to this file's line (1-based) of
790 
    /// the projected state; the hub records the line's atom.
791 
    #[serde(default)]
792 
    pub path: Option<String>,
793 
    #[serde(default)]
794 
    pub line: Option<usize>,
795 
}
796
797 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
798 
pub struct NewProposal {
799 
    pub title: String,
800 
    #[serde(default)]
801 
    pub body: String,
802 
    pub target: String,
803 
    /// A bookmark here, or `owner/name:bookmark` of a fork.
804 
    pub source: String,
805 
    #[serde(default)]
806 
    pub draft: bool,
807 
}
808
809 
/// `POST .../proposals/{number}/reviewers`: accounts to ask for a review.
810 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
811 
pub struct ReviewRequest {
812 
    pub reviewers: Vec<String>,
813 
}
814
815 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
816 
pub struct NewReview {
817 
    pub verdict: String,
818 
    #[serde(default)]
819 
    pub body: String,
820 
}
821
822 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
823 
pub struct IssueStateChange {
824 
    /// `open` or `closed`.
825 
    pub state: String,
826 
    #[serde(default)]
827 
    pub reason: String,
828 
}
829
830 
/// A webhook payload's envelope (hub spec §12.2).
831 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
832 
pub struct WebhookEnvelope {
833 
    pub event: String,
834 
    pub delivery: String,
835 
    pub repository: Option<Repository>,
836 
    pub actor: String,
837 
    pub at_ms: i64,
838 
    pub data: serde_json::Value,
839 
}
840
841 
/// A server-sent event on a proposal's stream.
842 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
843 
pub struct ProposalEvent {
844 
    pub number: i64,
845 
    pub kind: String,
846 
    pub check: Option<Check>,
847 
}
848
849 
// --------------------------------------------------------------- releases
850
851 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
852 
pub struct Release {
853 
    pub tag: String,
854 
    pub title: String,
855 
    pub notes: String,
856 
    pub prerelease: bool,
857 
    pub latest: bool,
858 
    pub author: String,
859 
    pub heads: Vec<String>,
860 
    pub signer: Option<String>,
861 
    pub assets: Vec<ReleaseAsset>,
862 
    pub archives: Vec<String>,
863 
    pub created_ms: i64,
864 
    pub url: String,
865 
}
866
867 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
868 
pub struct ReleaseAsset {
869 
    pub name: String,
870 
    pub size: i64,
871 
    /// BLAKE3 of the content, hex.
872 
    pub hash: String,
873 
    pub content_type: String,
874 
    pub downloads: i64,
875 
    pub url: String,
876 
    /// The OxygenFlow run and job whose artifact has this content, if any.
877 
    #[serde(default, skip_serializing_if = "Option::is_none")]
878 
    pub built_by: Option<AssetBuild>,
879 
}
880
881 
/// Where a release asset was built (hub spec §9): a job's artifact with the
882 
/// same BLAKE3, and that job's signed receipt when one was kept.
883 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
884 
pub struct AssetBuild {
885 
    pub run: i64,
886 
    pub job: String,
887 
    pub artifact: String,
888 
    pub run_url: String,
889 
    /// The receipt attestation, hex; `None` when the receipt was not signed.
890 
    pub receipt: Option<String>,
891 
    pub receipt_url: Option<String>,
892 
    pub signer: Option<String>,
893 
}
894
895 
/// `PATCH /repos/{o}/{n}/proposals/{number}`: what is given changes,
896 
/// the rest stays (oxygenhub#76).
897 
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
898 
pub struct ProposalEdit {
899 
    #[serde(default, skip_serializing_if = "Option::is_none")]
900 
    pub title: Option<String>,
901 
    #[serde(default, skip_serializing_if = "Option::is_none")]
902 
    pub body: Option<String>,
903 
    /// The whole set of labels, by name (triage); oxygenhub#80.
904 
    #[serde(default, skip_serializing_if = "Option::is_none")]
905 
    pub labels: Option<Vec<String>>,
906 
}
907
908 
/// `PATCH /repos/{owner}/{name}/releases/{tag}`: what to change; fields
909 
/// left out stay as they are.
910 
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
911 
pub struct ReleaseEdit {
912 
    #[serde(default, skip_serializing_if = "Option::is_none")]
913 
    pub title: Option<String>,
914 
    #[serde(default, skip_serializing_if = "Option::is_none")]
915 
    pub notes: Option<String>,
916 
    #[serde(default, skip_serializing_if = "Option::is_none")]
917 
    pub prerelease: Option<bool>,
918 
}
919
920 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
921 
pub struct NewRelease {
922 
    pub tag: String,
923 
    pub title: String,
924 
    #[serde(default)]
925 
    pub notes: Option<String>,
926 
    #[serde(default)]
927 
    pub prerelease: bool,
928 
}
929
930 
/// Every type of the API, for schema generation.
931 
pub fn schemas() -> Vec<(&'static str, schemars::Schema)> {
932 
    vec![
933 
        ("Repository", schemars::schema_for!(Repository)),
934 
        ("Visibility", schemars::schema_for!(Visibility)),
935 
        ("Bookmark", schemars::schema_for!(Bookmark)),
936 
        ("Tag", schemars::schema_for!(Tag)),
937 
        ("ChangeSummary", schemars::schema_for!(ChangeSummary)),
938 
        ("Author", schemars::schema_for!(Author)),
939 
        ("Signature", schemars::schema_for!(Signature)),
940 
        ("Problem", schemars::schema_for!(Problem)),
941 
        ("Proposal", schemars::schema_for!(Proposal)),
942 
        ("ProposalState", schemars::schema_for!(ProposalState)),
943 
        ("ProposalSource", schemars::schema_for!(ProposalSource)),
944 
        ("Approval", schemars::schema_for!(Approval)),
945 
        ("Issue", schemars::schema_for!(Issue)),
946 
        ("Label", schemars::schema_for!(Label)),
947 
        ("Milestone", schemars::schema_for!(Milestone)),
948 
        ("NewMilestone", schemars::schema_for!(NewMilestone)),
949 
        ("MilestoneEdit", schemars::schema_for!(MilestoneEdit)),
950 
        ("Comment", schemars::schema_for!(Comment)),
951 
        ("ProposalFile", schemars::schema_for!(ProposalFile)),
952 
        ("Notification", schemars::schema_for!(Notification)),
953 
        ("Inbox", schemars::schema_for!(Inbox)),
954 
        ("Atom", schemars::schema_for!(Atom)),
955 
        ("Review", schemars::schema_for!(Review)),
956 
        ("TreeEntry", schemars::schema_for!(TreeEntry)),
957 
        ("BlameLine", schemars::schema_for!(BlameLine)),
958 
        ("FileChange", schemars::schema_for!(FileChange)),
959 
        ("ChangeDetail", schemars::schema_for!(ChangeDetail)),
960 
        ("History", schemars::schema_for!(History)),
961 
        ("Conflict", schemars::schema_for!(Conflict)),
962 
        ("Push", schemars::schema_for!(Push)),
963 
        ("Trust", schemars::schema_for!(Trust)),
964 
        ("Policy", schemars::schema_for!(Policy)),
965 
        ("Rule", schemars::schema_for!(Rule)),
966 
        ("Hook", schemars::schema_for!(Hook)),
967 
        ("NewHook", schemars::schema_for!(NewHook)),
968 
        ("Check", schemars::schema_for!(Check)),
969 
        ("CheckStatus", schemars::schema_for!(CheckStatus)),
970 
        ("NewCheck", schemars::schema_for!(NewCheck)),
971 
        ("User", schemars::schema_for!(User)),
972 
        ("Organisation", schemars::schema_for!(Organisation)),
973 
        ("NewRepository", schemars::schema_for!(NewRepository)),
974 
        ("NewIssue", schemars::schema_for!(NewIssue)),
975 
        ("IssueEdit", schemars::schema_for!(IssueEdit)),
976 
        ("ReleaseEdit", schemars::schema_for!(ReleaseEdit)),
977 
        ("ProposalEdit", schemars::schema_for!(ProposalEdit)),
978 
        ("NewLabel", schemars::schema_for!(NewLabel)),
979 
        ("RequiredChecks", schemars::schema_for!(RequiredChecks)),
980 
        ("Project", schemars::schema_for!(Project)),
981 
        ("ProjectCard", schemars::schema_for!(ProjectCard)),
982 
        ("ProjectColumn", schemars::schema_for!(ProjectColumn)),
983 
        ("Board", schemars::schema_for!(Board)),
984 
        ("NewProject", schemars::schema_for!(NewProject)),
985 
        ("ProjectEdit", schemars::schema_for!(ProjectEdit)),
986 
        ("NewCard", schemars::schema_for!(NewCard)),
987 
        ("CardMove", schemars::schema_for!(CardMove)),
988 
        ("NewComment", schemars::schema_for!(NewComment)),
989 
        ("NewProposal", schemars::schema_for!(NewProposal)),
990 
        ("NewReview", schemars::schema_for!(NewReview)),
991 
        ("IssueStateChange", schemars::schema_for!(IssueStateChange)),
992 
        ("WebhookEnvelope", schemars::schema_for!(WebhookEnvelope)),
993 
        ("ProposalEvent", schemars::schema_for!(ProposalEvent)),
994 
        ("Release", schemars::schema_for!(Release)),
995 
        ("ReleaseAsset", schemars::schema_for!(ReleaseAsset)),
996 
        ("NewRelease", schemars::schema_for!(NewRelease)),
997 
    ]
998 
}
999
1000 
/// An OxygenFlow runner (`GET /api/v1/runners`, site administrators).
1001 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
1002 
pub struct Runner {
1003 
    pub id: i64,
1004 
    pub name: String,
1005 
    /// `online`, `offline`, `draining` or `disabled`.
1006 
    pub status: String,
1007 
    /// What it serves: empty for the whole site, an owner, or `owner/name`.
1008 
    pub serves: String,
1009 
    pub arch: String,
1010 
    pub os: String,
1011 
    pub version: String,
1012 
    pub labels: Vec<String>,
1013 
    pub max_jobs: i64,
1014 
    pub memory_mib: Option<i64>,
1015 
    pub cpus: Option<i64>,
1016 
    /// The key that signs its receipts (KeyId hex), empty until bound.
1017 
    pub key: String,
1018 
    /// `registered` or `config` (a hub.toml token).
1019 
    pub source: String,
1020 
    pub last_seen_ms: Option<i64>,
1021 
    /// Jobs it is running now.
1022 
    pub running: i64,
1023 
}
1024
1025 
/// A job a runner ran or is running.
1026 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
1027 
pub struct RunnerJob {
1028 
    pub repo: String,
1029 
    pub run: i64,
1030 
    pub job: String,
1031 
    pub status: String,
1032 
    pub started_ms: Option<i64>,
1033 
    pub finished_ms: Option<i64>,
1034 
}
1035
1036 
/// A job in the queue: running ones first, then queued ones in the order
1037 
/// runners claim them.
1038 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
1039 
pub struct QueueItem {
1040 
    pub repo: String,
1041 
    pub run: i64,
1042 
    pub job: String,
1043 
    /// `running` or `queued`.
1044 
    pub status: String,
1045 
    /// The runner holding it, when running.
1046 
    pub runner: String,
1047 
}