Documentation
¶
Overview ¶
Package bindings resolves Runtime Interface endpoints and the transport policy that guards them. Runtime bindings decouple mutable deployment endpoints from immutable AgentVersions. A manifest's remote-class entrypoint is a logical reference (fenced-binding://agent-name/remote); operators map version refs or agent names to concrete Runtime Interface endpoints in a binding file, so promoting one AgentVersion digest across dev/staging/prod or across regions never requires re-signing or re-publishing it.
The loader is also a security boundary (P0-02): every endpoint is validated against the EndpointPolicy before the process starts serving. Plaintext HTTP is tolerated only on loopback (a co-located runtime); a remote runtime must be HTTPS whose server certificate is verified - optionally pinned to a private CA and a client certificate (mTLS) declared on the binding. Binding files are mutable deployment state, so rotating a certificate never republishes the AgentVersion.
Index ¶
Constants ¶
const BindingScheme = "fenced-binding://"
BindingScheme is the URI scheme of a logical (environment-independent) runtime entrypoint embedded in an immutable AgentVersion.
Variables ¶
This section is empty.
Functions ¶
func IsLogicalEntrypoint ¶
IsLogicalEntrypoint reports whether a manifest entrypoint is a logical binding reference that must be resolved through runtime bindings (as opposed to an environment-embedded concrete URL).
func IsLoopbackHost ¶
IsLoopbackHost reports whether a URL hostname (no port) is a loopback address: the literal "localhost" or a loopback IP.
func ValidateEndpointOverride ¶
func ValidateEndpointOverride(endpoint string, bindings *RuntimeBindings, dedicated bool) error
ValidateEndpointOverride guards the explicit worker endpoint against routing every assignment of a multi-version (shared) worker to one endpoint: an explicit endpoint plus runtime bindings is a dedicated-worker configuration that must be acknowledged as such.
Types ¶
type BindingTLS ¶
type BindingTLS struct {
// CAFile is the PEM trust bundle used to verify the runtime's server
// certificate. Empty means the system roots.
CAFile string `json:"caFile,omitempty"`
// CertFile and KeyFile are the client certificate pair presented to the
// runtime (mutual TLS). Both must be set together.
CertFile string `json:"certFile,omitempty"`
KeyFile string `json:"keyFile,omitempty"`
}
BindingTLS names the certificate files of one binding endpoint.
func (*BindingTLS) Load ¶
func (t *BindingTLS) Load() (*tls.Config, string, error)
load reads the binding's certificate material into a TLS configuration and derives the stable identity fingerprint of that material: the trust bundle bytes plus every client-certificate DER, hashed. Rotating either side changes the fingerprint, which is what keeps the worker's HTTP client cache from reusing one identity's transport for another. Load reads the TLS material of the binding and returns the client configuration and the fingerprint of the material.
type EndpointPolicy ¶
type EndpointPolicy struct {
// AllowPlaintextRemote explicitly opts a development deployment into
// plaintext HTTP to non-loopback runtimes. It must stay false in
// production: a plaintext remote endpoint exposes the Runtime Interface
// (workload, identity, results) to interception and spoofing.
AllowPlaintextRemote bool
}
EndpointPolicy is the transport-security boundary for Runtime Interface endpoints. The zero value is the production policy: plaintext HTTP is allowed only on loopback; remote endpoints must be HTTPS. The structural rules are shared with the runtime client (agent.ValidateBaseURL), so an endpoint rejected by the client is rejected at load time.
func (EndpointPolicy) Validate ¶
func (p EndpointPolicy) Validate(endpoint string) error
Validate checks one endpoint against the policy.
type RuntimeBinding ¶
type RuntimeBinding struct {
AgentVersionRef string `json:"agentVersionRef"`
Endpoint string `json:"endpoint"`
// TLSServerName pins the TLS SNI/verification name when it differs from
// the endpoint host (for example a SPIFFE-identified runtime behind a
// load balancer).
TLSServerName string `json:"tlsServerName,omitempty"`
// RuntimePool and RuntimeClass bind the endpoint to the scheduler's pool
// identity; Region and Weight are routing hints. They are metadata for
// operators and audit - scheduling still flows through the kernel.
RuntimePool string `json:"runtimePool,omitempty"`
RuntimeClass string `json:"runtimeClass,omitempty"`
Region string `json:"region,omitempty"`
Weight int `json:"weight,omitempty"`
// TLS optionally loads certificate material for this endpoint's client:
// a private trust bundle (server verification), and a client certificate
// pair (mutual TLS). Paths are read once at load.
TLS *BindingTLS `json:"tls,omitempty"`
}
RuntimeBinding maps one agent version reference - or every version of one agent name via the "name@*" wildcard - to a concrete Runtime Interface endpoint plus optional deployment metadata.
type RuntimeBindings ¶
type RuntimeBindings struct {
// Policy is the endpoint policy the table was loaded under. A worker
// that resolves an endpoint from this table validates it against the
// same policy, so one table has one rule.
Policy EndpointPolicy
// contains filtered or unexported fields
}
RuntimeBindings is the resolved, immutable view of a binding file.
func LoadRuntimeBindings ¶
func LoadRuntimeBindings(path string) (*RuntimeBindings, error)
LoadRuntimeBindings reads a binding file with the production endpoint policy. An empty path yields nil (no bindings configured). Endpoints must be absolute http(s) URLs (remote endpoints require HTTPS), references must be name@version or name@* shapes, and duplicate references are rejected instead of silently overriding each other. Under the production policy a remote endpoint must also carry a mutual-TLS client certificate identity (P1-04); loopback endpoints and deployments that load with the explicitly acknowledged development policy are exempt.
func LoadRuntimeBindingsFor ¶
func LoadRuntimeBindingsFor(path string, policy EndpointPolicy) (*RuntimeBindings, error)
LoadRuntimeBindingsFor reads a binding file under an explicit endpoint policy (used by deployments that acknowledge plaintext remote runtimes).
func (*RuntimeBindings) Resolve ¶
func (b *RuntimeBindings) Resolve(agentVersionRef string) (string, bool)
Resolve returns the bound endpoint for one agent version reference: an exact ref match first, then the agent name's wildcard binding.
func (*RuntimeBindings) ResolveBinding ¶
func (b *RuntimeBindings) ResolveBinding(agentVersionRef string) (RuntimeBinding, bool)
ResolveBinding returns the full binding (endpoint plus deployment metadata and TLS configuration) for one agent version reference.
func (*RuntimeBindings) TransportFor ¶
func (b *RuntimeBindings) TransportFor(agentVersionRef string) (*tls.Config, string)
TransportFor returns the TLS configuration and its material fingerprint for the binding that covers the reference. The fingerprint joins the worker's HTTP client cache key so bindings that share an endpoint and SNI but carry different certificates (or one certificate at different rotation states) resolve to distinct clients instead of silently reusing the wrong identity (P1-03).
Source Files