HTTP client

Package names on this page are preview naming and may change before launch.

# pack.ael: calling web APIs needs no package
pack {
    schema = 1;
    dependencies = [];
}

To accept requests instead, you will add the optional server/http package and declare routes; see Services and APIs.

What a request will be

• Typed. A request will carry a method, an address, headers and a body; a response will carry a status, headers and a body. Both will be values your code builds and reads like any other.
• Bounded. Request and response bodies will have a maximum size. A response larger than its limit will be reported as an error, never cut off silently.
• Streamed when you ask. A response will be readable as a stream, with backpressure: the client will read more only when your code is ready for it.
• Deadline-bound. Every request will have a finite deadline, inherited from the work that makes it, and will be cancellable.

Many requests, few threads

The client will be nonblocking. A multi-core, nonblocking runtime will need no thread per user: while one request waits for the network, other work will run, and many requests will be in flight at once without a thread each. Connections to the same service will be reused from a pool with a fixed limit. Programs that don't need worker threads won't get them.

Security

• HTTPS connections will be authenticated with TLS.
• Endpoints and credentials will come from configuration, not from your source. A credential will be passed by reference, so it stays out of your source, your manifest, your logs and command-line arguments.
• Opening a network connection will be an effect, and reaching a destination a permission your program grants. See Effects and capabilities.
• A response will be data. Nothing in it will be able to grant your program a permission or choose where a reply goes.

Retries and resilience

Connections will be resilient, with idempotency-aware retries, backpressure, circuit breakers and health checks.

• A request will be retried only when it is safe to repeat: a read, or a write that carries an idempotency key, which marks every attempt as the same change.
• Retries will wait with a growing, slightly randomized delay, and honour a server's request to wait, but never past the deadline.
• Every attempt and every wait will draw on the budget of the work that made the request, so a retry cannot multiply its cost.
• A write that times out will never be repeated blindly. Its effect will be reported as uncertain, for your code to reconcile.
• The client will make no hidden retries of its own.
• A service that keeps failing will trip a circuit breaker, so new requests fail at once instead of piling up; the breaker will close again when the service recovers.

Failures

A failed request will return a typed error, so your code can react to each case. The kinds of failure will include:

Calling your own services

Code will call a typed service, and the deployment will decide whether it runs in the same process, on another machine, over HTTPS or over gRPC. Your code will stay the same when the service moves. See Tools and MCP.

Models and tools

The Model client and the MCP client (Tools and MCP) will use this client to reach their endpoints, with the same deadlines, budgets and credentials rules.

Where it will run

• Desktop, server and containers: the full client.
• Small networked boards: HTTPS where the board's profile provides networking and TLS. Microcontroller boards lists the boards and their profiles.
• The smallest boards: no network of their own. They reach services through a gateway.

How certificates and network proxies are provided on each target will be described in Platforms and deployment.

Not yet described

The names of the request, response and error types, and of the client's operations, will be published when the library is final.