protos/functions/v1/ and protos/metrics/v1/.
The server mounts three services on one listener:
The built-in web UI and the
@galaxy-io/alchemy-ui module call this same API.
Every RPC has a Connect HTTP POST route at /<package.Service>/<Method>:
server binary listens on ADDR (default :8780). The same listener also
serves the plain HTTP invoke endpoint, /healthz, /scaling and the web UI,
described in HTTP endpoints.
Protocols
The server accepts HTTP/1.1 and unencrypted HTTP/2 (h2c) on the same plaintext port, so all three ConnectRPC wire protocols work against it directly.
A proxy in front of the server must speak HTTP/2 to it for plain gRPC to pass
through.
The Connect protocol is JSON over POST, so any HTTP client works for unary
RPCs. Field names are lowerCamelCase in JSON, and
bytes fields such as
input are base64:
input is {"id":"abc"} in base64. The streaming RPCs,
GetInvocationLogs and TailInvocations, use Connect’s streaming envelope and
need a Connect, gRPC or gRPC-Web client. For invoking from scripts, the
HTTP invoke endpoint takes the raw
input as the body instead.
Unary calls may set a deadline with Connect-Timeout-Ms (or grpc-timeout).
Invoke waits for its result until that deadline, capped at
INVOKE_MAX_DEADLINE (default 1 hour), or INVOKE_DEADLINE (default 5
minutes) when the call sets none.
Authentication
WithAUTH_PROVIDER unset, the API is unauthenticated and every request runs
in the default tenant. Keep such deployments private or protect them at the
network layer.
With a provider configured, every RPC requires a caller except the
AuthService session procedures: GetAuthConfig, Login, GetToken,
Logout, Register and AcceptInvite. How the caller is read depends on the
provider:
The same check guards the HTTP invoke endpoint. See
Authentication for configuring a
provider.
Tenancy
The tenant comes from the caller. A token’s organization (or the gateway’s tenant header) resolves to an Alchemy tenant, created on first sight. With authentication disabled, every request uses the built-in default tenant. Request bodies never select a tenant. Functions, versions, invocations, instances, secrets and metrics are scoped to it.ListHosts and GetHost
report the cluster’s hosts, which every tenant of the deployment shares.
Pagination
ListFunctions, ListFunctionVersions and ListInvocations take an optional
PaginationRequest.
The response’s
PaginationResponse carries total, the count before the page
was cut, and previous_cursor and next_cursor when a page exists in that
direction. Omitting pagination returns every row, up to 10,000. A cursor the
server cannot decode is invalid_argument.
Errors
Failures are standard Connect error codes. These are the codes the server returns.
Some specifics worth knowing:
- An input that violates its contract is
invalid_argumentwith onefunctions.v1.ContractViolationerror detail per failure. failed_preconditioncovers invoking a function with no ready version or a version that is not ready,spec.secretsorsecret_valueson a server with no secret provider,spec.sourceon a server with no artifacts bucket, and anidempotency_keyonInvokewhen the server has no logs bucket.- A function that ran and failed is not an RPC error.
Invokesucceeds and its response carries aFunctionError.
API areas
Functions
Functions, their immutable versions, and the runtimes a source can build on.
Invocations
Invoking, reading invocation records, streaming logs and live transitions.
Hosts
The live hosts and the microVMs they are running.
Secrets
How a function version names and creates tenant secrets.
Metrics
Timeseries, aggregates and the in-flight queue.
HTTP endpoints
Plain HTTP invoke, health and the autoscaling feed.