mirror.proto RawHistoryFolder
1// SPDX-License-Identifier: MIT
2
3syntax = "proto3";
4
5package ermite;
6
7import "google/protobuf/timestamp.proto";
8
9// MirrorService configures the push mirrors of the server. Global settings and
10// key rotation need the admin token or a token with every scope and no
11// repository or branch limits; per-repository settings and SyncMirror need
12// repo:admin on the repository; status needs read access. GetMirrorKey needs a
13// non-anonymous caller. ListMirrorStatus and SyncMirror with All need owner
14// rights. No new token scope is required. Servers implementing this service
15// list "mirror" in GetVersionResponse.features.
16service MirrorService {
17 // GetMirrorKey returns the public mirror key, generating it on first use.
18 // Needs a non-anonymous caller. Fails with failed_precondition without
19 // ERMITE_SECRETS_KEY.
20 rpc GetMirrorKey(GetMirrorKeyRequest) returns (GetMirrorKeyResponse);
21 // RotateMirrorKey replaces the key immediately. Add the new key to remotes
22 // and sync with force to recover from authentication failures.
23 rpc RotateMirrorKey(RotateMirrorKeyRequest) returns (RotateMirrorKeyResponse);
24 // GetMirrorConfig returns the global mirror policy.
25 rpc GetMirrorConfig(GetMirrorConfigRequest) returns (GetMirrorConfigResponse);
26 // SetMirrorConfig patches the global policy. Unset fields are unchanged.
27 // Invalid fields give invalid_argument with field violations.
28 rpc SetMirrorConfig(SetMirrorConfigRequest) returns (SetMirrorConfigResponse);
29 // SetRepoMirror sets an override, even when global mirroring is disabled.
30 rpc SetRepoMirror(SetRepoMirrorRequest) returns (SetRepoMirrorResponse);
31 // RemoveRepoMirror removes the override so the global policy applies again.
32 rpc RemoveRepoMirror(RemoveRepoMirrorRequest) returns (RemoveRepoMirrorResponse);
33 // SetRepoMirrorExcluded excludes or includes a repository in the global
34 // policy. An explicit URL override takes precedence.
35 rpc SetRepoMirrorExcluded(SetRepoMirrorExcludedRequest) returns (SetRepoMirrorExcludedResponse);
36 // GetMirrorStatus returns the resolved target and status of one repository.
37 rpc GetMirrorStatus(GetMirrorStatusRequest) returns (GetMirrorStatusResponse);
38 // ListMirrorStatus lists mirror statuses and needs owner rights.
39 rpc ListMirrorStatus(ListMirrorStatusRequest) returns (ListMirrorStatusResponse);
40 // SyncMirror syncs Repo or, with All, every repository. Paused mirrors need
41 // Force. Manual requests without Force are at least 60 seconds apart.
42 rpc SyncMirror(SyncMirrorRequest) returns (SyncMirrorResponse);
43}
44
45// MirrorKey is the public SSH key used for push mirrors. Private key material
46// is never returned.
47message MirrorKey {
48 // AuthorizedKey is the SSH authorized_keys line.
49 string authorized_key = 1;
50 // Fingerprint is the SHA256 fingerprint of the public key.
51 string fingerprint = 2;
52 // CreatedAt is when the key was created.
53 google.protobuf.Timestamp created_at = 3;
54}
55
56// GetMirrorKeyRequest selects the input of GetMirrorKey.
57message GetMirrorKeyRequest {}
58
59// GetMirrorKeyResponse holds the result of GetMirrorKey.
60message GetMirrorKeyResponse {
61 // Key is the public mirror key.
62 MirrorKey key = 1;
63}
64
65// RotateMirrorKeyRequest selects the input of RotateMirrorKey.
66message RotateMirrorKeyRequest {}
67
68// RotateMirrorKeyResponse holds the result of RotateMirrorKey.
69message RotateMirrorKeyResponse {
70 // Key is the public mirror key.
71 MirrorKey key = 1;
72 // PreviousFingerprint is the fingerprint of the replaced key.
73 string previous_fingerprint = 2;
74}
75
76// MirrorConfig is the server-wide push mirror policy.
77message MirrorConfig {
78 // Enabled says whether mirroring is enabled.
79 bool enabled = 1;
80 // URLTemplate is an SSH URL containing "{repo}", replaced with the
81 // repository name.
82 string url_template = 2;
83 // Cron is a five-field cron expression in UTC, no more frequent than every
84 // five minutes.
85 string cron = 3;
86 // AllBranches includes every branch rather than only the default branch.
87 // Tags are always included.
88 bool all_branches = 4;
89 // UpdatedAt is when the configuration was last changed.
90 google.protobuf.Timestamp updated_at = 5;
91}
92
93// GetMirrorConfigRequest selects the input of GetMirrorConfig.
94message GetMirrorConfigRequest {}
95
96// GetMirrorConfigResponse holds the result of GetMirrorConfig.
97message GetMirrorConfigResponse {
98 // Config is the global mirror policy.
99 MirrorConfig config = 1;
100}
101
102// SetMirrorConfigRequest selects the input of SetMirrorConfig.
103message SetMirrorConfigRequest {
104 // Enabled says whether mirroring is enabled. Unset means unchanged.
105 optional bool enabled = 1;
106 // URLTemplate is an SSH URL containing "{repo}", replaced with the
107 // repository name. Unset means unchanged.
108 optional string url_template = 2;
109 // Cron is a five-field cron expression in UTC, no more frequent than every
110 // five minutes. Unset means unchanged.
111 optional string cron = 3;
112 // AllBranches includes every branch rather than only the default branch.
113 // Tags are always included. Unset means unchanged.
114 optional bool all_branches = 4;
115}
116
117// SetMirrorConfigResponse holds the result of SetMirrorConfig.
118message SetMirrorConfigResponse {
119 // Config is the global mirror policy.
120 MirrorConfig config = 1;
121}
122
123// MirrorSource says which configuration applies to a repository.
124enum MirrorSource {
125 // MIRROR_SOURCE_DISABLED: nothing applies; MIRROR_SOURCE_GLOBAL: the global
126 // template; MIRROR_SOURCE_OVERRIDE: a per-repository URL;
127 // MIRROR_SOURCE_EXCLUDED: opted out of the global template.
128 MIRROR_SOURCE_UNSPECIFIED = 0;
129 MIRROR_SOURCE_DISABLED = 1;
130 MIRROR_SOURCE_GLOBAL = 2;
131 MIRROR_SOURCE_OVERRIDE = 3;
132 MIRROR_SOURCE_EXCLUDED = 4;
133}
134
135// MirrorTarget is the resolved push mirror target of a repository.
136message MirrorTarget {
137 // Repo is the repository name.
138 string repo = 1;
139 // Enabled says whether mirroring is enabled.
140 bool enabled = 2;
141 // URL is the SSH destination of the mirror.
142 string url = 3;
143 // Cron is a five-field cron expression in UTC, no more frequent than every
144 // five minutes.
145 string cron = 4;
146 // AllBranches includes every branch rather than only the default branch.
147 // Tags are always included.
148 bool all_branches = 5;
149 // Source is the configuration used to resolve the target.
150 MirrorSource source = 6;
151}
152
153// SetRepoMirrorRequest selects the input of SetRepoMirror.
154message SetRepoMirrorRequest {
155 // Repo is the repository name.
156 string repo = 1;
157 // URL is the SSH destination of the mirror.
158 string url = 2;
159 // Cron is a five-field cron expression in UTC, no more frequent than every
160 // five minutes.
161 // Empty means inherit the global cron.
162 string cron = 3;
163 // AllBranches includes every branch rather than only the default branch.
164 // Tags are always included. Unset means inherit the global setting.
165 optional bool all_branches = 4;
166}
167
168// SetRepoMirrorResponse holds the result of SetRepoMirror.
169message SetRepoMirrorResponse {
170 // Target is the resolved mirror target.
171 MirrorTarget target = 1;
172}
173
174// RemoveRepoMirrorRequest selects the input of RemoveRepoMirror.
175message RemoveRepoMirrorRequest {
176 // Repo is the repository name.
177 string repo = 1;
178}
179
180// RemoveRepoMirrorResponse holds the result of RemoveRepoMirror.
181message RemoveRepoMirrorResponse {}
182
183// SetRepoMirrorExcludedRequest selects the input of SetRepoMirrorExcluded.
184message SetRepoMirrorExcludedRequest {
185 // Repo is the repository name.
186 string repo = 1;
187 // Excluded opts out of the global template, unless a URL override exists.
188 bool excluded = 2;
189}
190
191// SetRepoMirrorExcludedResponse holds the result of SetRepoMirrorExcluded.
192message SetRepoMirrorExcludedResponse {
193 // Target is the resolved mirror target.
194 MirrorTarget target = 1;
195}
196
197// MirrorState is the current state of a push mirror.
198enum MirrorState {
199 // MIRROR_STATE_OK: last sync succeeded; MIRROR_STATE_FAILING: retrying with
200 // backoff; MIRROR_STATE_PAUSED: stopped until a forced sync or a config change.
201 MIRROR_STATE_UNSPECIFIED = 0;
202 MIRROR_STATE_DISABLED = 1;
203 MIRROR_STATE_OK = 2;
204 MIRROR_STATE_FAILING = 3;
205 MIRROR_STATE_PAUSED = 4;
206}
207
208// MirrorStatus describes a repository mirror and its last attempts.
209message MirrorStatus {
210 // Target is the resolved mirror target.
211 MirrorTarget target = 1;
212 // State is the current mirror state.
213 MirrorState state = 2;
214 // FailureClass is the failure category, empty when there is no failure.
215 string failure_class = 3;
216 // Reason explains the current state.
217 string reason = 4;
218 // Detail is the last error detail, returned only to callers with repo:admin
219 // on the repository.
220 string detail = 5;
221 // ConsecutiveFailures counts failed attempts since the last success or
222 // reset.
223 int32 consecutive_failures = 6;
224 // LastAttemptAt is when the last sync was attempted.
225 google.protobuf.Timestamp last_attempt_at = 7;
226 // LastSuccessAt is when the last sync succeeded, including a no-op.
227 google.protobuf.Timestamp last_success_at = 8;
228 // NextRetryAt is the next retry time while failing; otherwise unset.
229 google.protobuf.Timestamp next_retry_at = 9;
230 // NextRunAt is the next scheduled sync time, or the retry time while
231 // failing.
232 google.protobuf.Timestamp next_run_at = 10;
233 // PausedAt is when the mirror was paused; otherwise unset.
234 google.protobuf.Timestamp paused_at = 11;
235}
236
237// GetMirrorStatusRequest selects the input of GetMirrorStatus.
238message GetMirrorStatusRequest {
239 // Repo is the repository name.
240 string repo = 1;
241}
242
243// GetMirrorStatusResponse holds the result of GetMirrorStatus.
244message GetMirrorStatusResponse {
245 // Status is the current mirror status.
246 MirrorStatus status = 1;
247}
248
249// ListMirrorStatusRequest selects the input of ListMirrorStatus.
250message ListMirrorStatusRequest {}
251
252// ListMirrorStatusResponse holds the result of ListMirrorStatus.
253message ListMirrorStatusResponse {
254 // Statuses are the mirror statuses.
255 repeated MirrorStatus statuses = 1;
256}
257
258// SyncMirrorRequest selects the input of SyncMirror.
259message SyncMirrorRequest {
260 // Repo is the repository name.
261 string repo = 1;
262 // All selects every repository and needs owner rights. Repo must be empty
263 // when true.
264 bool all = 2;
265 // Force lifts a pause and skips the no-op check and the 60-second manual
266 // throttle. It never forces a Git push.
267 bool force = 3;
268}
269
270// SyncMirrorResult is the result of a sync request for one repository.
271message SyncMirrorResult {
272 // Repo is the repository name.
273 string repo = 1;
274 // Queued says another sync is running and this request was queued.
275 bool queued = 2;
276 // NoOp says the refs already matched the last successful snapshot.
277 bool no_op = 3;
278 // Status is the current mirror status.
279 MirrorStatus status = 4;
280 // Error is a human-readable failure of this repository's sync, empty on
281 // success. It never contains the mirror URL.
282 string error = 5;
283}
284
285// SyncMirrorResponse holds the result of SyncMirror.
286message SyncMirrorResponse {
287 // Results are the per-repository sync results.
288 repeated SyncMirrorResult results = 1;
289}