Files
zeekayandHanzo Dev bfad54cb92 Reach an https forge, against the protocol forge 1.26.62 serves
The protocol module is carried in third_party/forge-runner (forge v1.26.62's
modules/actions/runner): the pinned 2026-09-06 pseudo-version is unpublished.
zip addresses a call by host and path and leaves the URI scheme http, which a
TLS HostClient refuses before it dials, so an https forge was unreachable.

Co-authored-by: Hanzo Dev <[email protected]>
2026-11-13 14:23:31 -08:00

343 lines
15 KiB
Go

// Copyright 2026 Hanzo AI, Inc. All rights reserved.
// SPDX-License-Identifier: MIT
// Package runner holds the values a runner and the forge exchange: the input
// and output of each of the five ops the forge serves under /v1/runner.
//
// It is a leaf on purpose. The runner is a separate module and imports this
// package to get the very types the handlers declare, so there is one
// definition of the protocol rather than a server copy and a client copy that
// drift. Nothing here may import the rest of the forge.
//
// Two rules govern every field, and both come from the wire rather than from
// taste. ZAP gives a field an offset and a width, so:
//
// - No map. A map has neither, and it is refused outright when the layout is
// derived. A set of names and values crosses as an ordered []Pair.
// - No time.Time. Every one of its fields is unexported, so it derives an
// empty layout: it is accepted, carries nothing, and arrives as the zero
// time with no error anywhere. Every instant here is an int64 of unix
// nanoseconds, and 0 means unset. Nanoseconds rather than milliseconds
// because the stored log format keeps 100ns ticks.
//
// Field ORDER is part of the wire: a field is found at its offset, not by its
// name. Append at the end, and only at the end.
package runner
// Result is how a job, a step or a task finished. The empty value means it has
// not finished, so a zero Result is "still going" rather than a fabricated
// outcome. The four names are the same words the forge's Status uses, so the
// wire needs no numbering to stay in step with the database.
type Result string
const (
Pending Result = ""
Success Result = "success"
Failure Result = "failure"
Cancelled Result = "cancelled"
Skipped Result = "skipped"
)
// Credential is what a registered runner presents on every op but register.
//
// It is embedded rather than repeated so it is declared once and serves both
// faces of the same op. Over HTTP the two values arrive as headers, which is
// what the `header:` tags say and what `json:"-"` makes the ONLY way to present
// them: a body carrying a uuid and a token reaches the handler with both fields
// empty. Over the call plane there are no headers, so they travel as ordinary
// arguments in their own slots.
type Credential struct {
// UUID is the handle the forge minted for this runner at registration.
UUID string `json:"-" header:"x-runner-uuid"`
// Token is the secret minted alongside that handle. It is presented on
// every call and is not readable back from anywhere.
Token string `json:"-" header:"x-runner-token"`
}
// Pair is one name and the value under it, and it is how every set of named
// values on this protocol crosses.
type Pair struct {
// Name is what the value is filed under.
Name string `json:"name"`
// Value is the value itself, always a string on this wire.
Value string `json:"value"`
}
// Identity is what the forge knows about a runner. The token is minted at
// registration and is the runner's credential for every later op.
type Identity struct {
// ID is the forge's own row id for this runner.
ID int64 `json:"id"`
// UUID is the handle the runner presents on every later op.
UUID string `json:"uuid"`
// Token is the secret that authenticates that handle. It is in cleartext
// here and nowhere else; the forge stores only a digest of it.
Token string `json:"token"`
// Name is what a person calls this runner in the forge's UI.
Name string `json:"name"`
// Version is the runner build the forge last heard from.
Version string `json:"version"`
// Labels are what a workflow's `runs-on:` selects this runner by.
Labels []string `json:"labels"`
// Ephemeral means the runner takes ONE job and exits, so the forge must not
// expect it back.
Ephemeral bool `json:"ephemeral"`
}
// RegisterIn trades a registration token for a runner identity. It is the one
// input with no Credential, because a runner has none until this answers; the
// token here is the REGISTRATION token, a different secret from the runner
// token the reply carries.
type RegisterIn struct {
// Name is what to call this runner. Required.
Name string `json:"name"`
// Token is the REGISTRATION secret, a different secret from the runner
// token the reply carries. Required.
Token string `json:"token"`
// Version is the runner build asking to register.
Version string `json:"version"`
// Labels are what a workflow's `runs-on:` will select this runner by.
Labels []string `json:"labels"`
// Ephemeral declares that this runner takes ONE job and exits.
Ephemeral bool `json:"ephemeral"`
// Capabilities are the optional protocol behaviours this runner
// understands, e.g. "cancelling".
Capabilities []string `json:"capabilities"`
}
// RegisterOut carries the minted runner credential in cleartext, exactly once.
type RegisterOut struct {
// Runner is the minted identity, carrying the token in cleartext once.
Runner Identity `json:"runner"`
}
// DeclareIn republishes what a registered runner can do. A runner sends it on
// start and after its configuration changes, so labels and version follow the
// runner without re-registering it.
type DeclareIn struct {
Credential
// Version is the runner build now running.
Version string `json:"version"`
// Labels replace what the forge holds, so a relabelled runner follows its
// configuration without re-registering.
Labels []string `json:"labels"`
// Capabilities are the optional protocol behaviours this runner
// understands, e.g. "cancelling".
Capabilities []string `json:"capabilities"`
}
// DeclareOut answers with the stored identity and the capabilities this forge
// understands, so a runner learns what the other side supports from the reply
// body rather than from a header.
type DeclareOut struct {
// Runner is the stored identity as the forge now holds it. Its Token is
// empty: the credential is minted once, by register.
Runner Identity `json:"runner"`
// Capabilities are what THIS FORGE understands, so a runner learns what the
// other side supports from the reply body rather than from a header.
Capabilities []string `json:"capabilities"`
}
// TaskIn asks for work. Queue is the queue version the runner last saw; when it
// equals the forge's, nothing has been queued since and the forge answers
// without opening the assignment transaction.
type TaskIn struct {
Credential
// Queue is the queue version the runner last saw. When it equals the
// forge's, nothing has been queued since.
Queue int64 `json:"queue"`
}
// TaskOut carries an assigned task, or no task and the current queue version
// for the runner to ask against next time. A nil Task is the "no work" answer
// and the only one: a present task always has a nonzero ID.
type TaskOut struct {
// Task is the assigned job, or nil for "no work".
Task *Task `json:"task,omitempty"`
// Queue is the forge's current queue version, to ask against next time.
Queue int64 `json:"queue"`
}
// Task is one job, expanded and ready to execute. ID is unique for all time —
// unlike a run or job id, it is never reused.
type Task struct {
// ID identifies this task on every later state and log report.
ID int64 `json:"id"`
// Workflow is the workflow document verbatim. The forge decides THAT a job
// runs; act, on the runner, decides what the document means.
Workflow []byte `json:"workflow"`
// Context is what the job evaluates github.* against.
Context Context `json:"context"`
// Secrets are the values masked out of the log and exposed as secrets.*.
Secrets []Pair `json:"secrets,omitempty"`
// Vars are the values exposed as vars.*.
Vars []Pair `json:"vars,omitempty"`
// Needs is what the jobs this one depends on produced.
Needs []Need `json:"needs,omitempty"`
}
// Need is what one job this task depends on produced. Job is the key the
// forge's needs map held, promoted to a field so the set crosses as a list.
type Need struct {
// Job is the depended-on job's id in the workflow.
Job string `json:"job"`
// Result is how it finished.
Result Result `json:"result"`
// Outputs are the values it published.
Outputs []Pair `json:"outputs,omitempty"`
}
// Context is what a job evaluates its expressions against, and what the runner
// hands to act as the github context.
//
// It is a struct, and that is the change with the most behaviour behind it. As
// a map the two sides could disagree in silence, and did: the forge wrote
// git_runtime_token while the runner read gitea_runtime_token and quietly fell
// back to the task token, which nothing anywhere reported. A field is a compile
// error instead.
//
// It carries what the forge computes AND the runner reads, and nothing else.
// The map shipped about thirteen keys that were always the empty string —
// action, action_path, env, path, job's siblings — because act fills those in
// itself; they crossed the wire to be discarded.
type Context struct {
// Event is the webhook payload that triggered the run, as opaque JSON. It
// stays bytes because its shape belongs to the event and not to us: the
// runner hands it to act, which evaluates github.event.* against it.
Event []byte `json:"event"`
// EventName is what triggered the run, e.g. "push".
EventName string `json:"event_name"`
// Job is which job of the workflow document this task is.
Job string `json:"job"`
// RunID identifies the run this task belongs to.
RunID string `json:"run_id"`
// RunNumber is the run's position in its repository, counting from 1.
RunNumber string `json:"run_number"`
// RunAttempt is which attempt of that run this is, counting from 1.
RunAttempt string `json:"run_attempt"`
// Actor is who caused the run.
Actor string `json:"actor"`
// Repository is "<owner>/<name>".
Repository string `json:"repository"`
// RepositoryOwner is the owner half of it.
RepositoryOwner string `json:"repository_owner"`
// Ref is the full ref the run is for, e.g. "refs/heads/main".
Ref string `json:"ref"`
// RefName is that ref without its refs/heads/ or refs/tags/ prefix.
RefName string `json:"ref_name"`
// RefType is "branch" or "tag".
RefType string `json:"ref_type"`
// HeadRef is the source branch of a pull request, empty otherwise.
HeadRef string `json:"head_ref"`
// BaseRef is the target branch of a pull request, empty otherwise.
BaseRef string `json:"base_ref"`
// Sha is the commit being run, in full.
Sha string `json:"sha"`
// ServerURL is the forge's own origin, as a link in a log points at it.
ServerURL string `json:"server_url"`
// APIURL is where the job reaches the forge's API.
APIURL string `json:"api_url"`
// RetentionDays is how long the run's artifacts are kept, as a number in a
// string because that is what an expression reads.
RetentionDays string `json:"retention_days"`
// Token is the job's credential against the forge's own API — github.token
// in an expression.
Token string `json:"token"`
// RuntimeToken authorizes the job against the actions runtime: artifacts,
// the cache. The runner passes it as ACTIONS_RUNTIME_TOKEN and masks it out
// of the log.
RuntimeToken string `json:"runtime_token"`
// ActionsURL is where act fetches an action repository from when a step
// names one. A runner that receives nothing here composes an unusable URL
// and every job dies before its first step, so the runner supplies its own
// fallback rather than trusting this to be set.
ActionsURL string `json:"actions_url"`
}
// StateIn reports progress. Outputs are sent incrementally: the reply names
// every key the forge has stored, so the runner stops resending them.
type StateIn struct {
Credential
// State is the task's progress and that of each of its steps.
State State `json:"state"`
// Outputs are values the job has published since the last report.
Outputs []Pair `json:"outputs,omitempty"`
}
// StateOut echoes the task's result as the forge now holds it, which is how a
// runner learns its task was cancelled from elsewhere. Stored names the outputs
// the forge has written down.
type StateOut struct {
// State is the task's result AS THE FORGE HOLDS IT, which may differ from
// what was reported: that is how a runner learns it was cancelled.
State State `json:"state"`
// Stored names the outputs the forge has written down, so the runner stops
// resending them.
Stored []string `json:"stored,omitempty"`
}
// State is a task's progress and that of each of its steps. Started and Stopped
// are unix nanoseconds, 0 for unset.
type State struct {
// ID is the task this is about.
ID int64 `json:"id"`
// Result is how it finished; empty means it has not.
Result Result `json:"result"`
// Started is when it began, in unix nanoseconds; 0 is unset.
Started int64 `json:"started,omitempty"`
// Stopped is when it finished, in unix nanoseconds; 0 is unset.
Stopped int64 `json:"stopped,omitempty"`
// Steps is each step's own progress, in the order the workflow declares.
Steps []Step `json:"steps,omitempty"`
}
// Step is one step's progress and the slice of the task log it wrote. Started
// and Stopped are unix nanoseconds, 0 for unset.
type Step struct {
// ID is the step's position in the job, counting from 0.
ID int64 `json:"id"`
// Result is how the step finished; empty means it has not.
Result Result `json:"result"`
// Started is when it began, in unix nanoseconds; 0 is unset.
Started int64 `json:"started,omitempty"`
// Stopped is when it finished, in unix nanoseconds; 0 is unset.
Stopped int64 `json:"stopped,omitempty"`
// LogIndex is the first line of the task log this step wrote.
LogIndex int64 `json:"log_index"`
// LogLength is how many lines it wrote from there.
LogLength int64 `json:"log_length"`
}
// LogIn appends console output. Index is the position of the first line in the
// task's log, so a resent batch overlaps rather than duplicates. Last seals the
// log and moves it to storage.
type LogIn struct {
Credential
// Task is whose log this is.
Task int64 `json:"task"`
// Index is the position of the first line in that log, so a resent batch
// overlaps rather than duplicates.
Index int64 `json:"index"`
// Lines is the batch itself.
Lines []Line `json:"lines,omitempty"`
// Last seals the log and moves it to storage. Appending past a seal is an
// error; resending one is acknowledged.
Last bool `json:"last,omitempty"`
}
// LogOut reports how far the log is durable: Ack is index + lines accepted, and
// the runner resends from there.
type LogOut struct {
// Ack is how far the log is durable — index plus lines accepted — and where
// the runner resends from.
Ack int64 `json:"ack"`
}
// Line is one line of console output. Time is unix nanoseconds.
type Line struct {
// Time is when the line was written, in unix nanoseconds.
Time int64 `json:"time"`
// Content is the line itself, without its terminator.
Content string `json:"content"`
}