wire

package
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: Oct 9, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package wire declares Racer's HTTPS/JSON contracts. Codecs validate bounded inputs before returning usable protocol state.

Index

Constants

View Source 
const (
	SchemaVersion          = 1
	BootstrapPath          = "/v1/bootstrap"
	SnapshotPath           = "/v1/snapshot"
	KeyringPath            = "/v1/keyring"
	TokenAudience          = "racer-control"
	MaxBootstrapBytes      = 64 * 1024
	MaxBundleBytes         = 512 * 1024
	MaxPublicationBytes    = 64 * 1024 * 1024
	MaxMembers             = 100_000
	PollWait               = 30 * time.Second
	CertificateLifetime    = 24 * time.Hour
	DefaultShares          = 4
	SharesAnnotation       = "racer.unbounded-cloud.io/shares"
	BlockDevicesAnnotation = "racer.unbounded-cloud.io/block-devices"
	RDMANICsAnnotation     = "racer.unbounded-cloud.io/rdma-nics"
	MaxRDMANICs            = 64
	ExclusionLabel         = "racer.unbounded-cloud.io/exclude"
)
View Source 
const (
	PageKey              KeyPurpose = "page"
	OriginCredentialsKey KeyPurpose = "origin_credentials"
	PreparedKey          KeyState   = "prepared"
	ActiveKey            KeyState   = "active"
)
View Source 
const (
	DeltaHeader   = "X-Racer-Delta-Base"
	MaxDeltaBytes = 4 * 1024 * 1024
)

Variables

This section is empty.

Functions

func CanonicalSocketPaths 

func CanonicalSocketPaths(name string) (client, origin string, err error)

CanonicalSocketPaths returns Linux pathname sockets including room for NUL in sockaddr_un.sun_path (108 bytes). Names are ASCII Kubernetes DNS subdomains.

func ContentHashes 

func ContentHashes(v Publication) (content, membership string, err error)

ContentHashes returns lowercase SHA-256 hex, suitable for VersionRecord fields.

func EncodeBootstrap 

func EncodeBootstrap(v BootstrapResponse) ([]byte, error)

func EncodeBootstrapRequest 

func EncodeBootstrapRequest(v BootstrapRequest) ([]byte, error)

func EncodeBundle 

func EncodeBundle(v KeyringBundle) ([]byte, error)

func EncodeDelta 

func EncodeDelta(base, next Publication) ([]byte, error)

func EncodeError 

func EncodeError(v ErrorResponse) ([]byte, error)

func EncodePublication 

func EncodePublication(v Publication) ([]byte, error)

EncodePublication sorts copies of the input collections, never caller state.

func ValidUUID 

func ValidUUID(s string) bool

ValidUUID checks canonical Kubernetes identities before constructing wire state.

func ValidateBootstrapRequest 

func ValidateBootstrapRequest(v BootstrapRequest) error

ValidateBootstrapRequest checks the wire fields, CSR syntax, and full encoded size without serializing. Proof of possession and identity binding belong to the issuer. Direct callers have the same size bound as EncodeBootstrapRequest.

Types

type BootstrapRequest 

type BootstrapRequest struct {
	Shares        uint32       `json:"shares"`
	RDMANICs      []RDMANIC    `json:"rdma_nics"`
	SchemaVersion uint32       `json:"schema_version"`
	Cluster       ClusterID    `json:"cluster"`
	Enrollment    EnrollmentID `json:"enrollment"`
	CSRDER        []byte       `json:"csr_der"`
}

BootstrapRequest contains no bearer token. The transport reads the projected token for each issuance attempt and supplies it in Authorization.

func DecodeBootstrap 

func DecodeBootstrap(r io.Reader) (BootstrapRequest, error)

DecodeBootstrap bounds the entire document before allocating decoded state.

type BootstrapResponse 

type BootstrapResponse struct {
	SchemaVersion    uint32       `json:"schema_version"`
	Cluster          ClusterID    `json:"cluster"`
	Node             NodeID       `json:"node"`
	Enrollment       EnrollmentID `json:"enrollment"`
	CertificateChain [][]byte     `json:"certificate_chain"`
	BlockDevices     string       `json:"block_devices,omitempty"`
}

func DecodeBootstrapResponse 

func DecodeBootstrapResponse(r io.Reader) (BootstrapResponse, error)

type CacheDefinition 

type CacheDefinition struct {
	ID           CacheID `json:"id"`
	Name         string  `json:"name"`
	ClientSocket string  `json:"client_socket"`
	OriginSocket string  `json:"origin_socket"`
}

type CacheID 

type CacheID string

type CacheKey 

type CacheKey struct {
	Key   CacheKeyRef
	State KeyState
	// contains filtered or unexported fields
}

CacheKey intentionally hides material from ordinary formatting and JSON. Only the bounded bundle codec may access and encode the 32-byte material.

func NewCacheKey 

func NewCacheKey(ref CacheKeyRef, state KeyState, material [32]byte) (CacheKey, error)

NewCacheKey is the only material ingress besides bounded bundle decoding.

func (CacheKey) EqualMaterial 

func (k CacheKey) EqualMaterial(other CacheKey) bool

EqualMaterial compares private key bytes without exposing them to consumers. It is intended for bundle replay validation, not authentication.

func (CacheKey) GoString 

func (CacheKey) GoString() string

func (CacheKey) String 

func (CacheKey) String() string

type CacheKeyRef 

