Sign in

flagon-io/g1t

public

g1t/crates/contracts/src/webhooks.rs

226 lines6,638 bytesCodeBlame

Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.

Webhooks: every event, to your own addresses, signed and retried1//! The webhooks service: events, delivered to the addresses a repository or
2//! a workspace registers.
3//!
4//! Every event g1t publishes can be delivered: an HTTPS `POST` of JSON,
5//! signed with the webhook's secret in `X-G1t-Signature-256`, and retried
6//! with growing waits when the receiver does not answer with a 2xx. Each
7//! delivery is kept, with what was sent and what came back, and can be sent
8//! again.
9//!
10//! Mirrors `packages/contracts/src/webhooks.ts`.
11
12use serde::{Deserialize, Serialize};
13
14use crate::repos::RepoPath;
15use crate::{User, Viewer};
16
17/// Every event a webhook can be sent, in the order people are shown them.
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member18pub const EVENT_TYPES: [&str; 39] = [
Webhooks: every event, to your own addresses, signed and retried19 "git.push",
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look20 "branch.renamed",
Webhooks: every event, to your own addresses, signed and retried21 "repo.created",
22 "repo.forked",
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look23 "repo.updated",
24 "repo.visibility_changed",
25 "repo.renamed",
26 "repo.transferred",
27 "repo.default_branch_changed",
28 "repo.archived",
29 "repo.unarchived",
30 "repo.deleted",
31 "repo.restored",
32 "repo.purged",
33 "repo.collaborator_added",
34 "repo.collaborator_removed",
35 "repo.collaborator_role_changed",
Webhooks: every event, to your own addresses, signed and retried36 "issue.opened",
37 "issue.updated",
38 "issue.assigned",
39 "issue.closed",
40 "issue.reopened",
41 "comment.created",
42 "pull.opened",
43 "pull.ready",
44 "pull.updated",
45 "pull.merge_requested",
46 "pull.merged",
47 "pull.closed",
Agents asked while not at work are woken to answer48 "agent.asked",
Webhooks: every event, to your own addresses, signed and retried49 "checks.completed",
50 "review.completed",
Actions: workflow_run, workflow.completed, artifacts on the run page, Node 2451 "workflow.completed",
Webhooks: every event, to your own addresses, signed and retried52 "queue.changed",
53 "session.appended",
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member54 "package.published",
55 "package.version_deleted",
56 "package.deleted",
57 "package.visibility_changed",
Webhooks: every event, to your own addresses, signed and retried58];
59
60/// What a webhook belongs to.
61#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
62#[serde(rename_all = "snake_case")]
63pub enum HookScope {
64 /// One repository's events.
65 Repo,
66 /// The events of every repository in a workspace.
67 Workspace,
68}
69
70#[derive(Clone, Debug, Serialize, Deserialize)]
71#[serde(rename_all = "camelCase")]
72pub struct Hook {
73 pub id: String,
74 pub scope: HookScope,
75 pub workspace: String,
76 /// For a repository's webhook: `owner/name`.
77 pub repo: Option<String>,
78 pub url: String,
79 /// The event types it is sent, or `["*"]` for all.
80 pub events: Vec<String>,
81 pub active: bool,
82 /// The last four characters of its secret.
83 pub secret_hint: String,
84 pub created_by: String,
85 /// RFC 3339.
86 pub created_at: String,
87 /// How its latest delivery went: `delivered`, `pending` or `failed`.
88 pub last_status: Option<String>,
89 pub last_delivered_at: Option<String>,
90}
91
92/// One event sent, or being sent, to a webhook.
93#[derive(Clone, Debug, Serialize, Deserialize)]
94#[serde(rename_all = "camelCase")]
95pub struct HookDelivery {
96 pub id: String,
97 pub hook_id: String,
98 /// The event's id, or empty for a ping.
99 pub event_id: String,
100 pub event: String,
101 /// `pending` while it will be tried again, `delivered`, or `failed` once
102 /// it has been tried as often as it will be.
103 pub status: String,
104 pub attempts: u32,
105 /// The receiver's HTTP status, the last time it answered.
106 pub response_status: Option<u16>,
107 /// The start of what it answered.
108 pub response_body: Option<String>,
109 /// Why the last attempt failed, when the receiver could not be reached.
110 pub error: Option<String>,
111 pub duration_ms: Option<u32>,
112 /// The JSON that was sent.
113 pub payload: String,
114 /// RFC 3339.
115 pub created_at: String,
116 pub delivered_at: Option<String>,
117 pub next_attempt_at: Option<String>,
118}
119
120/// Which webhooks a call is about: a repository's, or with `repo` left out,
121/// the workspace's own.
122#[derive(Clone, Debug, Serialize, Deserialize)]
123pub struct HookOwner {
124 pub workspace: String,
125 #[serde(default)]
126 pub repo: Option<RepoPath>,
127}
128
129/// `list`. Returns `Outcome<Vec<Hook>>`. Members of the workspace only.
130#[derive(Debug, Serialize, Deserialize)]
131pub struct ListArgs {
132 pub viewer: Viewer,
133 #[serde(flatten)]
134 pub owner: HookOwner,
135}
136
137/// `create`. Returns `Outcome<CreatedHook>`. Members, for a repository's
138/// webhooks; owners, for the workspace's.
139#[derive(Debug, Serialize, Deserialize)]
140pub struct CreateArgs {
141 pub actor: User,
142 #[serde(flatten)]
143 pub owner: HookOwner,
144 pub url: String,
145 /// Event types, or `["*"]` for all. All when empty.
146 #[serde(default)]
147 pub events: Vec<String>,
148 /// Made by g1t when left out.
149 #[serde(default)]
150 pub secret: Option<String>,
151}
152
153#[derive(Clone, Debug, Serialize, Deserialize)]
154pub struct CreatedHook {
155 pub hook: Hook,
156 /// The secret, when g1t made it: shown this once.
157 pub secret: Option<String>,
158}
159
160/// `update`: only the fields given change. Returns `Outcome<Hook>`.
161#[derive(Debug, Serialize, Deserialize)]
162pub struct UpdateArgs {
163 pub actor: User,
164 #[serde(flatten)]
165 pub owner: HookOwner,
166 pub id: String,
167 #[serde(default)]
168 pub url: Option<String>,
169 #[serde(default)]
170 pub events: Option<Vec<String>>,
171 #[serde(default)]
172 pub active: Option<bool>,
173}
174
175/// `delete` (returns `Outcome<bool>`) and `ping` (sends a `ping` event and
176/// returns `Outcome<HookDelivery>`).
177#[derive(Debug, Serialize, Deserialize)]
178pub struct HookArgs {
179 pub actor: User,
180 #[serde(flatten)]
181 pub owner: HookOwner,
182 pub id: String,
183}
184
185/// `deliveries`: a webhook's latest deliveries, newest first. Returns
186/// `Outcome<Vec<HookDelivery>>`.
187#[derive(Debug, Serialize, Deserialize)]
188pub struct DeliveriesArgs {
189 pub viewer: Viewer,
190 #[serde(flatten)]
191 pub owner: HookOwner,
192 pub id: String,
193}
194
195/// `redeliver`: sends a delivery's payload again, as a new delivery.
196/// Returns `Outcome<HookDelivery>`.
197#[derive(Debug, Serialize, Deserialize)]
198#[serde(rename_all = "camelCase")]
199pub struct RedeliverArgs {
200 pub actor: User,
201 #[serde(flatten)]
202 pub owner: HookOwner,
203 pub delivery_id: String,
204}
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look205
206#[cfg(test)]
207mod tests {
208 use super::EVENT_TYPES;
209
210 /// The TypeScript mirror lists the same events, in the same order.
211 #[test]
212 fn the_typescript_mirror_lists_the_same_events() {
213 let ts = include_str!("../../../packages/contracts/src/webhooks.ts");
214 let list = ts
215 .split_once("export const EVENT_TYPES = [")
216 .and_then(|(_, rest)| rest.split_once("] as const"))
217 .map(|(list, _)| list)
218 .expect("EVENT_TYPES in webhooks.ts");
219 let mirrored: Vec<&str> = list
220 .split(',')
221 .map(|item| item.trim().trim_matches('"'))
222 .filter(|item| !item.is_empty())
223 .collect();
224 assert_eq!(mirrored, EVENT_TYPES);
225 }
226}