Egress #
On this page
Egress is your application's side of the egress gateway. The gateway lets a backend on Turn Zero Cloud call an external application programming interface (API) with a stored key. The gateway adds the key to the request and never gives it to your process. It removes the key's header from the upstream's response and passes the rest through. So an upstream that echoes the key in its body returns it to your process.
This package's client sends the call, tells you whether a response came from the gateway or from the upstream, and reads a streamed response frame by frame. Egress firewall and request limits describes the gateway itself, and Call an external API with an API key the task.
Use it when #
Use Egress by default for an API with a stored key, such as an AI provider, a payments API, or a search API. If the client's host is fixed in code the task forbids changing, follow the binding exception instead. Store the key once, declare the upstream against the key's name, and call /egress/v0/<upstream>/<path> through the client under your application's platform credential. The provider bills your own provider account. When you rotate the key in custody, no application code changes.
To use a provider's SDK (client library) unchanged, declare the upstream with sdk_settings; no Egress package is needed. Each deploy gives the SDK an egress key, which the gateway replaces with your stored provider key. The SDK does not receive this package's typed refusals (An unchanged SDK).
For a destination that needs no stored key, add its host to the manifest's egress list. Ordinary fetch then reaches it through the HTTPS tunnel (Egress firewall and request limits).
What it provides #
- A client,
EgressClient, which calls through a transport function your application supplies. The client describes it. - One call per request. The method
call(upstream, path, init)sends the method, the headers, the body, and the query string unchanged. It returns the upstream's own response, whatever its status, when the response has the gateway's marker headerx-egress-upstream. The gateway adds that header to every response that came from an upstream. - A typed refusal,
GatewayRefusal, thrown for every response without the marker header. That covers the gateway's own refusals, the platform's authentication challenge, and a response to a request that never reached the gateway. Each has the refusal's name, its status, its detail, and akindthat says what to do. - A frame reader,
readEventStream, for an upstream that responds with an event stream. It returns each frame in order as it arrives, and it follows your abort signal. It throwsegress_error, the one final event the gateway can send inside the stream, as the same typed refusal. - A test double,
createEgressDoubleat@turnzero/egress/testing, which takes the gateway's place behind the unchanged client. Test with the double shows it in use.
The client adds no header, no retry, no timeout, and no limit of its own. The gateway removes some headers before the request reaches the upstream, among them the forwarding headers a proxy adds and the platform's own: What the upstream receives lists them. The gateway limits the request size, the response size, and the upstream's time, and refuses a call over each limit by name. The package never switches to another provider: write any fallback in your application.
If the manifest includes upstreams, declare the upstream there. Otherwise call declare_outbound_api (Declare in the manifest). Edit a manifest-declared upstream in the manifest; declare_outbound_api refuses to change it with manifest_owned_field.
Availability #
Version 0.19.2 is the package's current version, and this page describes it. Until the library's next publish, read_library can return an earlier version, the one you can take, so this page can describe a change that version lacks. The entry includes the testing subpath. The entry contains the compiled client, the package's product statement and detailed contract, and its integration guide. The platform runs the egress gateway and counts use per upstream.
Related feature packages #
Secrets stores the keys the gateway adds. Logging records what your backend does with an upstream's response. Node.js Runtime routes calls through the tunnel to destinations that use no stored key. AI Allowance is the platform's own upstream, with its own package.
The client #
The package is published in the library as the npm package @turnzero/egress, not on the npm registry; Use the library installs it with one line. Call it from a route shows the client in a complete backend route, which a test checks.
Construction #
Build the client with new EgressClient(transport). Your function transport(path, init) adds the gateway's origin and your credential, sends the request, and returns the response. A deployed transport reads the gateway's origin from TURNZERO_CLOUD_GATEWAY_URL, or from TURNZERO_CLOUD_API where that is unset, and the credential from TURNZERO_CLOUD_APP_TOKEN, among the settings a deployed copy receives.
Where your backend runs under a minted token or a session, rather than its platform credential, set the environment once on its transport with the header x-turnzero-cloud-environment. Every gateway call then sends it. The Storage package's withEnvironment wraps a transport used only for storage the same way.
Methods and results #
- The method
call(upstream, path, init)sends one call to/egress/v0/<upstream><path>and returns the upstream's response. Itsinittakesmethod,headers,body, andsignal, each passed through unchanged. - The method
upstream(name)returns a function bound to one upstream,(path, init) => call(name, path, init). - The static method
EgressClient.pathFor(upstream, path)returns the path a call sends. A malformed upstream name throwsTypeErrorbefore any call. - The function
readEventStream(response, { signal })returns the frames of an event stream in order, each{ event, data, id }.
Confirm a call went through the gateway #
After you deploy, trigger the code that calls the provider. In your signed-in AI tool, call list_outbound_apis and find the upstream bound to your application. Compare last_call.at with the time of your test. The entry shows the latest HTTP call the gateway tried to forward for that upstream and application in the past seven days.
Read outcome for the gateway's result and status for the provider's HTTP status. If status is null, no HTTP response reached the gateway. The result covers both environments, so test when you can distinguish your call from other traffic.
If last_call is missing or older than your test, check that your code called the declared upstream through the gateway. The entry leaves out CONNECT tunnels and calls the gateway refused before forwarding. See the list_outbound_apis reference for the outcome values.
Failures #
A GatewayRefusal has error, the refusal's name, and status, detail, kind, upstream, and path. Where supplied, scope describes what the credential is bound to. The refusal's challenge carries the WWW-Authenticate header where the response is the platform's authentication challenge. Choose what to do by its kind:
kind |
Names | What to do |
|---|---|---|
declaration |
unknown_upstream, undeclared_upstream, upstream_scope_refused, refused_base_url, refused_platform_host, and the address refusals egress_private_address, egress_loopback_address, egress_link_local_address, egress_reserved_address, and egress_platform_address |
Correct the upstream's declaration. An address refusal means the declared host resolved, at the call, to an address that is not public (Address and host checks). |
credential |
credential_not_in_custody, credential_unreadable, platform_minted_name |
Store the credential the declaration gives. For platform_minted_name, the declaration gives a credential the platform mints for its own use: store your key under a name of your own and declare the upstream with it. |
bounds |
request_too_large, response_too_large, upstream_timeout |
Stay within the platform limit the refusal gives. |
transport |
upstream_unreachable, internal, store_unavailable, credential_lookup_busy |
Retry the call. For credential_lookup_busy, wait one second, then call again. |
authentication |
authentication_required, insufficient_scope, account_suspended, end_user_credential_not_admitted, transfer_grant_not_admitted, egress_key_not_admitted |
Refresh your application's own credential. For egress_key_not_admitted, an egress key was sent outside its own upstream: send it only to that upstream. |
environment |
environment_required, environment_mismatch |
Set the environment on the request. |
admission |
rate_capped, egress_daily_bytes_capped |
The platform's rate limit refused the call, or the application reached its outbound-byte limit for the UTC day. Wait, then call again: for the day limit, after the reset time the refusal's detail gives. |
address |
retired_host, misdirected_origin |
The request did not reach the platform through its public address. It used a retired hostname, a service's internal hostname, or a missing or wrong header from the platform's public entry service. Use the address in the refusal's detail. Retrying the same address fails again. |
unrecognized |
Any other name | This client version does not recognize the name. Read its error and status. |
unmarked |
unmarked |
The request never reached the gateway. Check the route your transport builds. |
A refused tunnel connection raises a different error: the runtime harness's EgressRefusedError, found in the cause of a rejected fetch. Node.js Runtime describes it.
Test with the double #
The function createEgressDouble() from @turnzero/egress/testing takes the gateway's place behind the real client. Declare each upstream with double.declare(name, handler, { application }), giving the application it is bound to, and the handler responds to that upstream's calls. Build EgressClient over double.transport, or stub the global fetch with double.fetch where your own transport wraps it. Calling reset() empties the recorded calls and keeps the declarations. Where your transport sends the environment header, as a local run under your own sign-in does, create the double with credential: 'session'. A test runs this sample over the double.
import assert from 'node:assert/strict';
import { EgressClient, GatewayRefusal } from '@turnzero/egress';
import { createEgressDouble } from '@turnzero/egress/testing';
const egress = createEgressDouble();
egress.declare('weather', (request) => ({ json: { path: request.path, query: request.query } }), { application: 'app' });
const client = new EgressClient(egress.transport);
const answer = await client.call('weather', '/v1/now?city=Oslo');
assert.equal(answer.status, 200);
assert.deepEqual(await answer.json(), { path: '/v1/now', query: 'city=Oslo' });
// An upstream the test never declared is the gateway's own refusal, thrown by the client.
await assert.rejects(client.call('maps', '/v1/route'), (error) => error instanceof GatewayRefusal && error.error === 'undeclared_upstream');
The client throws GatewayRefusal, with the refusal's name in error and its kind, as Failures lists. Where a refusal is the test's subject, assert the name instead of applying the remedy. The double returns these refusals for faults in its own setup:
| Refusal | Cause | Remedy |
|---|---|---|
undeclared_upstream, unknown_upstream |
The call named an upstream the test never declared, or none. A name containing a NUL character (U+0000) or an unpaired UTF-16 surrogate reads as no name. | Declare the upstream with double.declare, and send its name without the character. |
upstream_scope_refused |
The upstream is declared for an application the double's credential does not reach. | Declare it for the application of the double's scope. |
credential_not_in_custody |
The upstream was declared with credentialHeld: false. |
Declare it with the credential held. |
request_too_large, response_too_large |
The request or the response passed a size limit. | Keep the body within requestBytes or responseBytes. |
upstream_unreachable |
The handler threw, or responded with fail. |
Return a response from the handler. |
authentication_required, environment_required, environment_mismatch |
The double requires a bearer and got none, or the environment header is missing or wrong. | Send Bearer and the credential, and send the environment that the double's environment option gives. |
unmarked |
The request did not use the gateway path that includes its upstream key. | Call through the client. |
TypeError from declare |
The upstream's name is outside the allowed form, or the options give no application (application_required), or an empty or non-string application (invalid_request). |
Use the name the application declares, and pass { application }, the application's id as a string. |