aicoded.dev

Outside services

outbound.Client() returns the *http.Client an app calls outside services with. Every request goes to the runner, which sends it only to a host that egress in the permission list names, over HTTPS, adds the key bound to that host, and bounds its size and time. The key never reaches the app's code.

Declaring them

egress lists each outside service by host. An entry is the host alone, or the host with a secret that the runner adds to every request to it:

egress:
  - api.weather.example            # a host alone
  - host: api.partner.example      # a host with a key
    secret: partner_api_key        # a secret declared in secrets
    header: Authorization          # the header the key goes in
    prefix: "Bearer "              # text before the key, if the service wants one
secrets: [partner_api_key]

The permission list has the rules for hosts (E-MAN-018) and bindings (E-MAN-025). In short: a lower-case host name with no scheme, port, path, wildcard or IP address, never one of the platform's own; each host once; a binding names a secret that secrets declares and a header such as Authorization or X-Api-Key.

Calling a service

Keep the client in an unexported field of Deps, and call the service from a method of Deps with the context of the request or job it serves:

// Deps is what an app's pages share, as deps.Deps is in an app. It keeps the client in an
// unexported field: aicoded check refuses a value that holds a client in an exported field when
// it becomes an interface value, as each page's data provider does in the generated code
// (E-LINT-009).
type Deps struct {
	weather *http.Client
}
// New returns Deps with the client whose requests go through the runner.
func New() *Deps {
	return &Deps{weather: outbound.Client()}
}
// Today returns the weather service's summary of today in city. ctx is the context of the
// request or job it serves. The service's host, api.weather.example, is in egress in the
// permission list, and the runner adds the key that egress binds to it.
func (d *Deps) Today(ctx context.Context, city string) (string, error) {
	u := "https://api.weather.example/v1/today?city=" + url.QueryEscape(city)
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, http.NoBody)
	if err != nil {
		return "", err
	}
	resp, err := d.weather.Do(req)
	if err != nil {
		return "", err
	}
	defer func() { _ = resp.Body.Close() }()
	if resp.StatusCode != http.StatusOK {
		return "", fmt.Errorf("the weather service answered %s", resp.Status)
	}
	var today struct{ Summary string }
	if err := json.NewDecoder(resp.Body).Decode(&today); err != nil {
		return "", err
	}
	return today.Summary, nil
}

The key never reaches the code

Limits

What Limit Code
Scheme and port https to port 443; no user name or password in the URL E-OUT-002
Method GET, HEAD, POST, PUT, PATCH, DELETE or OPTIONS E-OUT-002
Host one that egress lists, by its lower-case name, never an IP address E-OUT-001
Address public only: the platform's own hosts, private networks, loopback, link-local and cloud metadata addresses are never reachable, whatever the host resolves to; on the platform, neither are the server's own addresses and the platform's other addresses E-OUT-003
Request body 10 MiB E-OUT-004
Response body 10 MiB E-OUT-005
Time 30 s for the whole request, connecting and reading the body included E-OUT-006
At once 16 requests under way per instance of the app; the 17th is refused at once E-OUT-007
Headers names of letters, digits and - and the other token characters; values without line breaks or other control characters E-OUT-009

What the trace shows

The runner records a span named outbound for every request, in the trace of the request or job that sent it: the host (server.address), the method, the status, the bytes sent and received, the duration, and the code of a refusal (aicoded.outbound.refused). It never records the path, the query, the headers or the bodies, which can hold personal data or keys.

In aicoded dev

aicoded dev sends the requests to the real service on the internet, with the platform's checks of the permission list, the limits and the base list of addresses no app may reach. A bound secret's value comes from dev.yaml, as for any secret: use a test key, never a production one. A service on a private or local address, such as loopback, a private network, link-local or cloud metadata, is unreachable (E-OUT-003). The platform's runner also refuses the addresses of its own server and of the platform; aicoded dev does not refuse your computer's public addresses. The dev UI's Traces page shows each outbound span. See aicoded dev.

On the platform

See also

Markdown · Source on GitHub · framework f46741f