outlet

type Call ¶

type Call struct {
	Tenant string
	Stack  string
	Outlet string
	Op     string
	SQL    string
	Args   []any
}

Call is one outlet operation as the processor hands it over: the trusted tenant and stack of the dispatching op (never envelope fields), the outlet and operation from the EXEC target, the literal statement and the converted arguments.

type Conn ¶

type Conn interface {
	Query(ctx context.Context, req Request) (*Result, error)
	Exec(ctx context.Context, req Request) (*Result, error)
	Close() error
}

Conn is one open pool. It is safe for concurrent use; the runtime hands the same Conn to every call on the outlet until the pool is superseded or idle-closed.

Errors: a Conn returns *Error for every failure it can classify (the caller reports Code and Message to the stack verbatim); anything else is reported as CodeUnavailable with a fixed message.

type ContextDialer ¶

type ContextDialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

ContextDialer reaches a relay. nil means the host network; a WireGuard tunnel living in this process (chassis/egress/wgtunnel) is the other one.

type Decl ¶

type Decl struct {
	Driver  string `yaml:"driver"`
	Secret  string `yaml:"secret"`
	Access  string `yaml:"access"`
	MaxRows int    `yaml:"max_rows"`
	Timeout int    `yaml:"timeout"`
	Egress  string `yaml:"egress"`
}

Decl is one OUTLETS/<name>.yaml: where to connect and the ceilings. The SQL lives in the ops that call the outlet, not here.

driver: postgres
secret: CRM_DSN      # a secret NAME; its value is the DSN
access: write        # read (default) | write
max_rows: 500        # tightens the node ceiling, never raises it
timeout: 5000        # ms; caps every call on this outlet
egress: relay        # direct | relay; omitted = the node's --outlet-egress

Parsed strictly: an unknown key is a deploy error, not a silent ignore.

func ParseDecl(data []byte, knownDriver func(string) bool) (*Decl, error)

func (d *Decl) Writable() bool

type DeclSource ¶

type DeclSource interface {
	Lookup(ctx context.Context, tenant, stack, name string) (*Decl, string, error)
}

DeclSource resolves (tenant, stack, name) → the stack's ACTIVE declaration and a hash of its bytes. It returns ErrNotDeclared when the stack has no outlet of that name. Package server implements it over the dbcache snapshot and the content store, the way txco://dataset finds a manifest.

type Deps ¶

type Deps struct {
	Lookup  func(driver string) (Driver, bool)
	Guard   egress.Guard
	Secrets SecretSource
	Decls   DeclSource
	Logger  *zap.Logger
	Limits  Limits
	Egress  EgressConfig
	Now     func() time.Time
}

Deps is everything a Runtime needs. Lookup defaults to the package registry; Now to time.Now.

type Driver ¶

type Driver interface {
	Name() string
	Open(ctx context.Context, p OpenParams) (Conn, error)
}

Driver opens pools for one protocol. Open must not block on the network: the first statement surfaces connect and auth failures, so a database that is down never blocks anything but the op that needs it.

func Lookup(name string) (Driver, bool)

type EgressConfig ¶

type EgressConfig struct {
	// Default is what a declaration without `egress` gets: EgressDirect
	// or EgressRelay. Empty means direct.
	Default string
	// Relays are SOCKS5 relays as ip:port on the fleet's private network
	// (or on the tunnel, when Forward is set), tried in order. Empty means
	// relay egress is unavailable on this node.
	Relays []string
	// Forward is how relays are reached; nil means the host network.
	Forward ContextDialer
}

EgressConfig is the node's egress default and its relays.

type EgressParams ¶

type EgressParams struct {
	Mode    string
	Relays  []string
	Forward ContextDialer
}

EgressParams is the egress a driver is handed for one pool.

type Error ¶

type Error struct {
	Code     string
	Message  string
	SQLState string
	Rows     int
	Bytes    int64
}

