Documentation
¶
Overview ¶
Package proxywire defines the wire format exchanged between haloyd (the control plane) and haloy-proxy (the data plane): a JSON routing snapshot pushed over the proxy control socket and persisted as an atomic snapshot file so the proxy can boot with last-known-good routes while haloyd is down.
Versioning policy: additive optional fields do NOT bump SchemaVersion (unknown JSON fields are ignored by older proxies). Semantics-breaking changes bump SchemaVersion; the proxy rejects snapshots with a newer schema than it supports. When a schema bump ships, upgrade haloy-proxy before haloyd.
Index ¶
Constants ¶
const ( // SchemaVersion is the highest snapshot schema version this build understands. SchemaVersion = 1 // ProxyGeneration is the minimum proxy rollout generation required by this // build of haloyd. Bump it when a proxy change must be deployed even though // the snapshot schema is unchanged (for example, an important bug or // security fix). Ordinary haloyd releases leave it unchanged so a compatible // proxy can keep serving traffic without a restart. ProxyGeneration = 1 // LegacyProxyGeneration is assigned to split-proxy builds released before // generation metadata was added. LegacyProxyGeneration = 1 )
Variables ¶
var ErrSchemaTooNew = errors.New("snapshot schema version is newer than supported")
ErrSchemaTooNew indicates a snapshot with a schema version newer than this build supports. The receiver should keep its current config and ask the operator to upgrade haloy-proxy.
Functions ¶
func IsProxyCompatible ¶
IsProxyCompatible reports whether a proxy can satisfy this haloyd build.
func NormalizeProxyGeneration ¶
NormalizeProxyGeneration maps missing generation metadata from legacy proxies to the initial generation.
func WriteSnapshotFile ¶
WriteSnapshotFile atomically writes the snapshot as JSON to path using the same tmp+rename pattern as certificate storage, so a concurrent reader sees either the old or the new snapshot, never a partial write.
Types ¶
type Route ¶
type Route struct {
Canonical string `json:"canonical"`
Aliases []string `json:"aliases,omitempty"`
Backends []Backend `json:"backends,omitempty"`
}
Route maps a canonical domain (plus aliases) to its backends. A route with no backends is valid: the proxy serves 502 instead of 404 for it.
type Snapshot ¶
type Snapshot struct {
SchemaVersion int `json:"schema_version"`
GeneratedAt time.Time `json:"generated_at,omitzero"`
APIDomain string `json:"api_domain,omitempty"`
// APIBackend is haloyd's loopback API listener; the proxy forwards
// API-domain and localhost API traffic to it.
APIBackend *Backend `json:"api_backend,omitempty"`
Routes []Route `json:"routes"`
}
Snapshot is a complete routing configuration for the proxy.
func ReadSnapshotFile ¶
ReadSnapshotFile reads and decodes a snapshot written by WriteSnapshotFile. A missing file is returned as-is so callers can detect it with errors.Is(err, os.ErrNotExist) and treat it as a fresh install.
func (*Snapshot) CheckSchemaVersion ¶
CheckSchemaVersion returns ErrSchemaTooNew if the snapshot was produced by a newer haloyd than this build understands.
type Status ¶
type Status struct {
// Version is the haloy-proxy build version.
Version string `json:"version"`
// Generation controls required proxy rollouts that do not change the wire schema.
Generation int `json:"generation"`
// SchemaVersion is the highest snapshot schema the proxy supports.
SchemaVersion int `json:"schema_version"`
// ConfigHash is the Hash() of the currently applied snapshot.
ConfigHash string `json:"config_hash,omitempty"`
// Routes is the number of canonical domains currently routed.
Routes int `json:"routes"`
// LoadedFrom reports where the current config came from:
// "socket", "snapshot-file" or "empty".
LoadedFrom string `json:"loaded_from"`
// LastUpdateAt is when the config was last applied.
LastUpdateAt time.Time `json:"last_update_at,omitzero"`
// CertsLoaded is the number of TLS certificates in the proxy's cache.
CertsLoaded int `json:"certs_loaded"`
}
Status is the payload of the proxy control API's status endpoint.
Source Files