flagon-io/g1t

public

1	//! The actions service: GitHub Actions workflows, run on g1t as they are.
2	//!
3	//! A repository's `.g1t/workflows/*.yml`, in GitHub's format, are read
4	//! from the commit an
5	//! event is about (the default branch for issues, schedules and manual
6	//! runs). Each workflow an event starts becomes a run; each job of the run
7	//! (one per matrix combination) runs in a sandbox once the jobs it needs
8	//! have finished. Jobs report their steps and logs back as they go, and a
9	//! run on a pull request's head is a status on that pull request.
10	//!
11	//! Secrets and variables belong to a repository or to its workspace; a
12	//! repository's override its workspace's of the same name. Secret values
13	//! are sealed at rest and never returned.
14	//!
15	//! Mirrors `packages/contracts/src/actions.ts`.
16
17	use serde::{Deserialize, Serialize};
18	use serde_json::Value;
19
20	use crate::repos::RepoPath;
21	use crate::{User, Viewer};
22
23	/// A note on something in a workflow that runs differently on g1t.
24	#[derive(Clone, Debug, Serialize, Deserialize)]
25	#[serde(rename_all = "camelCase")]
26	pub struct WorkflowNote {
27	/// `info`, `warning` or `unsupported`.
28	pub severity: String,
29	pub job: Option<String>,
30	pub message: String,
31	}
32
33	#[derive(Clone, Debug, Serialize, Deserialize)]
34	#[serde(rename_all = "camelCase")]
35	pub struct Workflow {
36	pub id: String,
37	/// `.g1t/workflows/ci.yml`.
38	pub path: String,
39	pub name: String,
40	/// The events that start it, such as `push` and `pull_request`.
41	pub events: Vec<String>,
42	/// `active`, or `disabled` when a member turned it off.
43	pub state: String,
44	/// Why the file cannot be used, if it cannot.
45	pub error: Option<String>,
46	pub notes: Vec<WorkflowNote>,
47	/// `on.workflow_dispatch.inputs` as written, when it can be run by hand.
48	pub dispatch: Option<Value>,
49	pub last_run: Option<WorkflowRun>,
50	}
51
52	#[derive(Clone, Debug, Serialize, Deserialize)]
53	#[serde(rename_all = "camelCase")]
54	pub struct WorkflowRun {
55	pub id: String,
56	pub workflow_id: String,
57	pub path: String,
58	/// The workflow's name.
59	pub name: String,
60	/// `run-name`, or what started it: a commit's subject, a pull request's title.
61	pub title: String,
62	/// Counts the workflow's runs: 1, 2, 3…
63	pub number: u64,
64	pub attempt: u64,
65	/// The GitHub event: `push`, `pull_request`, `schedule`…
66	pub event: String,
67	#[serde(rename = "ref")]
68	pub git_ref: String,
69	pub sha: String,
70	/// The pull request it ran for, if any.
71	pub pull: Option<u32>,
72	/// `queued`, `in_progress` or `completed`.
73	pub status: String,
74	/// When completed: `success`, `failure`, `cancelled` or `skipped`.
75	pub conclusion: Option<String>,
76	/// Why it could not start, such as a workflow file that does not read.
77	pub error: Option<String>,
78	/// Username of whoever caused it.
79	pub actor: Option<String>,
80	pub created_at: String,
81	pub started_at: Option<String>,
82	pub finished_at: Option<String>,
83	}
84
85	#[derive(Clone, Debug, Default, Serialize, Deserialize)]
86	#[serde(rename_all = "camelCase")]
87	pub struct StepState {
88	/// From 1.
89	pub number: u32,
90	pub name: String,
91	/// `queued`, `in_progress` or `completed`.
92	pub status: String,
93	/// `success`, `failure`, `cancelled` or `skipped`.
94	pub conclusion: Option<String>,
95	pub started_at: Option<String>,
96	pub finished_at: Option<String>,
97	}
98
99	/// A message a step left with `::error::`, `::warning::` or `::notice::`.
100	#[derive(Clone, Debug, Default, Serialize, Deserialize)]
101	#[serde(rename_all = "camelCase")]
102	pub struct Annotation {
103	/// `error`, `warning` or `notice`.
104	pub level: String,
105	pub message: String,
106	pub title: Option<String>,
107	pub file: Option<String>,
108	pub line: Option<u32>,
109	}
110
111	#[derive(Clone, Debug, Serialize, Deserialize)]
112	#[serde(rename_all = "camelCase")]
113	pub struct Job {
114	pub id: String,
115	pub run_id: String,
116	/// Its key under `jobs:`.
117	pub key: String,
118	/// With its matrix combination: `test (ubuntu-latest, 20)`.
119	pub name: String,
120	pub needs: Vec<String>,
121	/// `queued`, `waiting` (for the jobs it needs), `in_progress` or `completed`.
122	pub status: String,
123	pub conclusion: Option<String>,
124	pub steps: Vec<StepState>,
125	pub annotations: Vec<Annotation>,
126	/// Why it did not run, what stopped it, or what it waits for.
127	pub reason: Option<String>,
128	pub started_at: Option<String>,
129	pub finished_at: Option<String>,
130	/// The environment it names, once its needs are done (an expression
131	/// read by then). A job held by the environment's protection rules is
132	/// `pending` until they let it through.
133	#[serde(default)]
134	pub environment: Option<String>,
135	/// Its `runs-on` names self-hosted runners (see `runners`).
136	#[serde(default)]
137	pub self_hosted: bool,
138	/// The self-hosted runner that took it, by name.
139	#[serde(default)]
140	pub runner: Option<String>,
141	/// It was cancelled and is running its `if: always()` and `cancelled()`
142	/// steps and its post steps before it ends.
143	#[serde(default)]
144	pub cancelling: bool,
145	}
146
147	#[derive(Clone, Debug, Serialize, Deserialize)]
148	#[serde(rename_all = "camelCase")]
149	pub struct RunDetail {
150	pub run: WorkflowRun,
151	pub jobs: Vec<Job>,
152	/// The workflow's notes, as of the run's commit.
153	pub notes: Vec<WorkflowNote>,
154	/// For a run of a pull request from outside: whether it waits for, or
155	/// had, someone's approval (`status` is `action_required` while it waits).
156	#[serde(default)]
157	pub approval: Option<RunApproval>,
158	/// The environments whose protection rules hold its jobs, this attempt.
159	#[serde(default)]
160	pub pending_deployments: Vec<PendingDeployment>,
161	/// Every attempt of the run, oldest first, the one shown included.
162	/// `run.attempt` says which one `jobs` belong to.
163	#[serde(default)]
164	pub attempts: Vec<RunAttempt>,
165	}
166
167	/// One attempt of a run: the first, or a re-run.
168	#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
169	#[serde(rename_all = "camelCase")]
170	pub struct RunAttempt {
171	/// From 1.
172	pub attempt: u64,
173	/// `queued`, `in_progress` or `completed`; earlier attempts are completed.
174	pub status: String,
175	pub conclusion: Option<String>,
176	/// Who started it: whoever caused the run for the first, whoever re-ran
177	/// it for the rest.
178	pub actor: Option<String>,
179	/// It ran with debug logging (`RUNNER_DEBUG=1`).
180	pub debug: bool,
181	pub started_at: Option<String>,
182	pub finished_at: Option<String>,
183	}
184
185	/// One job's summary: what its steps wrote to `$GITHUB_STEP_SUMMARY`, in
186	/// Markdown, masked.
187	#[derive(Clone, Debug, Serialize, Deserialize)]
188	#[serde(rename_all = "camelCase")]
189	pub struct JobSummary {
190	/// The job's id, as `RunDetail.jobs` gives it for the attempt.
191	pub job_id: String,
192	pub name: String,
193	pub steps: Vec<StepSummary>,
194	}
195
196	#[derive(Clone, Debug, Serialize, Deserialize)]
197	#[serde(rename_all = "camelCase")]
198	pub struct StepSummary {
199	/// The step, from 1 (post steps follow the job's own).
200	pub step: u32,
201	pub markdown: String,
202	}
203
204	/// A job's whole log, for downloading: its steps, to split the text by.
205	#[derive(Clone, Debug, Serialize, Deserialize)]
206	#[serde(rename_all = "camelCase")]
207	pub struct JobLogText {
208	pub job_id: String,
209	pub name: String,
210	pub steps: Vec<StepState>,
211	pub chunks: Vec<LogChunk>,
212	/// Whether the job has finished.
213	pub done: bool,
214	/// Its log was left out: the run's logs reached `MAX_RUN_LOG_BYTES`.
215	#[serde(default)]
216	pub omitted: bool,
217	}
218
219	/// A run that needed approval before it started.
220	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
221	#[serde(rename_all = "camelCase")]
222	pub struct RunApproval {
223	/// `required` while it waits, then `approved`.
224	pub state: String,
225	/// Why it waits, in words.
226	pub reason: String,
227	/// Who approved it.
228	pub approved_by: Option<String>,
229	}
230
231	/// One person or team who may approve a job's deployment to an
232	/// environment.
233	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
234	pub struct EnvironmentReviewer {
235	/// `user` or `team`.
236	#[serde(rename = "type")]
237	pub kind: String,
238	/// A username, or a team's slug in the repository's workspace.
239	pub name: String,
240	}
241
242	/// A branch or tag pattern an environment lets deploy.
243	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
244	pub struct BranchPattern {
245	/// fnmatch-style, as branch filters are: `main`, `release/`, `v`.
246	pub name: String,
247	/// `branch` or `tag`.
248	#[serde(rename = "type", default = "branch_kind")]
249	pub kind: String,
250	}
251
252	fn branch_kind() -> String {
253	"branch".to_owned()
254	}
255
256	/// The most reviewers an environment may have, as on GitHub.
257	pub const MAX_ENVIRONMENT_REVIEWERS: usize = 6;
258	/// The longest wait timer, in minutes: 30 days.
259	pub const MAX_WAIT_MINUTES: u32 = 43_200;
260
261	/// An environment and its protection rules. Jobs that name it with
262	/// `environment:` wait until the rules let them through; only then does the
263	/// job get the environment's secrets.
264	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
265	#[serde(rename_all = "camelCase")]
266	pub struct Environment {
267	/// Lowercase.
268	pub name: String,
269	/// Who may approve its jobs; none means no review is needed.
270	pub reviewers: Vec<EnvironmentReviewer>,
271	/// Whoever started a run may not approve its jobs, even as a reviewer.
272	pub prevent_self_review: bool,
273	/// Minutes each job waits before it may start.
274	pub wait_minutes: u32,
275	/// Which refs may deploy: `all`, `protected` (branches the rules
276	/// protect, the default branch included) or `selected` (`branch_patterns`).
277	pub branch_policy: String,
278	pub branch_patterns: Vec<BranchPattern>,
279	/// Admins may approve without being reviewers, which also skips the wait.
280	pub admins_bypass: bool,
281	/// Whether it has rules saved; false for one only named by a workflow,
282	/// a secret or a deployment.
283	pub protected: bool,
284	pub updated_at: Option<String>,
285	pub updated_by: Option<String>,
286	}
287
288	/// An environment holding a run's jobs, and where its rules stand.
289	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
290	#[serde(rename_all = "camelCase")]
291	pub struct PendingDeployment {
292	pub environment: String,
293	/// `waiting`, `approved` or `rejected`.
294	pub state: String,
295	/// Whether a reviewer must approve it before its jobs start.
296	pub needs_review: bool,
297	/// When its wait timer lets its jobs start, if it has one.
298	pub wait_until: Option<String>,
299	pub reviewers: Vec<EnvironmentReviewer>,
300	/// The jobs it holds, by name.
301	pub jobs: Vec<String>,
302	/// Whether the viewer may approve or reject it now.
303	#[serde(default)]
304	pub can_review: bool,
305	pub reviewed_by: Option<String>,
306	pub comment: Option<String>,
307	pub reviewed_at: Option<String>,
308	}
309
310	/// A repository's choices for its workflows.
311	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
312	#[serde(rename_all = "camelCase")]
313	pub struct ActionsSettings {
314	/// What a workflow without `permissions:` gets: `read` (contents and
315	/// packages read) or `write` (every permission). Unchosen, a repository
316	/// made before restricted tokens keeps `write`; a newer one takes its
317	/// workspace's default. Never more than the workspace's maximum.
318	pub default_permissions: String,
319	/// Whether the repository chose it, rather than taking it as above.
320	#[serde(default)]
321	pub default_chosen: bool,
322	/// The most the workspace lets a repository's default be.
323	#[serde(default = "write")]
324	pub max_permissions: String,
325	/// Which pull requests' runs wait for approval: `first_time_contributors`,
326	/// `outside_contributors` (the default) or `all_external_contributors`.
327	pub approval_policy: String,
328	/// Whether a job's token may open pull requests and approve them. Off
329	/// unless the repository turns it on, and only where the workspace
330	/// allows it.
331	#[serde(default)]
332	pub can_approve_pull_requests: bool,
333	/// Whether the workspace lets its repositories turn that on.
334	#[serde(default)]
335	pub workspace_allows_pull_requests: bool,
336	}
337
338	fn write() -> String {
339	"write".to_owned()
340	}
341
342	/// A workspace's policy for its repositories' tokens.
343	#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
344	#[serde(rename_all = "camelCase")]
345	pub struct WorkspaceActionsSettings {
346	/// What a repository made from now on gets by default: `read` (the
347	/// default) or `write`.
348	pub default_permissions: String,
349	/// The most any repository's default may be: `write` (the default) or
350	/// `read`, which holds every repository to read-only.
351	pub max_permissions: String,
352	/// Whether its repositories may let jobs open and approve pull
353	/// requests. Off by default.
354	pub can_approve_pull_requests: bool,
355	}
356
357	/// `workspace_actions_settings`: members only. Returns
358	/// `Outcome<WorkspaceActionsSettings>`.
359	#[derive(Debug, Serialize, Deserialize)]
360	pub struct WorkspaceActionsSettingsArgs {
361	pub viewer: Viewer,
362	pub workspace: String,
363	}
364
365	/// `set_workspace_actions_settings`: owners only. Fields left out stay as
366	/// they are. Returns `Outcome<WorkspaceActionsSettings>`.
367	#[derive(Debug, Serialize, Deserialize)]
368	#[serde(rename_all = "camelCase")]
369	pub struct SetWorkspaceActionsSettingsArgs {
370	pub actor: User,
371	pub workspace: String,
372	#[serde(default)]
373	pub default_permissions: Option<String>,
374	#[serde(default)]
375	pub max_permissions: Option<String>,
376	#[serde(default)]
377	pub can_approve_pull_requests: Option<bool>,
378	}
379
380	/// The approval policies, least strict first.
381	pub const APPROVAL_POLICIES: [&str; 3] = ["first_time_contributors", "outside_contributors", "all_external_contributors"];
382
383	/// `actions_settings`. Returns `Outcome<ActionsSettings>`; anyone who can
384	/// read the repository may see them.
385	#[derive(Debug, Serialize, Deserialize)]
386	pub struct ActionsSettingsArgs {
387	pub viewer: Viewer,
388	pub repo: RepoPath,
389	}
390
391	/// `set_actions_settings`: Admins only. Fields left out stay as they are.
392	/// Returns `Outcome<ActionsSettings>`.
393	#[derive(Debug, Serialize, Deserialize)]
394	#[serde(rename_all = "camelCase")]
395	pub struct SetActionsSettingsArgs {
396	pub actor: User,
397	pub repo: RepoPath,
398	/// `read` or `write`; `inherit` goes back to the workspace's (or, for a
399	/// repository made before restricted tokens, `write`).
400	#[serde(default)]
401	pub default_permissions: Option<String>,
402	#[serde(default)]
403	pub approval_policy: Option<String>,
404	#[serde(default)]
405	pub can_approve_pull_requests: Option<bool>,
406	}
407
408	/// `environments`: every environment a repository's workflows, secrets,
409	/// deployments or rules name, with its rules. `environment`: one, by
410	/// `name`. Returns `Outcome<Vec<Environment>>` and `Outcome<Environment>`.
411	#[derive(Debug, Serialize, Deserialize)]
412	pub struct EnvironmentsArgs {
413	pub viewer: Viewer,
414	pub repo: RepoPath,
415	#[serde(default)]
416	pub name: Option<String>,
417	}
418
419	/// `set_environment`: create an environment's rules or change them. Fields
420	/// left out stay as they are (none, for a new one). Admins only. Returns
421	/// `Outcome<Environment>`.
422	#[derive(Debug, Serialize, Deserialize)]
423	#[serde(rename_all = "camelCase")]
424	pub struct SetEnvironmentArgs {
425	pub actor: User,
426	pub repo: RepoPath,
427	pub name: String,
428	#[serde(default)]
429	pub reviewers: Option<Vec<EnvironmentReviewer>>,
430	#[serde(default)]
431	pub prevent_self_review: Option<bool>,
432	#[serde(default)]
433	pub wait_minutes: Option<u32>,
434	#[serde(default)]
435	pub branch_policy: Option<String>,
436	#[serde(default)]
437	pub branch_patterns: Option<Vec<BranchPattern>>,
438	#[serde(default)]
439	pub admins_bypass: Option<bool>,
440	}
441
442	/// `delete_environment`: its rules go; jobs naming it run without them.
443	/// Its secrets' rows stay. Admins only. Returns `Outcome<bool>`.
444	#[derive(Debug, Serialize, Deserialize)]
445	pub struct DeleteEnvironmentArgs {
446	pub actor: User,
447	pub repo: RepoPath,
448	pub name: String,
449	}
450
451	/// `pending_deployments`: the environments holding a run's jobs. Returns
452	/// `Outcome<Vec<PendingDeployment>>`.
453	#[derive(Debug, Serialize, Deserialize)]
454	pub struct PendingDeploymentsArgs {
455	pub viewer: Viewer,
456	pub repo: RepoPath,
457	pub id: String,
458	}
459
460	/// `review_deployments`: approve or reject a run's jobs for `environments`
461	/// (every one waiting, if empty). Returns `Outcome<Vec<PendingDeployment>>`.
462	#[derive(Debug, Serialize, Deserialize)]
463	pub struct ReviewDeploymentsArgs {
464	pub actor: User,
465	pub repo: RepoPath,
466	pub id: String,
467	#[serde(default)]
468	pub environments: Vec<String>,
469	/// `approved` or `rejected`.
470	pub state: String,
471	#[serde(default)]
472	pub comment: Option<String>,
473	}
474
475	/// `repository_dispatch`: start the default branch's workflows that run
476	/// `on: repository_dispatch` for `event_type`. Needs the Write role (a
477	/// token's `code:write`). Returns `Outcome<u32>`: how many started.
478	#[derive(Debug, Serialize, Deserialize)]
479	#[serde(rename_all = "camelCase")]
480	pub struct RepositoryDispatchArgs {
481	pub actor: User,
482	pub repo: RepoPath,
483	pub event_type: String,
484	#[serde(default)]
485	pub client_payload: Value,
486	}
487
488	#[derive(Clone, Debug, Serialize, Deserialize)]
489	#[serde(rename_all = "camelCase")]
490	pub struct LogChunk {
491	pub seq: u64,
492	/// The step it belongs to, from 1; 0 for the job's setup.
493	pub step: u32,
494	pub text: String,
495	}
496
497	#[derive(Clone, Debug, Serialize, Deserialize)]
498	#[serde(rename_all = "camelCase")]
499	pub struct JobLog {
500	pub chunks: Vec<LogChunk>,
501	/// Whether the job has finished, so no more will come.
502	pub done: bool,
503	}
504
505	/// Who may read a secret or variable: workflows (`secrets.` and `vars.`
506	/// in GitHub Actions) and deployments (a deploy build's environment and the
507	/// running app's bindings). Agents, checks and the merge queue read none.
508	pub const CONSUMERS: [&str; 2] = ["workflows", "deployments"];
509
510	/// One row of a repository's or workspace's secrets and variables, as
511	/// Vercel lists environment variables: a key, its type, the environments
512	/// it applies to and who reads it. A key may have one row per environment.
513	/// Secrets' values are never returned.
514	#[derive(Clone, Debug, Serialize, Deserialize)]
515	#[serde(rename_all = "camelCase")]
516	pub struct Setting {
517	#[serde(default)]
518	pub id: String,
519	pub name: String,
520	/// `secret`, or `variable` (shown as Config).
521	#[serde(default)]
522	pub kind: String,
523	/// A variable's value; secrets' are never returned.
524	pub value: Option<String>,
525	/// `project` (a repository's, which belong to its project) or
526	/// `workspace`.
527	pub scope: String,
528	pub updated_at: String,
529	/// `workflows` and/or `deployments`.
530	#[serde(default)]
531	pub available_to: Vec<String>,
532	/// The environments it applies to; empty is every environment.
533	#[serde(default)]
534	pub environments: Vec<String>,
535	/// A workspace's row: the projects it reaches, by slug; empty is every
536	/// project.
537	#[serde(default)]
538	pub projects: Vec<String>,
539	#[serde(default)]
540	pub note: Option<String>,
541	#[serde(default)]
542	pub updated_by: Option<String>,
543	}
544
545	// --- Methods ---------------------------------------------------------------
546
547	/// `workflows`. Returns `Outcome<Vec<Workflow>>`.
548	#[derive(Debug, Serialize, Deserialize)]
549	pub struct WorkflowsArgs {
550	pub repo: RepoPath,
551	pub viewer: Viewer,
552	}
553
554	/// `runs`: newest first. Returns `Outcome<Vec<WorkflowRun>>`.
555	#[derive(Debug, Serialize, Deserialize)]
556	pub struct RunsArgs {
557	pub repo: RepoPath,
558	pub viewer: Viewer,
559	/// A workflow's id or file name.
560	#[serde(default)]
561	pub workflow: Option<String>,
562	#[serde(default)]
563	pub branch: Option<String>,
564	#[serde(default)]
565	pub event: Option<String>,
566	/// The pull request's number.
567	#[serde(default)]
568	pub pull: Option<u32>,
569	#[serde(default)]
570	pub sha: Option<String>,
571	#[serde(default)]
572	pub limit: Option<u32>,
573	}
574
575	/// `run`. Returns `Outcome<RunDetail>`.
576	#[derive(Debug, Serialize, Deserialize)]
577	pub struct RunArgs {
578	pub repo: RepoPath,
579	pub viewer: Viewer,
580	pub id: String,
581	/// An earlier attempt; the latest when absent.
582	#[serde(default)]
583	pub attempt: Option<u64>,
584	}
585
586	/// `summaries`: the job summaries of a run's attempt (the latest when
587	/// `attempt` is absent), jobs in the run's order, those with none left
588	/// out. Returns `Outcome<Vec<JobSummary>>`.
589	#[derive(Debug, Serialize, Deserialize)]
590	pub struct SummariesArgs {
591	pub repo: RepoPath,
592	pub viewer: Viewer,
593	pub id: String,
594	#[serde(default)]
595	pub attempt: Option<u64>,
596	}
597
598	/// `job_log_text`: one job's whole log, any attempt's (by the id the run
599	/// gave the job). Returns `Outcome<JobLogText>`.
600	#[derive(Debug, Serialize, Deserialize)]
601	pub struct JobLogTextArgs {
602	pub repo: RepoPath,
603	pub viewer: Viewer,
604	pub job: String,
605	}
606
607	/// `run_logs`: every job's whole log for an attempt of a run (the latest
608	/// when `attempt` is absent), until they add up to `MAX_RUN_LOG_BYTES`;
609	/// jobs past it come `omitted`, with no chunks. Returns
610	/// `Outcome<Vec<JobLogText>>`.
611	#[derive(Debug, Serialize, Deserialize)]
612	pub struct RunLogsArgs {
613	pub repo: RepoPath,
614	pub viewer: Viewer,
615	pub id: String,
616	#[serde(default)]
617	pub attempt: Option<u64>,
618	}
619
620	/// The most log `run_logs` returns at once, in bytes.
621	pub const MAX_RUN_LOG_BYTES: usize = 24 * 1024 * 1024;
622
623	/// `logs`: a job's log after `after`. Returns `Outcome<JobLog>`.
624	#[derive(Debug, Serialize, Deserialize)]
625	pub struct LogsArgs {
626	pub repo: RepoPath,
627	pub viewer: Viewer,
628	pub job: String,
629	#[serde(default)]
630	pub after: u64,
631	}
632
633	/// `dispatch`: run a workflow that has `workflow_dispatch`. Members only.
634	/// Returns `Outcome<WorkflowRun>`.
635	#[derive(Debug, Serialize, Deserialize)]
636	pub struct DispatchArgs {
637	pub actor: User,
638	pub repo: RepoPath,
639	/// A workflow's id or file name.
640	pub workflow: String,
641	/// A branch or tag; the default branch when absent.
642	#[serde(default, rename = "ref")]
643	pub git_ref: Option<String>,
644	#[serde(default)]
645	pub inputs: serde_json::Map<String, Value>,
646	}
647
648	/// `cancel` and `rerun`: every job, with `failed_only` the ones that did
649	/// not succeed, or with `job` that one job (by its id in the run's latest
650	/// attempt); each with the jobs that need them. `debug` runs the new
651	/// attempt with debug logging. Members only. Returns `Outcome<WorkflowRun>`.
652	#[derive(Debug, Serialize, Deserialize)]
653	pub struct RunActionArgs {
654	pub actor: User,
655	pub repo: RepoPath,
656	pub id: String,
657	#[serde(default)]
658	pub failed_only: bool,
659	#[serde(default)]
660	pub job: Option<String>,
661	#[serde(default)]
662	pub debug: bool,
663	/// `cancel`: stop running jobs outright, without their cleanup steps.
664	#[serde(default)]
665	pub force: bool,
666	}
667
668	/// `set_workflow_enabled`. Members only. Returns `Outcome<Workflow>`.
669	#[derive(Debug, Serialize, Deserialize)]
670	pub struct SetWorkflowEnabledArgs {
671	pub actor: User,
672	pub repo: RepoPath,
673	pub workflow: String,
674	pub enabled: bool,
675	}
676
677	/// Whose secrets or variables: a repository's, or with only `workspace`,
678	/// a workspace's.
679	#[derive(Clone, Debug, Serialize, Deserialize)]
680	pub struct SettingsOwner {
681	#[serde(default)]
682	pub repo: Option<RepoPath>,
683	#[serde(default)]
684	pub workspace: Option<String>,
685	}
686
687	/// `settings`: the secrets (`kind: secret`) or variables (`kind: variable`)
688	/// of a repository, with its workspace's, or of a workspace. Members only.
689	/// Returns `Outcome<Vec<Setting>>`.
690	#[derive(Debug, Serialize, Deserialize)]
691	pub struct SettingsArgs {
692	pub actor: User,
693	#[serde(flatten)]
694	pub owner: SettingsOwner,
695	pub kind: String,
696	}
697
698	/// `set_setting`: add or replace one. A repository's need a member; a
699	/// workspace's an owner. Returns `Outcome<Setting>`.
700	#[derive(Debug, Serialize, Deserialize)]
701	pub struct SetSettingArgs {
702	pub actor: User,
703	#[serde(flatten)]
704	pub owner: SettingsOwner,
705	/// `secret` or `variable`. Changing a variable's row to `secret` seals
706	/// it; a secret cannot become a variable.
707	pub kind: String,
708	pub name: String,
709	/// The row to change. Left out, the key's row for every environment, as
710	/// GitHub's API addresses a secret by name alone.
711	#[serde(default)]
712	pub id: Option<String>,
713	/// Needed for a new row; left out, an existing row keeps its value.
714	#[serde(default)]
715	pub value: Option<String>,
716	/// `workflows` and/or `deployments`; left out, unchanged (both, for a
717	/// new row).
718	// Named as callers send it: an `alias` is not honoured beside the
719	// flattened owner in the Worker's build.
720	#[serde(default, rename = "availableTo")]
721	pub available_to: Option<Vec<String>>,
722	/// The environments it applies to; empty is every one. Left out,
723	/// unchanged.
724	#[serde(default)]
725	pub environments: Option<Vec<String>>,
726	/// A workspace's row: project slugs; empty for every one.
727	#[serde(default)]
728	pub projects: Option<Vec<String>>,
729	#[serde(default)]
730	pub note: Option<String>,
731	}
732
733	/// `resolve_settings`: the secrets and variables one reader gets, for the
734	/// services that hand them out (the deployments service). Returns
735	/// `ResolvedSettings`.
736	#[derive(Debug, Serialize, Deserialize)]
737	#[serde(rename_all = "camelCase")]
738	pub struct ResolveSettingsArgs {
739	pub repo_id: String,
740	pub repo: RepoPath,
741	/// The project being read for; its repository's primary project if left
742	/// out.
743	#[serde(default)]
744	pub project_id: Option<String>,
745	#[serde(default)]
746	pub project_slug: Option<String>,
747	/// `workflows` or `deployments`.
748	pub consumer: String,
749	/// The environment being read for, such as `production` or `preview`.
750	#[serde(default)]
751	pub environment: Option<String>,
752	/// Whether the run is trusted; an untrusted one gets no secrets.
753	pub trusted: bool,
754	}
755
756	#[derive(Debug, Default, Serialize, Deserialize)]
757	pub struct ResolvedSettings {
758	pub secrets: serde_json::Map<String, serde_json::Value>,
759	pub variables: serde_json::Map<String, serde_json::Value>,
760	}
761
762	/// `delete_setting`. Returns `Outcome<bool>`.
763	#[derive(Debug, Serialize, Deserialize)]
764	pub struct DeleteSettingArgs {
765	pub actor: User,
766	#[serde(flatten)]
767	pub owner: SettingsOwner,
768	pub kind: String,
769	pub name: String,
770	/// One row; left out, every row of the key.
771	#[serde(default)]
772	pub id: Option<String>,
773	}
774
775	/// `job_spec` and `job_report`: the sandbox running a job, with the job's
776	/// own token. `report` is one of:
777	/// `{"kind": "step", "number", "status", "conclusion"}`,
778	/// `{"kind": "log", "step", "text"}`,
779	/// `{"kind": "annotation", "level", "message", "title", "file", "line"}`,
780	/// `{"kind": "done", "conclusion", "outputs", "reason"}`.
781	#[derive(Debug, Serialize, Deserialize)]
782	pub struct JobCallArgs {
783	pub job: String,
784	pub token: String,
785	#[serde(default)]
786	pub report: Value,
787	}
788
789	/// What the runner needs to start a job's sandbox.
790	#[derive(Debug, Serialize, Deserialize)]
791	#[serde(rename_all = "camelCase")]
792	pub struct StartJobArgs {
793	pub job: String,
794	pub token: String,
795	pub repo: RepoPath,
796	/// Minutes before the job is stopped.
797	pub timeout_minutes: u32,
798	/// The workflow file the job is in (`.g1t/workflows/deploy.yml`), for
799	/// the guardrails' workflow-only domains.
800	#[serde(default)]
801	pub workflow: Option<String>,
802	/// The environment the job names with `environment:`, when it names
803	/// one plainly (not with an expression).
804	#[serde(default)]
805	pub environment: Option<String>,
806	/// Whether its run is trusted: not a pull request from a fork. Only a
807	/// trusted run's jobs reach workflow-only domains.
808	#[serde(default)]
809	pub trusted: bool,
810	/// The machine its `runs-on` asked for, by label (`instance_for`):
811	/// `g1t-2core` or `g1t-4core`; absent, the standard one.
812	#[serde(default)]
813	pub instance: Option<String>,
814	}
815
816	/// A size of machine g1t runs workflow jobs on, asked for by a label in
817	/// `runs-on`. Each is a Cloudflare Containers instance type; it costs what
818	/// that instance costs g1t, plus the margin, like any sandbox time.
819	#[derive(Clone, Copy, Debug, PartialEq)]
820	pub struct InstanceType {
821	/// The `runs-on` label, or `standard` for the default.
822	pub label: &'static str,
823	/// The Containers instance type.
824	pub container: &'static str,
825	pub vcpu: f64,
826	pub memory_gib: f64,
827	pub disk_gb: f64,
828	/// What a second of it costs g1t as a multiple of the standard
829	/// machine's, with its vCPUs as busy (Cloudflare's list prices:
830	/// memory $0.0000025 a GiB-second, disk $0.00000007 a GB-second, vCPU
831	/// $0.00002 a second). Used to reserve before a job starts, and to
832	/// price a job that did not report its own CPU.
833	pub price_scale: f64,
834	}
835
836	/// The default: what `ubuntu-latest` and every other hosted label get.
837	pub const STANDARD_INSTANCE: InstanceType =
838	InstanceType { label: "standard", container: "standard-1", vcpu: 0.5, memory_gib: 4.0, disk_gb: 8.0, price_scale: 1.0 };
839
840	/// Every machine a workflow job can ask for, the default first.
841	pub const INSTANCE_TYPES: [InstanceType; 3] = [
842	STANDARD_INSTANCE,
843	InstanceType { label: "g1t-2core", container: "standard-3", vcpu: 2.0, memory_gib: 8.0, disk_gb: 16.0, price_scale: 2.8 },
844	InstanceType { label: "g1t-4core", container: "standard-4", vcpu: 4.0, memory_gib: 12.0, disk_gb: 20.0, price_scale: 5.1 },
845	];
846
847	/// The machine a job's `runs-on` labels ask for: the largest named, or the
848	/// standard one. Labels compare without regard to case.
849	pub fn instance_for(labels: &[String]) -> InstanceType {
850	INSTANCE_TYPES
851	.iter()
852	.rev()
853	.find(\|instance\| instance.label != STANDARD_INSTANCE.label && labels.iter().any(\|label\| label.trim().eq_ignore_ascii_case(instance.label)))
854	.copied()
855	.unwrap_or(STANDARD_INSTANCE)
856	}
857
858	/// An instance type by its label, if it is one.
859	pub fn instance_named(label: &str) -> Option<InstanceType> {
860	INSTANCE_TYPES.iter().find(\|instance\| instance.label.eq_ignore_ascii_case(label.trim())).copied()
861	}
862
863	// ── The cache (actions/cache) ─────────────────────────────────────────────
864	//
865	// Entries are kept in R2 by the API (the ACTIONS_CACHE bucket) and listed
866	// here, by the actions service, which decides what is found, what fits and
867	// what is evicted. A sandbox reaches these through the API with its job's
868	// token: `/actions/jobs/{job}/cache` (see apps/api/src/blobs.rs).
869
870	/// The largest one cache entry may be, compressed.
871	pub const CACHE_MAX_ENTRY_BYTES: u64 = 2 * 1024 * 1024 * 1024;
872	/// What one repository's entries may hold together. Saving past it evicts
873	/// the entries restored longest ago.
874	pub const CACHE_REPO_QUOTA_BYTES: u64 = 10 * 1024 * 1024 * 1024;
875	/// An entry not restored for this long is deleted.
876	pub const CACHE_UNUSED_DAYS: u64 = 7;
877	/// An entry is deleted this long after it was saved, however often it is
878	/// restored (the bucket's own lifecycle rule deletes objects at 30 days).
879	pub const CACHE_MAX_AGE_DAYS: u64 = 28;
880	/// An upload is sent in parts of this size (the last may be smaller).
881	pub const CACHE_PART_BYTES: u64 = 32 * 1024 * 1024;
882	/// What R2 charges g1t to store a GB for a month, in millionths of a
883	/// dollar ($0.015): what the cache's storage is charged at, plus the margin.
884	pub const CACHE_MICROS_PER_GB_MONTH: i64 = 15_000;
885
886	/// `cache_lookup`: the entry a job restores: its key exactly, else the
887	/// newest whose key starts with one of `restore`, in order.
888	/// Returns `Outcome<Option<CacheHit>>`.
889	#[derive(Debug, Serialize, Deserialize)]
890	pub struct CacheLookupArgs {
891	pub job: String,
892	pub token: String,
893	pub key: String,
894	#[serde(default)]
895	pub restore: Vec<String>,
896	/// The entry's version, a hash of its paths and compression, as the
897	/// toolkit's client and g1t's runner both send it: only an entry of the
898	/// same version is found. `None` from runners that send none, whose
899	/// entries have none.
900	#[serde(default)]
901	pub version: Option<String>,
902	}
903
904	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
905	pub struct CacheHit {
906	pub key: String,
907	pub object: String,
908	pub size: u64,
909	/// When it was saved, RFC 3339.
910	#[serde(default)]
911	pub created_at: String,
912	/// A signed token for downloading it through the toolkit's blob
913	/// endpoint, when the lookup came with a version.
914	#[serde(default)]
915	pub blob: Option<String>,
916	}
917
918	/// `cache_reserve`: a job about to save `size` bytes under `key`. Refused
919	/// when the key is taken (`conflict`: keys are written once) or the entry
920	/// is too large. Returns `Outcome<CacheReservation>`.
921	#[derive(Debug, Serialize, Deserialize)]
922	pub struct CacheReserveArgs {
923	pub job: String,
924	pub token: String,
925	pub key: String,
926	/// Its size, when known before it is sent (the toolkit's newer client
927	/// says only when it finishes: 0 then).
928	pub size: u64,
929	/// As in `CacheLookupArgs`.
930	#[serde(default)]
931	pub version: Option<String>,
932	}
933
934	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
935	pub struct CacheReservation {
936	pub id: String,
937	/// Where the API puts it in R2.
938	pub object: String,
939	/// The entry's number, which the toolkit's older protocol names it by.
940	#[serde(default)]
941	pub number: u64,
942	/// Its R2 upload, once one is started.
943	#[serde(default)]
944	pub upload: Option<String>,
945	/// A signed token for sending its parts through the toolkit's blob
946	/// endpoint, once its upload is started.
947	#[serde(default)]
948	pub blob: Option<String>,
949	}
950
951	/// `cache_upload`: an entry a job is still uploading, by its number or by
952	/// key and version. Returns `Outcome<CacheReservation>`, with `upload` and
953	/// `blob` set once its upload has been started.
954	#[derive(Debug, Serialize, Deserialize)]
955	pub struct CacheUploadArgs {
956	pub job: String,
957	pub token: String,
958	#[serde(default)]
959	pub number: Option<u64>,
960	#[serde(default)]
961	pub key: Option<String>,
962	#[serde(default)]
963	pub version: Option<String>,
964	}
965
966	/// `cache_commit`: the upload of `id` is complete, at `size` bytes. Returns
967	/// `Outcome<CacheCommitted>`: the objects of entries it evicted, which the
968	/// API deletes from R2.
969	#[derive(Debug, Serialize, Deserialize)]
970	pub struct CacheCommitArgs {
971	pub job: String,
972	pub token: String,
973	pub id: String,
974	pub size: u64,
975	}
976
977	#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
978	pub struct CacheCommitted {
979	pub evicted: Vec<String>,
980	}
981
982	/// `cache_abort`: an upload that will not finish; its reservation goes.
983	/// Returns `Outcome<bool>`.
984	#[derive(Debug, Serialize, Deserialize)]
985	pub struct CacheAbortArgs {
986	pub job: String,
987	pub token: String,
988	pub id: String,
989	}
990
991	// ── Artifacts (actions/upload-artifact) ───────────────────────────────────
992	//
993	// Kept in R2 by the API (the ACTIONS_CACHE bucket, under `a/`) and listed
994	// here, by the actions service, which decides names, sizes and how long
995	// each is kept. A sandbox reaches them with its job's token
996	// (`/actions/jobs/{job}/artifacts…`) or, through the toolkit's protocol,
997	// with its runtime token (`ACTIONS_RUNTIME_TOKEN`); people through the
998	// REST API and the run's page.
999
1000	/// The largest one artifact may be.
1001	pub const ARTIFACT_MAX_BYTES: u64 = 5 * 1024 * 1024 * 1024;
1002	/// What one run's artifacts may hold together.
1003	pub const RUN_ARTIFACTS_MAX_BYTES: u64 = 10 * 1024 * 1024 * 1024;
1004	/// How long artifacts are kept unless a repository says otherwise.
1005	pub const ARTIFACT_RETENTION_DEFAULT_DAYS: u32 = 14;
1006	/// The longest a repository may keep them.
1007	pub const ARTIFACT_RETENTION_MAX_DAYS: u32 = 90;
1008	/// A native upload is sent in parts of this size (the last may be smaller).
1009	pub const ARTIFACT_PART_BYTES: u64 = 32 * 1024 * 1024;
1010
1011	/// An artifact, as the API and the site show it.
1012	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1013	pub struct Artifact {
1014	pub id: u64,
1015	pub name: String,
1016	pub size: u64,
1017	/// `sha256:<hex>`, when the uploader said.
1018	pub digest: Option<String>,
1019	/// `zip`, or `tgz` for one an older runner sent.
1020	pub format: String,
1021	pub run_id: String,
1022	pub job_id: String,
1023	pub repo_id: String,
1024	/// Whether it has expired or been deleted (its bytes are gone).
1025	pub expired: bool,
1026	pub created_at: String,
1027	pub updated_at: String,
1028	pub expires_at: String,
1029	/// The run's branch and commit, for the REST shape.
1030	#[serde(default)]
1031	pub head_branch: Option<String>,
1032	#[serde(default)]
1033	pub head_sha: Option<String>,
1034	}
1035
1036	/// An artifact with where its bytes are, and a signed token for them.
1037	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1038	pub struct ArtifactBlob {
1039	pub artifact: Artifact,
1040	pub object: String,
1041	/// For the toolkit's blob endpoint (`/actions/toolkit/blobs/{blob}`).
1042	pub blob: String,
1043	}
1044
1045	/// A page of artifacts, in GitHub's shape.
1046	#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
1047	pub struct ArtifactList {
1048	pub total_count: u64,
1049	pub artifacts: Vec<Artifact>,
1050	}
1051
1052	/// `artifact_reserve`: a job about to upload an artifact. Refused when its
1053	/// run has one of that name and `overwrite` is not set (`conflict`), or it
1054	/// is too large. Returns `Outcome<ArtifactReservation>`.
1055	#[derive(Debug, Default, Serialize, Deserialize)]
1056	pub struct ArtifactReserveArgs {
1057	pub job: String,
1058	/// The job's token, or its runtime token.
1059	pub token: String,
1060	pub name: String,
1061	/// Its size, when known before it is sent (0 otherwise).
1062	#[serde(default)]
1063	pub size: u64,
1064	/// Days to keep it: 0 for the repository's default; at most the
1065	/// repository's setting.
1066	#[serde(default)]
1067	pub retention_days: u32,
1068	/// When to expire it, RFC 3339, as the toolkit says it (in place of
1069	/// `retention_days`).
1070	#[serde(default)]
1071	pub expires_at: Option<String>,
1072	#[serde(default)]
1073	pub overwrite: bool,
1074	/// `zip` (the default) or `tgz`.
1075	#[serde(default)]
1076	pub format: Option<String>,
1077	}
1078
1079	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1080	pub struct ArtifactReservation {
1081	pub id: u64,
1082	/// Where the API puts it in R2.
1083	pub object: String,
1084	/// The days it will be kept, and until when.
1085	pub retention_days: u32,
1086	pub expires_at: String,
1087	}
1088
1089	/// `artifact_commit`: its upload is complete, at `size` bytes. The artifact
1090	/// is named by `id`, or by `name` in the job's run (the toolkit's way).
1091	/// Returns `Outcome<Artifact>`.
1092	#[derive(Debug, Default, Serialize, Deserialize)]
1093	pub struct ArtifactCommitArgs {
1094	pub job: String,
1095	pub token: String,
1096	#[serde(default)]
1097	pub id: Option<u64>,
1098	#[serde(default)]
1099	pub name: Option<String>,
1100	pub size: u64,
1101	#[serde(default)]
1102	pub digest: Option<String>,
1103	}
1104
1105	/// `job_artifacts`: a running job listing the artifacts of its own run, or
1106	/// of another run of its repository (`run_id`), narrowed by `name` or
1107	/// `id`: `Outcome<Vec<Artifact>>`. `job_artifact` gives the one named, with
1108	/// a token to download it: `Outcome<ArtifactBlob>`. `job_delete_artifact`
1109	/// deletes one of its own run's: `Outcome<Artifact>`. `artifact_abort`
1110	/// gives up an upload by `id`: `Outcome<bool>`.
1111	#[derive(Debug, Default, Serialize, Deserialize)]
1112	pub struct JobArtifactsArgs {
1113	pub job: String,
1114	pub token: String,
1115	#[serde(default)]
1116	pub run_id: Option<String>,
1117	#[serde(default)]
1118	pub name: Option<String>,
1119	#[serde(default)]
1120	pub id: Option<u64>,
1121	}
1122
1123	/// `artifacts`: a repository's artifacts, newest first, or one run's.
1124	/// Anyone who can see the repository. Returns `Outcome<ArtifactList>`.
1125	#[derive(Debug, Serialize, Deserialize)]
1126	pub struct ArtifactsArgs {
1127	pub repo: RepoPath,
1128	pub viewer: Viewer,
1129	#[serde(default)]
1130	pub run: Option<String>,
1131	#[serde(default)]
1132	pub name: Option<String>,
1133	#[serde(default)]
1134	pub page: Option<u32>,
1135	#[serde(default)]
1136	pub per_page: Option<u32>,
1137	}
1138
1139	/// `artifact` (`Outcome<Artifact>`) and `artifact_download`
1140	/// (`Outcome<ArtifactBlob>`, with a token good for a few minutes): one
1141	/// artifact by `id`, or by `name` within `run`. Anyone who can see the
1142	/// repository.
1143	#[derive(Debug, Serialize, Deserialize)]
1144	pub struct ArtifactArgs {
1145	pub repo: RepoPath,
1146	pub viewer: Viewer,
1147	#[serde(default)]
1148	pub id: Option<u64>,
1149	#[serde(default)]
1150	pub run: Option<String>,
1151	#[serde(default)]
1152	pub name: Option<String>,
1153	}
1154
1155	/// `delete_artifact`: needs the Write role. Returns `Outcome<Artifact>`.
1156	#[derive(Debug, Serialize, Deserialize)]
1157	pub struct DeleteArtifactArgs {
1158	pub actor: User,
1159	pub repo: RepoPath,
1160	pub id: u64,
1161	}
1162
1163	/// `artifact_retention`: anyone who can see the repository. With `days`,
1164	/// sets it, which needs the Maintain role. Returns
1165	/// `Outcome<ArtifactRetention>`.
1166	#[derive(Debug, Serialize, Deserialize)]
1167	pub struct ArtifactRetentionArgs {
1168	pub repo: RepoPath,
1169	pub viewer: Viewer,
1170	#[serde(default)]
1171	pub days: Option<u32>,
1172	}
1173
1174	/// GitHub's shape: the days artifacts are kept by default, and the most a
1175	/// repository may choose.
1176	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1177	pub struct ArtifactRetention {
1178	pub days: u32,
1179	pub maximum_allowed_days: u32,
1180	}
1181
1182	// ── The toolkit's protocols ───────────────────────────────────────────────
1183	//
1184	// Actions built on GitHub's toolkit (`@actions/cache`, `@actions/artifact`,
1185	// `@actions/core`'s `getIDToken`) reach g1t with the job's runtime token,
1186	// `ACTIONS_RUNTIME_TOKEN`: a JSON Web Token whose `scp` names the run and
1187	// job, signed with a key derived from the job's own token, so the actions
1188	// service checks it without keeping another secret. Cache and artifact
1189	// operations above take it in place of the job's token.
1190
1191	/// `runtime_auth`: which job a runtime token is, while it runs:
1192	/// `Outcome<RuntimeJob>`. `oidc_claims` takes the same and returns
1193	/// `Outcome<Value>`: the claims of the job's OIDC token, less `iss`, `aud`,
1194	/// `jti` and the times, or `forbidden` when the job's `permissions` do not
1195	/// give it `id-token: write`.
1196	#[derive(Debug, Serialize, Deserialize)]
1197	pub struct RuntimeAuthArgs {
1198	pub job: String,
1199	pub token: String,
1200	}
1201
1202	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1203	pub struct RuntimeJob {
1204	pub job: String,
1205	pub run: String,
1206	pub repo_id: String,
1207	pub namespace: String,
1208	/// `owner/name`.
1209	pub repository: String,
1210	}
1211
1212	/// What a signed blob token lets its holder do.
1213	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1214	pub struct BlobGrant {
1215	/// `cache` or `artifact`.
1216	pub kind: String,
1217	/// The entry's id: a cache entry's `cache_…`, an artifact's number.
1218	pub id: String,
1219	pub object: String,
1220	/// The R2 upload it sends parts to; `None` for a download.
1221	pub upload: Option<String>,
1222	/// For a download: what to call the file, and its type.
1223	#[serde(default)]
1224	pub filename: Option<String>,
1225	#[serde(default)]
1226	pub content_type: Option<String>,
1227	}
1228
1229	/// `blob_sign`: a token for uploading an entry the job reserved, to the R2
1230	/// upload the API started for it. Returns `Outcome<String>`.
1231	#[derive(Debug, Serialize, Deserialize)]
1232	pub struct BlobSignArgs {
1233	pub job: String,
1234	pub token: String,
1235	/// `cache` or `artifact`.
1236	pub kind: String,
1237	pub id: String,
1238	pub upload: String,
1239	}
1240
1241	/// `blob_open`: what a signed token grants, while it is good and its entry
1242	/// is there: `Outcome<BlobGrant>`. `blob_part` records a part sent with an
1243	/// upload token (`part`, `etag`, `size`): `Outcome<bool>`. `blob_parts`
1244	/// gives the parts recorded, in order: `Outcome<Vec<BlobPart>>`, and
1245	/// `blob_done` forgets them: `Outcome<bool>`.
1246	#[derive(Debug, Default, Serialize, Deserialize)]
1247	pub struct BlobArgs {
1248	pub blob: String,
1249	#[serde(default)]
1250	pub part: u32,
1251	#[serde(default)]
1252	pub etag: String,
1253	#[serde(default)]
1254	pub size: u64,
1255	}
1256
1257	#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1258	pub struct BlobPart {
1259	pub part: u32,
1260	pub etag: String,
1261	pub size: u64,
1262	}
1263
1264	#[cfg(test)]
1265	mod instance_tests {
1266	use super::*;
1267
1268	fn labels(given: &[&str]) -> Vec<String> {
1269	given.iter().map(\|l\| (*l).to_owned()).collect()
1270	}
1271
1272	#[test]
1273	fn runs_on_picks_the_machine() {
1274	assert_eq!(instance_for(&labels(&["ubuntu-latest"])).container, "standard-1");
1275	assert_eq!(instance_for(&labels(&[])).label, "standard");
1276	assert_eq!(instance_for(&labels(&["g1t-4core"])).container, "standard-4");
1277	assert_eq!(instance_for(&labels(&["ubuntu-latest", "G1T-2Core"])).container, "standard-3");
1278	// Both named: the larger.
1279	assert_eq!(instance_for(&labels(&["g1t-2core", "g1t-4core"])).label, "g1t-4core");
1280	assert_eq!(instance_named("g1t-4core").map(\|i\| i.vcpu), Some(4.0));
1281	assert_eq!(instance_named("standard"), Some(STANDARD_INSTANCE));
1282	assert_eq!(instance_named("g1t-64core"), None);
1283	}
1284
1285	#[test]
1286	fn start_args_from_older_callers_read() {
1287	let args: StartJobArgs = serde_json::from_value(serde_json::json!({
1288	"job": "job_1", "token": "t", "repo": { "namespace": "acme", "name": "web" }, "timeoutMinutes": 30
1289	}))
1290	.unwrap();
1291	assert!(args.workflow.is_none() && args.environment.is_none() && !args.trusted && args.instance.is_none());
1292	}
1293	}
1294
1295	#[cfg(test)]
1296	mod setting_args_tests {
1297	use super::*;
1298
1299	#[test]
1300	fn who_reads_a_row_is_read_as_the_site_and_api_send_it() {
1301	let args: SetSettingArgs = serde_json::from_value(serde_json::json!({
1302	"actor": { "id": "usr_1", "username": "a" },
1303	"repo": { "namespace": "acme", "name": "web" },
1304	"kind": "secret",
1305	"name": "STRIPE_KEY",
1306	"availableTo": ["deployments"],
1307	"environments": ["production"],
1308	}))
1309	.unwrap();
1310	assert_eq!(args.available_to, Some(vec!["deployments".to_owned()]));
1311	}
1312	}