Documentation
¶
Overview ¶
Package gateway is the workspace gateway (gateway.md): an explicit forward proxy that is the workspace's only TCP route out. It accepts connections only from its VM's exact addresses, tunnels CONNECTs and forwards absolute-form http requests after the egress check, dials every upstream through one egress dialer (resolve once, check every address, dial the literals), and writes one egress record per request. Every decision is the pure policy package's.
A CONNECT to an intercepted host is TLS-terminated with the agent host's CA (package ca), and each request inside it is forwarded to that host over TLS with every credential carrier stripped; a WebSocket upgrade passes through. github.com gets the git credentials by repo (Basic), with every repo that isn't rw fail-closed to the two fetch forms, and api.github.com the task token on reads (GET, HEAD, and POST /graphql when the document only queries). The dispatcher's name serves only POST effects, over its own transport, with Config.DispatcherToken. The Anthropic hosts get Config.Anthropic's credential when the VM sent a carrier, and chatgpt.com Config.ChatGPT's account id and, with Authorization, its access token; the model hosts keep only the infrastructure cookies. Every record classifies the VM's carriers (none, placeholder, other) and names the credential class added, never a value.
Index ¶
Constants ¶
const ( InjectedAnthropicOAuth = "anthropic-oauth" // AnthropicAuth.OAuthToken as Bearer InjectedAnthropicKey = "anthropic-key" // AnthropicAuth.APIKey as X-Api-Key InjectedChatGPT = "chatgpt" // ChatGPTLogin.AccessToken as Bearer on chatgpt.com )
The model credential classes a record's Injected names.
const ( ClientNone = "none" // no carrier ClientPlaceholder = "placeholder" // every carrier holds harness.Placeholder ClientOther = "other" // a carrier held something else: a credential reached the VM )
The client classes: what the VM sent in its credential carriers (Record.Client).
const ( InjectedGitHubAPI = "github-api" // the task token as Bearer on api.github.com InjectedDispatcher = "dispatcher-token" // Config.DispatcherToken on the dispatcher route )
The credential classes a record's Injected names.
const ChatGPTAccountHeader = "ChatGPT-Account-Id"
ChatGPTAccountHeader is the header chatgpt.com gets the login's account id in.
const RecordType = "factory.egress"
RecordType is a Record's transcript line type.
Variables ¶
var ErrConfig = errors.New("invalid gateway config")
ErrConfig is wrapped by every *ConfigError.
Functions ¶
This section is empty.
Types ¶
type AnthropicAuth ¶
type AnthropicAuth struct{ OAuthToken, APIKey string }
AnthropicAuth is the Claude credential the Anthropic hosts get: exactly one of the OAuth token (a subscription login) and the API key. String, Format, GoString, LogValue, MarshalJSON and MarshalText redact, so fmt, slog (inside a slice or map too) and encoding/json never print it. fmt's reflection paths call no method: %p on the value, and the value in an unexported field of an enclosing struct, print the token. Pass it by pointer or hold it only in exported fields.
func (AnthropicAuth) Format ¶
func (a AnthropicAuth) Format(f fmt.State, _ rune)
Format redacts every verb, %#v included.
func (AnthropicAuth) MarshalJSON ¶
func (a AnthropicAuth) MarshalJSON() ([]byte, error)
MarshalJSON is the redacted form as a JSON string.
func (AnthropicAuth) MarshalText ¶
func (a AnthropicAuth) MarshalText() ([]byte, error)
MarshalText is the redacted form (slog's text handler, encoding/xml, map keys).
func (AnthropicAuth) String ¶
func (AnthropicAuth) String() string
type ChatGPTLogin ¶
type ChatGPTLogin struct{ AccessToken, AccountID string }
ChatGPTLogin is the codex login chatgpt.com gets: the access token and the account id. It redacts as AnthropicAuth does, with the same limits: pass it by pointer or hold it only in exported fields.
func (ChatGPTLogin) Format ¶
func (l ChatGPTLogin) Format(f fmt.State, _ rune)
Format redacts every verb, %#v included.
func (ChatGPTLogin) MarshalJSON ¶
func (l ChatGPTLogin) MarshalJSON() ([]byte, error)
MarshalJSON is the redacted form as a JSON string.
func (ChatGPTLogin) MarshalText ¶
func (l ChatGPTLogin) MarshalText() ([]byte, error)
MarshalText is the redacted form (slog's text handler, encoding/xml, map keys).
func (ChatGPTLogin) String ¶
func (ChatGPTLogin) String() string
type Config ¶
type Config struct {
// TaskID and RunID identify the workspace; both required.
TaskID, RunID string
// Clients are the VM's exact addresses (IPv4-mapped ones unmapped): any other peer is closed
// at accept. Required.
Clients []netip.Addr
// CA signs the leaves of the intercepted hosts; required.
CA *ca.CA
// Git is the job's git credentials; nil: none. It is read on every request, so a
// heartbeat's Set and SetReads apply at once. Only github.com credentials are used.
Git *runner.Credentials
// Dispatcher is the supervisor's dispatcher base URL (absolute http or https, without user
// info, query or fragment); required. The VM reaches it as dispatcher.factory.internal.
Dispatcher *url.URL
// DispatcherToken returns the bearer token for the dispatcher route, read on every request;
// required. For the PoC it is the worker's agent token (worker.Token); the lease's run token
// (#101) when that lands. "" sends the request without one.
DispatcherToken func() string
// Anthropic returns the Claude credential (exactly one of its fields) the Anthropic hosts
// get, read on every request that carried a carrier, so the supervisor hands it in from its
// login store; nil: none (a codex task's gateway). A value returned with an error is still
// used; none is no-login. The gateway logs its error, which must never hold a credential.
Anthropic func(ctx context.Context) (AnthropicAuth, error)
// ChatGPT returns the codex login chatgpt.com gets, read on every request; nil: none (a
// claude task's gateway). A token returned with an error is still sent (its 401 shows in the
// record); no token is no-login. The gateway logs its error, which must never hold a
// credential. The supervisor hands in its chatgpt.Refresher's Current.
ChatGPT func(ctx context.Context) (ChatGPTLogin, error)
// injected in: it returns the login to resend the request with once (the Refresher's
// Unauthorized). nil: the client gets the 401.
ChatGPTUnauthorized func(ctx context.Context, used string) (ChatGPTLogin, error)
// UpstreamRoots verifies the intercepted hosts' upstreams, and an https dispatcher; default
// the system roots.
UpstreamRoots *x509.CertPool
// Egress is the task's mode and allow list, extra denied prefixes and open addresses.
Egress policy.Egress
// Sink receives the egress log; required.
Sink Sink
// Clock times the records and the interface cache; default the real clock.
Clock clock.Clock
// Logger defaults to discarding.
Logger *slog.Logger
// Resolver resolves the destinations; default net.DefaultResolver.
Resolver Resolver
}
Config configures a Gateway (gateway.md, API).
type ConfigError ¶
type ConfigError struct {
Field string
Err error // a policy or v1alpha1 sentinel, when there is one
}
ConfigError is a Config field that New or Serve refuses. It never carries the value.
func (*ConfigError) Error ¶
func (e *ConfigError) Error() string
func (*ConfigError) Unwrap ¶
func (e *ConfigError) Unwrap() error
type Gateway ¶
type Gateway struct {
// contains filtered or unexported fields
}
Gateway is one workspace's proxy. New validates it, Serve runs it and Close ends it.
func (*Gateway) Close ¶
Close stops the gateway: it closes the listener and every connection (hijacked ones, tunnels' upstream sides included), cancels the requests in flight, waits for every handler and copy (whose records are written then), and returns nil. Nothing is recorded after it returns. It is idempotent; a concurrent call waits for the first.
type Mode ¶
type Mode string
Mode says where a request was handled.
const ( ModeConnect Mode = "connect" // a CONNECT to one of the gateway's own hosts ModeIntercept Mode = "intercept" // a request inside an intercepted CONNECT (PR 5) ModeTunnel Mode = "tunnel" // any other CONNECT: one record per tunnel, when it closes ModeForward Mode = "forward" // plain HTTP ModeDispatcher Mode = "dispatcher" // plain HTTP to the dispatcher ModeAccept Mode = "accept" // a peer outside Clients )
The modes.
type Record ¶
type Record struct {
Type string // RecordType
At time.Time // the request's start, on the injected clock
Mode Mode
Method string
Host string // the target as policy normalised it; empty when it didn't parse
Port uint16
Path string // the URL path only, cut at 512 bytes; empty for CONNECT and tunnels
Status int // the status the client got; 0 for a connection closed without one
Injected string // the credential class added (Injected* constants, git:<owner>/<repo>) or ""
Client string // the VM's carriers: ClientNone, ClientPlaceholder or ClientOther; "" at accept
Refusal policy.Code
Up, Down int64 // bytes from the client and to it (bodies, or a tunnel's streams)
Duration time.Duration
}
Record is one request, refusals included. It never holds a header value, a body, a query or a resolved address.
func (Record) MarshalJSON ¶
MarshalJSON is the transcript line: gateway.md's factory.egress object.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ca is the agent host's gateway CA (gateway.md, "The CA"): a name-constrained ECDSA P-256 certificate authority whose leaves the gateway presents for the hosts it intercepts.
|
Package ca is the agent host's gateway CA (gateway.md, "The CA"): a name-constrained ECDSA P-256 certificate authority whose leaves the gateway presents for the hosts it intercepts. |
|
Package chatgpt is the codex ChatGPT login the gateway sends to chatgpt.com, and its Refresher (gateway.md, "ChatGPT refresh").
|
Package chatgpt is the codex ChatGPT login the gateway sends to chatgpt.com, and its Refresher (gateway.md, "ChatGPT refresh"). |
|
Package policy holds the workspace gateway's decisions as data (gateway.md): the host classes and what a CONNECT or a plain HTTP request to each gets, the egress check (the task's mode and allow list, the deny table, the open addresses), the github.com, api.github.com (with the GraphQL read check), dispatcher and model host (methods and path lists) request rules, the refusal codes and bodies, and the cookie filter of the model hosts.
|
Package policy holds the workspace gateway's decisions as data (gateway.md): the host classes and what a CONNECT or a plain HTTP request to each gets, the egress check (the task's mode and allow list, the deny table, the open addresses), the github.com, api.github.com (with the GraphQL read check), dispatcher and model host (methods and path lists) request rules, the refusal codes and bodies, and the cookie filter of the model hosts. |