Documentation
¶
Overview ¶
Package fakegateway is a test-only stand-in for phase 4's gateway (P1 §3): an explicit forward proxy that injects every credential, so the workspace under test never holds one.
- Absolute-form HTTP to the dispatcher (runbundle.DefaultDispatcherURL's host): only the Config.DispatcherRoutes (default POST /api/v1/tasks/{id}/effects) are forwarded, with the client's Authorization replaced by Bearer <run token>; any other method or path gets a 403, and a path that isn't canonical a 400.
- CONNECT to github.com or api.github.com: TLS is terminated with a leaf from a per-instance CA. git smart HTTP gets Basic x-access-token:<token> for the repo in the path. A repo that isn't rw fails closed: only a smart-HTTP fetch (GET info/refs?service=git-upload-pack and POST git-upload-pack) is forwarded, and every other request gets a 403. api.github.com gets the API token on GET and HEAD; every other method is refused with a 403.
- Any other CONNECT is tunnelled as it is, or refused, by Config.AllowTunnel. The tunnel dials any address: P1 §3's egress deny list (169.254.0.0/16, RFC 1918, the agent host's own addresses, other workspaces) belongs to phase 4's gateway and the network layer, and isn't modelled here.
Host names are matched lower-cased and without a trailing dot. The client's Authorization is always replaced, never matched, and its other credential carriers (Proxy-Authorization, X-Api-Key, Cookie, URL userinfo) are dropped on the injected routes. Every request is recorded with the credential it got and the classification of each credential it arrived with, never a value.
Index ¶
Constants ¶
const ( // RunToken is a run token in the API's shape (rtk_ and 43 base64url characters) for tests. RunToken = "rtk_fakegatewayRunTokenNeverInTheWorkspace01234" // DefaultPlaceholder is the placeholder credential the workspace carries. DefaultPlaceholder = harness.Placeholder // DefaultGitHost and DefaultAPIHost are the intercepted GitHub hosts. DefaultGitHost = "github.com" DefaultAPIHost = "api.github.com" )
const ( PushRefused = "fakegateway: push refused: the repository is not writable for this task" APIWriteRefused = "fakegateway: refused: api.github.com is read-only for workspaces" DispatcherRefused = "fakegateway: refused: the dispatcher route is not open to workspaces" TunnelRefused = "fakegateway: refused: tunnels are not allowed" PlainRefused = "fakegateway: refused: plain HTTP to an intercepted host" BadPath = "fakegateway: refused: the path is not canonical" NotProxyRequest = "fakegateway: not a proxy request" )
The bodies of the gateway's refusals, which tests and the workspace's logs recognise.
const ( InjectedNone = "" InjectedRunToken = "run-token" InjectedAPI = "api-token" )
Record.Injected values; a git request records "git:<owner>/<repo>".
const ClientAuthNone = "none"
ClientAuthNone is Record.ClientAuth for a request without an Authorization header. Otherwise it is "<scheme> placeholder" or "<scheme> other", with scheme one of basic, bearer or token (anything else is "unknown"). Basic is a placeholder only when its password is one and its username is empty, x, x-access-token or a placeholder: a token as the username is "other".
Variables ¶
var ErrConfig = errors.New("fakegateway: invalid config")
ErrConfig is wrapped by New's errors for a Config it rejects.
Functions ¶
This section is empty.
Types ¶
type CA ¶
type CA struct {
// contains filtered or unexported fields
}
CA is a per-instance test certificate authority: the stand-in for the agent host's gateway CA (P1 Decision 9). Its leaf certificates are minted on demand, one per intercepted host. Its validity is on the real clock, because the clients that verify it (git, Go's TLS) use it.
type Config ¶
type Config struct {
// RunToken replaces Authorization on the dispatcher route.
RunToken string
// Dispatcher is the upstream URL of DispatcherHost (the test dispatcher).
Dispatcher string
DispatcherHost string
// TaskID binds {id} in DispatcherRoutes; empty matches any task.
TaskID string
// DispatcherRoutes are the only dispatcher requests forwarded; default
// DefaultDispatcherRoutes(). Everything else gets a 403 with DispatcherRefused.
DispatcherRoutes []Route
// GitUpstream serves GitHost's git smart HTTP (a git http-backend server).
GitHost string
GitUpstream string
// Repos maps owner/name to its credential. Keys are case-insensitive and may end in .git; a
// key that isn't owner/name, or two keys that are the same repo, are an error. A repo that
// isn't listed is fetched anonymously and can't be pushed to.
Repos map[string]Repo
// APIUpstream serves APIHost's GETs, with APIToken injected.
APIHost string
APIUpstream string
APIToken string
// Placeholders are the Authorization values that aren't credentials; default
// {DefaultPlaceholder}.
Placeholders []string
// AllowTunnel tunnels CONNECTs (and forwards plain HTTP) to any other host, at any address
// (no egress deny list); else they get 403.
AllowTunnel bool
// CA signs the intercepted hosts' leaves; default a new one.
CA *CA
}
Config configures a Gateway. Hosts default to the real names; an upstream that's empty makes that route answer 502.
type Gateway ¶
type Gateway struct {
// contains filtered or unexported fields
}
Gateway is a running fake gateway.
func (*Gateway) AssertNoClientCredential ¶
AssertNoClientCredential fails t when any request arrived with a credential that was neither absent nor a placeholder, in its Authorization or any other carrier Record.Credentials classifies: the workspace held a credential.
func (*Gateway) Client ¶
Client is the HTTP client that goes through the gateway and trusts only its CA. Close closes its idle connections.
func (*Gateway) Close ¶
func (g *Gateway) Close()
Close stops the gateway: it closes every tunnel and intercepted connection, including a CONNECT still in its TLS handshake, and waits for the handlers in flight, so nothing is recorded after it returns. It is idempotent.
type Record ¶
type Record struct {
Method string
// Host is the request's host name, lower-cased and without the port.
Host string
// Path is the URL path, without the query; empty for a CONNECT.
Path string
// Injected names the credential the gateway added (Injected* or git:<repo>).
Injected string
// Status is the status the client got.
Status int
// ClientAuth classifies the inbound Authorization (ClientAuthNone, "<scheme> placeholder",
// "<scheme> other"). With several values, the first "other" wins.
ClientAuth string
// Credentials classifies the request's other credential carriers, comma-separated in this
// order and only those present: "proxy-authorization <class>" (classified as ClientAuth),
// "x-api-key placeholder|other", "cookie other" and "userinfo basic placeholder|other" (an
// absolute-form URL's). Empty when there were none.
Credentials string
}
Record is one request the gateway saw. It holds no credential values.
type Route ¶
Route is a dispatcher route the gateway forwards: an HTTP method and a canonical path whose segment {id} is Config.TaskID (any one non-empty segment when TaskID is empty). The query isn't matched.
func DefaultDispatcherRoutes ¶
func DefaultDispatcherRoutes() []Route
DefaultDispatcherRoutes are the routes a run's VM needs (P1 §3): its effects only.