Help us shape the future of Go! Take the 2026 Go Developer Survey

workertype

package
v0.21.0 Latest Latest
Warning

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

 Go to latest Published: Oct 29, 2026 License: AGPL-3.0 Imports: 12 Imported by: 0

Documentation

Overview

Package workertype contains the design-time Worker Type manifest contract from ADR-0207. Manifests describe package identity, compatibility, authoring metadata and executable artifact identity; they do not execute Worker code or participate in runtime job processing.

Package workertype defines the declarative Worker Type package contract from ADR-0207. It is design-time metadata: parsing and validation must never run in the processor hot path.

Index

Constants

View Source 
const (
	// APIVersionV1Alpha1 is the first Worker Type manifest schema version.
	APIVersionV1Alpha1 = "atlas.io/v1alpha1"
	// KindWorkerType identifies a Worker Type manifest.
	KindWorkerType = "WorkerType"
	// WorkerProtocolV1 is the first public Worker protocol version supported by manifests.
	WorkerProtocolV1 = "v1"
	// RuntimeExternal describes a separately packaged Worker runtime.
	RuntimeExternal = "external"
	// RuntimeBundled describes a Worker runtime shipped as part of Atlas.
	RuntimeBundled = "bundled"
)
View Source 
const MaxTechnicalSchemaInstanceBytes = 1 << 20

MaxTechnicalSchemaInstanceBytes bounds fixture payloads during offline conformance checks. Schema compilation and validation are never job hot-path operations.

View Source 
const TechnicalContractAPIVersion = "atlas.io/technical-capability/v1alpha1"

TechnicalContractAPIVersion is the first descriptive technical capability contract format. It is independent of Worker Type package and job protocol versions; this is never consulted by the job processor.

View Source 
const TechnicalContractJSONSchemaDialect = "https://json-schema.org/draft/2020-12/schema"

TechnicalContractJSONSchemaDialect pins embedded schema documents to a dialect. This package checks schema roots and local references, not full JSON Schema conformance.

View Source 
const TechnicalContractKind = "TechnicalCapabilityContract"

TechnicalContractKind identifies the semantic contract document.

Variables

This section is empty.

Functions

func DigestTechnicalContractJSON added in v0.21.0 

func DigestTechnicalContractJSON(raw []byte) (string, error)

DigestTechnicalContractJSON names a technical contract file by the SHA-256 of its exact bytes, as sha256:<hex> (ADR-0483). Nothing is re-serialized, so any tool can recompute the digest, and a reformatted file is a different artifact. The bytes must be one valid contract: within the size bound, valid UTF-8 without a byte-order mark, LF line endings only, and no duplicate JSON member at any depth. A mark or a carriage return would let the same contract hash differently on another machine or editor, so such a file gets no digest.

Digesting is an offline publication step, never a processor operation. A digest binds bytes only: it does not certify a Worker, grant routing or record an approval.

func ValidateTechnicalContracts added in v0.20.0 

func ValidateTechnicalContracts(contracts []TechnicalContract) error

ValidateTechnicalContracts refuses duplicate contract identities in a design-time collection; it neither certifies claims nor selects Workers.

Types

type Artifact 

type Artifact struct {
	Platform  string `json:"platform"`
	MediaType string `json:"mediaType"`
	Digest    string `json:"digest"`
}

Artifact identifies an executable runtime artifact by content digest.

type CapabilityClaim added in v0.20.0 

type CapabilityClaim struct {
	ID      string `json:"id"`
	Version string `json:"version"`
	// Profile distinguishes provider-specific semantic constraints. Omitting it
	// does not imply cross-provider equivalence.
	Profile string `json:"profile,omitempty"`
}

CapabilityClaim is a descriptive assertion that one Worker Type operation offers a versioned technical capability. It is not evidence that another operation is interchangeable, nor an authorization or routing permission. See ADR-0480.

type CompiledTechnicalContract added in v0.20.0 

type CompiledTechnicalContract struct {
	// contains filtered or unexported fields
}

CompiledTechnicalContract validates JSON documents against both complete Draft 2020-12 schemas. Its results are NOT provider conformance certificates, evidence of a verified Worker, or authorization to route a job.

