Documentation versions

文档版本

Gateway documentation follows the same stable and development-channel model as A3S Cloud. The selected version stays visible in the navigation and version switches preserve the current section.

Gateway 文档采用与 A3S Cloud 一致的稳定版和开发通道模型。导航栏始终显示当前版本，切换版本时会保留正在阅读的章节。

v1.0Stable稳定版

Released 1.0.x behavior and operator contracts. This is the default, indexable route.

已发布的 1.0.x 行为和运维契约。这是默认且可被索引的路由。

nextDevelopment开发通道

Forward-looking documentation under active development. It is not release evidence.

持续更新的前瞻文档，不作为版本已交付的证据。

The registry, Cargo major/minor series, routes, and section parity are checked before deployment. See the 发布前会检查版本注册表、Cargo 主次版本、路由和章节一致性。查看 product roadmap产品路线图 for maturity and promotion gates. 了解成熟度与晋级门槛。

Runtime model

运行时模型

Gateway binds listeners, matches routes, applies local policy, selects healthy backends, and relays HTTP, SSE, WebSocket, gRPC, TCP, or UDP. Every request uses one validated runtime snapshot.

Gateway 绑定监听器、匹配路由、执行本地策略、选择健康后端，并转发 HTTP、SSE、WebSocket、gRPC、TCP 或 UDP。每个请求只使用一个已校验的运行时快照。

Feature status and roadmap

特性状态与路线图

The status column separates shipped Gateway behavior from local foundations, experiments, and planned cross-product work. A foundation is usable inside Gateway but does not claim that the complete A3S Cloud workflow is finished.

状态列把已交付的 Gateway 行为与本地基础、实验能力和计划中的跨产品工作分开。“Gateway 基础已提供”表示本地部分可用，但不代表完整 A3S Cloud 工作流已经完成。

Current delivery

当前交付

Planned work and open proof

计划能力与待完成验证

Install

安装

The installers detect the platform, download a release archive, verify its published SHA-256 checksum and binary version, then replace the user-local executable.

安装脚本会检测平台、下载发布归档、校验已发布的 SHA-256 和二进制版本，然后替换用户目录中的可执行文件。

macOS / Linux

curl --proto '=https' --tlsv1.2 -LsSf https://a3s-lab.github.io/Gateway/install.sh | sh

Windows PowerShell

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
irm https://a3s-lab.github.io/Gateway/install.ps1 | iex

Cargo / Homebrew

cargo install a3s-gateway
# or
brew install a3s-lab/tap/a3s-gateway

First route

第一条路由

Start an HTTP backend on port 8000, save the following file as gateway.acl, validate it, and start Gateway.

先在 8000 端口启动一个 HTTP 后端，把下面的内容保存为 gateway.acl，完成校验后启动 Gateway。

mode { kind = "standalone" }

entrypoints "web" {
  address = "127.0.0.1:8080"
}

routers "models" {
  rule        = "PathPrefix(`/v1`)"
  service     = "models"
  entrypoints = ["web"]
  middlewares = ["rate-limit"]
}

middlewares "rate-limit" {
  type  = "rate-limit"
  rate  = 60
  burst = 10
}

services "models" {
  load_balancer {
    strategy             = "least-connections"
    request_timeout      = "30s"
    stream_idle_timeout  = "5m"
    stream_total_timeout = "60m"
    servers = [{ url = "http://127.0.0.1:8000" }]
  }
}

a3s-gateway validate --config gateway.acl
a3s-gateway config --config gateway.acl summary
a3s-gateway --config gateway.acl

curl http://127.0.0.1:8080/v1/models

ACL configuration model

ACL 配置模型

ACL is the configuration source of truth. References are resolved before listeners change. A router must name an existing service, middleware, and entrypoint; every service needs at least one server or revision target.

ACL 是配置事实源。Gateway 会在监听器变化前解析全部引用。路由必须引用已有的服务、中间件和 entrypoint；每个服务至少要有一个 server 或 revision target。

Routing and services

路由与服务

Rules support host, path prefix, method, header, and SNI conditions. Explicit priority decides evaluation order. The selected service uses round-robin, weighted, least-connections, or random balancing after health filtering.

规则支持 Host、PathPrefix、Method、Header 和 SNI 条件。显式 priority 决定评估顺序。选中的服务在健康过滤后使用 round-robin、weighted、least-connections 或 random 均衡。

routers "chat" {
  rule        = "Host(`api.example.com`) && PathPrefix(`/v1/chat`)"
  service     = "models"
  entrypoints = ["web"]
  middlewares = ["auth", "limits"]
  priority    = 100
}

• request_timeout bounds connection and first response.request_timeout 限制连接和首响应等待。
• stream_idle_timeout resets when a body chunk arrives.stream_idle_timeout 在收到 body chunk 后重新计时。
• stream_total_timeout is an absolute operation bound.stream_total_timeout 是整个操作的绝对上限。
• Retry and failover are allowed only before the upstream response starts.重试和故障转移只允许发生在上游响应开始前。

Middleware pipeline

中间件处理链

The router's middlewares list is ordered. Request hooks run left to right and may short-circuit with a response. Response header and bounded body hooks run right to left. One middleware definition can be reused by multiple routers.

路由的 middlewares 列表有顺序。请求钩子从左到右执行，并可直接返回响应中止后续流程；响应 header 和有界 body 钩子从右到左执行。一个中间件定义可以被多个路由复用。

