workertype

package
v0.25.0 Latest Latest
Warning

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

 Go to latest Published: Nov 9, 2026 License: AGPL-3.0 Imports: 13 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 (
	// IdempotencyNatural: a second delivery is harmless by nature.
	IdempotencyNatural = "natural"
	// IdempotencyKey: the target filters duplicates by the job's idempotencyKey.
	IdempotencyKey = "key"
	// IdempotencyCheck: the worker checks before acting whether it already happened.
	IdempotencyCheck = "check"
	// IdempotencyNone: a second delivery can repeat the effect.
	IdempotencyNone = "none"
)

How an operation behaves when one of its jobs is delivered a second time.

View Source 
const (
	// EffectReversible: a repeated effect can be undone or is tolerable.
	EffectReversible = "reversible"
	// EffectIrreversible: a repeated effect cannot be undone.
	EffectIrreversible = "irreversible"
)

What a repeated effect means.

View Source 
const MaxConfigurationSchemaBytes = 64 << 10

MaxConfigurationSchemaBytes bounds an inline configuration schema.

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 MediaTypeExecutable = "application/vnd.atlas.worker.executable"

MediaTypeExecutable is the media type of a native executable artifact: one binary for one platform, launched as a process (ADR-0535 §1).

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 CheckIdentity added in v0.25.0 

func CheckIdentity(id, version, digest string) error

CheckIdentity validates the Worker Type identity a Worker Instance reports in the protocol handshake (ADR-0535 §3): the same stable id and semantic version a manifest declares, and, when the instance knows it, the sha256 digest of the artifact it runs. An empty digest is allowed — a Worker Instance an operator runs by hand may not know its own — and an empty id with nothing else is "no identity reported", which the caller decides on before calling this.

It checks shape only. Whether the reported digest is the one atlas installed is the supervisor's question, not this function's.

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 ConfigurationSchema added in v0.25.0 

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

ConfigurationSchema is a Worker Type's configuration contract (ADR-0535 §4): the JSON Schema a configured Worker's settings must satisfy, inline in the manifest under spec.configuration. A top-level property marked "writeOnly": true is a secret: a configured Worker names a vault entry for it and never holds its value, and only the launched instance receives the value.

func CompileConfiguration added in v0.25.0 

func CompileConfiguration(raw json.RawMessage) (*ConfigurationSchema, error)

CompileConfiguration compiles a configuration schema offline: no reference may reach outside the document.

func (*ConfigurationSchema) IsSecret added in v0.25.0 

func (c *ConfigurationSchema) IsSecret(name string) bool

IsSecret reports whether name is one of the schema's secret properties.

func (*ConfigurationSchema) Secrets added in v0.25.0 

func (c *ConfigurationSchema) Secrets() []string

Secrets are the top-level properties the schema marks writeOnly, sorted.

func (*ConfigurationSchema) Validate added in v0.25.0 

func (c *ConfigurationSchema) Validate(config map[string]any) error

Validate checks a complete configuration — secrets included — against the schema.

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) ArtifactFor added in v0.25.0 

func (m Manifest) ArtifactFor(platform string) (Artifact, bool)

ArtifactFor returns the artifact the manifest declares for platform ("os/arch").

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) Configuration added in v0.25.0 

func (m Manifest) Configuration() (*ConfigurationSchema, error)

Configuration compiles the manifest's inline configuration schema. A manifest without one has no configuration: nil, nil.

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"`
	// Idempotency and Effect say what a second delivery of one of its jobs does
	// (ADR-0538): both are required, so the
	// property is never assumed silently.
	Idempotency string `json:"idempotency"`
	Effect      string `json:"effect"`
}

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

func (Operation) DuplicateRisk added in v0.25.0 

func (op Operation) DuplicateRisk() string

DuplicateRisk grades what a second delivery of op can do: "" for none, "notice" for a tolerable repeat, "warning" for an irreversible one, as ADR-0538 §3 grades it.

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"`
	// Configuration is the configuration contract inline, as a JSON Schema object
	// whose writeOnly top-level properties are secrets (ADR-0535 §4). An installed
	// artifact carries no other file, so this is where its schema travels.
	Configuration   json.RawMessage `json:"configuration,omitempty"`
	ModelerTemplate string          `json:"modelerTemplate"`
	Artifact        *Artifact       `json:"artifact,omitempty"`
	// Artifacts are the runtime's executables, one per platform (ADR-0535 §1). A
	// manifest names either Artifact (one platform) or Artifacts, not both.
	Artifacts []Artifact `json:"artifacts,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).
Package install keeps the Worker Type artifacts installed on this server: a content-addressed store under the data directory, from which the supervisor launches a Worker Type's executable after verifying it again (ADR-0535 §2, migration step 3).
 Package install keeps the Worker Type artifacts installed on this server: a content-addressed store under the data directory, from which the supervisor launches a Worker Type's executable after verifying it again (ADR-0535 §2, migration step 3).

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.