1// SPDX-License-Identifier: AGPL-3.0-or-later
2
3package ports
4
5import (
6 "context"
7 "errors"
8 "fmt"
9 "strconv"
10 "time"
11
12 "bnema.dev/ermite/internal/domain"
13)
14
15// CIRunDraft is what CreateRun stores: a run with its source, its jobs and
16// their checks, built once the store has chosen the ids.
17type CIRunDraft struct {
18 Run domain.CIRun
19 Source domain.CIRunSource
20 Jobs []domain.CIJob
21 Checks []domain.CICheck
22}
23
24// CIWrite is a set of records written in one atomic batch. A run or a job with
25// Version 0 must not exist yet; any other must be unchanged since it was read.
26// Checks are derived from the jobs and upserted without a precondition.
27// Apply returns domain.ErrConflict otherwise and domain.ErrNotFound when the
28// repository no longer exists.
29//
30// RepoTokens are job repository tokens created with the batch (they must not
31// exist yet), RevokeJobs the jobs whose repository tokens are deleted by it,
32// and Resolutions the action resolutions of a run attempt to keep. They are
33// written under the lock of the run that owns them.
34//
35// Annotations replace, for each (execution of a job, step) they name, all the
36// annotations stored for it (none deletes them); ClearAnnotations deletes all
37// the annotations of the executions of jobs they name, steps included. Both
38// are written with the batch, so a call is applied whole or not at all.
39type CIWrite struct {
40 Runs []domain.CIRun
41 Jobs []domain.CIJob
42 Checks []domain.CICheck
43 RepoTokens []domain.CIRepoToken
44 RevokeJobs []CIJobRef
45 Resolutions []domain.CIActionResolution
46 Annotations []CIStepAnnotations
47 ClearAnnotations []CILogRef
48}
49
50// CIConcurrencyGroup is a stored concurrency group: its repository, its key (the
51// group, canonical: ConcurrencyKey), its record and its marks.
52type CIConcurrencyGroup struct {
53 Repo domain.RepoName
54 Group string
55 State domain.CIConcurrencyGroupState
56}
57
58// CIStepAnnotations are all the annotations of one step of one execution of a
59// job, in the order the step produced them.
60type CIStepAnnotations struct {
61 Repo domain.RepoName
62 Exec CILogRef
63 Step int32
64 // Items are the annotations; none removes those of the step.
65 Items []domain.CIAnnotation
66}
67
68// CIJobRef names one execution of a job.
69type CIJobRef struct {
70 RunID int64
71 RunAttempt int32
72 JobID string
73}
74
75// CIRepoTokenStore reads the job repository tokens, for the authentication of
76// a request. They are written by CIStore.Apply. *kvstore.CI implements it.
77type CIRepoTokenStore interface {
78 // FindRepoTokenByHash returns the token whose secret has that hash, or
79 // domain.ErrNotFound.
80 FindRepoTokenByHash(ctx context.Context, hash domain.TokenHash) (domain.CIRepoToken, error)
81 // GetRepoToken returns the token with that id, or domain.ErrNotFound.
82 GetRepoToken(ctx context.Context, id string) (domain.CIRepoToken, error)
83}
84
85// CIRefTipStore keeps, per branch or tag (full ref name), who moves it to its
86// object (domain.CIRefTip). The record is written before the ref moves.
87// *kvstore.CI implements it; the records go with the repository.
88type CIRefTipStore interface {
89 // PutRefTip stores the record of a ref, replacing the earlier one. A
90 // repository that does not exist is domain.ErrNotFound.
91 PutRefTip(ctx context.Context, t domain.CIRefTip) error
92 // GetRefTip returns the record of a ref, or domain.ErrNotFound.
93 GetRefTip(ctx context.Context, repo domain.RepoName, ref string) (domain.CIRefTip, error)
94 // DeleteRefTip removes the record of a ref; a missing one is not an error.
95 DeleteRefTip(ctx context.Context, repo domain.RepoName, ref string) error
96}
97
98// CIStore keeps CI runs, jobs and checks. The store derives its own indexes
99// (the queue of ready jobs, the active jobs, the open runs, the job tokens)
100// from the records it writes.
101type CIStore interface {
102 // CreateRun takes the next run id and the next number of the workflow in
103 // the repository (both never reused), calls build with them and stores
104 // the draft it returns, in one batch that fails with domain.ErrNotFound
105 // once the repository is deleted. The records come back with their
106 // versions.
107 CreateRun(ctx context.Context, repo domain.RepoName, workflowPath string, build func(id, number int64) CIRunDraft) (CIRunDraft, error)
108 // Apply writes the records in one batch and returns the version they all
109 // have afterwards.
110 Apply(ctx context.Context, w CIWrite) (version uint64, err error)
111 // GetRun returns the run, or domain.ErrNotFound.
112 GetRun(ctx context.Context, repo domain.RepoName, id int64) (domain.CIRun, error)
113 // GetActionResolution returns the resolution kept for the key in the run
114 // attempt, or domain.ErrNotFound.
115 GetActionResolution(ctx context.Context, runID int64, runAttempt int32, key string) (domain.CIActionResolution, error)
116 // GetRunSource returns what the run was planned from, or
117 // domain.ErrNotFound. It is how a run is found from its id alone.
118 GetRunSource(ctx context.Context, runID int64) (domain.CIRunSource, error)
119 // ListRuns returns the runs of the repository with an id below before (0
120 // for no bound), newest first, at most limit.
121 ListRuns(ctx context.Context, repo domain.RepoName, before int64, limit int) ([]domain.CIRun, error)
122 // RunIDs returns the ids of the runs of the repository.
123 RunIDs(ctx context.Context, repo domain.RepoName) ([]int64, error)
124 // ListOpenRuns returns the runs that have not completed.
125 ListOpenRuns(ctx context.Context) ([]domain.CIRun, error)
126 // JobAnnotations returns the annotations of one execution of a job
127 // (CIJob.Attempt), ordered by step then by the order the step produced
128 // them. A job without annotation gives an empty list.
129 JobAnnotations(ctx context.Context, runID int64, attempt int32, jobID string) ([]domain.CIAnnotation, error)
130 // GetJob returns a job of a run at an attempt of the run, or
131 // domain.ErrNotFound.
132 GetJob(ctx context.Context, runID int64, runAttempt int32, jobID string) (domain.CIJob, error)
133 // ListJobs returns the jobs of a run at an attempt, ordered by index then
134 // combination.
135 ListJobs(ctx context.Context, runID int64, runAttempt int32) ([]domain.CIJob, error)
136 // FindJobByToken returns the job whose current token has that hash and
137 // whose token is still valid at now, or domain.ErrNotFound.
138 FindJobByToken(ctx context.Context, hash domain.TokenHash, now time.Time) (domain.CIJob, error)
139 // ListReadyJobs returns the jobs that wait for a runner, oldest first, at
140 // most limit.
141 ListReadyJobs(ctx context.Context, limit int) ([]domain.CIJob, error)
142 // ListActiveJobs returns the jobs given to a runner and not over.
143 ListActiveJobs(ctx context.Context) ([]domain.CIJob, error)
144 // ListChecks returns the checks of a commit, at most limit; more is true
145 // when there are more.
146 ListChecks(ctx context.Context, repo domain.RepoName, sha string, limit int) (checks []domain.CICheck, more bool, err error)
147 // UpdateConcurrency reads a concurrency group of a repository (compared
148 // with domain.ConcurrencyKey) with the marks of its entries, calls fn on a
149 // copy and stores what fn leaves in it, in one batch: the record, the marks
150 // that changed and the marks that fn removed. A group left with neither
151 // record nor marks is removed. The batch carries the version precondition of
152 // the group whatever fn does, and every change of the marks rewrites the
153 // record, so no two transactions of a group both succeed on the same state:
154 // on a conflict fn is called again on the new state and must be repeatable.
155 // A deleted repository is domain.ErrNotFound.
156 UpdateConcurrency(ctx context.Context, repo domain.RepoName, group string, fn func(*domain.CIConcurrencyGroupState) error) error
157 // ListConcurrency returns every concurrency group that has an entry, for
158 // the reconciliation at startup.
159 ListConcurrency(ctx context.Context) ([]CIConcurrencyGroup, error)
160 // Sweep removes the runs completed before the time, with their jobs,
161 // checks and sources (not their numbers), and returns their ids so that
162 // the logs can go too.
163 Sweep(ctx context.Context, before time.Time) ([]int64, error)
164 // CreateRunner stores the runner and the index of its token. A name in use
165 // is domain.ErrAlreadyExists, or with replace the old runner is removed in
166 // the same batch and returned.
167 CreateRunner(ctx context.Context, r domain.CIRunner, replace bool) (removed []domain.CIRunner, err error)
168 // GetRunner returns the runner, or domain.ErrNotFound.
169 GetRunner(ctx context.Context, id string) (domain.CIRunner, error)
170 // FindRunnerByToken returns the runner whose token has that hash, or
171 // domain.ErrNotFound.
172 FindRunnerByToken(ctx context.Context, hash domain.TokenHash) (domain.CIRunner, error)
173 // ListRunners returns every runner ordered by name.
174 ListRunners(ctx context.Context) ([]domain.CIRunner, error)
175 // SetRunnerVersion records the version the runner runs now. It writes only
176 // when the stored version differs, and returns domain.ErrNotFound for a
177 // runner that is gone.
178 SetRunnerVersion(ctx context.Context, id, version string) error
179 // RemoveRunner removes the runner and its token, or returns
180 // domain.ErrNotFound.
181 RemoveRunner(ctx context.Context, id string) (domain.CIRunner, error)
182}
183
184// CIRunCleaner is what repository deletion needs from CI: the runs of the
185// repository before its records go, and the removal of their logs and
186// summaries after. *usecase.CI implements it.
187type CIRunCleaner interface {
188 RunIDs(ctx context.Context, repo domain.RepoName) ([]int64, error)
189 RemoveLogs(ctx context.Context, runIDs []int64) error
190 // ForgetRepo drops what CI keeps in memory for the deleted repository (its
191 // cached schedules).
192 ForgetRepo(repo domain.RepoName)
193}
194
195// CIChecksReader is the read side of the checks, for the merge rule and the
196// pages that show them. *usecase.CI implements it.
197type CIChecksReader interface {
198 // CommitChecks returns the checks of a commit, without access control (the
199 // caller has checked it). More than 1,000 is domain.ErrResourceExhausted,
200 // not a part of them: a rule must not decide on some of the checks.
201 CommitChecks(ctx context.Context, repo domain.RepoName, sha string) ([]domain.CICheck, error)
202}
203
204// CILogRef names one execution of a job: its log, its summaries and its
205// annotations are kept under it.
206type CILogRef struct {
207 RunID int64
208 JobID string
209 Attempt int32
210}
211
212// ErrCILogLimit is returned by CILogStore.Append when the lines do not fit in
213// the log limit; nothing was appended.
214var ErrCILogLimit = errors.New("log limit reached")
215
216// ErrCILogGap wraps domain.ErrOutOfRange when an offset is above the count.
217type ErrCILogGap struct{ Count int64 }
218
219// Error implements error.
220func (e *ErrCILogGap) Error() string {
221 return "out of range: the log holds lines up to the offset of " + strconv.FormatInt(e.Count, 10)
222}
223
224// Is makes errors.Is(err, domain.ErrOutOfRange) true.
225func (e *ErrCILogGap) Is(target error) bool { return target == domain.ErrOutOfRange }
226
227// CILogStore keeps the logs of the jobs: append-only files, one line per log
228// line, never in the metadata store. Lines are numbered from 0.
229type CILogStore interface {
230 // Append appends the lines at offset (the number of the first line), with
231 // the idempotence of AppendLog: lines already stored are skipped, a gap is
232 // an *ErrCILogGap. It returns the number of lines after the call and how
233 // many of the request were new. A log that would exceed limit bytes gets
234 // nothing and ErrCILogLimit.
235 Append(ctx context.Context, ref CILogRef, offset int64, lines []domain.CILogLine, limit int64) (next int64, added int, err error)
236 // AppendForced appends lines whatever the limit (the last line of a log
237 // that reached it).
238 AppendForced(ctx context.Context, ref CILogRef, lines []domain.CILogLine) (next int64, err error)
239 // Count returns the number of lines held, 0 for a log that does not exist.
240 Count(ctx context.Context, ref CILogRef) (int64, error)
241 // Read returns lines from the one numbered from, at most maxLines lines and
242 // about maxBytes of text. It returns domain.ErrNotFound when the log does
243 // not exist and domain.ErrOutOfRange when from is above the count.
244 Read(ctx context.Context, ref CILogRef, from int64, maxLines, maxBytes int) ([]domain.CILogLine, error)
245 // Changed returns a channel that is closed at the next append to the log.
246 Changed(ref CILogRef) <-chan struct{}
247 // Reset empties the log.
248 Reset(ctx context.Context, ref CILogRef) error
249 // RemoveRuns deletes the logs of the runs.
250 RemoveRuns(ctx context.Context, runIDs []int64) error
251 // RunIDs lists the runs that have a log directory, for the orphan sweep.
252 RunIDs(ctx context.Context) ([]int64, error)
253}
254
255// CISummaryStore keeps the job summaries (the Markdown a step wrote to
256// GITHUB_STEP_SUMMARY): one file per step of an execution of a job, never in
257// the metadata store.
258type CISummaryStore interface {
259 // Put stores the summary of a step, replacing the one it has; the file
260 // appears whole or not at all. An empty markdown removes the summary.
261 Put(ctx context.Context, ref CILogRef, step int32, markdown string) error
262 // List returns the summaries of the steps that have one, by step number,
263 // at most limit; more is true when there are others. With maxBytes above
264 // 0 the files are sized (stat) before they are read, and a summary that
265 // would take the total of the Markdown read past maxBytes is returned
266 // Omitted, unread, as are all the ones after it: a call never reads more
267 // than maxBytes.
268 List(ctx context.Context, ref CILogRef, limit int, maxBytes int64) (summaries []domain.CIStepSummary, more bool, err error)
269 // RemoveJob deletes the summaries of one execution of a job.
270 RemoveJob(ctx context.Context, ref CILogRef) error
271 // RemoveRuns deletes the summaries of the runs.
272 RemoveRuns(ctx context.Context, runIDs []int64) error
273 // RunIDs lists the runs that have a summary directory, for the orphan
274 // sweep.
275 RunIDs(ctx context.Context) ([]int64, error)
276}
277
278// DispatchParams are the arguments of RunService.DispatchWorkflow.
279type DispatchParams struct {
280 // WorkflowPath is the path of the workflow file, or its file name.
281 WorkflowPath string
282 // Ref is a branch or a tag, short or full name; empty is the default branch.
283 Ref string
284 // Inputs are the values of the inputs by name, as text.
285 Inputs map[string]string
286}
287
288// WorkflowTrigger starts the workflows that match pushed refs. OnPush only
289// queues the work and returns: planning happens in the background and its
290// errors never reach the push.
291type WorkflowTrigger interface {
292 OnPush(ctx context.Context, repo domain.RepoName, updates []domain.RefUpdate, pusher domain.Principal)
293 // OnMerge is OnPush for the move of a target branch by a merge. GitHub shows
294 // the owner as the actor of the push of a merge, whoever merged; but the
295 // rights the run's actions are resolved with are those of merger, the
296 // principal that merged, never the owner's.
297 OnMerge(ctx context.Context, repo domain.RepoName, updates []domain.RefUpdate, merger domain.Principal)
298}
299
300// PullRequestTrigger starts the pull_request workflows of the merge requests
301// (CI-3, D5), like WorkflowTrigger does for pushes. It only queues the work.
302// The synchronize activity needs no call here: the push of the source branch
303// reaches WorkflowTrigger.OnPush.
304type PullRequestTrigger interface {
305 // OnPullRequest queues the activity ev of a merge request. p is who caused
306 // it: its trust is the run's, whatever happens to the branches before the
307 // event is handled. A job token starts no run.
308 OnPullRequest(ctx context.Context, repo domain.RepoName, ev PullRequestEvent, p domain.Principal)
309}
310
311// PullRequestEvent is one activity of a merge request, with the commits it is
312// for fixed when it happened: it runs for exactly these, with the trust of
313// whoever caused it, even when the branches have moved on by the time it is
314// handled.
315type PullRequestEvent struct {
316 Number int64
317 // Action is domain.PullOpened or domain.PullClosed.
318 Action string
319 // Head is the head of the source branch and Base the tip of the target at
320 // that moment; either may be zero when unknown (the current one is read).
321 Head, Base domain.ObjectID
322 // Merged is set on the closing a merge makes: its runs have the merger's
323 // trust (usecase.CI checks the merge against the request).
324 Merged bool
325}
326
327// PullGate lets the CI change what depends on a merge request staying open
328// (its refs/pull refs, the runs of its opening and updates) without racing a
329// close or a merge. *usecase.MergeRequests implements it.
330type PullGate interface {
331 // WhileOpen runs fn holding the merge lock of the repository (the one
332 // Close and Merge take) when merge request number is open, and returns
333 // domain.ErrPreconditionFailed without running fn when it is not. fn must
334 // be short and must not call the merge request use cases.
335 WhileOpen(ctx context.Context, repo domain.RepoName, number int64, fn func() error) error
336}
337
338// PullGit is what the refs/pull/<n>/{head,merge} of the merge requests need
339// from Git. Every method returns domain.ErrNotFound when the repository has no
340// directory.
341type PullGit interface {
342 // TestMerge merges head into base without touching a ref (`git merge-tree
343 // --write-tree`) and returns the tree of the result. clean is false when
344 // the merge conflicts, or when the commits share no history.
345 TestMerge(ctx context.Context, repo domain.RepoName, base, head domain.ObjectID) (tree domain.ObjectID, clean bool, err error)
346 // SetPullRef points a ref of domain.IsPullRef to the commit. Any other ref
347 // name is domain.ErrInvalid.
348 SetPullRef(ctx context.Context, repo domain.RepoName, ref string, id domain.ObjectID) error
349 // PullRef returns the commit a ref of domain.IsPullRef points to, or
350 // domain.ErrNotFound.
351 PullRef(ctx context.Context, repo domain.RepoName, ref string) (domain.ObjectID, error)
352}
353
354// CIGit is what planning needs from Git beyond RepoReader and MergeGit.
355type CIGit interface {
356 // ChangedPaths returns the paths changed from base to head (a zero base
357 // means the empty tree), in the order of the diff and without renames
358 // detection, at most max; truncated is true when there were more.
359 ChangedPaths(ctx context.Context, repo domain.RepoName, base, head domain.ObjectID, max int) (paths []string, truncated bool, err error)
360 // CommitsOffBranches returns the commits reachable from head and from no
361 // branch (refs/heads/*; tags do not count), newest first, at most limit
362 // (1 to MaxCommitLimit); more is true when there are others. It is empty
363 // for a commit that a branch already has.
364 CommitsOffBranches(ctx context.Context, repo domain.RepoName, head domain.ObjectID, limit int) (commits []domain.Commit, more bool, err error)
365}
366
367// PushObjects tells where the objects of a push in progress are. Git receives a
368// push into a quarantine directory and moves the objects into the repository
369// only when pre-receive accepts it, so the objects a pre-receive check reads are
370// not in the repository yet. Both fields are what git's own environment holds
371// in the hook (GIT_OBJECT_DIRECTORY and GIT_ALTERNATE_OBJECT_DIRECTORIES). The
372// zero value is a push with nothing in quarantine.
373type PushObjects struct {
374 Dir string
375 Alternates string
376}
377
378// WorkflowGuard finds the changes of a push to the workflow files of a
379// repository.
380type WorkflowGuard interface {
381 // ChangedWorkflow returns the first path under .github/workflows/ that the
382 // updates change, "" for none. Two checks, as GitHub judges the token of a
383 // job: (1) every commit the push brings (those no ref has yet) is compared
384 // with each of its parents (a root commit with nothing) and is a change when
385 // it has workflows that differ from every parent's; (2) the workflows a ref
386 // ends with must be its old ones or none for an update, and the default
387 // branch head's or none for a new ref (none when there is no head). A
388 // workflows directory that disappears is no change, and a deleted ref changes
389 // nothing. objects are those of the push in progress; a directory that is not
390 // inside the repository is refused. A push beyond the bounds of the check
391 // (commits, parents) is an error that matches domain.ErrInvalid.
392 ChangedWorkflow(ctx context.Context, repo domain.RepoName, updates []domain.RefUpdate, objects PushObjects) (path string, err error)
393}
394
395// --- inbound ---
396
397// RegisterRunnerParams describe a runner to register.
398type RegisterRunnerParams struct {
399 Name string
400 Labels []string
401 Version string
402 Isolation domain.CIIsolation
403 Arch, OS string
404 Replace bool
405}
406
407// RegisteredRunner is a new runner with its secret, shown once.
408type RegisteredRunner struct {
409 Runner domain.CIRunner
410 Token string
411}
412
413// RunnerJob is a job given to a runner.
414type RunnerJob struct {
415 Job domain.CIJob
416 Token string
417 // GithubToken is the job repository token, the "github.token" of the job.
418 GithubToken string
419 Repo domain.RepoName
420 Sha, Ref string
421 WorkflowPath string
422 WorkflowYAML string
423 // Environment is the environment the job deploys to, "" for none.
424 Environment string
425 // Vars are the merged variables of the job (environment over repository
426 // over instance), already in its "vars" context.
427 Vars map[string]string
428 // Secrets are the secrets the job refers to, in plain text: empty when the
429 // run is not trusted, when the job refers to none and when the server has
430 // no key. They go to the runner and nowhere else: never into the run
431 // record, the github context or a log.
432 Secrets map[string]string
433 // Trusted is the trusted flag of the run: secrets were allowed.
434 Trusted bool
435 // Permissions are the permissions of GithubToken (key to level), after the
436 // trust rule: no write when the run is not trusted.
437 Permissions map[string]string
438 // Cache is the scope of the job in the runner's cache (Job.cache).
439 Cache JobCache
440 // IDTokenURL is the token endpoint of the job's OIDC ID tokens and
441 // IDTokenRequestToken its bearer (Job.id_token_url and
442 // id_token_request_token); both "" when the job may not have ID tokens.
443 IDTokenURL string
444 IDTokenRequestToken string
445}
446
447// JobCache is what a job may do in the cache the runner serves: save entries
448// under WriteRef only ("" for none) and restore those of ReadRefs, most
449// specific first. Repository is "owner/name".
450type JobCache struct {
451 Repository string
452 WriteRef string
453 ReadRefs []string
454}
455
456// String describes the job without its secrets and tokens, so that a job
457// printed by mistake leaks nothing.
458func (j RunnerJob) String() string {
459 return fmt.Sprintf("RunnerJob{job:%s run:%d repo:%s secrets:%d trusted:%t}", j.Job.ID, j.Job.RunID, j.Repo, len(j.Secrets), j.Trusted)
460}
461
462// GoString is String for %#v.
463func (j RunnerJob) GoString() string { return j.String() }
464
465// FetchJobParams selects the job a runner asks for.
466type FetchJobParams struct {
467 Labels []string
468 PollID string
469 // Version is the version of the running runner, "" from an older runner.
470 Version string
471}
472
473// FetchJobResult is the answer of a poll.
474type FetchJobResult struct {
475 Job *RunnerJob
476 // RetryAfter is how long the runner waits before polling again.
477 RetryAfter time.Duration
478}
479
480// StepUpdate is the state of one step as a runner reports it.
481type StepUpdate struct {
482 Number int32
483 Name string
484 State domain.CIStepState
485 Conclusion domain.CIConclusion
486 // Outcome is how the step ended before continue-on-error; none when the
487 // runner does not report it.
488 Outcome domain.CIConclusion
489 StartedAt time.Time
490 CompletedAt time.Time
491}
492
493// CompleteJobParams end a job.
494type CompleteJobParams struct {
495 JobID string
496 Conclusion domain.CIConclusion
497 Outputs map[string]string
498 RunnerShutdown bool
499 Steps []StepUpdate
500 // Annotations replace those of each step they name, as in UpdateJob.
501 Annotations []domain.CIAnnotation
502}
503
504// CompleteJobResult is the stored result of a job.
505type CompleteJobResult struct {
506 Conclusion domain.CIConclusion
507 Error string
508 Applied bool
509}
510
511// ResolvedAction is the resolution of one "uses" of ResolveActions: where to
512// download the action, or Error (then only Ref is set).
513type ResolvedAction struct {
514 Ref string
515 NameWithOwner string
516 Path string
517 ResolvedSHA string
518 TarballURL string
519 Token string
520 Source domain.CIActionSource
521 Error string
522}
523
524// RemoteRef is a ref of a remote repository, as `git ls-remote` lists it.
525type RemoteRef struct {
526 // Name is the full ref name ("refs/heads/main", "refs/tags/v1").
527 Name string
528 // ID is the object the ref points to (the tag object of an annotated tag).
529 ID string
530 // Peeled is the commit an annotated tag points to; empty for other refs.
531 Peeled string
532}
533
534// GitRemote lists the refs of a repository on github.com, with no
535// credentials. It returns domain.ErrNotFound for a repository that does not
536// exist or needs credentials (GitHub answers alike), and an error matching
537// domain.ErrUnavailable when it cannot tell (network, timeout, too large an
538// answer).
539type GitRemote interface {
540 ListRefs(ctx context.Context, owner, repo string) ([]RemoteRef, error)
541}
542
543// WorkflowFetcher downloads one reusable workflow file from github.com at a
544// commit that was already resolved (CI-3, D7), with no credentials. It returns
545// domain.ErrNotFound for a file or repository that does not exist or needs
546// credentials, domain.ErrResourceExhausted for a file larger than maxBytes, and
547// an error matching domain.ErrUnavailable when it cannot tell.
548type WorkflowFetcher interface {
549 FetchWorkflow(ctx context.Context, owner, repo, sha, path string, maxBytes int64) ([]byte, error)
550}
551
552// JobSignal is one message of WatchJob.
553type JobSignal struct {
554 Keepalive bool
555 // Cancel is set for a cancel request.
556 Cancel *JobCancel
557 // Ended is set when the job has ended.
558 Ended *domain.JobEndedError
559}
560
561// JobCancel is a cancel request for a running job.
562type JobCancel struct {
563 Reason domain.CICancelReason
564 Message string
565 RequestedAt time.Time
566}
567
568// RunnerService is what runners call. The secret is the bearer secret of the
569// call: the runner token for FetchJob, the job token for the other calls.
570// A bad secret is domain.ErrUnauthenticated; a job token of another job than
571// the one named is domain.ErrForbidden. *usecase.CI implements it.
572type RunnerService interface {
573 Register(ctx context.Context, p domain.Principal, params RegisterRunnerParams) (RegisteredRunner, error)
574 FetchJob(ctx context.Context, secret string, params FetchJobParams) (FetchJobResult, error)
575 // UpdateJob applies the steps and the annotations whole or not at all: for
576 // each step number present in annotations, the annotations of that step are
577 // replaced (also for a step already completed, or not in steps).
578 UpdateJob(ctx context.Context, secret, jobID string, steps []StepUpdate, annotations []domain.CIAnnotation) error
579 AppendLog(ctx context.Context, secret, jobID string, step int32, offset int64, lines []domain.CILogLine) (next int64, err error)
580 Heartbeat(ctx context.Context, secret, jobID string) error
581 // WatchJob calls ready once the job token is valid and the stream is
582 // registered, before any message: the adapter flushes the response headers
583 // then, because a client's call returns only when they arrive.
584 WatchJob(ctx context.Context, secret, jobID string, ready func(), send func(JobSignal) error) error
585 CompleteJob(ctx context.Context, secret string, params CompleteJobParams) (CompleteJobResult, error)
586 // ResolveActions resolves the "uses" of the job's steps, one answer per
587 // reference in the same order. A reference that cannot be resolved is not
588 // an error: its answer carries Error. A local ("./") or Docker
589 // ("docker://") reference, or more than 100, is domain.ErrInvalid.
590 ResolveActions(ctx context.Context, secret, jobID string, uses []string) ([]ResolvedAction, error)
591 // UploadSummary stores the summary of a step, replacing the one it has; an
592 // empty markdown removes it. More than 1 MiB, invalid UTF-8 or a step
593 // number outside 1 to 1,000 is domain.ErrInvalid.
594 UploadSummary(ctx context.Context, secret, jobID string, step int32, markdown string) error
595}
596
597// JobView is a job as owners see it.
598type JobView struct {
599 domain.CIJob
600 // Lines is the number of lines of its log now.
601 Lines int64
602 // RunnerGone is set when the runner of the job was removed since.
603 RunnerGone bool
604}
605
606// StepRanges returns where the lines of every step are in the log.
607func (v JobView) StepRanges() []domain.StepRange { return domain.StepRanges(v.Steps, v.Lines) }
608
609// ListRunsParams select a page of runs.
610type ListRunsParams struct {
611 PageSize int
612 PageToken string
613 // Workflow restricts the result to a workflow file: its path or its file
614 // name. Branch restricts it to the runs of a branch, by short name. Status
615 // restricts it to the runs of that status. Empty means no restriction.
616 Workflow string
617 Branch string
618 Status domain.CIStatus
619}
620
621// RunPage is a page of runs, newest first.
622type RunPage struct {
623 Runs []domain.CIRun
624 NextPageToken string
625}
626
627// RunDetail is a run with its jobs.
628type RunDetail struct {
629 Run domain.CIRun
630 Jobs []JobView
631 LatestAttempt int32
632}
633
634// LogBatch is a message of a log stream: consecutive lines from Offset.
635type LogBatch struct {
636 Offset int64
637 Lines []JobLogLine
638}
639
640// JobLogLine is a log line with its step.
641type JobLogLine struct {
642 Step int32
643 domain.CILogLine
644}
645
646// GetJobLogParams select the log to stream.
647type GetJobLogParams struct {
648 JobID string
649 // Attempt is the attempt of the job, 0 for the latest.
650 Attempt int32
651 Offset int64
652 Follow bool
653 // Ready, when not nil, is called once the access is checked and the
654 // stream is counted, before any batch: the adapter flushes the response
655 // headers then (a follow on a job with no line yet would keep the client's
656 // call waiting for the first one).
657 Ready func()
658 // Client identifies where the call comes from, for the limit of streams
659 // per client; empty counts against the total only.
660 Client string
661}
662
663// CheckView is a check with what owners need to read it.
664type CheckView struct {
665 domain.CICheck
666 // WaitingForRunner is set for a queued check whose job no registered
667 // runner can take (no runner has all its labels).
668 WaitingForRunner bool
669}
670
671// ChecksResult are the checks of a commit.
672type ChecksResult struct {
673 Checks []CheckView
674 Truncated bool
675}
676
677// RunnerPage is a page of runners.
678type RunnerPage struct {
679 Runners []RunnerView
680 NextPageToken string
681}
682
683// RunnerView is a runner with what is known of it now.
684type RunnerView struct {
685 domain.CIRunner
686 LastSeen time.Time
687 Busy bool
688 // Online is decided by the server's clock (see usecase.RunnerOnlineWindow).
689 Online bool
690}
691
692// JobAnnotation is an annotation with the job it belongs to.
693type JobAnnotation struct {
694 JobID string
695 Annotation domain.CIAnnotation
696}
697
698// AnnotationList are the annotations of a run, at most
699// domain.CIMaxListedAnnotations.
700type AnnotationList struct {
701 Annotations []JobAnnotation
702 Truncated bool
703}
704
705// SummaryList are the summaries of a job, at most domain.CIMaxListedSummaries.
706type SummaryList struct {
707 Summaries []domain.CIStepSummary
708 Truncated bool
709}
710
711// RunService is the owner side of CI. *usecase.CI implements it.
712type RunService interface {
713 ListRuns(ctx context.Context, p domain.Principal, repo domain.RepoName, params ListRunsParams) (RunPage, error)
714 GetRun(ctx context.Context, p domain.Principal, repo domain.RepoName, runID int64, attempt int32) (RunDetail, error)
715 GetJob(ctx context.Context, p domain.Principal, repo domain.RepoName, jobID string, attempt int32) (JobView, error)
716 GetJobLog(ctx context.Context, p domain.Principal, repo domain.RepoName, params GetJobLogParams, send func(LogBatch) error) error
717 CancelRun(ctx context.Context, p domain.Principal, repo domain.RepoName, runID int64) (domain.CIRun, error)
718 RerunRun(ctx context.Context, p domain.Principal, repo domain.RepoName, runID int64, failedOnly bool) (domain.CIRun, error)
719 // DispatchWorkflow starts a run of a workflow file by hand (workflow_dispatch).
720 // The caller needs ci:write on the repository, or is a job token with the
721 // permission actions: write. The run is returned queued.
722 DispatchWorkflow(ctx context.Context, p domain.Principal, repo domain.RepoName, params DispatchParams) (domain.CIRun, error)
723 ListChecks(ctx context.Context, p domain.Principal, repo domain.RepoName, sha string) (ChecksResult, error)
724 // ListAnnotations returns the annotations of a run attempt (0 for the
725 // latest), of one job when jobID is not empty. Each job gives those of the
726 // attempt in which it executed.
727 ListAnnotations(ctx context.Context, p domain.Principal, repo domain.RepoName, runID int64, attempt int32, jobID string) (AnnotationList, error)
728 // GetStepSummaries returns the summaries of a job at an attempt (0 for the
729 // latest), by step number. maxBytes above 0 bounds the Markdown read: the
730 // summaries past it come back Omitted, without their Markdown (the API
731 // passes 0, no bound).
732 GetStepSummaries(ctx context.Context, p domain.Principal, repo domain.RepoName, jobID string, attempt int32, maxBytes int64) (SummaryList, error)
733 ListRunners(ctx context.Context, p domain.Principal, size int, token string) (RunnerPage, error)
734 RemoveRunner(ctx context.Context, p domain.Principal, id string) error
735}
736
737// ErrSecretNotOpened means a sealed secret does not open: another key, other
738// additional data (a value moved to another scope or name) or a damaged value.
739var ErrSecretNotOpened = errors.New("secret does not open")
740
741// SecretSealer encrypts the values of secrets at rest. The adapter holds the
742// master key; without one the use cases get no sealer and refuse secrets.
743type SecretSealer interface {
744 // Seal returns plaintext sealed and bound to aad. It never fails.
745 Seal(plaintext, aad []byte) []byte
746 // Open reverses Seal with the same aad, or returns ErrSecretNotOpened.
747 Open(sealed, aad []byte) ([]byte, error)
748 // KeyCheck is a value derived from the key that does not reveal it.
749 KeyCheck() []byte
750}
751
752// SealedSecret is a stored secret: its value is sealed.
753type SealedSecret struct {
754 Name string
755 Sealed []byte
756 UpdatedAt time.Time
757}
758
759// CISettingsStore keeps the secrets, variables and environments of CI (ADR
760// 0019). A scope that names a missing repository or environment is
761// domain.ErrNotFound for every write and every read of its content. Names are
762// already upper-cased (domain.ParseSettingName).
763type CISettingsStore interface {
764 // BindSecretsKey records the key check beside the secrets when none is
765 // stored, and returns domain.ErrSecretsKeyMismatch when the stored one
766 // differs.
767 BindSecretsKey(ctx context.Context, check []byte) error
768 // PutSecret creates or replaces a secret.
769 PutSecret(ctx context.Context, scope domain.SettingsScope, name string, sealed []byte, at time.Time) (domain.Secret, error)
770 // GetSealedSecret reads one secret of a scope, or domain.ErrNotFound when
771 // it, the repository or the environment does not exist.
772 GetSealedSecret(ctx context.Context, scope domain.SettingsScope, name string) (SealedSecret, error)
773 // ListSealedSecrets lists the secrets of one scope ordered by name.
774 ListSealedSecrets(ctx context.Context, scope domain.SettingsScope) ([]SealedSecret, error)
775 // DeleteSecret deletes a secret, or returns domain.ErrNotFound.
776 DeleteSecret(ctx context.Context, scope domain.SettingsScope, name string) error
777 // PutVariable creates or replaces a variable.
778 PutVariable(ctx context.Context, scope domain.SettingsScope, name, value string, at time.Time) (domain.Variable, error)
779 // GetVariable returns a variable, or domain.ErrNotFound.
780 GetVariable(ctx context.Context, scope domain.SettingsScope, name string) (domain.Variable, error)
781 // ListVariables lists the variables of one scope ordered by name.
782 ListVariables(ctx context.Context, scope domain.SettingsScope) ([]domain.Variable, error)
783 // DeleteVariable deletes a variable, or returns domain.ErrNotFound.
784 DeleteVariable(ctx context.Context, scope domain.SettingsScope, name string) error
785 // CreateEnvironment creates the environment, or returns the existing one
786 // (compared without regard to case) unchanged.
787 CreateEnvironment(ctx context.Context, repo domain.RepoName, name string, at time.Time) (domain.Environment, error)
788 // ListEnvironments lists the environments of a repository ordered by name.
789 ListEnvironments(ctx context.Context, repo domain.RepoName) ([]domain.Environment, error)
790 // DeleteEnvironment deletes the environment with its secrets and
791 // variables, or returns domain.ErrNotFound.
792 DeleteEnvironment(ctx context.Context, repo domain.RepoName, name string) error
793}
794
795// JobSettingsRequest asks for the variables, and when wanted the secrets, a job
796// sees.
797type JobSettingsRequest struct {
798 Repo domain.RepoName
799 // Environment is the environment of the job, "" for none.
800 Environment string
801 // CreateEnvironment creates the environment first when it does not exist
802 // (a job that names one creates it on first use).
803 CreateEnvironment bool
804 // WantSecrets asks for secrets at all: false for a run that is not
805 // trusted. SecretNames are the (upper-cased) names to return, or AllSecrets
806 // for every secret of the scopes.
807 WantSecrets bool
808 SecretNames []string
809 AllSecrets bool
810}
811
812// JobSettings are what a job sees: the merged variables and secrets, with the
813// environment over the repository over the instance.
814type JobSettings struct {
815 Vars map[string]string
816 Secrets map[string]string
817 // SecretsOff is set when secrets were wanted but the server has no
818 // ERMITE_SECRETS_KEY, so none can be given.
819 SecretsOff bool
820}
821
822// CIJobSettings resolves the variables and secrets of a job. *usecase.CISettings
823// implements it.
824type CIJobSettings interface {
825 Resolve(ctx context.Context, req JobSettingsRequest) (JobSettings, error)
826}