conformance

Documentation

Overview

Package conformance is the public conformance suite for the secure-oci stable v1 pipeline API (including its v1alpha1/v1beta1 compatibility inputs) and the v1 plugin protocol. The golden vectors pin validation outcomes, canonical fingerprints and stage cache keys so an independent implementation (or a future version of this one) can prove compatibility; the plugin checks exercise a plugin executable's protocol behavior from the outside. The suite ships as the platform-factory-conformance binary with the vectors embedded, so it runs without this repository.

Index

• func EmbeddedBackendVectors() fs.FS
• func EmbeddedPublicationVectors() fs.FS
• func EmbeddedVectors() fs.FS
• type BackendExpect
• type BackendVector
• type Expect
  • func Evaluate(raw json.RawMessage) (Expect, error)
• type PublicationExpect
• type PublicationVector
• type RegistryPublicationInput
• type Result
  • func RunBackend(fsys fs.FS) ([]Result, error)
  • func RunPlugin(ctx context.Context, executable string) ([]Result, error)
  • func RunPublication(fsys fs.FS) ([]Result, error)
  • func RunVectors(fsys fs.FS) ([]Result, error)
• type Vector

Functions

func EmbeddedBackendVectors

func EmbeddedBackendVectors() fs.FS

EmbeddedBackendVectors returns the execution-backend vector corpus compiled into this build.

func EmbeddedPublicationVectors

func EmbeddedPublicationVectors() fs.FS

func EmbeddedVectors

func EmbeddedVectors() fs.FS

EmbeddedVectors returns the vector corpus compiled into this build.

Types

type BackendExpect

type BackendExpect struct {
	ExitCode int    `json:"exit_code"`
	Stdout   string `json:"stdout"`
}

BackendExpect describes the pinned outcome. ExitCode -1 is the internal/executor convention for a stage rejected before it ever ran (an unsupported policy, for example), distinct from a stage that ran and exited non-zero.

type BackendVector

type BackendVector struct {
	Name   string        `json:"name"`
	Stage  api.Stage     `json:"stage"`
	Expect BackendExpect `json:"expect"`
}

BackendVector pins the expected outcome of running one stage in isolation - no dependency on any other stage, cache, or DAG - against an execution backend.

type Expect

type Expect struct {
	Valid       bool              `json:"valid"`
	Issues      []pipeline.Issue  `json:"issues,omitempty"`
	Fingerprint string            `json:"fingerprint,omitempty"`
	Order       []string          `json:"order,omitempty"`
	StageKeys   map[string]string `json:"stage_keys,omitempty"`
}

Expect describes the pinned outcome of decoding a vector's pipeline. For invalid pipelines Issues holds the exact sorted validation issues. For valid pipelines Fingerprint pins the canonical SHA-256, Order the topological order, and StageKeys the cache key of every stage computed with the fixed conformance inputs (engine version "conformance/1", the empty-string sha256 as base digest, linux/amd64, and per-input digests derived from sha256("stage/name")).

func Evaluate

func Evaluate(raw json.RawMessage) (Expect, error)

Evaluate computes the actual outcome for one pipeline document with the fixed conformance inputs.

type PublicationExpect

type PublicationExpect struct {
	Valid      bool   `json:"valid"`
	Target     string `json:"target,omitempty"`
	Repository string `json:"repository,omitempty"`
	Tag        string `json:"tag,omitempty"`
	SHA256     string `json:"sha256,omitempty"`
}

type PublicationVector

type PublicationVector struct {
	Name       string                            `json:"name"`
	Registry   *RegistryPublicationInput         `json:"registry,omitempty"`
	Kubernetes *publicationtarget.KubernetesSpec `json:"kubernetes,omitempty"`
	Expect     PublicationExpect                 `json:"expect"`
}

type RegistryPublicationInput

type RegistryPublicationInput struct {
	Reference string `json:"reference"`
}

type Result

type Result struct {
	Name   string `json:"name"`
	Passed bool   `json:"passed"`
	Detail string `json:"detail,omitempty"`
}

Result is the outcome of one conformance check.

func RunBackend

func RunBackend(fsys fs.FS) ([]Result, error)

RunBackend evaluates every vector in fsys against a fresh local (unsandboxed) internal/executor.Executor, one per vector so no vector can observe another's filesystem or environment. This is the conformance baseline every execution backend must satisfy - the sandboxed backend adds isolation on top without changing these observable outcomes, and is not itself exercised here because its namespace and cgroup requirements are not available on every host (see internal/executor.ProbeSandbox). The vectors assume a POSIX shell at /bin/sh.

func RunPlugin

func RunPlugin(ctx context.Context, executable string) ([]Result, error)

RunPlugin exercises a plugin executable's protocol conformance from the outside: handshake correctness, exact protocol version, unknown method rejection with code 404, and rejection of malformed and oversized frames. Each check starts a fresh plugin process because protocol violations are fatal by design.

func RunPublication

func RunPublication(fsys fs.FS) ([]Result, error)

func RunVectors

func RunVectors(fsys fs.FS) ([]Result, error)

RunVectors evaluates every vector in fsys against the engine and reports mismatches. Vectors are processed in file-name order.

type Vector

type Vector struct {
	Name     string          `json:"name"`
	Pipeline json.RawMessage `json:"pipeline"`
	Expect   Expect          `json:"expect"`
}

Vector pins the expected engine behavior for one pipeline document.