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

runtimelease

package
v0.55.5 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2026 License: Apache-2.0, Apache-2.0 Imports: 12 Imported by: 0

README

runtimelease

Secret-free contract for the Runtime Lease Authority. Techstack owns the durable lease state; this package defines the wire and local validation. The authority owns lease identity and validity window, caller-owned desired state (running, stopped, absent), cancellation and a monotonic non-zero revision for CAS. Provider execution, observations, cleanup, server lifecycle, Guard, billing, catalog policy and access custody are separate authorities.

Identity

  • server_id: one durable RuntimeServer, unchanged when infrastructure is replaced.
  • resource_generation_id: one replaceable infrastructure generation; non-nil canonical lowercase UUID.
  • tenant_id and owner_id are explicit. Provider/adapter names, native handles, simulation or VM identifiers, provisioning specs, observed state, metadata, credentials and access material are absent.

Validation and enrollment fence both identities plus the exact lease revision.

Wire

No vmlease compatibility package. Validation requests carry tenant_id, owner_id, lease_id, lease_revision, server_id, resource_generation_id. Closed failure reasons: lease_cancelled, lease_not_yet_valid, lease_expired, binding_mismatch, revision_mismatch, invalid_lease. Enrollment requests and acknowledgements repeat the fence; the enrollment idempotency key is not a provider idempotency key.

Snapshots

Signed with the authority's Ed25519 key; the wire fixes runtimelease-snapshot/v1, Ed25519 and a signed key_id. Consumers hold only a rotation-capable public-key set. expires_at is at most five minutes after issuance; optional authority-signed grace_until (max five minutes) is accepted only by VerifySnapshotFallback when FallbackEligible classifies the failure as an outage. An explicit invalid result from the authority never falls back to a cached snapshot. Consumers verify against a public-key resolver, issuer, audience, owner, revision, server and generation. HTTP transport and routing belong to the owning runtime.

The package has no provider SDK, database, durable claim, adapter configuration, private module or product-policy dependency.

Documentation

Overview

Package runtimelease defines the shared runtime-lease wire contract.

Authority

The runtimelease wire is authoritative for stable JSON field names, snapshot signatures, and local validation rules. The owning runtime control plane, Techstack, is authoritative for lease validity, desired state, cancellation, revision issuance, enrollment admission, and durable persistence.

Non-authority

The package does not own provider execution or provider state, adapter selection, provider-native resource identities or handles, cleanup evidence, server lifecycle, health, connection, inventory, billing, catalog, or access policy. A lease's desired state is input to separate reconciliation; it is not an observed provider or Guard state.

Side effects

Lease, enrollment, and snapshot validation are in-memory operations. The package performs no network I/O.

Persistence

This package persists no leases, snapshots, claims, or enrollment state.

Concurrency

Values carry no synchronization or compare-and-swap implementation. Every durable mutation must use the exact non-zero Lease.Revision issued by the owning authority; stale revisions fail rather than merging projections.

Secrets

Lease and enrollment fields are closed and contain no provider references, raw credentials, access material, or caller-defined metadata. Snapshot Ed25519 private signing keys remain inside the lease authority and must never be passed to consumers, persisted with a payload, or logged. Consumers hold only public verification keys selected by the signed key ID.

Index

Constants

View Source 
const (
	// SnapshotVersion is the exact signed runtime-lease snapshot format.
	SnapshotVersion = "runtimelease-snapshot/v1"
	// SnapshotAlgorithm is the only signature algorithm accepted by v1.
	SnapshotAlgorithm = "Ed25519"
	// MaximumSnapshotTTL limits how long a projection can hide a later lease
	// revision or cancellation while its authority is unreachable.
	MaximumSnapshotTTL = 5 * time.Minute
	// MaximumSnapshotGrace bounds authority-signed offline fallback. Authorities
	// may issue a shorter window or no grace at all.
	MaximumSnapshotGrace = 5 * time.Minute
)
View Source 
const (
	ReasonLeaseCancelled   = "lease_cancelled"
	ReasonLeaseNotYetValid = "lease_not_yet_valid"
	ReasonLeaseExpired     = "lease_expired"
	ReasonBindingMismatch  = "binding_mismatch"
	ReasonRevisionMismatch = "revision_mismatch"
	ReasonInvalidLease     = "invalid_lease"
)

