fakegateway

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 28 Imported by: 0

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

View Source
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"
)
View Source
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.

View Source
const (
	InjectedNone     = ""
	InjectedRunToken = "run-token"
	InjectedAPI      = "api-token"
)

Record.Injected values; a git request records "git:<owner>/<repo>".

View Source
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

View Source
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.

func NewCA

func NewCA() (*CA, error)

NewCA creates a CA with a fresh P-256 key, valid from an hour ago for a day.

func (*CA) CertPEM

func (c *CA) CertPEM() []byte

CertPEM is the CA certificate in PEM: what a bundle's gateway/ca.pem holds.

func (*CA) Leaf

func (c *CA) Leaf(host string) (*tls.Certificate, error)

Leaf is the leaf certificate for host (a DNS name or an IP address), minted on first use.

func (*CA) Pool

func (c *CA) Pool() *x509.CertPool

Pool is a certificate pool holding only the CA, for Go clients in tests.

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 New

func New(cfg Config) (*Gateway, error)

New starts a gateway listening on 127.0.0.1.

func Start

func Start(t testing.TB, cfg Config) *Gateway

Start is New for a test: it fails t on an error and closes the gateway in t.Cleanup.

func (*Gateway) AssertNoClientCredential

func (g *Gateway) AssertNoClientCredential(t testing.TB)

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) CA

func (g *Gateway) CA() *CA

CA is the gateway's CA.

func (*Gateway) Client

func (g *Gateway) Client() *http.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.

func (*Gateway) Records

func (g *Gateway) Records() []Record

Records is a copy of what the gateway has seen so far, in order.

func (*Gateway) URL

func (g *Gateway) URL() string

URL is the proxy's URL, for HTTP_PROXY and HTTPS_PROXY.

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 Repo

type Repo struct {
	Token string
	RW    bool
}

Repo is what the gateway may inject for one repository.

type Route

type Route struct {
	Method string
	Path   string
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL