Documentation
¶
Overview ¶
Package dialhome is the hosted side of Omnia's dial-home channel: the connection a runtime hosted outside the cluster (Vertex Agent Runtime, AgentCore, Foundry, a VM on site) opens to the relay that stands in for it as its AgentRuntime's runtime container.
The hosted runtime opens ONE outbound connection; nothing ever dials into it. Over that connection both ends run a yamux session, and every stream on it begins with a two-byte header naming its kind:
relay → runtime KindRuntime omnia.runtime.v1, exactly as the facade
speaks it (the relay forwards it unparsed)
runtime → relay KindMemory HTTP/1.1 to the agent's memory-api
runtime → relay KindEvents HTTP/1.1 to the agent's session-api
runtime → relay KindConfig HTTP/1.1, GET ConfigPath: the agent's
resolved provider config (RemoteConfig)
Wire contract, version 1 ¶
- Transport: a WebSocket (wss:// in production) carrying the yamux byte stream in binary messages. WebSocket, not a raw upgrade, because it is the one upgrade every platform egress path and every Gateway passes.
- Handshake: GET ChannelPath with `Authorization: Bearer <key>` and HeaderVersion: ProtocolVersion. The key is an Omnia-issued dial-home key scoped to one AgentRuntime. A missing or unknown key is refused with 401 before the upgrade; an unsupported version with 400.
- Streams: the opener writes {streamVersion, kind} and then the stream is the protocol named by kind. A kind the receiver does not serve is closed at once — the channel is not a general-purpose tunnel.
- Liveness: yamux keepalives. A session that misses them closes, the relay reports the runtime unavailable, and the runtime re-dials with a capped exponential backoff.
- Revocation: when a key stops being valid the relay closes every live session that authenticated with it.
KindConfig was added after version 1 shipped, without a version bump: the rule above already makes a relay that predates it close the stream, and the runtime then keeps its baked configuration.
Configuration over the channel ¶
While the channel is up, the provider configuration the relay serves wins over whatever was baked into the hosted deployment; the baked config (EnvConfig) is the fallback when the channel is down or the relay serves none, and supplies a provider the relay withheld when it has one for the same group (ConfigSource). The relay serves only providers that need no in-cluster secret, and names the rest as withheld.
Client is the runtime side. It is a net.Listener: serve omnia.runtime.v1 on it (package server does that for any Handler, package promptkit for a PromptKit pack) exactly as on a TCP listener.
Index ¶
- Constants
- Variables
- func BearerKey(h string) (string, bool)
- func CleartextAllowed(host string) bool
- func NewWSConn(ws *websocket.Conn) net.Conn
- func WriteStreamHeader(w io.Writer, k StreamKind) error
- func YamuxConfig(keepAlive time.Duration) *yamux.Config
- type Addr
- type AuthConfig
- type Client
- func (c *Client) Accept() (net.Conn, error)
- func (c *Client) Addr() net.Addr
- func (c *Client) Close() error
- func (c *Client) Connected() bool
- func (c *Client) FetchConfig(ctx context.Context) (*RemoteConfig, error)
- func (c *Client) ForwardLocal(kind StreamKind) (*LocalForward, error)
- func (c *Client) OpenStream(kind StreamKind) (net.Conn, error)
- type ClientConfig
- type ConfigOrigin
- type ConfigSource
- type CredentialConfig
- type EmbeddingConfig
- type LocalForward
- type PlatformConfig
- type ProviderDefaults
- type ProviderPricing
- type ProviderSpec
- type RefusedError
- type RemoteConfig
- type RemoteProvider
- type STTConfig
- type SecretKeyRef
- type StreamKind
- type TTSConfig
- type WithheldProvider
Constants ¶
const ( // WithheldSecretBacked: the credential lives in a cluster Secret, which // never leaves the cluster. WithheldSecretBacked = "SecretBackedCredential" // WithheldCredentialHeader: spec.headers carries a credential // (Authorization, an API-key header), which is a secret even though it is // not in a Secret. WithheldCredentialHeader = "CredentialInHeaders" //nolint:gosec // a reason, not a credential // WithheldUnresolved: the Provider could not be read. WithheldUnresolved = "ProviderUnresolved" )
Withheld reasons.
const ( // ChannelPath is where the relay accepts the dial-home connection. ChannelPath = "/v1/channel" // HeaderVersion carries the channel protocol version on the handshake. HeaderVersion = "X-Omnia-Dial-Home-Version" // ProtocolVersion is the only channel version this package speaks. ProtocolVersion = "1" // HandshakeTimeout bounds the WebSocket handshake, on either end. HandshakeTimeout = 15 * time.Second )
Handshake contract.
const ( // EnvURL is the relay's connect-back URL (wss://.../v1/channel). EnvURL = "OMNIA_DIAL_HOME_URL" // EnvKey is the Omnia-issued dial-home key. EnvKey = "OMNIA_DIAL_HOME_KEY" // EnvConfig carries the baked RemoteConfig, as JSON, that a hosted runtime // falls back to when the channel is down. Optional. EnvConfig = "OMNIA_DIAL_HOME_CONFIG" )
Runtime-side configuration, read from the hosted runtime's environment (ConfigFromEnv, BakedConfigFromEnv).
const ( PlatformBedrock = "bedrock" PlatformVertex = "vertex" PlatformAzure = "azure" )
Platform types.
const ConfigPath = "/v1/config"
ConfigPath is where the relay serves RemoteConfig on a KindConfig stream.
const DefaultKeepAlive = 15 * time.Second
DefaultKeepAlive is how often each end proves the session alive.
const EnvFoundryProjectEndpoint = "FOUNDRY_PROJECT_ENDPOINT"
EnvFoundryProjectEndpoint is the project endpoint Azure AI Foundry injects into a hosted agent's container. On Foundry it wins over a provider's spec.platform.endpoint: it is the project inference proxy, which is what lets the agent's own identity call the model with no extra RBAC.
Variables ¶
var ErrBadStreamHeader = errors.New("dial-home: bad stream header")
ErrBadStreamHeader is returned for a stream header of an unknown version.
var ErrNoConfig = errors.New("dial-home: no configuration: channel unavailable and none baked")
ErrNoConfig is returned when the channel serves none and nothing was baked.
var ErrNotConnected = errors.New("dial-home: channel not connected")
ErrNotConnected is returned when the channel has no live session.
Functions ¶
func BearerKey ¶
BearerKey extracts the key from an Authorization header value. The scheme is matched case-insensitively and surrounding space is trimmed.
func CleartextAllowed ¶
CleartextAllowed reports whether ws:// may be used to host: only when its traffic never leaves the machine or the cluster — loopback, and cluster-local Service names (*.svc, *.svc.cluster.local).
func NewWSConn ¶
NewWSConn presents ws as the byte stream both ends run yamux over: each Write is one binary message, and Read concatenates them, skipping any text message.
func WriteStreamHeader ¶
func WriteStreamHeader(w io.Writer, k StreamKind) error
WriteStreamHeader names a new stream's kind. The opener of every stream writes it before anything else.
Types ¶
type Addr ¶
type Addr string
Addr is the net.Addr of a channel endpoint: network "dial-home", and the relay URL (or another label) as its string.
type AuthConfig ¶
type AuthConfig struct {
Type string `json:"type"`
CredentialsSecretRef *SecretKeyRef `json:"credentialsSecretRef,omitempty"`
}
AuthConfig is how a platform provider authenticates: workloadIdentity on a served provider, the identity the hosted runtime runs with.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the runtime side of the channel. It dials the relay, keeps the session up across drops, and is a net.Listener: the relay's runtime streams arrive on Accept, so a runtime serves omnia.runtime.v1 on it exactly as it would on a TCP listener.
func Dial ¶
func Dial(ctx context.Context, cfg ClientConfig) (*Client, error)
Dial validates cfg and starts dialling home in the background. It returns at once; the channel connects (and reconnects) on its own until Close.
func (*Client) FetchConfig ¶
func (c *Client) FetchConfig(ctx context.Context) (*RemoteConfig, error)
FetchConfig reads the agent's configuration from the relay over a KindConfig stream.
func (*Client) ForwardLocal ¶
func (c *Client) ForwardLocal(kind StreamKind) (*LocalForward, error)
ForwardLocal starts a LocalForward for kind on 127.0.0.1 (an ephemeral port). Loopback only: the forward is this process's door to the channel, not a port anything else on the host may use.
func (*Client) OpenStream ¶
func (c *Client) OpenStream(kind StreamKind) (net.Conn, error)
OpenStream opens a stream of kind to the relay on the live session.
type ClientConfig ¶
type ClientConfig struct {
// URL is the relay's connect-back URL, ws:// or wss://.
URL string
// Key is the Omnia-issued dial-home key.
Key string
// Log receives connection lifecycle events. Zero value discards.
Log logr.Logger
// TLSConfig overrides the TLS client config for wss:// URLs.
TLSConfig *tls.Config
// MinBackoff and MaxBackoff bound the re-dial delay.
MinBackoff, MaxBackoff time.Duration
// KeepAlive is the yamux keepalive interval.
KeepAlive time.Duration
}
ClientConfig configures the runtime side of the channel.
func ConfigFromEnv ¶
func ConfigFromEnv(getenv func(string) string) (cfg ClientConfig, ok bool, err error)
ConfigFromEnv reads the runtime-side config from EnvURL and EnvKey. ok is false when neither is set — the runtime is not configured to dial home, which is a normal deployment, not an error.
func (ClientConfig) Validate ¶
func (c ClientConfig) Validate() error
Validate checks the config: a key, and an absolute ws:// or wss:// URL, with ws:// only to a loopback or in-cluster host.
type ConfigOrigin ¶
type ConfigOrigin string
ConfigOrigin says where a ConfigSource's answer came from.
const ( OriginChannel ConfigOrigin = "channel" OriginBaked ConfigOrigin = "baked" )
Config origins.
type ConfigSource ¶
type ConfigSource struct {
// contains filtered or unexported fields
}
ConfigSource is a hosted runtime's configuration: the channel's config wins while the channel is connected, and the baked config is the fallback. A provider the relay withheld (its credential stays in the cluster) is filled from the baked config's entry for the same group, when it has one: that is a provider the hosted runtime holds its own credential for.
The channel's config is read on demand, at most once per 30 seconds per connection; no background reads. A failed read keeps the last config that connection served, else falls back to the baked one, and is logged.
func NewConfigSource ¶
func NewConfigSource(c *Client, baked *RemoteConfig) *ConfigSource
NewConfigSource builds a ConfigSource over c. baked may be nil.
func (*ConfigSource) Current ¶
func (s *ConfigSource) Current(ctx context.Context) (*RemoteConfig, ConfigOrigin, error)
Current returns the configuration to use now and where it came from.
type CredentialConfig ¶
type CredentialConfig struct {
SecretRef *SecretKeyRef `json:"secretRef,omitempty"`
EnvVar string `json:"envVar,omitempty"`
FilePath string `json:"filePath,omitempty"`
}
CredentialConfig says where a direct provider's credential comes from. On a served provider only EnvVar or FilePath can be set, naming a variable or file in the hosted runtime's own environment.
type EmbeddingConfig ¶
type EmbeddingConfig struct {
Dimensions int32 `json:"dimensions,omitempty"`
}
EmbeddingConfig configures an embedding-role provider.
type LocalForward ¶
type LocalForward struct {
// contains filtered or unexported fields
}
LocalForward is a loopback listener whose connections ride the channel as streams of one kind. It lets a runtime point an unmodified HTTP client — a session-api or memory-api client — at the channel: set its base URL to URL() and every request it makes is carried to the relay, which terminates it in-cluster.
func (*LocalForward) Close ¶
func (f *LocalForward) Close() error
Close stops accepting. Connections already carried finish on their own.
func (*LocalForward) URL ¶
func (f *LocalForward) URL() string
URL is the base URL to give an HTTP client.
type PlatformConfig ¶
type PlatformConfig struct {
// Type is bedrock, vertex or azure.
Type string `json:"type"`
Region string `json:"region,omitempty"`
Project string `json:"project,omitempty"`
Endpoint string `json:"endpoint,omitempty"`
}
PlatformConfig is the hyperscaler hosting a provider.
type ProviderDefaults ¶
type ProviderDefaults struct {
Temperature *string `json:"temperature,omitempty"`
TopP *string `json:"topP,omitempty"`
MaxTokens *int32 `json:"maxTokens,omitempty"`
ThinkingBudgetTokens *int32 `json:"thinkingBudgetTokens,omitempty"`
ContextWindow *int32 `json:"contextWindow,omitempty"`
TruncationStrategy string `json:"truncationStrategy,omitempty"`
RequestTimeout string `json:"requestTimeout,omitempty"`
StreamIdleTimeout string `json:"streamIdleTimeout,omitempty"`
FirstTokenTimeout string `json:"firstTokenTimeout,omitempty"`
}
ProviderDefaults are a provider's tuning parameters. Decimals are strings, as on the resource.
type ProviderPricing ¶
type ProviderPricing struct {
InputCostPer1K *string `json:"inputCostPer1K,omitempty"`
OutputCostPer1K *string `json:"outputCostPer1K,omitempty"`
CachedCostPer1K *string `json:"cachedCostPer1K,omitempty"`
}
ProviderPricing is a provider's cost per 1000 tokens, as decimal strings.
type ProviderSpec ¶
type ProviderSpec struct {
// Type is the provider's wire protocol / vendor: claude, openai, gemini,
// ollama, vllm, mock, …
Type string `json:"type"`
// Role is llm (the default when empty), embedding, tts, stt, image,
// inference or rerank.
Role string `json:"role,omitempty"`
TTS *TTSConfig `json:"tts,omitempty"`
STT *STTConfig `json:"stt,omitempty"`
Embedding *EmbeddingConfig `json:"embedding,omitempty"`
// Model is the model identifier.
Model string `json:"model,omitempty"`
// BaseURL overrides the provider's default API endpoint.
BaseURL string `json:"baseURL,omitempty"`
// Headers are sent on every provider request.
Headers map[string]string `json:"headers,omitempty"`
// MessageMetadataTemplate renders a user message's metadata as text the
// model reads.
MessageMetadataTemplate string `json:"messageMetadataTemplate,omitempty"`
// Platform is the hyperscaler hosting the provider, if any.
Platform *PlatformConfig `json:"platform,omitempty"`
// Auth is how the platform is authenticated to.
Auth *AuthConfig `json:"auth,omitempty"`
// Credential is where a direct provider's credential comes from.
Credential *CredentialConfig `json:"credential,omitempty"`
// Defaults are the provider's tuning parameters.
Defaults *ProviderDefaults `json:"defaults,omitempty"`
// Pricing overrides the built-in cost table.
Pricing *ProviderPricing `json:"pricing,omitempty"`
// Capabilities are free-form feature tags (text, streaming, vision, …).
Capabilities []string `json:"capabilities,omitempty"`
}
ProviderSpec is an Omnia Provider's spec as the relay serves it, field for field and in the same JSON as the Provider resource's spec. It is a plain mirror so a hosted runtime can read it without Omnia's API types; fields it does not use are kept so a config passes through unchanged.
The relay serves no secret: a provider whose credential lives in a cluster Secret, or rides in Headers, is withheld instead (WithheldProvider), so on a served provider SecretRef and CredentialsSecretRef are always empty.
type RefusedError ¶
type RefusedError struct{ Status int }
RefusedError is a handshake the relay answered with an HTTP status rather than an upgrade: 401 for a key it does not accept, 400 for a version it does not speak.
func (*RefusedError) Error ¶
func (e *RefusedError) Error() string
type RemoteConfig ¶
type RemoteConfig struct {
// Agent is the AgentRuntime's name.
Agent string `json:"agent"`
// PackDigest is the content digest the agent's PromptPack published, so
// the hosted runtime can tell whether it runs the pack Omnia serves.
PackDigest string `json:"packDigest,omitempty"`
// Providers are the agent's providers the hosted runtime may use.
Providers []RemoteProvider `json:"providers"`
// Withheld are the agent's providers that were not served, and why.
Withheld []WithheldProvider `json:"withheld,omitempty"`
}
RemoteConfig is the configuration the relay resolves for its AgentRuntime and serves to the hosted runtime: what Omnia would have materialised for an in-cluster runtime, less anything secret.
func BakedConfigFromEnv ¶
func BakedConfigFromEnv(getenv func(string) string) (cfg *RemoteConfig, ok bool, err error)
BakedConfigFromEnv reads the baked fallback config from EnvConfig. ok is false when none is set.
func (*RemoteConfig) Default ¶
func (c *RemoteConfig) Default() (RemoteProvider, bool)
Default returns the default provider, if the relay served it.
func (*RemoteConfig) Group ¶
func (c *RemoteConfig) Group(group string) (RemoteProvider, bool)
Group returns the provider served under group, if any.
type RemoteProvider ¶
type RemoteProvider struct {
// Group is the entry's spec.providers[].name.
Group string `json:"group"`
// Name is the Provider object's name.
Name string `json:"name"`
// Default marks the entry the agent's default LLM comes from.
Default bool `json:"default,omitempty"`
// Spec is the Provider's spec with no Secret reference in it.
Spec ProviderSpec `json:"spec"`
}
RemoteProvider is one of the agent's spec.providers entries, resolved.
func (RemoteProvider) PlatformEndpoint ¶
func (p RemoteProvider) PlatformEndpoint(getenv func(string) string) string
PlatformEndpoint is the endpoint the hosted runtime should call for p. For an azure-platform provider on Foundry the platform-injected project endpoint wins over spec.platform.endpoint; everywhere else it is the spec's.
type STTConfig ¶
type STTConfig struct {
SampleRate int32 `json:"sampleRate,omitempty"`
Language string `json:"language,omitempty"`
}
STTConfig configures an stt-role provider.
type SecretKeyRef ¶
SecretKeyRef names a key in a cluster Secret. Never set on a provider the relay serves.
type StreamKind ¶
type StreamKind byte
StreamKind names what a stream on the channel carries.
const ( KindRuntime StreamKind = 1 KindMemory StreamKind = 2 KindEvents StreamKind = 3 // KindConfig (runtime → relay, HTTP) serves the agent's resolved // configuration at ConfigPath. Added without a version bump: a relay that // predates it closes the stream, as the contract requires for any kind it // does not serve, and the runtime keeps its baked config. KindConfig StreamKind = 4 )
Stream kinds. Values are wire bytes; never renumber.
func ReadStreamHeader ¶
func ReadStreamHeader(c net.Conn) (StreamKind, error)
ReadStreamHeader reads a stream's kind, bounded by a ten-second deadline.
func (StreamKind) String ¶
func (k StreamKind) String() string
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
omnia-dialhome
command
Command omnia-dialhome runs a PromptKit pack as an Omnia agent's runtime from outside the cluster.
|
Command omnia-dialhome runs a PromptKit pack as an Omnia agent's runtime from outside the cluster. |
|
internal
|
|
|
relaytest
Package relaytest is an in-process stand-in for Omnia's relay, the cluster end of the dial-home channel, for tests.
|
Package relaytest is an in-process stand-in for Omnia's relay, the cluster end of the dial-home channel, for tests. |
|
Package promptkit is a server.Handler backed by a PromptKit pack: each Omnia session is one PromptKit SDK conversation, its replies stream as they are generated, and the pack's client tools travel the protocol as client tool calls.
|
Package promptkit is a server.Handler backed by a PromptKit pack: each Omnia session is one PromptKit SDK conversation, its replies stream as they are generated, and the pack's client tools travel the protocol as client tool calls. |
|
Package providerspec turns a provider served over the dial-home channel into a PromptKit provider, for a hosted runtime built on PromptKit.
|
Package providerspec turns a provider served over the dial-home channel into a PromptKit provider, for a hosted runtime built on PromptKit. |
|
Package server serves omnia.runtime.v1 for a Handler: the hello-first Converse stream, client tool round-trips, heartbeats, Health and the optional RPCs.
|
Package server serves omnia.runtime.v1 for a Handler: the hello-first Converse stream, client tool round-trips, heartbeats, Health and the optional RPCs. |