type CacheKeyRef struct {
	Cache   CacheID    `json:"cache"`
	ID      []byte     `json:"id"` // Exactly 16 bytes, padded standard base64 on the wire.
	Purpose KeyPurpose `json:"purpose"`
}

type CanonicalCandidate 

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

CanonicalCandidate owns validated, sorted publication content, including nested pointers. Its private state can be reused for hashing and encoding after counter assignment without retaining caller-owned mutable state. The zero value is invalid.

func NewCanonicalCandidate 

func NewCanonicalCandidate(v Publication) (CanonicalCandidate, error)

NewCanonicalCandidate validates and copies content once. Input counters are ignored; final encoding checks the assigned counters and complete byte bound.

func (CanonicalCandidate) ContentHashes 

func (c CanonicalCandidate) ContentHashes() (content, membership string, err error)

ContentHashes returns the same counter-free hashes as ContentHashes without repeating validation, copying, or sorting of the candidate's collections.

func (CanonicalCandidate) EncodePublication 

func (c CanonicalCandidate) EncodePublication(sequence Sequence, membership MembershipVersion) ([]byte, error)

EncodePublication encodes the candidate with nonzero counters. It does not mutate the candidate, and each call returns independently owned bytes.

type ClusterID 

type ClusterID string

type Delta 

type Delta struct {
	DeltaVersion      uint32            `json:"delta_version"`
	Cluster           ClusterID         `json:"cluster"`
	BaseSequence      Sequence          `json:"base_sequence,string"`
	BaseHash          string            `json:"base_hash"`
	Sequence          Sequence          `json:"sequence,string"`
	MembershipVersion MembershipVersion `json:"membership_version,string"`
	ContentHash       string            `json:"content_hash"`
	UpsertMembers     []Member          `json:"upsert_members"`
	RemoveMembers     []NodeID          `json:"remove_members"`
	Caches            []CacheDefinition `json:"caches"`
}

Delta is transported only on the authenticated snapshot endpoint. Hashes use ContentHashes, not a second canonical representation or placement authority.

type EnrollmentID 

type EnrollmentID string

type ErrorCode 

type ErrorCode string
const (
	InvalidRequest     ErrorCode = "invalid_request"
	Unauthenticated    ErrorCode = "unauthenticated"
	Forbidden          ErrorCode = "forbidden"
	Conflict           ErrorCode = "conflict"
	TooLarge           ErrorCode = "too_large"
	UnsupportedVersion ErrorCode = "unsupported_version"
	Overloaded         ErrorCode = "overloaded"
	Unavailable        ErrorCode = "unavailable"
)

func (ErrorCode) Error 

func (c ErrorCode) Error() string

Error returns only a protocol code, never input or secret material.

type ErrorResponse 

type ErrorResponse struct {
	Code ErrorCode `json:"code"`
}

func DecodeError 

func DecodeError(r io.Reader) (ErrorResponse, error)

type Generation 

type Generation uint64

type KeyPurpose 

type KeyPurpose string

type KeyState 

type KeyState string

type KeyringBundle 

type KeyringBundle struct {
	SchemaVersion  uint32
	Cluster        ClusterID
	Generation     Generation
	PeerTrustRoots [][]byte
	CacheKeys      []CacheKey
}

func DecodeBundle 

func DecodeBundle(r io.Reader) (KeyringBundle, error)

func (KeyringBundle) MarshalJSON 

func (b KeyringBundle) MarshalJSON() ([]byte, error)

MarshalJSON prevents bypassing validation through the standard JSON encoder.

type Member 

type Member struct {
	Node         NodeID    `json:"node"`
	Shares       uint32    `json:"shares"`
	PeerEndpoint string    `json:"peer_endpoint"`
	RDMANICs     []RDMANIC `json:"rdma_nics"`
	// Site is the RDMA boundary. Empty means HTTP-only, not a shared default site.
	Site string `json:"site"`
}

func DecodeAdmittedMember 

func DecodeAdmittedMember(r io.Reader) (Member, error)

DecodeAdmittedMember validates current restart hints with the strict wire shape, including required arrays and rejection of duplicate fields.

type MembershipVersion 

type MembershipVersion uint64

type NodeID 

type NodeID string

type Publication 

type Publication struct {
	SchemaVersion     uint32            `json:"schema_version"`
	Cluster           ClusterID         `json:"cluster"`
	Sequence          Sequence          `json:"sequence,string"`
	MembershipVersion MembershipVersion `json:"membership_version,string"`
	Members           []Member          `json:"members"`
	Caches            []CacheDefinition `json:"caches"`
}

func ApplyDelta 

func ApplyDelta(base Publication, reader io.Reader) (Publication, error)

func DecodePublication 

func DecodePublication(r io.Reader) (Publication, error)

type RDMANIC 

type RDMANIC struct {
	Device   string  `json:"device"`
	Port     uint8   `json:"port"`
	Rail     uint16  `json:"rail"`
	GID      string  `json:"gid,omitempty"`
	NUMANode *uint32 `json:"numa_node,omitempty"`
}

func CanonicalRDMANICs 

func CanonicalRDMANICs(nics []RDMANIC) []RDMANIC

CanonicalRDMANICs copies NICs, including nested pointers, in rail/device/port order.

func DecodeRDMANICs 

func DecodeRDMANICs(r io.Reader) ([]RDMANIC, error)

DecodeRDMANICs strictly decodes a bounded NIC annotation and canonicalizes it.

type Sequence 

type Sequence uint64

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.