Error is the classified failure of an outlet call. Message is a fixed string chosen by the chassis or the driver — never a driver's own error text, which names hosts, users and databases. SQLState carries the database's code when there is one. Rows and Bytes report how far a read got before a ceiling fired (CodeResultTooLarge), for the trace only.

func AsError(err error, fallback, message string) *Error

func ConvertArgs(r gjson.Result) ([]any, *Error)

func NewError(code, message string) *Error

func (e *Error) Error() string

type Limits ¶

type Limits struct {
	MaxRows      int
	MaxBytes     int64
	PoolMaxConns int
	PoolIdle     time.Duration
	// IdleClose is how long an unused pool stays open before the runtime
	// closes it. The next call reopens it.
	IdleClose time.Duration
}

Limits are the node's ceilings and pool defaults; a declaration can only tighten them.

type OpenParams ¶

type OpenParams struct {
	// DSN is the materialized secret value. The runtime zeroes it the
	// moment Open returns; a driver that must keep connection parameters
	// (a pool config) copies what it needs and must never log or encode it.
	DSN []byte
	// Guard is the egress policy for every dial. When non-nil the driver
	// MUST route its connections through it (net.Dialer.Control =
	// egress.DialControl(guard)) so a DSN cannot point the chassis at
	// loopback, link-local or private address space. nil = no policy
	// (dev/test).
	Guard egress.Guard
	// Logger is scoped for this outlet. Drivers log codes and durations,
	// never SQL, values, rows or the DSN.
	Logger *zap.Logger
	Pool   PoolLimits
	// Egress says how to dial: install DialFunc(Egress, Guard, timeout)
	// on the client rather than a dialer of the driver's own, so every
	// driver shares one direct/relay path.
	Egress EgressParams
}

OpenParams carries everything a Driver needs to open one pool. The credential is live only for the duration of the Open call.

type Outcome ¶

type Outcome struct {
	Result   *Result
	Err      *Error
	Driver   string
	Egress   string
	Duration time.Duration
}

Outcome is what the processor reports: the result or the classified error, plus the driver name and duration for the trace.

type PoolLimits ¶

type PoolLimits struct {
	// MaxConns caps live connections; the minimum is always zero, so an
	// idle outlet costs nothing.
	MaxConns int
	// IdleTimeout closes a connection unused for this long.
	IdleTimeout time.Duration
}

PoolLimits bounds one outlet's pool on this node. Pools are per node, so a customer database sees roughly nodes × MaxConns connections.

type Request ¶

type Request struct {
	SQL  string
	Args []any
	// MaxRows and MaxBytes are safety ceilings: crossing one aborts the read
	// with CodeResultTooLarge and no rows. A driver measures while rows
	// stream so a huge result is dropped early rather than buffered.
	MaxRows  int
	MaxBytes int64
}

Request is one statement with its bound arguments and ceilings.

type Result ¶

type Result struct {
	Columns      []string
	RowsJSON     []byte
	Count        int
	RowsAffected int64
	// Bytes is the size of RowsJSON — what fuel is charged on.
	Bytes int64
}

Result is what a statement produced. RowsJSON is a JSON array of objects, one per row in column order, "[]" when there are none; Columns gives SELECT order, which object keys don't. RowsAffected is set by exec.

type Runtime ¶

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

Runtime owns every open outlet pool on this node.

func NewRuntime(d Deps) *Runtime

func (r *Runtime) Call(ctx context.Context, c Call) Outcome

func (r *Runtime) Close()

func (r *Runtime) OpenPools() int

func (r *Runtime) Start(ctx context.Context)

func (r *Runtime) Sweep()

type SecretSource ¶

type SecretSource interface {
	MaterializeForOpSlug(ctx context.Context, tenantSlug, stack, name string) ([]byte, *secrets.SecretMetadata, error)
}

SecretSource materializes a declared secret by name for the calling tenant and stack, with the store's ordinary scoping: stack-scoped first, then tenant-wide. *secrets.Resolver satisfies it.