Compute Gateway

Preview Base URL: https://j5afbrmr6qzrwewgxdwacvmedq0ylxvy.lambda-url.us-east-1.on.aws

Overview

Compute Gateway runs a developer’s WebAssembly module on behalf of a person, and lets the module do only what a Granite grant allows.

You publish a module (a WebAssembly file plus a list of the capabilities it needs) to your app’s space in Drive.
The person approves a grant in Granite for your app. Its scopes are the capabilities the module may use, and its limits set how much fuel (counted WebAssembly work) one call may use.
You ask Compute Gateway to run the module for that person. It checks the grant with Granite, reserves fuel through Spend Gateway against the person’s Spend Gateway wallet, runs the module in a sandbox, and charges the fuel the module used.

The module reaches nothing outside the sandbox except through host functions, and Compute Gateway links only the host functions for capabilities the grant holds. Work that touches the person’s data, such as reading a file in their Drive app space, is done by Compute Gateway for that person and that app; the module never names either.

It is for developers who want to run their code for a person without the person handing that code their credentials, and for people who want to see and limit what such code can do.

What preview means here: Compute Gateway is deployed and answers at the base URL above, but no outside developer can use it yet:

It accepts only a person’s ChirpAuth sign-in issued to Compute Gateway itself, and there is no Compute Gateway sign-in page or app. It accepts no machine tokens.
A run is charged to the person’s Spend Gateway wallet. Spend Gateway takes no payments; balances are set by Stackwell.
Some capabilities do not work against the live services; see Concepts.

There is no pricing, and Stackwell does not offer Compute Gateway as a product to outside developers today.

Quickstart

Only the first step works for an outside developer today. The rest shows what a first run needs, so you can see the shape of the service.

1. Check that Compute Gateway is reachable

No credentials needed:

curl -fsS https://j5afbrmr6qzrwewgxdwacvmedq0ylxvy.lambda-url.us-east-1.on.aws/health

{"service":"compute","status":"ok"}

2. What you need before a first run

A credential. A person’s ChirpAuth ID token issued to Compute Gateway’s own sign-in. Nothing issues these to outside developers yet; see Authentication.
A module in Drive. Publish the WebAssembly file and its capability list to Drive under your app id, as {name}@{version}. Drive’s own docs cover publishing. See Concepts for what the module must export.
A Granite grant from the person to your app (the same app id), whose scopes cover every capability the module declares and whose limits include per_call_fuel_cap. See Concepts.
A Spend Gateway grant from the person for your app, and a wallet balance to draw on. Spend Gateway’s own docs cover its grants.

3. Run the module once

curl https://j5afbrmr6qzrwewgxdwacvmedq0ylxvy.lambda-url.us-east-1.on.aws/v1/compute/invoke \
  -H "Authorization: Bearer $CHIRP_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "module_ref": {
      "owner_uid": "<the person'\''s id>",
      "app_id": "acme.hello",
      "name": "main",
      "version": "1.0.0"
    },
    "grant_id": "<the Granite grant id>",
    "payload": "optional input"
  }'

Response, 200 OK, for a module that prints a line and a number:

{"exit":0,"stdout":"from drive\n42\n","output":""}

exit is the value the module’s main returned. stdout is what it printed; output is what it wrote with post_output.

Authentication

Every endpoint except /health and a diagnostics endpoint needs Authorization: Bearer <token>. The live service accepts one kind of token: a person’s ChirpAuth ID token issued to Compute Gateway’s own sign-in. Nothing issues these to outside developers yet. Some endpoints, which act for the person who signed in, never accept a machine token even where machine tokens are enabled. Authentication has the details.

API reference

The full endpoint list is in the generated API reference. API examples walks through each endpoint with responses captured from the service’s own code, and Concepts explains modules, grants, runs and capabilities.

Conventions shared by every endpoint:

Base URL https://j5afbrmr6qzrwewgxdwacvmedq0ylxvy.lambda-url.us-east-1.on.aws.
Request and response bodies are JSON; send Content-Type: application/json.
Run and grant ids are UUIDs.
There are no idempotency keys: every POST /v1/compute/invoke or POST /v1/compute/runs runs the module again and is charged again.

Errors and limits

Errors are JSON, {"error": "<message>"}, except parsing errors, which are plain text. Most failures to run a module, such as a refused grant, a refused reservation, a missing module or a trap, are 400 with a message for people. A service Compute Gateway depends on being down is 503. Each call is bounded by its fuel, 256 MiB of memory and 30 seconds. Errors and limits lists the status codes and every limit.

Data and privacy

Compute Gateway has no database of its own. It keeps run records, connector records and its link to Model Gateway in the person’s Drive, and passes the person’s id to Granite, Spend Gateway, Drive and Model Gateway. It has no endpoint to delete those records. Data and privacy says what is stored, where, and who can read it.

Keyboard shortcuts

Stackwell developers