protocol

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Oct 4, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package protocol validates the versioned wire contract before domain state is mutated.

Package protocol defines message validation, compatibility, and the protocol-level domain vocabulary shared by the client, the allocator, and the local API. Everything here is transport-independent core.

Index

Constants

View Source
const (
	MaxCapabilityKeyLen     = 64
	MaxCapabilityValueLen   = 128
	MaxCapabilityLabels     = 8
	MaxCapabilityDevices    = 8
	MaxCapabilityProfiles   = 16
	MaxCapabilityCache      = 16
	MaxCapabilityCacheImage = 256
)

Bounds for node capability metadata. Every value is deliberately small so a node advertisement always fits the RNS announce app-data budget (255 bytes) and a client request stays within the command envelope size. Capability identity strings are lowercase ASCII; anything else is rejected by Validate.

View Source
const DefaultLease = 10 * time.Minute

DefaultLease is the default duration of the client-held execution lease. The allocator grants it at assignment, a bare keep-alive renewal re-records it, and the `--lease` flag defaults to it, so the three sites cannot drift apart.

View Source
const LeaseExpiredDetail = "execution lease expired"

LeaseExpiredDetail is the stable terminal-state detail that marks an execution evicted because its client-held lease expired without renewal. It is deliberately distinct from any client-supplied cancellation reason so clients can tell lease loss from cancellation and, for example, re-request lost work.

View Source
const MaxLogBytes = 64 << 10

MaxLogBytes bounds one log read or response chunk. It must stay well under the envelope/message memory limits so a single request cannot force the allocator to buffer or a client to receive an unbounded payload. 64 KiB is a deliberate implementation choice inside F22's 16–64 KiB range: large enough that tailing does not drown in round trips, small enough to preserve the bounded-memory invariant.

Variables

View Source
var ErrInvalidEnvelope = errors.New("invalid envelope")
View Source
var ErrorCodes = map[string]bool{
	"INVALID_REQUEST": true, "CAPACITY": true, "NOT_FOUND": true,
	"CONFLICT": true, "EXPIRED": true, "UNAVAILABLE": true, "DENIED": true,
	"INTERNAL": true, "OUTCOME_UNKNOWN": true, "INCOMPATIBLE": true,
}

Functions

func CapabilitiesEqual added in v0.3.1

func CapabilitiesEqual(left, right *r1sv1.NodeCapabilities) bool

CapabilitiesEqual reports deep equality of two capability sets. It is used by the client to detect a changed advertisement and by tests.

func Contains added in v0.3.1

func Contains(values []string, target string) bool

Contains reports whether values holds target. It is the small set-membership helper for bounded capability lists, shared by the allocator.

func PlacementCompatible added in v0.3.1

func PlacementCompatible(constraints *r1sv1.PlacementConstraints, node *r1sv1.NodeCapabilities) bool

PlacementCompatible is the advisory companion to PlacementMatches, used by the client when deciding whether to send a request to a discovered allocator. A nil node is "unknown", not "incompatible": an allocator that advertises no capabilities is still tried, and its local admission is the authority. Only a node with positive evidence of mismatch is skipped. Empty constraints always match.

func PlacementConflictDetails added in v0.3.1

func PlacementConflictDetails(constraints *r1sv1.PlacementConstraints, node *r1sv1.NodeCapabilities) string

PlacementConflictDetails describes why a node does not satisfy constraints, for the explicit INCOMPATIBLE rejection detail. It must never contain workload output or secrets.

func PlacementMatches added in v0.3.1

func PlacementMatches(constraints *r1sv1.PlacementConstraints, node *r1sv1.NodeCapabilities) bool

func TargetsToProto added in v0.3.1

func TargetsToProto(targets []tunnel.Target) []*r1sv1.TunnelTarget

TargetsToProto converts a list of internal tunnel targets (container ports) to the protobuf representation. It is used by the client to populate the grant request and by the allocator to echo the port list in the grant ack.

func Terminal added in v0.4.0

func Terminal(phase r1sv1.ExecutionPhase) bool

Terminal reports whether an execution phase ends the execution's lifetime: no further lease renewals, no further commands, and retained metadata only.

func ValidateCapabilities added in v0.3.1

func ValidateCapabilities(node *r1sv1.NodeCapabilities) error

ValidateCapabilities bounds node capability metadata. It is applied by the allocator when it builds its advertisement and by the transport when it parses a descriptor; a malformed or oversized advertisement is rejected rather than trusted.

func ValidateConstraints added in v0.3.1

func ValidateConstraints(constraints *r1sv1.PlacementConstraints) error

ValidateConstraints bounds and normalizes placement constraints. Constraints travel in client requests, so they are bounded against the same budget as capabilities: they can only ask for a subset of what a node may declare.

func ValidateEnvelope

func ValidateEnvelope(envelope *r1sv1.Envelope) error

ValidateEnvelope validates required metadata and the complete active payload.

func ValidateTunnelTargets added in v0.3.1

func ValidateTunnelTargets(protoTargets []*r1sv1.TunnelTarget) ([]tunnel.Target, error)

ValidateTunnelTargets validates a client-supplied container port list and converts it to the internal tunnel.Target representation. Each target must name a positive container port in [1, 65535]; a zero or out-of-range port is invalid. At least one target is required. There are no named slots: each target is just the container port to export, resolved on the allocator loopback.

Types

type ValidationError

type ValidationError struct {
	Field   string
	Problem string
}

ValidationError identifies a field that violates the wire contract.

func (*ValidationError) Error

func (e *ValidationError) Error() string

func (*ValidationError) Unwrap

func (e *ValidationError) Unwrap() error

Jump to

Keyboard shortcuts

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