Sign in

flagon-io/g1t

public

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

gitagentscloudflarerustforgemcp

g1t/crates/contracts/src/repos.rs

407 lines11,945 bytesCodeBlame
1//! The repos service: repository metadata, contents, forks and git access.
2//!
3//! Each `*Args` struct is the argument of the method of the same name,
4//! served at `POST /rpc/<method>`.
5
6use serde::{Deserialize, Serialize};
7
8use crate::{User, Viewer};
9
10#[derive(Clone, Debug, Serialize, Deserialize)]
11#[serde(rename_all = "camelCase")]
12pub struct Repo {
13 pub id: String,
14 /// The slug of the workspace that owns it: the first URL segment.
15 pub namespace: String,
16 pub name: String,
17 pub description: Option<String>,
18 pub is_private: bool,
19 pub owner_id: String,
20 pub default_branch: String,
21 /// Set when this repo is a pull request's working copy of another repo.
22 pub fork_of: Option<String>,
23 /// Whether the default branch is protected: it changes only by merging
24 /// a pull request, and pushes to it are refused.
25 #[serde(default)]
26 pub protected: bool,
27 /// RFC 3339.
28 pub created_at: String,
29}
30
31#[derive(Clone, Debug, Serialize, Deserialize)]
32pub struct RepoPath {
33 pub namespace: String,
34 pub name: String,
35}
36
37#[derive(Clone, Debug, Serialize, Deserialize)]
38pub struct Signature {
39 pub name: String,
40 pub email: String,
41}
42
43#[derive(Clone, Debug, Serialize, Deserialize)]
44#[serde(rename_all = "camelCase")]
45pub struct Commit {
46 pub hash: String,
47 pub tree_hash: String,
48 pub message: String,
49 pub author: Signature,
50 pub parents: Vec<String>,
51 /// RFC 3339.
52 pub authored_at: String,
53}
54
55#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
56#[serde(rename_all = "lowercase")]
57pub enum EntryKind {
58 Tree,
59 Blob,
60 Symlink,
61 Gitlink,
62 Exec,
63}
64
65#[derive(Clone, Debug, Serialize, Deserialize)]
66pub struct TreeEntry {
67 pub name: String,
68 pub hash: String,
69 pub kind: EntryKind,
70}
71
72#[derive(Clone, Debug, Serialize, Deserialize)]
73pub struct Readme {
74 pub name: String,
75 /// Null when the file is binary or too large to show.
76 pub text: Option<String>,
77}
78
79#[derive(Clone, Debug, Serialize, Deserialize)]
80pub struct TreeView {
81 pub repo: Repo,
82 #[serde(rename = "ref")]
83 pub git_ref: String,
84 pub path: String,
85 /// Null when the repo has no commits yet.
86 pub head: Option<Commit>,
87 pub entries: Vec<TreeEntry>,
88 pub readme: Option<Readme>,
89}
90
91#[derive(Clone, Debug, Serialize, Deserialize)]
92pub struct BlobView {
93 pub repo: Repo,
94 #[serde(rename = "ref")]
95 pub git_ref: String,
96 pub path: String,
97 pub size: u64,
98 /// Null when the file is binary or too large to show.
99 pub text: Option<String>,
100}
101
102/// A git remote and a short-lived credential for it.
103#[derive(Clone, Debug, Serialize, Deserialize)]
104pub struct GitAccess {
105 pub remote: String,
106 pub token: String,
107}
108
109#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
110pub enum GitService {
111 #[serde(rename = "git-upload-pack")]
112 UploadPack,
113 #[serde(rename = "git-receive-pack")]
114 ReceivePack,
115}
116
117/// The result of landing a pull request.
118#[derive(Clone, Debug, Serialize, Deserialize)]
119pub struct Landed {
120 /// The commit the branch points to now.
121 pub commit: String,
122 /// The commit it pointed to before, if it had one. Comparing against
123 /// this shows what the pull request changed.
124 pub previous: Option<String>,
125}
126
127/// `get`. Returns `Outcome<Repo>`.
128#[derive(Debug, Serialize, Deserialize)]
129pub struct GetArgs {
130 pub path: RepoPath,
131 pub viewer: Viewer,
132}
133
134/// `get_by_id`. Returns `Outcome<Repo>`.
135#[derive(Debug, Serialize, Deserialize)]
136pub struct GetByIdArgs {
137 pub id: String,
138 pub viewer: Viewer,
139}
140
141/// `list`: repos the viewer may see, newest first. Returns `Vec<Repo>`.
142#[derive(Debug, Default, Serialize, Deserialize)]
143#[serde(rename_all = "camelCase")]
144pub struct ListArgs {
145 pub viewer: Viewer,
146 #[serde(default)]
147 pub query: Option<String>,
148 /// Only repos in this workspace.
149 #[serde(default)]
150 pub namespace: Option<String>,
151 /// Only repos in workspaces the viewer belongs to.
152 #[serde(default)]
153 pub member_only: bool,
154}
155
156/// `create`. Returns `Outcome<Repo>`.
157#[derive(Debug, Serialize, Deserialize)]
158#[serde(rename_all = "camelCase")]
159pub struct CreateArgs {
160 /// Who is creating it; they must belong to the workspace.
161 pub owner: User,
162 /// The workspace it is created in.
163 pub namespace: String,
164 pub name: String,
165 #[serde(default)]
166 pub description: Option<String>,
167 #[serde(default)]
168 pub is_private: bool,
169 /// The https address of a public git repository to copy the default
170 /// branch of, such as `https://github.com/owner/repo`.
171 #[serde(default)]
172 pub import_url: Option<String>,
173}
174
175/// `update`: changes whichever of a repository's details are given.
176/// Members of its workspace only. Returns `Outcome<Repo>`.
177#[derive(Debug, Serialize, Deserialize)]
178#[serde(rename_all = "camelCase")]
179pub struct UpdateArgs {
180 pub actor: User,
181 pub path: RepoPath,
182 /// An empty description clears it.
183 #[serde(default)]
184 pub description: Option<String>,
185 #[serde(default)]
186 pub is_private: Option<bool>,
187 #[serde(default)]
188 pub protected: Option<bool>,
189}
190
191/// `tree`. Returns `Outcome<TreeView>`.
192#[derive(Debug, Serialize, Deserialize)]
193#[serde(rename_all = "camelCase")]
194pub struct TreeArgs {
195 pub path: RepoPath,
196 pub viewer: Viewer,
197 /// The default branch when absent.
198 #[serde(default, rename = "ref")]
199 pub git_ref: Option<String>,
200 #[serde(default)]
201 pub tree_path: String,
202}
203
204/// `blob`. Returns `Outcome<BlobView>`.
205#[derive(Debug, Serialize, Deserialize)]
206#[serde(rename_all = "camelCase")]
207pub struct BlobArgs {
208 pub path: RepoPath,
209 pub viewer: Viewer,
210 #[serde(rename = "ref")]
211 pub git_ref: String,
212 pub file_path: String,
213}
214
215/// `log`. Returns `Outcome<Vec<Commit>>`.
216#[derive(Debug, Serialize, Deserialize)]
217pub struct LogArgs {
218 pub path: RepoPath,
219 pub viewer: Viewer,
220 #[serde(default, rename = "ref")]
221 pub git_ref: Option<String>,
222 pub limit: u32,
223}
224
225/// `fork_for_pull`: a copy-on-write copy of the source repo, hidden from
226/// listings, for one pull request to be made in. Returns `Outcome<Repo>`.
227#[derive(Debug, Serialize, Deserialize)]
228#[serde(rename_all = "camelCase")]
229pub struct ForkArgs {
230 pub source_id: String,
231 pub pull_id: String,
232 pub actor: User,
233}
234
235/// `git_access`: authorizes a git operation and says where to send it.
236/// Pushing to a repo that does not exist creates it in the pusher's own
237/// namespace. Returns `Outcome<GitAccess>`.
238#[derive(Debug, Serialize, Deserialize)]
239pub struct GitAccessArgs {
240 pub path: RepoPath,
241 pub viewer: Viewer,
242 pub service: GitService,
243}
244
245/// `land`: moves a repository's default branch to the head of a pull
246/// request's source. Refused with `conflict` when the source is behind,
247/// since that would discard commits. Returns `Outcome<Landed>`.
248#[derive(Debug, Serialize, Deserialize)]
249#[serde(rename_all = "camelCase")]
250pub struct LandArgs {
251 /// The repository holding the commits: a pull request's fork, or the
252 /// target itself when landing one of its own branches.
253 pub source_id: String,
254 /// The branch of the source to land. Required when the source is the
255 /// target; a fork lands its default branch.
256 #[serde(default)]
257 pub branch: Option<String>,
258 pub actor: User,
259}
260
261#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
262#[serde(rename_all = "lowercase")]
263pub enum FileStatus {
264 Added,
265 Modified,
266 Deleted,
267}
268
269#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
270#[serde(rename_all = "lowercase")]
271pub enum LineKind {
272 /// Unchanged, shown for context.
273 Context,
274 Add,
275 Delete,
276}
277
278#[derive(Clone, Debug, Serialize, Deserialize)]
279pub struct DiffLine {
280 pub kind: LineKind,
281 /// Line number in the old file; absent for added lines.
282 pub old: Option<u32>,
283 /// Line number in the new file; absent for deleted lines.
284 pub new: Option<u32>,
285 pub text: String,
286}
287
288/// A run of changed lines with their surrounding context.
289#[derive(Clone, Debug, Serialize, Deserialize)]
290pub struct Hunk {
291 pub lines: Vec<DiffLine>,
292}
293
294#[derive(Clone, Debug, Serialize, Deserialize)]
295pub struct FileDiff {
296 pub path: String,
297 pub status: FileStatus,
298 pub additions: u32,
299 pub deletions: u32,
300 /// True when the file is binary or too large, so no lines are shown.
301 pub binary: bool,
302 pub hunks: Vec<Hunk>,
303}
304
305/// What changed between two commits.
306#[derive(Clone, Debug, Serialize, Deserialize)]
307pub struct Comparison {
308 /// Null when the head has no earlier commit to compare against.
309 pub base: Option<String>,
310 pub head: String,
311 pub files: Vec<FileDiff>,
312 /// True when the change was too large to return in full.
313 pub truncated: bool,
314}
315
316/// `compare`: what `head` changes relative to `base`.
317///
318/// `head` is a branch or a commit, and defaults to the default branch.
319/// With no `base`, a fork is compared against the point where it and the
320/// repository it came from last agreed; a branch against the point where it
321/// left the default branch; and the default branch against its head's
322/// parent. Returns `Outcome<Comparison>`.
323#[derive(Debug, Serialize, Deserialize)]
324#[serde(rename_all = "camelCase")]
325pub struct CompareArgs {
326 pub repo_id: String,
327 pub viewer: Viewer,
328 #[serde(default)]
329 pub base: Option<String>,
330 #[serde(default)]
331 pub head: Option<String>,
332}
333
334/// Lines `start` to `end` of a file, inclusive and counted from 1, last
335/// changed by `commit`.
336#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
337pub struct BlameRange {
338 pub start: u32,
339 pub end: u32,
340 pub commit: String,
341}
342
343/// Who last changed each line of a file.
344#[derive(Clone, Debug, Serialize, Deserialize)]
345pub struct Blame {
346 /// The commit the file was read at.
347 pub head: String,
348 /// Every line, in order, in runs that share a commit.
349 pub ranges: Vec<BlameRange>,
350 /// The commits the ranges name, each once.
351 pub commits: Vec<Commit>,
352 /// True when the history was too long to read in full, so the oldest
353 /// lines are given to the oldest commit read.
354 pub partial: bool,
355}
356
357/// `blame`: who last changed each line of `path` as of `ref` (the default
358/// branch if absent). Returns `Outcome<Blame>`; not found when the file is
359/// missing or is not text.
360#[derive(Debug, Serialize, Deserialize)]
361pub struct BlameArgs {
362 pub path: RepoPath,
363 pub viewer: Viewer,
364 #[serde(default, rename = "ref")]
365 pub git_ref: Option<String>,
366 #[serde(rename = "filePath")]
367 pub file_path: String,
368}
369
370/// A branch and the commit it points to.
371#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
372pub struct Branch {
373 pub name: String,
374 pub hash: String,
375}
376
377/// `branches`: the repository's branches, default branch first.
378/// Returns `Outcome<Vec<Branch>>`.
379#[derive(Debug, Serialize, Deserialize)]
380pub struct BranchesArgs {
381 pub path: RepoPath,
382 pub viewer: Viewer,
383}
384
385/// `behind`: whether the default branch of the repository a pull request
386/// would merge into has commits its source does not. For services that
387/// have already decided the caller may see the pull request; it reveals
388/// one bit. Returns `bool`.
389#[derive(Debug, Serialize, Deserialize)]
390#[serde(rename_all = "camelCase")]
391pub struct BehindArgs {
392 /// The pull request's fork, or the repository itself for a branch.
393 pub source_id: String,
394 /// The branch of the source. A fork is compared on its default branch.
395 #[serde(default)]
396 pub branch: Option<String>,
397}
398
399/// `head`: the commit a branch points to, or null. For services reacting
400/// to a push, which have no viewer; it reveals nothing but a commit hash.
401/// Returns `Option<String>`.
402#[derive(Debug, Serialize, Deserialize)]
403#[serde(rename_all = "camelCase")]
404pub struct HeadArgs {
405 pub repo_id: String,
406 pub branch: String,
407}