proto

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 13, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

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

View Source
const FeatureMultiPlatform = "multi-platform"

FeatureMultiPlatform means the runner honours BuildConfig.Platforms.

View Source
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

func WriteJob

func WriteJob(w io.Writer, j JobSpec) error

WriteJob writes the single JobSpec that opens a job stream.

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.

func (*FrameWriter) Result

func (fw *FrameWriter) Result(step int, digest string, exit int) error

Result reports a build step's produced image digest and exit code.

func (*FrameWriter) Step

func (fw *FrameWriter) Step(ordinal int, status string) error

Step reports a step's status transition.

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.

func ReadJob

func ReadJob(r io.Reader) (JobSpec, error)

ReadJob reads the JobSpec at the start of a job stream.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL