aicoded.dev

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

  1. 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's secrets, and never write a key anywhere in the app. The permission list has the rules for hosts and bindings.

  2. Keep the client of outbound.Client() in an unexported field of Deps:

    // 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()}
    }
    
  3. Call the service from a method of Deps, with a request made by http.NewRequestWithContext and the context of the request or job it serves, and send it with Do:

    // 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 Authorization header: 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 Data with the context Data gets, as p.d.Today(ctx, city), and returns its error. A call when the app starts uses the context OnStart gets.
    • Escape every value that goes in the URL, as url.QueryEscape does here.

Check it

See also

Markdown · Source on GitHub · framework f46741f