routers "models" {
  rule        = "PathPrefix(`/v1`)"
  service     = "models"
  entrypoints = ["web"]
  middlewares = ["auth", "limits", "security-headers"]
}

middlewares "auth" {
  type   = "api-key"
  header = "X-API-Key"
  keys   = ["replace-me"]
}

middlewares "limits" {
  type = "body-limit"
  max_body_bytes = 8388608
}

middlewares "security-headers" {
  type = "headers"
  response_headers = [{ name = "X-Content-Type-Options", value = "nosniff" }]
}

Built-in catalog

内置目录

Custom middleware in Rust

使用 Rust 自定义中间件

An embedded deployment can implement the public Middleware trait, register the value by a stable router-facing name, and create Gateway with Gateway::with_middlewares. Custom and built-in middleware can appear in the same ordered route list.

嵌入式部署可以实现公开的 Middleware trait，用稳定的路由引用名称注册实例，再通过 Gateway::with_middlewares 创建 Gateway。自定义和内置中间件可以出现在同一个有序路由列表中。

use a3s_gateway::{Gateway, Middleware, MiddlewareRegistry, RequestContext, Result};
use a3s_gateway::config::GatewayConfig;
use async_trait::async_trait;
use http::{request::Parts, HeaderValue, Response};

struct TenantPolicy;

#[async_trait]
impl Middleware for TenantPolicy {
    async fn handle_request(
        &self,
        request: &mut Parts,
        _context: &RequestContext,
    ) -> Result<Option<Response<Vec<u8>>>> {
        request.headers.insert(
            "x-policy-source",
            HeaderValue::from_static("tenant-policy"),
        );
        Ok(None)
    }

    fn name(&self) -> &str { "tenant-policy" }
}

#[tokio::main]
async fn main() -> Result<()> {
    let config = GatewayConfig::from_file("gateway.acl").await?;
    let mut middleware = MiddlewareRegistry::new();
    middleware.register("tenant-policy", TenantPolicy)?;

    let gateway = Gateway::with_middlewares(config, middleware)?;
    gateway.start().await?;
    gateway.wait_for_shutdown().await;
    Ok(())
}

routers "models" {
  rule        = "PathPrefix(`/v1`)"
  service     = "models"
  entrypoints = ["web"]
  middlewares = ["tenant-policy", "rate-limit"]
}

# No middlewares "tenant-policy" block: Rust supplies that name.

Performance measurements

性能测量与结果

Criterion measures in-process operations. The proxy matrix measures every supported data-plane traffic type against NGINX on the same runner and shared local upstreams.

Criterion 测量进程内操作；代理矩阵在同一 runner 和共享本地上游上，对 A3S Gateway 支持的所有数据面流量类型与 NGINX 进行测试。

Feature-free HTTP, finite SSE, and standalone OpenAI profiles use the startup-bound direct relay and one sharded Hyper upstream pool. A startup-bound single backend also skips backend-operation counters because routing, scaling, concurrency, and telemetry consumers are absent. TLS, HTTP/2, gRPC, feature-bearing streaming, upgrade, and layer-4 profiles retain their protocol-specific paths.

无附加功能的 HTTP、有限 SSE 和独立 OpenAI 场景使用启动时绑定的直达转发与同一组分片 Hyper 上游连接池。启动时绑定的单一后端还会跳过后端操作计数，因为路由、扩缩容、并发控制和遥测均不会读取该计数；TLS、HTTP/2、gRPC、带功能的流式、升级和四层场景保留各自的协议路径。

Internal Criterion baseline

内部 Criterion 基线

Same-host protocol matrix

同机协议矩阵

OpenAI JSON and stream rows enable bounded A3S request validation and the shared streaming response relay while NGINX performs transport-only forwarding. Use those rows to quantify feature cost, not as an equivalent policy comparison.

OpenAI JSON 与流式场景中，A3S 开启有界请求校验并使用共享流式响应转发，NGINX 仅执行传输转发。这两行用于量化功能成本，不作为等价策略能力对比。

This run used the same image and EPYC 9V74 as the preceding 68c5d2d run. The WebSocket-only change measured +0.03%, while eight other non-gRPC A3S medians stayed between -1.2% and -0.4%. Untouched gRPC varied by -19% and NGINX HTTP/2 also moved materially, exposing shared-runner protocol noise. Treat this as regression evidence, not an isolated speedup or capacity forecast.

本次与紧邻的 68c5d2d 运行使用相同镜像和 EPYC 9V74。仅 WebSocket 的改动测得 +0.03%，其余 8 个非 gRPC A3S 中位数在 -1.2% 至 -0.4%；未受改动的 gRPC 波动 -19%，且 NGINX HTTP/2 也有明显变化，说明共享 runner 存在协议级噪声。本数据仅作为回归证据，不作为单项加速或容量预测。

Criterion JSON / Protocol matrix JSON / Workflow run / Benchmark source

A3S Cloud integration

A3S Cloud 集成

The Node API exposes health, metrics, version, and managed snapshot operations. A3S Cloud provides deployment, rollout, tenancy, and the long-term usage ledger.

Node API 提供健康、指标、版本和受管快照操作；A3S Cloud 提供部署、发布、租户和长期用量账本。

Troubleshooting

故障排查

Open an issue with the redacted ACL, Gateway version, validation output, and the smallest reproducible request.提交 issue 时请附上脱敏 ACL、Gateway 版本、校验输出和最小复现请求。