Stable validation reason codes returned over the wire.

View Source 
const MaximumWireRevision uint64 = 1<<53 - 1

MaximumWireRevision is the largest exact JSON integer accepted for a lease revision. It is safe in PostgreSQL BIGINT and IEEE-754/JavaScript consumers.

Variables

View Source 
var (
	ErrSnapshotInvalid   = errors.New("runtimelease: invalid snapshot")
	ErrSnapshotExpired   = errors.New("runtimelease: snapshot expired")
	ErrSnapshotSignature = errors.New("runtimelease: snapshot signature invalid")
	ErrSnapshotKey       = errors.New("runtimelease: snapshot key unavailable")
	ErrSnapshotGrace     = errors.New("runtimelease: snapshot grace unavailable")
)

Snapshot validation, key-resolution, and signature errors.

View Source 
var (
	ErrInvalidLease      = errors.New("runtimelease: invalid lease")
	ErrLeaseNotYetValid  = errors.New("runtimelease: lease not yet valid")
	ErrLeaseExpired      = errors.New("runtimelease: lease expired")
	ErrLeaseCancelled    = errors.New("runtimelease: lease cancelled")
	ErrBindingMismatch   = errors.New("runtimelease: runtime binding mismatch")
	ErrRevisionMismatch  = errors.New("runtimelease: lease revision mismatch")
	ErrInvalidEnrollment = errors.New("runtimelease: invalid enrollment")
)

Lease validation errors.

Functions

func FallbackEligible 

func FallbackEligible(err error) bool

FallbackEligible reports whether err is an authority outage for which a caller may separately verify an authority-signed cached snapshot. Explicit invalid results, 4xx responses, malformed responses, and caller cancellation are never eligible. The accepted status codes are 500, 502, 503, and 504.

func ValidationReasonForError 

func ValidationReasonForError(err error) string

ValidationReasonForError maps validation errors to stable wire reason codes.

Types

type AuthorityError 

type AuthorityError struct {
	Operation  string
	Kind       AuthorityErrorKind
	StatusCode int
	Err        error
}

AuthorityError reports a failed authority call. It never contains a response body. StatusCode is set only for AuthorityErrorStatus.

func (*AuthorityError) Error 

func (e *AuthorityError) Error() string

Error returns a secret-free description of the authority failure.

func (*AuthorityError) Unwrap 

func (e *AuthorityError) Unwrap() error

Unwrap exposes the underlying transport or protocol error.

type AuthorityErrorKind 

type AuthorityErrorKind string

AuthorityErrorKind classifies failures reported by a caller-owned Runtime Lease Authority transport without embedding that transport in this package. 

const (
	AuthorityErrorTransport AuthorityErrorKind = "transport"
	AuthorityErrorStatus    AuthorityErrorKind = "status"
	AuthorityErrorProtocol  AuthorityErrorKind = "protocol"
)

Runtime Lease Authority error classes.

type DesiredState 

type DesiredState string

DesiredState is the caller-owned requested runtime state. 

const (
	DesiredStateRunning DesiredState = "running"
	DesiredStateStopped DesiredState = "stopped"
	DesiredStateAbsent  DesiredState = "absent"
)

Supported desired runtime states.

type EnrollmentRequest 

type EnrollmentRequest struct {
	TenantID             string               `json:"tenant_id"`
	OwnerID              string               `json:"owner_id"`
	LeaseID              LeaseID              `json:"lease_id"`
	LeaseRevision        uint64               `json:"lease_revision"`
	ServerID             RuntimeServerID      `json:"server_id"`
	ResourceGenerationID ResourceGenerationID `json:"resource_generation_id"`
	IdempotencyKey       string               `json:"idempotency_key"`
}

EnrollmentRequest binds runtime enrollment to an exact lease revision, durable RuntimeServer, and resource generation. IdempotencyKey is scoped and persisted by the owning authority; it is not a provider idempotency key.

func (EnrollmentRequest) Validate 

func (r EnrollmentRequest) Validate() error

