Call an outside service
Call a service on the internet over HTTPS, with a key the runner adds so that the app never reads
it. The example asks a weather service for a city's weather, from a method of the app's Deps.
Steps
-
Declare the service in the permission list. A service that needs no key is a host alone; one that needs a key binds a secret to the header the service reads it from:
egress: - host: api.weather.example secret: weather_api_key header: Authorization prefix: "Bearer " secrets: [weather_api_key]Ask the developer to put a test key in
dev.yaml, under the app'ssecrets, and never write a key anywhere in the app. The permission list has the rules for hosts and bindings. -
Keep the client of
outbound.Client()in an unexported field ofDeps:// 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()} } -
Call the service from a method of
Deps, with a request made byhttp.NewRequestWithContextand the context of the request or job it serves, and send it withDo:// 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 request sets no
Authorizationheader: the runner adds it, and replaces one the app sets.secrets.Get(ctx, "weather_api_key")fails with E-RUN-015. - A page calls it from
Datawith the contextDatagets, asp.d.Today(ctx, city), and returns its error. A call when the app starts uses the contextOnStartgets. - Escape every value that goes in the URL, as
url.QueryEscapedoes here.
- The request sets no
Check it
aicoded checkrefuses any other HTTP client, and any change to this one (E-LINT-009).aicoded devsends the request to the real service with the key fromdev.yaml. The dev UI's Traces page shows the page's request with a spanoutboundthat names the host, the method and the status, and never the path, the headers or the key.- A host missing from
egressis E-OUT-001; the other refusals and the limits are in outside services. - On the platform, the new binding Needs approval: the approver sees which key goes to which outside service.