Skip to content
372 linesCodeBlameRaw
1//! Mirroring over REST and MCP: a repository's links to copies of it on
2//! other hosts (see `g1t_contracts::mirrors`), at
3//! `/repos/{owner}/{name}/mirror…`, and as the MCP `mirror` tool.
4//!
5//! The integrations service keeps the links and decides who may change
6//! them: the Admin role on the repository; syncing needs push. Agents never
7//! move a repository to g1t or handle a remote's token.
8
9use g1t_contracts::mirrors::{
10 MirrorActArgs, MirrorAddArgs, MirrorCiArgs, MirrorHandBackArgs, MirrorMoveInArgs, MirrorRemoveArgs, MirrorSettings,
11 MirrorSettingsArgs, MirrorViewArgs, RefDecision, RemoteProvider, RemoteRole,
12};
13use g1t_contracts::repos::{GetArgs, Repo};
14use g1t_contracts::{FailureCode, Outcome, Viewer};
15use serde_json::{Value, json};
16use std::collections::BTreeMap;
17use worker::Result;
18
19use crate::operations::{Services, repo_path};
20
21/// One operation on a repository's mirroring.
22#[derive(Clone, Copy, Debug, PartialEq, Eq)]
23pub enum MirrorsOp {
24 GetMirror,
25 GetHandBackPlan,
26 TakeOver,
27 SetCiFailover,
28 HandBack,
29 MoveToG1t,
30 SyncMirror,
31 AddRemote,
32 UpdateRemote,
33 RemoveRemote,
34}
35
36impl MirrorsOp {
37 /// Every one: `Op::ALL` lists each as `Op::Mirrors(…)`, which a test
38 /// checks against this.
39 #[cfg(test)]
40 pub const ALL: [MirrorsOp; 10] = [
41 MirrorsOp::GetMirror,
42 MirrorsOp::GetHandBackPlan,
43 MirrorsOp::TakeOver,
44 MirrorsOp::SetCiFailover,
45 MirrorsOp::HandBack,
46 MirrorsOp::MoveToG1t,
47 MirrorsOp::SyncMirror,
48 MirrorsOp::AddRemote,
49 MirrorsOp::UpdateRemote,
50 MirrorsOp::RemoveRemote,
51 ];
52
53 pub fn name(self) -> &'static str {
54 match self {
55 MirrorsOp::GetMirror => "get_mirror",
56 MirrorsOp::GetHandBackPlan => "get_hand_back_plan",
57 MirrorsOp::TakeOver => "take_over_mirror",
58 MirrorsOp::SetCiFailover => "set_ci_failover",
59 MirrorsOp::HandBack => "hand_back_mirror",
60 MirrorsOp::MoveToG1t => "move_mirror_to_g1t",
61 MirrorsOp::SyncMirror => "sync_mirror",
62 MirrorsOp::AddRemote => "add_mirror_remote",
63 MirrorsOp::UpdateRemote => "update_mirror_remote",
64 MirrorsOp::RemoveRemote => "remove_mirror_remote",
65 }
66 }
67
68 /// For the API reference.
69 pub fn title(self) -> &'static str {
70 match self {
71 MirrorsOp::GetMirror => "Get a repository's mirroring",
72 MirrorsOp::GetHandBackPlan => "Get the hand-back plan",
73 MirrorsOp::TakeOver => "Take over a mirror",
74 MirrorsOp::SetCiFailover => "Start or end CI failover",
75 MirrorsOp::HandBack => "Hand a takeover back",
76 MirrorsOp::MoveToG1t => "Move a mirror to g1t",
77 MirrorsOp::SyncMirror => "Sync a repository's remotes",
78 MirrorsOp::AddRemote => "Add a remote",
79 MirrorsOp::UpdateRemote => "Update a remote's settings",
80 MirrorsOp::RemoveRemote => "Remove a remote",
81 }
82 }
83
84 pub fn description(self) -> &'static str {
85 match self {
86 MirrorsOp::GetMirror => "A repository's links to other hosts. `remotes` lists each with its `role` (`leader`: the remote leads and this repository is its mirror; `follower`: g1t leads and the remote is kept in step), `provider` (`github`, `g1t` or `git`), `name` (`github.com/acme/web`), `state` (a mirror is `standby`, `ci`, `takeover` or `handing_back`; a follower is `following` or `stuck`), `reachable` and `unreachable_since`, `synced_at`, `last_error` and its `settings`. `can_manage` says whether you may change them. A mirror standing by is read-only on g1t and runs nothing. Needs read access.",
87 MirrorsOp::GetHandBackPlan => "What handing a takeover back would do, ref by ref, in `plan.refs`: each with `base` (where it was when the takeover began), `ours`, `theirs` and `action`: `push` (only g1t moved), `fetch` (only the remote moved), `pull_request` (the remote protects the branch: g1t's commits go to `g1t/handback/<branch>` there as a pull request, and g1t follows the remote's branch) or `diverged` (both moved: it needs a decision). `plan.reachable` is false while the remote does not answer; `plan.ready` once it answers and every diverged ref has a decision. Asks the remote, so it takes a moment. Needs the Admin role.",
88 MirrorsOp::TakeOver => "Take over a mirror: g1t leads it for now, so pushes, pull requests, issues, agents and workflows work on g1t, whether or not the remote is answering. Each ref's commit is recorded as where the takeover began. Workflows that deploy wait for approval, unless the link's settings say otherwise. End it with hand_back_mirror, or keep it with move_mirror_to_g1t. Needs the Admin role.",
89 MirrorsOp::SetCiFailover => "Start (`on: true`) or end (`on: false`) CI failover on a mirror standing by: the remote keeps the code, and g1t runs its workflows, `.github/workflows` as well as `.g1t/workflows`, on each push copied in. Workflows that deploy wait for approval unless the link's settings say otherwise. Needs the Admin role.",
90 MirrorsOp::HandBack => "Hand a takeover back to the remote, as get_hand_back_plan describes, with `decisions` for diverged refs: an object from ref (`refs/heads/docs`) to `keep_ours` (g1t's commit is pushed over the remote's), `keep_theirs` (the remote's is taken; g1t's is kept under `refs/g1t/replaced/`) or `pull_request`. Refused while the remote does not answer or a diverged ref has no decision. The repository is read-only while it goes back; if anything is refused, g1t keeps the lead and says why. On success the mirror stands by again, and `notes` lists the pull requests opened. Needs the Admin role.",
91 MirrorsOp::MoveToG1t => "Move a mirror to g1t for good: it stops being a mirror and g1t no longer tracks the remote, so pushes made there no longer come here. Allowed while it stands by, in CI failover, or during a takeover, whose work stays as it is. With `keep_remote_updated: true` the remote becomes a follower instead of being unlinked, and g1t pushes to it from then on. Needs the Admin role; agents' tokens are refused.",
92 MirrorsOp::SyncMirror => "Bring a repository's remotes in step now: a mirror standing by or in CI failover copies the remote's branches and tags in; each follower is pushed g1t's (which also clears a follower that was stuck by pushing over what changed there). Needs push access.",
93 MirrorsOp::AddRemote => "Link a repository to a remote on another g1t or any git host over HTTPS (GitHub repositories are linked by importing them through g1t's GitHub App). `role` `follower`: g1t leads and pushes to it. `role` `leader`: this repository becomes its mirror; only an empty repository can, and it is filled from the remote. `url` is its https clone address, `token` a token that can read and push (kept sealed, never returned), `username` the user it is sent as. Needs the Admin role; agents' tokens are refused.",
94 MirrorsOp::UpdateRemote => "Change a remote's `settings`, all optional: `notify` (`banner`, or `inbox` to also tell the workspace's owners), `take_over_after` (minutes, 5 to 1440, after which g1t takes over on its own while the remote does not answer; null for never), `hand_back` (`when_clean`: an automatic takeover goes back on its own once every ref goes back without a decision; `ask`), `keep_ci_warm` (run `.g1t/workflows` on pushes copied in while standing by), `github_workflows` (run `.github/workflows` in CI failover and takeovers), `hold_deploys`, and for a follower `remote_pushes` (`adopt` fast-forwards made there, or `overwrite` them). Needs the Admin role; agents' tokens are refused.",
95 MirrorsOp::RemoveRemote => "Unlink a remote. A mirror becomes an ordinary repository with what it has; a follower is no longer pushed to. Refused during a takeover: hand it back or move it to g1t first. Needs the Admin role; agents' tokens are refused.",
96 }
97 }
98
99 pub fn input(self) -> Value {
100 let repo = json!({ "type": "string", "description": "Repository as \"owner/name\", e.g. \"flagon-io/hello\"." });
101 let id = json!({ "type": "string", "description": "The remote's id (rmt_…), from get_mirror." });
102 let (properties, required): (Value, &[&str]) = match self {
103 MirrorsOp::GetMirror | MirrorsOp::GetHandBackPlan | MirrorsOp::TakeOver | MirrorsOp::SyncMirror => {
104 (json!({ "repo": repo }), &["repo"])
105 }
106 MirrorsOp::SetCiFailover => (
107 json!({ "repo": repo, "on": { "type": "boolean", "description": "True to start CI failover, false to end it." } }),
108 &["repo", "on"],
109 ),
110 MirrorsOp::HandBack => (
111 json!({
112 "repo": repo,
113 "decisions": {
114 "type": "object",
115 "description": "For each diverged ref, by its full name: keep_ours, keep_theirs or pull_request.",
116 "additionalProperties": { "type": "string", "enum": ["keep_ours", "keep_theirs", "pull_request"] },
117 },
118 }),
119 &["repo"],
120 ),
121 MirrorsOp::MoveToG1t => (
122 json!({
123 "repo": repo,
124 "keep_remote_updated": { "type": "boolean", "description": "True to keep pushing to the remote from g1t; false (the default) to stop tracking it." },
125 }),
126 &["repo"],
127 ),
128 MirrorsOp::AddRemote => (
129 json!({
130 "repo": repo,
131 "provider": { "type": "string", "enum": ["g1t", "git"], "description": "Another g1t (g1t.sh or your own), or any git host." },
132 "role": { "type": "string", "enum": ["follower", "leader"], "description": "follower: g1t leads and pushes to it. leader: this empty repository becomes its mirror." },
133 "url": { "type": "string", "description": "Its https clone address, such as https://g1t.sh/acme/web.git." },
134 "username": { "type": "string", "description": "The user the token is sent as. x-access-token when left out." },
135 "token": { "type": "string", "description": "A token that can read and push. Kept sealed; never returned." },
136 }),
137 &["repo", "provider", "role", "url", "token"],
138 ),
139 MirrorsOp::UpdateRemote => (
140 json!({
141 "repo": repo,
142 "id": id,
143 "notify": { "type": "string", "enum": ["banner", "inbox"] },
144 "take_over_after": { "type": ["integer", "null"], "minimum": 5, "maximum": 1440 },
145 "hand_back": { "type": "string", "enum": ["when_clean", "ask"] },
146 "keep_ci_warm": { "type": "boolean" },
147 "github_workflows": { "type": "boolean" },
148 "hold_deploys": { "type": "boolean" },
149 "remote_pushes": { "type": "string", "enum": ["adopt", "overwrite"] },
150 }),
151 &["repo", "id"],
152 ),
153 MirrorsOp::RemoveRemote => (json!({ "repo": repo, "id": id }), &["repo", "id"]),
154 };
155 json!({ "type": "object", "properties": properties, "required": required })
156 }
157}
158
159fn text(input: &Value, key: &str) -> String {
160 input[key].as_str().map(str::trim).unwrap_or_default().to_owned()
161}
162
163/// A boolean as sent: JSON, or a word from a form.
164fn flag(value: &Value) -> Option<bool> {
165 match value {
166 Value::Bool(flag) => Some(*flag),
167 Value::String(word) => match word.trim().to_ascii_lowercase().as_str() {
168 "true" | "1" => Some(true),
169 "false" | "0" => Some(false),
170 _ => None,
171 },
172 _ => None,
173 }
174}
175
176/// `settings` with what `input` changes, in `snake_case` as sent.
177pub fn settings_from(mut settings: MirrorSettings, input: &Value) -> std::result::Result<MirrorSettings, String> {
178 let word = |key: &str| input.get(key).filter(|value| !value.is_null()).map(|value| value.as_str().unwrap_or_default());
179 if let Some(notify) = word("notify") {
180 settings.notify = serde_json::from_value(json!(notify)).map_err(|_| "notify is banner or inbox.")?;
181 }
182 if let Some(value) = input.get("take_over_after") {
183 settings.take_over_after = match value {
184 Value::Null => None,
185 value => Some(value.as_u64().map(|minutes| minutes as u32).ok_or("take_over_after is a number of minutes, or null.")?),
186 };
187 }
188 if let Some(hand_back) = word("hand_back") {
189 settings.hand_back = serde_json::from_value(json!(hand_back)).map_err(|_| "hand_back is when_clean or ask.")?;
190 }
191 if let Some(remote_pushes) = word("remote_pushes") {
192 settings.remote_pushes = serde_json::from_value(json!(remote_pushes)).map_err(|_| "remote_pushes is adopt or overwrite.")?;
193 }
194 for (key, field) in [
195 ("keep_ci_warm", &mut settings.keep_ci_warm),
196 ("github_workflows", &mut settings.github_workflows),
197 ("hold_deploys", &mut settings.hold_deploys),
198 ] {
199 if let Some(value) = input.get(key).filter(|value| !value.is_null()) {
200 *field = flag(value).ok_or_else(|| format!("{key} is true or false."))?;
201 }
202 }
203 Ok(settings)
204}
205
206/// `decisions` as sent: ref to `keep_ours`, `keep_theirs` or `pull_request`.
207pub fn decisions_from(input: &Value) -> std::result::Result<BTreeMap<String, RefDecision>, String> {
208 let Some(decisions) = input.get("decisions").filter(|value| !value.is_null()) else {
209 return Ok(BTreeMap::new());
210 };
211 let Some(decisions) = decisions.as_object() else {
212 return Err("decisions is an object from ref to keep_ours, keep_theirs or pull_request.".to_owned());
213 };
214 decisions
215 .iter()
216 .map(|(git_ref, decision)| {
217 let decision = serde_json::from_value(decision.clone())
218 .map_err(|_| format!("{git_ref}: say keep_ours, keep_theirs or pull_request."))?;
219 let git_ref = if git_ref.starts_with("refs/") { git_ref.clone() } else { format!("refs/heads/{git_ref}") };
220 Ok((git_ref, decision))
221 })
222 .collect()
223}
224
225pub async fn run(op: MirrorsOp, services: &Services, viewer: &Viewer, input: &Value) -> Result<Outcome<Value>> {
226 let Some(path) = repo_path(input) else {
227 return Ok(Outcome::fail(FailureCode::Invalid, "Give the repository as \"owner/name\"."));
228 };
229 let found: Outcome<Repo> = g1t_kit::call(&services.repos, "get", &GetArgs { path, viewer: viewer.clone() }).await?;
230 let repo = match found {
231 Outcome::Ok(repo) => repo,
232 Outcome::Fail(failure) => return Ok(Outcome::Fail(failure)),
233 };
234 let integrations = &services.integrations;
235 if op == MirrorsOp::GetMirror {
236 return g1t_kit::call(integrations, "mirror_view", &MirrorViewArgs { viewer: viewer.clone(), repo_id: repo.id }).await;
237 }
238 let Some(actor) = viewer.clone() else {
239 return Ok(Outcome::fail(FailureCode::Unauthenticated, "Sign in to change a repository's mirroring."));
240 };
241 let act = || MirrorActArgs { actor: actor.clone(), repo_id: repo.id.clone() };
242 let id = text(input, "id");
243 if matches!(op, MirrorsOp::UpdateRemote | MirrorsOp::RemoveRemote) && id.is_empty() {
244 return Ok(Outcome::fail(FailureCode::Invalid, "Name the remote by its id (rmt_…), from get_mirror."));
245 }
246 match op {
247 MirrorsOp::GetMirror => unreachable!("answered above"),
248 MirrorsOp::GetHandBackPlan => g1t_kit::call(integrations, "mirror_hand_back_plan", &act()).await,
249 MirrorsOp::TakeOver => g1t_kit::call(integrations, "mirror_take_over", &act()).await,
250 MirrorsOp::SyncMirror => g1t_kit::call(integrations, "mirror_sync", &act()).await,
251 MirrorsOp::SetCiFailover => {
252 let Some(on) = flag(&input["on"]) else {
253 return Ok(Outcome::fail(FailureCode::Invalid, "Say on: true to start CI failover, or false to end it."));
254 };
255 g1t_kit::call(integrations, "mirror_ci", &MirrorCiArgs { actor, repo_id: repo.id, on }).await
256 }
257 MirrorsOp::HandBack => {
258 let decisions = match decisions_from(input) {
259 Ok(decisions) => decisions,
260 Err(problem) => return Ok(Outcome::fail(FailureCode::Invalid, problem)),
261 };
262 g1t_kit::call(integrations, "mirror_hand_back", &MirrorHandBackArgs { actor, repo_id: repo.id, decisions }).await
263 }
264 MirrorsOp::MoveToG1t => {
265 let keep_remote_updated = match &input["keep_remote_updated"] {
266 Value::Null => false,
267 value => match flag(value) {
268 Some(keep) => keep,
269 None => return Ok(Outcome::fail(FailureCode::Invalid, "keep_remote_updated is true or false.")),
270 },
271 };
272 g1t_kit::call(integrations, "mirror_move_in", &MirrorMoveInArgs { actor, repo_id: repo.id, keep_remote_updated }).await
273 }
274 MirrorsOp::AddRemote => {
275 let provider = match text(input, "provider").as_str() {
276 "g1t" => RemoteProvider::G1t,
277 "git" => RemoteProvider::Git,
278 "github" => {
279 return Ok(Outcome::fail(
280 FailureCode::Invalid,
281 "GitHub repositories are linked by importing them through g1t's GitHub App.",
282 ));
283 }
284 _ => return Ok(Outcome::fail(FailureCode::Invalid, "provider is g1t or git.")),
285 };
286 let role = match text(input, "role").as_str() {
287 "leader" => RemoteRole::Leader,
288 "follower" => RemoteRole::Follower,
289 _ => return Ok(Outcome::fail(FailureCode::Invalid, "role is follower (g1t leads) or leader (the remote leads).")),
290 };
291 let username = Some(text(input, "username")).filter(|name| !name.is_empty());
292 let token = Some(text(input, "token")).filter(|token| !token.is_empty());
293 let args = MirrorAddArgs { actor, repo_id: repo.id, provider, role, url: text(input, "url"), username, token };
294 g1t_kit::call(integrations, "mirror_add", &args).await
295 }
296 MirrorsOp::UpdateRemote => {
297 let view: Outcome<g1t_contracts::mirrors::MirrorView> =
298 g1t_kit::call(integrations, "mirror_view", &MirrorViewArgs { viewer: viewer.clone(), repo_id: repo.id }).await?;
299 let view = match view {
300 Outcome::Ok(view) => view,
301 Outcome::Fail(failure) => return Ok(Outcome::Fail(failure)),
302 };
303 let Some(remote) = view.remotes.into_iter().find(|remote| remote.id == id) else {
304 return Ok(Outcome::fail(FailureCode::NotFound, "That remote is not one of this repository's."));
305 };
306 let settings = match settings_from(remote.settings, input) {
307 Ok(settings) => settings,
308 Err(problem) => return Ok(Outcome::fail(FailureCode::Invalid, problem)),
309 };
310 g1t_kit::call(integrations, "mirror_settings", &MirrorSettingsArgs { actor, remote_id: id, settings }).await
311 }
312 MirrorsOp::RemoveRemote => {
313 let view: Outcome<g1t_contracts::mirrors::MirrorView> =
314 g1t_kit::call(integrations, "mirror_view", &MirrorViewArgs { viewer: viewer.clone(), repo_id: repo.id }).await?;
315 if !matches!(&view, Outcome::Ok(view) if view.remotes.iter().any(|remote| remote.id == id)) {
316 return Ok(Outcome::fail(FailureCode::NotFound, "That remote is not one of this repository's."));
317 }
318 g1t_kit::call(integrations, "mirror_remove", &MirrorRemoveArgs { actor, remote_id: id }).await
319 }
320 }
321}
322
323#[cfg(test)]
324mod tests {
325 use super::*;
326 use g1t_contracts::credentials::NEVER;
327 use g1t_contracts::mirrors::{HandBack, Notify, RemotePushes};
328 use g1t_contracts::scopes::{Level, scope_for};
329
330 #[test]
331 fn each_operation_is_described_and_scoped() {
332 for op in MirrorsOp::ALL {
333 assert!(crate::operations::Op::ALL.contains(&crate::operations::Op::Mirrors(op)), "{}", op.name());
334 assert!(!op.title().is_empty() && op.description().len() > 40, "{}", op.name());
335 assert!(op.input()["required"].as_array().unwrap().contains(&json!("repo")), "{}", op.name());
336 let level = scope_for(op.name()).unwrap_or_else(|| panic!("{} has no scope", op.name())).level();
337 let expected = match op {
338 MirrorsOp::GetMirror => Level::Read,
339 MirrorsOp::SyncMirror => Level::Write,
340 _ => Level::Admin,
341 };
342 assert_eq!(level, expected, "{}", op.name());
343 }
344 for op in [MirrorsOp::MoveToG1t, MirrorsOp::AddRemote, MirrorsOp::UpdateRemote, MirrorsOp::RemoveRemote] {
345 assert!(NEVER.contains(&op.name()), "agents never {}", op.name());
346 }
347 }
348
349 #[test]
350 fn settings_change_only_what_is_sent() {
351 let base = MirrorSettings::default();
352 let changed = settings_from(base.clone(), &json!({ "notify": "inbox", "take_over_after": 30, "keep_ci_warm": "true" })).unwrap();
353 assert_eq!(changed.notify, Notify::Inbox);
354 assert_eq!(changed.take_over_after, Some(30));
355 assert!(changed.keep_ci_warm);
356 assert_eq!(changed.hand_back, HandBack::WhenClean);
357 assert_eq!(changed.remote_pushes, RemotePushes::Adopt);
358 let cleared = settings_from(changed, &json!({ "take_over_after": null })).unwrap();
359 assert_eq!(cleared.take_over_after, None);
360 assert!(settings_from(base.clone(), &json!({ "notify": "pager" })).is_err());
361 assert!(settings_from(base, &json!({ "hold_deploys": "maybe" })).is_err());
362 }
363
364 #[test]
365 fn decisions_name_refs_or_branches() {
366 let decisions = decisions_from(&json!({ "decisions": { "docs": "keep_theirs", "refs/tags/v1": "keep_ours" } })).unwrap();
367 assert_eq!(decisions.get("refs/heads/docs"), Some(&RefDecision::KeepTheirs));
368 assert_eq!(decisions.get("refs/tags/v1"), Some(&RefDecision::KeepOurs));
369 assert!(decisions_from(&json!({ "decisions": { "docs": "merge" } })).is_err());
370 assert!(decisions_from(&json!({})).unwrap().is_empty());
371 }
372}