Appearance
Transport and limits
xgress3 relays HTTP over a single outbound tunnel from your agent to the regional gateway. Multiple client requests share that tunnel at the same time. Gateway and agent must be deployed together at the same version — mixed versions are not supported in production.
This page describes what you can configure, what behavior to expect, and errors you may see — without platform-side capacity numbers (those vary with deployment and scale).
For ingress authentication and hostnames, see Overview and Ingress authentication.
How traffic flows
- The client calls your public service hostname (
https://{account}--{service}.{region}.xg3.io/...). - The gateway authenticates the request and checks service policy.
- The agent receives the relayed request on the tunnel and forwards it to your backend.
- The response returns on the same path. Every response includes
X-Xg3-Request-Id.
Agent limits (operator-controlled)
These apply on your agent host and are the main throughput knob you control.
| Limit | Default | Configure |
|---|---|---|
| Concurrent backend requests | 128 per tunnel | XG3_AGENT_MAX_CONCURRENT_BACKEND_REQUESTS |
bash
export XG3_AGENT_MAX_CONCURRENT_BACKEND_REQUESTS=256Raise this only when your backends can absorb additional parallel connections and CPU. Invalid or non-positive values fall back to 128.
When the agent cannot accept another concurrent forward, or a backend forward fails unexpectedly, the gateway returns 502 with Content-Type: application/vnd.xg3.error+json and a message such as Concurrent backend request limit exceeded.
See Agent operations for tunnel behavior, reconnection, and exit codes.
Parallel downloads and response pacing
All relayed requests share one tunnel. xgress3 paces each response independently: a slow or large download should not block other requests on the same service from starting or receiving their response headers.
What you should observe
- Several downloads or API calls in parallel complete without one large file stalling small requests for many seconds in the browser (“Waiting for server response”).
- Cancelling or closing a large download mid-stream should not permanently reduce how many concurrent requests the agent can handle.
If you still see long delays on small requests while a large download runs
- Confirm the agent is on a current release.
- Check the agent is connected in the console and the service is enabled.
- Review agent logs under
{data-dir}/logs/— the agent may have received requests while the client still waited at the gateway. - Contact support with
X-Xg3-Request-Idfrom a slow request.
Ingress errors you may see
These are customer-visible outcomes. They do not expose internal platform capacity.
| HTTP | X-Xg3-Status or body | Typical cause |
|---|---|---|
| 429 | RateLimited | Too many requests to this service in a short period |
| 502 | Policy / validation codes | Auth deny, headers too large, relay error — see Deny codes |
| 502 | Agent error JSON | Agent concurrency exceeded or backend forward failed |
| 504 | AGENT_UNAVAILABLE | No active tunnel (agent offline or reconnecting) |
The gateway validates caller identity and service policy before relaying. The agent does not validate JWT or service keys.
Platform API rate limits
Enrollment and token endpoints on the regional apex (https://{region}.xg3.io) are rate-limited to protect the platform. If you automate enrollment or token minting, use exponential backoff on 429 responses and avoid tight polling loops.
| Endpoint | Guidance |
|---|---|
POST /enroll | One enrollment flow per agent; do not burst |
GET /enroll/status | Poll at reasonable intervals (agent handles enrollment internally in normal installs) |
POST /oauth/token | Cache tokens until near expiry; do not mint on every API call |
Production agents use the tunnel for renewal — not repeated CSR REST calls.
Request logging limits
When Capture backend response is enabled on a service (console), xgress3 stores backend response bodies in request logs up to 1 MB per request; larger bodies are truncated. Request lookup retains records for 7 days.
See Request logging.
Tunnel keepalive and reconnection
- The agent sends application heartbeats on the tunnel so the connection stays active during idle periods.
- The gateway and network stack use transport keepalive to detect abrupt disconnects (for example unplugged cable) within tens of seconds.
- On tunnel loss, the agent reconnects with exponential backoff (1 s → 120 s cap, resetting to 1 s after a prior successful connection). No operator action is required.
Details: Agent operations — Reconnection.
What is not limited on the agent side
- Backend HTTP timeout: the agent does not impose a fixed timeout on calls to your backend; long-running backend work continues until the client or gateway ends the relay.
- Request body size: no separate agent-side cap beyond what the gateway relays and your backend accepts.
Ensure your backends and any upstream proxies tolerate the concurrency you configure on the agent.
Related documentation
- Agent operations — concurrency, reconnection, renewal, exit codes
- Ingress authentication — JWT and service keys
- Deny codes — 502 policy and validation errors
- Troubleshooting — console workflows
- Request logging — capture and lookup