func CompileTechnicalContract added in v0.20.0 

func CompileTechnicalContract(contract TechnicalContract) (*CompiledTechnicalContract, error)

CompileTechnicalContract compiles both JSON Schemas and verifies keyword structure, references and metadata offline. All caller-provided references are restricted to the existing envelope's local #/$defs/ convention. This is a design-time-only operation, never called from the processor.

func (*CompiledTechnicalContract) ValidateInputJSON added in v0.20.0 

func (compiled *CompiledTechnicalContract) ValidateInputJSON(raw []byte) error

ValidateInputJSON checks one bounded JSON payload against all input schema keywords. Success demonstrates a matching JSON shape, NOT provider behavior.

func (*CompiledTechnicalContract) ValidateOutputJSON added in v0.20.0 

func (compiled *CompiledTechnicalContract) ValidateOutputJSON(raw []byte) error

ValidateOutputJSON checks one bounded JSON payload against all output schema keywords. It is independent of the provider's actual returned errors/effects.

type ContractError added in v0.20.0 

type ContractError struct {
	Code        string `json:"code"`
	Description string `json:"description"`
	Retryable   bool   `json:"retryable"`
}

ContractError describes a stable semantic outcome, not a raw vendor code.

type ContractMetadata added in v0.20.0 

type ContractMetadata struct {
	ID      string `json:"id"`
	Version string `json:"version"`
	Profile string `json:"profile,omitempty"`
	Name    string `json:"name"`
}

ContractMetadata is the exact identity of a technical capability contract. A new meaning requires a new version or profile, not mutation in place.

type ContractSpec added in v0.20.0 

type ContractSpec struct {
	ResourceKind  string          `json:"resourceKind"`
	IdentityScope string          `json:"identityScope"`
	Verb          string          `json:"verb"`
	InputSchema   json.RawMessage `json:"inputSchema"`
	OutputSchema  json.RawMessage `json:"outputSchema"`
	Errors        []ContractError `json:"errors,omitempty"`
	Idempotency   string          `json:"idempotency"`
	Consistency   string          `json:"consistency"`
	Pagination    string          `json:"pagination"`
	MaxResults    int             `json:"maxResults,omitempty"`
}

ContractSpec makes provider-agnostic semantics explicit without creating another Worker Type operation registry.

type Manifest 

type Manifest struct {
	APIVersion string   `json:"apiVersion"`
	Kind       string   `json:"kind"`
	Metadata   Metadata `json:"metadata"`
	Spec       Spec     `json:"spec"`
}

Manifest is a versioned declarative Worker Type package description.

func ParseJSON 

func ParseJSON(data []byte) (Manifest, error)

ParseJSON decodes and validates one Worker Type manifest. Unknown fields are rejected so package authors cannot believe Atlas is enforcing metadata it has silently ignored.

func (Manifest) CompatibleWith 

func (m Manifest) CompatibleWith(atlasVersion string) (bool, error)

CompatibleWith reports whether an Atlas semantic version satisfies the manifest's declared compatibility conjunction.

func (Manifest) Validate 

func (m Manifest) Validate() error

Validate checks the static Worker Type package contract without executing any package content or resolving runtime configuration.

type Metadata 

type Metadata struct {
	ID      string `json:"id"`
	Version string `json:"version"`
	Name    string `json:"name"`
}

Metadata is the stable package identity plus presentation name.

type Operation 

type Operation struct {
	ID           string            `json:"id"`
	JobType      string            `json:"jobType"`
	Capabilities []CapabilityClaim `json:"capabilities,omitempty"`
}

Operation is one authorable operation implemented by a declared job type.

type Runtime 

type Runtime struct {
	Mode string `json:"mode"`
}

Runtime declares how the Worker runtime is supplied.

type Spec 

type Spec struct {
	AtlasCompatibility  string      `json:"atlasCompatibility"`
	WorkerProtocol      string      `json:"workerProtocol"`
	Runtime             Runtime     `json:"runtime"`
	JobTypes            []string    `json:"jobTypes"`
	Operations          []Operation `json:"operations"`
	ConfigurationSchema string      `json:"configurationSchema"`
	ModelerTemplate     string      `json:"modelerTemplate"`
	Artifact            *Artifact   `json:"artifact,omitempty"`
}