Validate checks that the enrollment request is secret-free and binds one exact lease projection to one exact runtime generation.

type EnrollmentResult 

type EnrollmentResult struct {
	TenantID             string               `json:"tenant_id"`
	OwnerID              string               `json:"owner_id"`
	LeaseID              LeaseID              `json:"lease_id"`
	LeaseRevision        uint64               `json:"lease_revision"`
	ServerID             RuntimeServerID      `json:"server_id"`
	ResourceGenerationID ResourceGenerationID `json:"resource_generation_id"`
}

EnrollmentResult acknowledges the exact identities accepted for runtime enrollment. It is not a provider receipt or an observed-state projection.

func (EnrollmentResult) Validate 

func (r EnrollmentResult) Validate() error

Validate checks that the enrollment result acknowledges one exact runtime binding and lease revision.

type Lease 

type Lease struct {
	ID                   LeaseID              `json:"id"`
	Revision             uint64               `json:"revision"`
	TenantID             string               `json:"tenant_id"`
	OwnerID              string               `json:"owner_id"`
	ServerID             RuntimeServerID      `json:"server_id"`
	ResourceGenerationID ResourceGenerationID `json:"resource_generation_id"`
	DesiredState         DesiredState         `json:"desired_state"`
	ValidFrom            time.Time            `json:"valid_from"`
	ValidUntil           time.Time            `json:"valid_until"`
	RenewedAt            *time.Time           `json:"renewed_at,omitempty"`
	CancelledAt          *time.Time           `json:"cancelled_at,omitempty"`
}

Lease is the secret-free runtime-lease projection. TenantID and OwnerID express ownership; ServerID identifies the durable RuntimeServer; ResourceGenerationID fences the exact replaceable resource generation. Revision is the authority-issued compare-and-swap revision and starts at 1. The projection intentionally carries no provider, inventory, health, connection, cleanup, billing, or provisioning state.

func VerifySnapshot 

func VerifySnapshot(snapshot Snapshot, resolver SnapshotKeyResolver, expected SnapshotBinding, now time.Time) (*Lease, error)

VerifySnapshot verifies a snapshot for one exact expected binding and rejects it at ExpiresAt.

func VerifySnapshotFallback 

func VerifySnapshotFallback(snapshot Snapshot, resolver SnapshotKeyResolver, expected SnapshotBinding, now time.Time, authorityErr error) (*Lease, error)

VerifySnapshotFallback verifies a snapshot against its signed, bounded GraceUntil only after FallbackEligible classifies the live authority failure as an outage. A caller cannot turn an authoritative rejection into offline grace by invoking snapshot verification directly.

func (Lease) ActiveAt 

func (l Lease) ActiveAt(now time.Time) bool

ActiveAt reports whether the lease is valid and has entered its validity window.

func (Lease) Validate 

func (l Lease) Validate(now time.Time) error

Validate checks the lease contract and its authority-owned validity at now.

type LeaseID 

type LeaseID string

LeaseID is an opaque, stable runtime-lease identifier.

type ResolveQuery 

type ResolveQuery struct {
	TenantID string  `json:"tenant_id"`
	OwnerID  string  `json:"owner_id"`
	LeaseID  LeaseID `json:"lease_id"`
}

ResolveQuery selects one lease within an exact tenant and responsible owner.

func (ResolveQuery) Validate 

func (q ResolveQuery) Validate() error

Validate checks that the query names one lease in one tenant.

type Resolver 

type Resolver interface {
	Resolve(ctx context.Context, query ResolveQuery) (*Lease, error)
	Validate(ctx context.Context, check ValidationCheck) (*ValidationResult, error)
}

Resolver resolves and validates leases through their owning authority.

type ResourceGenerationID 

type ResourceGenerationID string

ResourceGenerationID is the canonical lowercase UUID of one exact, replaceable resource generation bound to a RuntimeServer.

type RuntimeServerID 

type RuntimeServerID string

RuntimeServerID is the opaque identity of a durable RuntimeServer aggregate. It remains stable when the bound provider resource is replaced.

type Snapshot 

