The external entry point into the Airymax runtime: every inbound HTTP, HTTP/2, WebSocket, SSE, Stdio, MCP, A2A, or OpenAI-compatible request is translated into a unified JSON-RPC 2.0 call and dispatched to the runtime.
Language: English | 简体中文
- Repository: https://atomgit.com/openairymax/gateway
- Version: 0.1.16
- Artifact: static library
gateway
gateway is the protocol gateway layer of the Airymax agent runtime. It sits between external clients and the runtime core: it accepts inbound HTTP, HTTP/2, WebSocket, SSE, and Stdio traffic, auto-detects the wire protocol (JSON-RPC, MCP, A2A, OpenAI-compatible), normalizes it into JSON-RPC 2.0, and forwards it inward — either through the syscall interface (atoms/syscall) or through a thin business-delegation layer that calls backend service endpoints (LLM, tool-execution, scheduling).
Its focus is protocol translation and connection management, not application logic: business decisions are handed off to the runtime. The module additionally provides cross-cutting boundary controls — token-bucket rate limiting, entry authentication (fail-closed, loopback-aware), URL sanitization, and CORS.
external client ──► gateway ──► JSON-RPC 2.0 ──► runtime (syscall / backend services)
(HTTP/HTTP2/WS/SSE/Stdio · MCP/A2A/OpenAI)
The gateway library is intended to be embedded and launched by a host process (for example a gateway daemon) that owns the event loop and graceful-shutdown lifecycle.
| Area | Detail |
|---|---|
| Transports | HTTP/1.1 (libmicrohttpd), HTTP/2 (nghttp2, POSIX only), WebSocket (libwebsockets), SSE, Stdio REPL |
| Protocol handling | Auto-detect and convert JSON-RPC 2.0, MCP, A2A, and OpenAI-compatible request bodies to a single internal JSON-RPC 2.0 shape |
| Inward dispatch | Route JSON-RPC methods to the syscall interface, or forward business calls (agent.run, tools/call, embeddings, task scheduling) to backend service endpoints |
| Streaming | Server-Sent Events for chat stream, agent run stream, and hall event watch |
| Boundary security | Entry authentication (fail-closed, loopback-aware), token-bucket rate limiting (per IP / per API key), URL sanitization, CORS |
| Operations | /health and /metrics endpoints |
The library target gateway is built from two source areas:
| Area | Path | Responsibility |
|---|---|---|
| Transports | src/gateway/ |
HTTP, HTTP/2, WebSocket, SSE, Stdio servers; endpoint authentication; protocol bridge; hall event read/write; southbound A-IPC client face |
| Shared utilities | src/utils/ |
JSON-RPC 2.0 helpers, syscall router, RPC handler, protocol detect/convert, rate limiter |
Business delegation (unified protocol entry, agent.run/tools/call/embeddings/scheduling forwarding, capability registry, PEP cache) is a product piece at products/gateway_biz/, assembled by the gateway daemon host and not part of the gateway mechanism core.
The same source list is shared with the gateway daemon host via cmake/gateway-sources.cmake.
gateway/
├── CMakeLists.txt # CMake build (static library `gateway`)
├── cmake/
│ └── gateway-sources.cmake # Source list shared with the daemon host
├── include/
│ ├── gateway.h # Public API (lifecycle / control / query)
├── src/
│ ├── gateway/ # Transport layer
│ │ ├── gateway_api.c # Public API implementation
│ │ ├── http_gateway.[ch] # HTTP/1.1 server (libmicrohttpd)
│ │ ├── http_gateway_routes.[ch] # Static HTTP route table + entry auth gate
│ │ ├── http_gateway_sse*.c # SSE base + frame/stream/run/hall/memory/tool
│ │ ├── http2_gateway*.[ch] # HTTP/2 server (nghttp2, POSIX only)
│ │ ├── ws_gateway*.[ch] # WebSocket server (libwebsockets)
│ │ ├── stdio_gateway.[ch] # Stdio REPL gateway
│ │ ├── gateway_auth.[ch] # Entry authentication
│ │ ├── gateway_hall_store.[ch] # Hall event recording (write side)
│ │ └── gateway_aipc_client.[ch] # Southbound A-IPC unified client face
│ └── utils/ # Shared utilities
│ ├── jsonrpc.[ch] # JSON-RPC 2.0 validate / respond
│ ├── syscall/ # JSON-RPC method → syscall dispatch
│ ├── gateway_rpc_handler.[ch] # Shared RPC handling for all transports
│ ├── gateway_protocol_*.[ch] # Protocol detect / convert / handler
│ └── gateway_rate_limiter.[ch] # Token-bucket rate limiter
├── tests/ # Unit tests + benchmark
├── deploy/ # Kubernetes manifests (see deploy/README.md)
└── config/ # Static-analysis config (see config/README.md)
The static route table (see src/gateway/http_gateway_routes.c):
| Method | Path | Streaming | Auth | Purpose |
|---|---|---|---|---|
POST |
/ |
no | yes | JSON-RPC 2.0 entry (also MCP / A2A / OpenAI bodies) |
POST |
/api/v1/agent/run/stream |
SSE | yes | Agent run stream |
GET |
/api/v1/hall/watch |
SSE | no | Hall event watch |
OPTIONS |
* |
no | no | CORS preflight |
GET |
/health |
no | no | Liveness / readiness |
GET |
/metrics |
no | yes | Metrics export |
The public surface (include/gateway.h) is intentionally minimal —
lifecycle only. Instances are created by the transport constructors
declared in src/gateway/*.h and shared with the daemon host via
cmake/gateway-sources.cmake:
| Function | Declared in | Description |
|---|---|---|
http_gateway_create(host, port) |
src/gateway/http_gateway.h |
Create an HTTP/1.1 gateway instance |
http2_gateway_create(host, port) |
src/gateway/http2_gateway.h |
Create an HTTP/2 gateway instance (POSIX only) |
ws_gateway_create(host, port) |
src/gateway/ws_gateway.h |
Create a WebSocket gateway instance |
stdio_gateway_create() |
src/gateway/stdio_gateway.h |
Create a Stdio gateway instance (blocking REPL after start) |
gateway_start(gw) |
include/gateway.h |
Start the gateway (HTTP/WS non-blocking; Stdio blocking) |
gateway_destroy(gw) |
include/gateway.h |
Destroy the instance and release resources (stops a running gateway automatically) |
#include "gateway.h"
#include "http_gateway.h"
int main(void) {
gateway_t *gw = http_gateway_create("0.0.0.0", 8080);
if (!gw) return 1;
gateway_start(gw);
/* the gateway serves until destroyed */
gateway_destroy(gw); /* stops + frees */
return 0;
}GATEWAY_SUCCESS (0), GATEWAY_ERROR_INVALID (-1), GATEWAY_ERROR_MEMORY (-2), GATEWAY_ERROR_IO (-3), GATEWAY_ERROR_TIMEOUT (-4), GATEWAY_ERROR_CLOSED (-5), GATEWAY_ERROR_PROTOCOL (-6).
Boundary rejections are reported as JSON-RPC errors: authentication failure (-32001), unsafe URL (-32002), rate limit exceeded (-32004), parse error (-32700), method not found (-32601), oversized request (413), internal error (-32603).
# Requires cJSON development headers (hard dependency).
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON -DBUILD_BENCHMARK=ON
cmake --build build --target gateway --parallel
# Tests
ctest --test-dir build --output-on-failure
# Static analysis & formatting
cmake --build build --target cppcheck
cmake --build build --target formatCMake options:
| Option | Default | Effect |
|---|---|---|
BUILD_TESTS |
ON |
Build the unit-test targets (disabled on Windows) |
BUILD_BENCHMARK |
ON |
Build the benchmark target (Linux only) |
Conditional compilation:
| Feature | Macro | Behavior when absent |
|---|---|---|
| cJSON | AIRY_HAS_CJSON |
Hard failure — FATAL_ERROR (stub libraries are not supported) |
| HTTP/1.1 | AIRY_HAS_MICROHTTPD → GATEWAY_HAS_HTTP |
HTTP gateway unavailable |
| WebSocket | AIRY_HAS_LIBWEBSOCKETS |
WebSocket gateway unavailable |
| HTTP/2 | AIRY_HAS_HTTP2 |
HTTP/2 gateway unavailable; always disabled on Windows (POSIX only) |
| libcurl | AIRY_HAS_CURL |
Benchmark runs in simulation mode |
Artifact: static library gateway; public headers install under include/agentrt/gateway.
The gateway is configured through environment variables (there is no JSON config file).
| Variable | Purpose |
|---|---|
GATEWAY_API_KEY |
API key for entry authentication |
GATEWAY_RATE_LIMIT_ENABLED / _RPS / _RPM |
Enable rate limiting; requests per second / minute |
GATEWAY_CORS_MODE / GATEWAY_CORS_ORIGINS |
CORS policy |
GATEWAY_HTTP_CONN_LIMIT / GATEWAY_HTTP_TIMEOUT / GATEWAY_HTTP_THREADS |
HTTP/1.1 server tuning |
GATEWAY_HTTP2_MAX_STREAMS / GATEWAY_HTTP2_TIMEOUT |
HTTP/2 server tuning |
GATEWAY_MAX_REQUEST_SIZE |
Maximum request body size |
GATEWAY_PROTOCOL_HANDLER |
Protocol-handler selection |
AIRY_LLM_SOCK / AIRY_LLM_TCP_ADDR / AIRY_LLM_TCP_PORT |
LLM backend endpoint |
AIRY_AGENT_SOCK / AIRY_TOOL_SOCK |
Agent / tool backend endpoints |
AIRY_AGENT_MODEL |
Default model for agent runs |
AIRY_MAX_SESSIONS / AIRY_RATE_LIMIT_TABLE_SIZE |
Session and rate-limiter table sizes |
AIRY_STDIO_BUFFER_SIZE / AIRY_GATEWAY_MEM_PUBLIC |
Stdio buffer size; public-memory flag |
Upstream dependencies (linked by this module):
| Dependency | Provides |
|---|---|
| protocols | Router / gateway / registry interfaces and the A2A / MCP / OpenAI adapters (airy_protocols) |
| agentrt atoms | Syscall dispatch target and memory primitives (airy_memory) |
| agentrt commons | Platform, types, error, logging, and sync foundation (airy_common, svc_common, airy_syscall) |
| cJSON (external) | JSON parsing — hard dependency |
| libmicrohttpd / libwebsockets / nghttp2 / OpenSSL | HTTP, WebSocket, HTTP/2, and TLS transports |
Downstream consumers: the gateway daemon host wraps this library and runs it as a system service; SDKs and agent applications connect over HTTP / WebSocket / SSE / Stdio / MCP.
Copyright (c) 2025-2026 SPHARX Ltd.
This module is open source and dual-licensed; you may choose either license:
- GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), or
- Apache License, Version 2.0 (Apache-2.0)
SPDX-License-Identifier: AGPL-3.0-or-later OR Apache-2.0
The full license texts are in LICENSE; the copyright notice is in NOTICE.