Spec describes compatibility, authoring metadata and runtime packaging.

type TechnicalContract added in v0.20.0 

type TechnicalContract struct {
	APIVersion string           `json:"apiVersion"`
	Kind       string           `json:"kind"`
	Metadata   ContractMetadata `json:"metadata"`
	Spec       ContractSpec     `json:"spec"`
}

TechnicalContract is a versioned definition of *one* technical capability, never proof that a provider implements it or a permission to route a job. See ADR-0485 and ADR-0480.

func ParseTechnicalContractJSON added in v0.20.0 

func ParseTechnicalContractJSON(raw []byte) (TechnicalContract, error)

ParseTechnicalContractJSON decodes and validates one contract document at design time. Unknown envelope fields and multiple JSON values are refused. Successful parsing does not establish provider or JSON Schema conformance.

func (TechnicalContract) Validate added in v0.20.0 

func (c TechnicalContract) Validate() error

Validate checks an independently versioned technical capability contract. It does not interpret any provider call, perform I/O, or validate every JSON Schema keyword; a separate conformance suite must do that before publication.

type TechnicalSchemaFixture added in v0.20.0 

type TechnicalSchemaFixture struct {
	Name      string          `json:"name"`
	Direction string          `json:"direction"`
	Document  json.RawMessage `json:"document"`
	Valid     bool            `json:"valid"`
}

TechnicalSchemaFixture is a fixture for schema validation only. Valid=false means the document must be rejected by its declared input/output schema; malformed JSON is never a meaningful negative fixture.

type TechnicalSchemaFixtureResult added in v0.20.0 

type TechnicalSchemaFixtureResult struct {
	Name    string `json:"name"`
	Passed  bool   `json:"passed"`
	Message string `json:"message,omitempty"`
}

TechnicalSchemaFixtureResult records whether one offline check met the expected schema outcome, without claiming implementation conformance.

type TechnicalSchemaReport added in v0.20.0 

type TechnicalSchemaReport struct {
	ContractID      string                         `json:"contractId"`
	ContractVersion string                         `json:"contractVersion"`
	Profile         string                         `json:"profile,omitempty"`
	SchemaOnly      bool                           `json:"schemaOnly"`
	Results         []TechnicalSchemaFixtureResult `json:"results"`
}

TechnicalSchemaReport is deliberately schema-only. No verification, publication, package identity, claim approval or routing eligibility is derived from it; these require the separate ADR-0483 review/evidence gates.

func EvaluateTechnicalSchemaFixtures added in v0.20.0 

func EvaluateTechnicalSchemaFixtures(contract TechnicalContract, fixtures []TechnicalSchemaFixture) (TechnicalSchemaReport, error)

EvaluateTechnicalSchemaFixtures checks bounded, well-formed positive and negative input/output cases. A completed report cannot upgrade a Worker Type claim to "verified": that requires independent provider evidence.

func (TechnicalSchemaReport) AllPassed added in v0.20.0 

func (report TechnicalSchemaReport) AllPassed() bool

AllPassed reports whether every executed schema fixture matched its expectation. It is not a provider verification result.

Source Files

View all Source files

Directories

Path Synopsis
Package evidence keeps and checks the evidence that one built-in Worker Type operation conforms to one technical capability contract (ADR-0483).
 Package evidence keeps and checks the evidence that one built-in Worker Type operation conforms to one technical capability contract (ADR-0483).
cmd/evidence command
Command evidence creates, renews and verifies the conformance evidence records of built-in Worker Types, and prints the dependency digest of any set of packages (ADR-0483).
 Command evidence creates, renews and verifies the conformance evidence records of built-in Worker Types, and prints the dependency digest of any set of packages (ADR-0483).
gate
Package gate holds the CI check over the evidence records in workertype/evidence/records and nothing else: its test verifies every record against the module, with every registered suite, so a change that moves what a record binds fails until the same change renews the record (ADR-0483).
 Package gate holds the CI check over the evidence records in workertype/evidence/records and nothing else: its test verifies every record against the module, with every registered suite, so a change that moves what a record binds fails until the same change renews the record (ADR-0483).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.