type Snapshot struct {
	Version    string     `json:"version"`
	Algorithm  string     `json:"algorithm"`
	KeyID      string     `json:"key_id"`
	Issuer     string     `json:"issuer"`
	Audience   string     `json:"audience"`
	Lease      Lease      `json:"lease"`
	IssuedAt   time.Time  `json:"issued_at"`
	ExpiresAt  time.Time  `json:"expires_at"`
	GraceUntil *time.Time `json:"grace_until,omitempty"`
	Signature  string     `json:"signature"`
}

Snapshot is a versioned, audience-bound, asymmetrically signed lease projection. GraceUntil is authority-issued and may extend ExpiresAt by at most MaximumSnapshotGrace; consumers cannot choose their own grace.

func SignSnapshot 

func SignSnapshot(snapshot Snapshot, keyID string, privateKey ed25519.PrivateKey) (Snapshot, error)

SignSnapshot seals one canonical snapshot with an authority-owned Ed25519 private key. The key ID, issuer, audience, and complete runtime binding are signed; private signing material never leaves the lease authority.

type SnapshotBinding 

type SnapshotBinding struct {
	Issuer               string
	Audience             string
	TenantID             string
	OwnerID              string
	LeaseID              LeaseID
	LeaseRevision        uint64
	ServerID             RuntimeServerID
	ResourceGenerationID ResourceGenerationID
}

SnapshotBinding is the exact authority, consumer, and runtime identity a caller expects before it may use a verified snapshot.

func (SnapshotBinding) Validate 

func (binding SnapshotBinding) Validate() error

Validate rejects an incomplete expected snapshot binding.

type SnapshotKeyResolver 

type SnapshotKeyResolver interface {
	ResolveSnapshotVerificationKey(keyID string) (SnapshotVerificationKey, error)
}

SnapshotKeyResolver resolves a public verification key by signed key ID. Implementations must be concurrency-safe and return an independent key copy.

type SnapshotKeySet 

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

SnapshotKeySet is an immutable, concurrency-safe in-memory key resolver. Rotation constructs a new key set and atomically swaps the owning pointer; callers cannot mutate the set's private map or stored key bytes.

func NewSnapshotKeySet 

func NewSnapshotKeySet(keys []SnapshotVerificationKey) (*SnapshotKeySet, error)

NewSnapshotKeySet validates and copies one or more authority verification keys. Duplicate key IDs are rejected.

func (*SnapshotKeySet) ResolveSnapshotVerificationKey 

func (set *SnapshotKeySet) ResolveSnapshotVerificationKey(keyID string) (SnapshotVerificationKey, error)

ResolveSnapshotVerificationKey returns an independent copy of one key.

type SnapshotVerificationKey 

type SnapshotVerificationKey struct {
	KeyID     string
	Issuer    string
	PublicKey ed25519.PublicKey
	NotBefore time.Time
	NotAfter  time.Time
	Revoked   bool
}

SnapshotVerificationKey is one immutable authority verification-key record. NotBefore and NotAfter bound signing time; Revoked keys fail closed even for otherwise valid snapshots.

type ValidationCheck 

type ValidationCheck struct {
	TenantID             string               `json:"tenant_id"`
	OwnerID              string               `json:"owner_id"`
	LeaseID              LeaseID              `json:"lease_id"`
	LeaseRevision        uint64               `json:"lease_revision"`
	ServerID             RuntimeServerID      `json:"server_id"`
	ResourceGenerationID ResourceGenerationID `json:"resource_generation_id"`
}

ValidationCheck requests validation of an exact owner, lease revision, and runtime binding. It cannot ask the lease authority to validate provider state.

func (ValidationCheck) Validate 

func (c ValidationCheck) Validate() error

Validate checks that the request fences one exact lease projection and runtime binding.

type ValidationResult 

type ValidationResult struct {
	Valid    bool      `json:"valid"`
	Lease    *Lease    `json:"lease,omitempty"`
	Snapshot *Snapshot `json:"snapshot,omitempty"`
	Reason   string    `json:"reason,omitempty"`
}

ValidationResult reports the lease authority's validity decision. It does not report provider, cleanup, connection, health, or inventory state.

Source Files

View all Source files

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.