| 1 | // SPDX-License-Identifier: AGPL-3.0-or-later |
| 2 | |
| 3 | // Package engine defines the runner execution boundary. |
| 4 | package engine |
| 5 | |
| 6 | import ( |
| 7 | "context" |
| 8 | "encoding/json" |
| 9 | "errors" |
| 10 | "time" |
| 11 | ) |
| 12 | |
| 13 | const ( |
| 14 | ConclusionSuccess = "success" |
| 15 | ConclusionFailure = "failure" |
| 16 | ConclusionCancelled = "cancelled" |
| 17 | ConclusionTimedOut = "timed_out" |
| 18 | ) |
| 19 | |
| 20 | // ErrJobTimedOut marks an execution failure caused by the workflow job's |
| 21 | // timeout-minutes deadline, not by runner shutdown or user cancellation. |
| 22 | var ErrJobTimedOut = errors.New("runner engine: job timed out") |
| 23 | |
| 24 | type Engine interface { |
| 25 | Execute(ctx context.Context, job Job) (Outcome, error) |
| 26 | StreamLogs(ctx context.Context, jobID int64) (<-chan LogChunk, error) |
| 27 | Cancel(ctx context.Context, jobID int64) error |
| 28 | } |
| 29 | |
| 30 | // EventStreamer is an optional engine capability for preserving runner API |
| 31 | // ordering between final log chunks and step completion updates. |
| 32 | type EventStreamer interface { |
| 33 | StreamEvents(ctx context.Context, jobID int64) (<-chan Event, error) |
| 34 | } |
| 35 | |
| 36 | type Job struct { |
| 37 | ID int64 |
| 38 | RunID int64 |
| 39 | RepoID int64 |
| 40 | RunIndex int64 |
| 41 | WorkflowFile string |
| 42 | WorkflowName string |
| 43 | CheckoutURL string |
| 44 | CheckoutToken string |
| 45 | HeadSHA string |
| 46 | HeadRef string |
| 47 | Event string |
| 48 | EventPayload map[string]any |
| 49 | JobKey string |
| 50 | JobName string |
| 51 | RunsOn string |
| 52 | Needs []string |
| 53 | If string |
| 54 | TimeoutMinutes int32 |
| 55 | Permissions json.RawMessage |
| 56 | Secrets map[string]string |
| 57 | Env map[string]string |
| 58 | Steps []Step |
| 59 | WorkspaceDir string |
| 60 | Image string |
| 61 | MaskValues []string |
| 62 | } |
| 63 | |
| 64 | type Step struct { |
| 65 | ID int64 |
| 66 | Index int32 |
| 67 | StepID string |
| 68 | Name string |
| 69 | If string |
| 70 | Run string |
| 71 | Uses string |
| 72 | WorkingDirectory string |
| 73 | Env map[string]string |
| 74 | With map[string]string |
| 75 | ContinueOnError bool |
| 76 | } |
| 77 | |
| 78 | type Outcome struct { |
| 79 | Conclusion string |
| 80 | StartedAt time.Time |
| 81 | CompletedAt time.Time |
| 82 | StepOutcomes []StepOutcome |
| 83 | } |
| 84 | |
| 85 | type StepOutcome struct { |
| 86 | StepID int64 |
| 87 | Status string |
| 88 | Conclusion string |
| 89 | StartedAt time.Time |
| 90 | CompletedAt time.Time |
| 91 | } |
| 92 | |
| 93 | type LogChunk struct { |
| 94 | JobID int64 |
| 95 | StepID int64 |
| 96 | Seq int32 |
| 97 | Chunk []byte |
| 98 | } |
| 99 | |
| 100 | type Event struct { |
| 101 | Log *LogChunk |
| 102 | Step *StepOutcome |
| 103 | } |
| 104 |