transport

Documentation

Overview

Package transport is the edge's egress-only call-home client. It dials OUT to the SaaS Connector Gateway, registers for its tenant, and serves dispatched single-tool calls by running them through the edge registry and streaming results back over the same stream. It is the Go counterpart of the Python connector/agent.py "connect" path, scoped to the edge's role: run one read-only tool per assignment (no local LLM loop).

Index

• Constants
• type Client
  • func New(cfg Config, reg *edge.Registry, logger *slog.Logger) *Client
  • func (c *Client) Run(ctx context.Context) error
• type Config

Constants

const DefaultIamEnrollTokenPath = "/api/v1/skybridge/enrollments-iam"

DefaultIamEnrollTokenPath is used when Config.IamEnrollURL is set but no override path is given (there is currently no per-call override — every connector deployment hits the same path).

const DefaultTrustDomain = "skybridge.edge"

DefaultTrustDomain is the SPIFFE trust domain placed in the CSR's URI SAN. The CSR SAN is only informational — the gateway's CA sets the authoritative identity SAN when it signs — so this value does not need to match the gateway and stays vendor-neutral by default.

const Version = "0.1.0"

Version reported to the gateway on Register.

Types

type Client

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

Client maintains the call-home connection and serves dispatched tool work.

func New

func New(cfg Config, reg *edge.Registry, logger *slog.Logger) *Client

New builds a call-home client. reg supplies the edge-handled tools.

func (*Client) Run

func (c *Client) Run(ctx context.Context) error

Run dials the gateway and serves work, reconnecting with backoff until ctx is cancelled.

type Config

type Config struct {
	Target      string        // gateway Connect endpoint host:port (dialed OUT)
	TenantID    string        // organization id this edge serves
	ConnectorID string        // stable edge instance id
	Token       string        // bearer token (when not using mTLS)
	Insecure    bool          // plaintext channel (dev only; ignored when mTLS material is present)
	Reconnect   bool          // reconnect with backoff on stream loss
	MaxBackoff  time.Duration // cap for reconnect backoff (default 30s)

	// gRPC keepalive: detects a dead/killed gateway (crash, ECS task replacement) without waiting
	// on OS TCP keepalive (hours) or an incidental LB idle-timeout reset. Must stay in lockstep with
	// whatever server-side keepalive policy the gateway enforces — KeepaliveTime here should stay
	// above the server's minimum ping interval without data, or healthy pings risk an
	// ENHANCE_YOUR_CALM.
	KeepaliveTime    time.Duration // ping interval when the stream is idle (default 20s)
	KeepaliveTimeout time.Duration // time to wait for a ping ack before declaring the peer dead (default 10s)

	// ForceBearer, when true (SKYBRIDGE_CONNECTOR_KEY configured), skips mTLS/certstore entirely —
	// including never calling certstore.FromEnv — even if CABundlePEM/TLSDir are also set. This is
	// the stateless mode: Token is presented fresh on every boot, nothing is ever persisted to disk
	// or Secrets Manager. See internal/config.Edge.ConnectorKey's doc comment.
	ForceBearer bool

	// mTLS (hardened path). When CABundlePEM is empty and TLSDir is unset, the client uses bearer.
	// Ignored entirely when ForceBearer is true.
	CABundlePEM []byte // CA bundle trusted for the gateway (enables mTLS)
	TLSDir      string // directory holding/persisting ca.pem, client.crt, client.key
	// IdentitySecretARN, when set, mirrors the issued cert to this AWS Secrets Manager secret so a
	// replaced task (fresh disk) recovers its identity instead of re-enrolling with an already-used
	// one-time token. See SKYBRIDGE_IDENTITY_SECRET_ARN.
	IdentitySecretARN string
	EnrollTarget      string // Enroll endpoint host:port (defaults to Target)
	EnrollToken       string // one-time enrollment token (needed to obtain the first cert)
	TrustDomain       string // SPIFFE trust domain placed in the CSR SAN (cosmetic; default skybridge.edge)

	// Targets is the same configured database target list dbexec/studiotransport use (from
	// SKYBRIDGE_STUDIO_TARGETS, merged with any wire-proxy targets) — metadata discovery resolves
	// an incoming account_key/driver/database triple against this list rather than opening its own.
	Targets []dbquery.Target

	// IamAuthEnabled, when true, mints its own enroll token by presigning sts:GetCallerIdentity
	// with the edge's ambient AWS credentials (an ECS task role, in production) instead of relying
	// on a static, single-use EnrollToken — see internal/edgeiam. Safe to use on every restart,
	// including a redeployed task with a wiped disk. IamEnrollURL is the control-plane HTTPS
	// origin that verifies the presigned request (see SKYBRIDGE_IAM_AUTH / SKYBRIDGE_IAM_ENROLL_URL).
	IamAuthEnabled bool
	IamEnrollURL   string

	// SpireSocketPath, when set, loads a fresh JWT-SVID from SPIRE at each connect attempt,
	// using it as a bearer token instead of mTLS certs. Falls back to mTLS enrollment if the
	// socket is unavailable or the SVID is expired. See internal/spire and docs/design/
	// kubernetes-access-broker.md §12.
	SpireSocketPath string
}

Config is the call-home client configuration. When a CA bundle (and optionally an enrollment token) is supplied the client uses mTLS — calling Enroll to obtain a client cert, then Connect with it; otherwise it falls back to bearer-token-over-TLS.