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/lib.rs

193 lines7,004 bytesCodeBlame
1//! Types and service interfaces shared by every g1t service.
2//!
3//! Each service has a module here holding the data it exchanges and the
4//! arguments of each of its methods. Services and their callers depend on
5//! this crate, never on each other's code.
6
7pub mod access;
8pub mod accounts;
9pub mod actions;
10pub mod agents;
11pub mod audit;
12pub mod billing;
13pub mod capture;
14pub mod credentials;
15pub mod events;
16pub mod github;
17pub mod guardrails;
18pub mod identity;
19pub mod integrations;
20mod ids;
21mod names;
22mod outcome;
23pub mod projects;
24pub mod repos;
25pub mod runners;
26pub mod scopes;
27pub mod search;
28pub mod security;
29pub mod time;
30pub mod webhooks;
31pub mod work;
32
33pub use ids::new_id;
34pub use names::{is_valid_namespace, is_valid_repo_name};
35pub use outcome::{Failure, FailureCode, Outcome};
36
37use serde::{Deserialize, Serialize};
38
39/// What a member may do in a workspace.
40#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
41#[serde(rename_all = "lowercase")]
42pub enum Role {
43 /// Everything a member can, plus managing members.
44 Owner,
45 /// Create repositories, push, manage issues and merge pull requests.
46 Member,
47}
48
49/// One workspace a user belongs to.
50#[derive(Clone, Debug, Serialize, Deserialize)]
51pub struct Membership {
52 /// The workspace's name in URLs: `g1t.sh/<slug>`.
53 pub slug: String,
54 pub role: Role,
55 /// The workspace's display name, for showing it to people. Set when a
56 /// user is resolved from credentials; absent on principals made up by
57 /// a service.
58 #[serde(default, skip_serializing_if = "Option::is_none")]
59 pub name: Option<String>,
60 /// The workspace's uploaded icon: the SHA-256 of its bytes, served at
61 /// `/avatars/<avatar>`. Absent means the generated letter avatar.
62 #[serde(default, skip_serializing_if = "Option::is_none")]
63 pub avatar: Option<String>,
64 /// What a member gets on each of the workspace's repositories: the
65 /// workspace's base permission. Set when a user is resolved from
66 /// credentials; absent means the default, Write. Owners have Admin
67 /// whatever it says. See [`access`].
68 #[serde(default, skip_serializing_if = "Option::is_none")]
69 pub base_permission: Option<access::BasePermission>,
70}
71
72impl Membership {
73 /// A plain member of `slug`, as services act inside one workspace.
74 pub fn member(slug: impl Into<String>) -> Self {
75 Membership {
76 slug: slug.into(),
77 role: Role::Member,
78 name: None,
79 avatar: None,
80 base_permission: None,
81 }
82 }
83}
84
85/// What a set of credentials resolved to.
86#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
87#[serde(rename_all = "lowercase")]
88pub enum PrincipalKind {
89 /// A person's account.
90 #[default]
91 User,
92 /// A workspace, acting through one of its own access tokens. Its `id`
93 /// is the workspace's, its `username` the workspace's slug, and it is a
94 /// member of that workspace and no other.
95 Workspace,
96 /// A g1t agent at work in a sandbox, acting through a token that lives
97 /// as long as its run and can do only what that token's scope lists, in
98 /// one repository. Its `username` is `g1t-agent`.
99 Agent,
100 /// g1t itself: the platform acting on its own, as when it opens a
101 /// pull request to upgrade a vulnerable dependency or merges from the
102 /// queue. Never resolved from credentials: only services make one,
103 /// with [`User::system`]. Its `username` is `g1t`, which nobody can
104 /// register.
105 System,
106}
107
108/// g1t's own identity, as [`PrincipalKind::System`] work is recorded.
109pub mod system {
110 /// Its id wherever an author or actor id is stored.
111 pub const ID: &str = "g1t";
112 /// Its name, shown as the author of what it does.
113 pub const USERNAME: &str = "g1t";
114 /// The address on the commits it makes, which no mailbox receives.
115 pub const EMAIL: &str = "g1t@users.noreply.g1t.sh";
116 /// Ids that earlier versions stored for g1t's own actions, such as a
117 /// merge its settings made. Read as g1t too.
118 pub const LEGACY_IDS: [&str; 3] = ["g1t_policy", "svc_runner", "g1t_runner"];
119
120 /// Whether `id` is g1t's own.
121 pub fn is_system_id(id: &str) -> bool {
122 id == ID || LEGACY_IDS.contains(&id)
123 }
124}
125
126#[derive(Clone, Debug, Default, Serialize, Deserialize)]
127pub struct User {
128 pub id: String,
129 pub username: String,
130 #[serde(default)]
131 pub kind: PrincipalKind,
132 /// Whether the account's email address has been confirmed. Unverified
133 /// accounts can sign in but cannot create or change anything.
134 #[serde(default)]
135 pub verified: bool,
136 /// The workspaces this user belongs to. Filled in when a user is
137 /// resolved from credentials, so any service can authorize from it.
138 #[serde(default)]
139 pub workspaces: Vec<Membership>,
140 /// The person's uploaded avatar: the SHA-256 of its bytes, served at
141 /// `/avatars/<avatar>`. Absent means the generated letter avatar.
142 #[serde(default, skip_serializing_if = "Option::is_none")]
143 pub avatar: Option<String>,
144 /// Set on an agent resolved from its token: who it acts for, with which
145 /// credential, and what it may do. See [`credentials`].
146 #[serde(default, skip_serializing_if = "Option::is_none")]
147 pub acting: Option<Box<credentials::Acting>>,
148 /// The repositories this user has been given a role on directly,
149 /// whether or not they belong to its workspace. Filled in with
150 /// `workspaces`; see [`access`].
151 #[serde(default, skip_serializing_if = "Vec::is_empty")]
152 pub grants: Vec<access::RepoGrant>,
153 /// Set on a user resolved from an access token: its scopes and the
154 /// workspaces or repositories it is limited to. Absent on a signed-in
155 /// session and on an agent (whose `acting` scope applies instead).
156 /// See [`scopes`].
157 #[serde(default, skip_serializing_if = "Option::is_none")]
158 pub token: Option<Box<scopes::TokenAccess>>,
159}
160
161impl User {
162 /// g1t itself, acting in `workspace`: what the platform's own work,
163 /// such as security updates, is done and recorded as.
164 pub fn system(workspace: &str) -> User {
165 User {
166 id: system::ID.to_owned(),
167 username: system::USERNAME.to_owned(),
168 kind: PrincipalKind::System,
169 verified: true,
170 workspaces: vec![Membership::member(workspace.to_lowercase())],
171 ..User::default()
172 }
173 }
174
175 /// Whether this is g1t itself.
176 pub fn is_system(&self) -> bool {
177 self.kind == PrincipalKind::System
178 }
179
180 pub fn role_in(&self, slug: &str) -> Option<Role> {
181 self.workspaces
182 .iter()
183 .find(|membership| membership.slug == slug)
184 .map(|membership| membership.role)
185 }
186
187 pub fn is_member(&self, slug: &str) -> bool {
188 self.role_in(slug).is_some()
189 }
190}
191
192/// Who is asking. Every read and write in every service takes one.
193pub type Viewer = Option<User>;