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
- Variables
- func CapabilitiesEqual(left, right *r1sv1.NodeCapabilities) bool
- func Contains(values []string, target string) bool
- func PlacementCompatible(constraints *r1sv1.PlacementConstraints, node *r1sv1.NodeCapabilities) bool
- func PlacementConflictDetails(constraints *r1sv1.PlacementConstraints, node *r1sv1.NodeCapabilities) string
- func PlacementMatches(constraints *r1sv1.PlacementConstraints, node *r1sv1.NodeCapabilities) bool
- func TargetsToProto(targets []tunnel.Target) []*r1sv1.TunnelTarget
- func Terminal(phase r1sv1.ExecutionPhase) bool
- func ValidateCapabilities(node *r1sv1.NodeCapabilities) error
- func ValidateConstraints(constraints *r1sv1.PlacementConstraints) error
- func ValidateEnvelope(envelope *r1sv1.Envelope) error
- func ValidateTunnelTargets(protoTargets []*r1sv1.TunnelTarget) ([]tunnel.Target, error)
- type ValidationError
Constants ¶
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.
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.
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.
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 ¶
var ErrInvalidEnvelope = errors.New("invalid envelope")
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
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 ¶
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 ¶
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