Documentation
¶
Overview ¶
Package proto is the job/report wire contract between the Miabi control plane and a runner, carried over one yamux stream (opened by the control plane via the shared wstunnel transport). The control plane writes exactly one JobSpec, then reads a sequence of report Frames the runner emits as it executes; both are newline-delimited JSON. Keeping the contract in the runner module (which the control plane imports) means a single source of truth and independent versioning, mirroring how the transport lives in github.com/miabi-io/wstunnel.
Index ¶
Constants ¶
const FeatureMultiPlatform = "multi-platform"
FeatureMultiPlatform means the runner honours BuildConfig.Platforms.
const HeaderFeatures = "X-Runner-Features"
HeaderFeatures carries the comma-separated features a runner supports when it connects, so the control plane schedules a job only on a runner that can carry it out.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type BuildConfig ¶ added in v0.0.4
type BuildConfig struct {
// Method is "" | "auto" | "dockerfile" | "buildpack" (empty/auto auto-detects).
Method string `json:"method,omitempty"`
// Dockerfile is the Dockerfile path for the dockerfile method (default "Dockerfile"),
// relative to the checked-out source root — NOT to Context, matching
// `docker build -f <dockerfile> <context>`, where the two are independent.
Dockerfile string `json:"dockerfile,omitempty"`
// Context is the build context directory, relative to the checked-out source
// root (default: the root itself). A monorepo commonly keeps its Dockerfile in
// docker/ while still building from the root, so this must be settable apart
// from Dockerfile.
Context string `json:"context,omitempty"`
// Builder is the CNB builder image for the buildpack method (empty = runner default).
Builder string `json:"builder,omitempty"`
// Buildpacks are extra buildpacks to apply (pack --buildpack).
Buildpacks []string `json:"buildpacks,omitempty"`
// BuildEnv is build-time env for the buildpack method (pack --env KEY=VALUE).
BuildEnv map[string]string `json:"build_env,omitempty"`
// BuildArgs are Dockerfile ARG values for the dockerfile method
// (docker build --build-arg KEY=VALUE). The buildpack equivalent is BuildEnv.
//
// NOT for secrets: a build arg is recorded in the image's own history, so
// anyone who can pull the image can read it back. Pass credentials through the
// job's env instead.
BuildArgs map[string]string `json:"build_args,omitempty"`
// NoCache builds every layer from scratch, ignoring any cache the builder
NoCache bool `json:"no_cache,omitempty"`
// CacheFrom are registry refs to seed the layer cache from. Ignored when NoCache is set.
CacheFrom []string `json:"cache_from,omitempty"`
// CacheTo is the registry ref this build writes its cache to. Separate from CacheFrom so a branch
// build can read the trunk's cache without ever writing layers into one a trunk build would trust.
CacheTo string `json:"cache_to,omitempty"`
// Platforms are the OS/architecture pairs to build for, e.g. "linux/amd64" and "linux/arm64". Several
// push one multi-platform image whose digest names the index; empty builds for the runner's own
// platform. Only a runner advertising FeatureMultiPlatform honours it: an older one ignores the field.
Platforms []string `json:"platforms,omitempty"`
}
type Frame ¶
type Frame struct {
Type FrameType `json:"type"`
Step int `json:"step,omitempty"` // step ordinal for log/step/result
Line string `json:"line,omitempty"` // FrameLog
Status string `json:"status,omitempty"` // FrameStep / FrameDone
Exit int `json:"exit,omitempty"` // FrameResult exit code
Digest string `json:"digest,omitempty"` // FrameResult image digest (sha256:…)
Error string `json:"error,omitempty"` // FrameError
}
Frame is one report from the runner to the control plane. The meaningful payload fields depend on Type (see FrameType).
type FrameType ¶
type FrameType string
FrameType is the kind of report a runner sends back.
const ( FrameLog FrameType = "log" // a line of step output (streamed to pipeline:{runID}) FrameStep FrameType = "step" // a step status transition (running/succeeded/failed) FrameResult FrameType = "result" // a build step produced an image (Digest) FrameDone FrameType = "done" // the run reached a terminal Status FrameError FrameType = "error" // a runner-side failure (Error) )
type FrameWriter ¶
type FrameWriter struct {
// contains filtered or unexported fields
}
FrameWriter emits report frames back to the control plane over the stream.
func NewFrameWriter ¶
func NewFrameWriter(w io.Writer) *FrameWriter
NewFrameWriter wraps the stream's write side. All emit helpers are safe to call from a single goroutine (the job runner); the control plane decodes the frames in order.
func (*FrameWriter) Done ¶
func (fw *FrameWriter) Done(status string) error
Done reports the run's terminal status (succeeded/failed/canceled).
func (*FrameWriter) Err ¶
func (fw *FrameWriter) Err(msg string) error
Err reports a runner-side failure that aborted the run.
func (*FrameWriter) Log ¶
func (fw *FrameWriter) Log(step int, line string) error
Log streams one output line for a step.
type JobSpec ¶
type JobSpec struct {
RunID uint `json:"run_id"`
RunNumber int `json:"run_number"`
Pipeline string `json:"pipeline"`
WorkspaceID uint `json:"workspace_id"`
Workspace string `json:"workspace"` // workspace handle (MIABI_WORKSPACE_NAME)
AppID *uint `json:"app_id,omitempty"`
App string `json:"app,omitempty"`
Commit string `json:"commit,omitempty"`
Ref string `json:"ref,omitempty"`
Branch string `json:"branch,omitempty"`
// SourceURL is the git remote the runner clones and checks out at Commit into
// the workdir before running steps. Empty means the workspace is pre-populated
// (or the job runs no build). Any credential is carried in the URL or the
// injected job env, never logged.
SourceURL string `json:"source_url,omitempty"`
Repository string `json:"repository,omitempty"` // fully-qualified image repo to push to
Registry string `json:"registry,omitempty"` // registry host
Steps []StepSpec `json:"steps"`
Env []string `json:"env,omitempty"` // KEY=VALUE, non-secret MIABI_* context
Deadline time.Time `json:"deadline"` // hard job deadline (per-job cap)
}
JobSpec is the control plane's request to execute one pipeline run on a runner. It carries the predefined, non-secret build context (the MIABI_* variables); secrets and the ready-to-use registry login are injected separately per job.
type StepSpec ¶
type StepSpec struct {
Ordinal int `json:"ordinal"`
Name string `json:"name"`
Uses string `json:"uses"` // "build" | "deploy" | custom-step
Image string `json:"image,omitempty"` // container image for a custom step
Env []string `json:"env,omitempty"` // KEY=VALUE, step-scoped
Run []string `json:"run,omitempty"` // command for a container step
// ContinueOnError keeps the run going when this step fails (the step is still
// reported failed, the run still succeeds)
ContinueOnError bool `json:"continue_on_error,omitempty"`
// Build configures a build step (Uses=="build"): how to turn the checked-out
// source into an image. Nil (or an empty Method) means auto-detect — a root
// Dockerfile selects a Dockerfile build, otherwise Cloud Native Buildpacks.
Build *BuildConfig `json:"build,omitempty"`
}
StepSpec is one step of a run, executed in an isolated container on the runner.