[gateway] Add the Gateway runtime, common HTTP layer, lifecycle, and test infrastructure

[beryllw]

Purpose

Linked issue: close #3958

First PR of FIP-49: the Gateway runtime and HTTP foundation. Authentication, the Fluss backend and the data
APIs come in follow-up issues.

Distilled from the FIP-49 PoC; the foundation was written by @gstamatakis95 and is credited via Co-authored-by.

Brief change log

• fluss-gateway/ as an independent Cargo workspace, library plus executable.
• gateway.yaml configuration: flat dotted keys, env and CLI overrides, validation, stable exit codes.
• Common HTTP layer: one error envelope, request IDs, 404/405/413/504.
• GET /health returning {status, uptime_ms}.
• Lifecycle: REST and Prometheus listeners, task supervision, SIGTERM draining.
• Metrics: the FIP-49 families that need no backend.
• OpenAPI 3.1 generated from the router and checked in, with CI drift and lint gates.
• CI: build, test, clippy, fmt, rustdoc, dependency licences, MSRV.

Tests

66 tests: unit tests, the HTTP contract over a real listener, and the compiled binary's startup, health, SIGTERM and exit codes. A --features integration_tests suite drives the gateway against a dockerized Fluss cluster on demand; it is not a pull-request gate yet.

API and Format

New endpoints GET /health and GET /v1/openapi.json. No change to existing APIs or storage formats.

Documentation

Module-level rustdoc, enforced by cargo doc -D warnings.

[beryllw]

@fresh-borzoni This is the first PR for FIP-49 — could you help review it when you have time? Thanks a lot! 🙏

[beryllw]

@luoyuxia @loserwang1024 @naivedogger cc

[Copilot]

Pull request overview

This PR introduces the initial Rust-based Fluss Gateway module (fluss-gateway/) as a standalone Cargo workspace, providing the runtime/lifecycle foundation, a shared HTTP layer (error envelope, request IDs, limits/timeouts), baseline observability (logging + Prometheus metrics), and integration test infrastructure for future gateway capabilities described in FIP-49 / issue #3958.

Changes:

• Adds gateway runtime + lifecycle (listener binding, readiness/draining, SIGTERM handling, stable exit codes).
• Adds REST foundation with GET /health, GET /v1/openapi.json, shared error envelope, request IDs, body limits, and request deadlines.
• Adds gateway-focused CI jobs (build/test, fmt/clippy/rustdoc, OpenAPI drift + lint, MSRV gate) and supporting test suites.

Reviewed changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
fluss-gateway/tests/support/mod.rs	Shared HTTP + process helpers for gateway integration tests.
fluss-gateway/tests/process.rs	End-to-end tests for the compiled binary (exit codes, SIGTERM drain, bind failures).
fluss-gateway/tests/http_api.rs	End-to-end HTTP contract tests against a real listener (health, OpenAPI, envelopes, limits).
fluss-gateway/tests/e2e_cluster.rs	Feature-gated dockerized cluster smoke test wiring (integration scaffolding).
fluss-gateway/src/protocol/rest/openapi.rs	Router-derived OpenAPI generation + serving and drift checks.
fluss-gateway/src/protocol/rest/mod.rs	REST router assembly and middleware (request IDs, envelopes, deadlines, body limits, acceptance guard).
fluss-gateway/src/protocol/rest/health.rs	GET /health endpoint and schema.
fluss-gateway/src/protocol/mod.rs	Protocol module root exporting REST surface.
fluss-gateway/src/observability.rs	Logging + Prometheus metrics inventory and runtime/process metric sampling.
fluss-gateway/src/main.rs	Binary entrypoint (CLI, config load/validate, init logging, lifecycle run + exit codes).
fluss-gateway/src/lifecycle.rs	Listener/task supervision, readiness state machine, graceful shutdown/draining.
fluss-gateway/src/lib.rs	Gateway library crate root (internal implementation modules).
fluss-gateway/src/error.rs	Error taxonomy + REST error envelope and OpenAPI-friendly schema generation.
fluss-gateway/src/config.rs	Gateway configuration loading (CLI/env/YAML precedence), parsing, validation, and warnings.
fluss-gateway/rustfmt.toml	Gateway-local rustfmt configuration.
fluss-gateway/rust-toolchain.toml	Gateway-local toolchain selection (stable + components).
fluss-gateway/openapi.yaml	Checked-in generated OpenAPI document.
fluss-gateway/justfile	Developer recipes for build/test/fmt/clippy/doc/openapi/licenses.
fluss-gateway/deny.toml	cargo-deny license allowlist/config.
fluss-gateway/copyright.txt	License header template for tooling.
fluss-gateway/clippy.toml	Clippy configuration (cognitive complexity threshold).
fluss-gateway/Cargo.toml	Standalone workspace/package definition, deps, features, tests, MSRV.
fluss-gateway/.licenserc.yaml	License header checking configuration (with generated-file exclusions).
fluss-gateway/.gitignore	Gateway-local ignore rules.
.github/workflows/rust-license-and-format.yml	Extends Rust license/format workflow to include gateway checks.
.github/workflows/rust-build-and-test.yml	Adds gateway build/test/OpenAPI/MSRV/E2E jobs and triggers.
.github/workflows/license-check.yml	Excludes gateway from the generic license-check workflow (gateway has its own checks).
.github/workflows/ci.yaml	Excludes gateway-only changes from the main CI workflow (gateway has dedicated Rust workflows).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[beryllw]

Split out the module scaffolding (workspace setup, toolchain/lint/license configs, placeholder targets, and the dedicated gateway CI gates) into #4002 for a fast first merge. This PR keeps all of the gateway runtime, HTTP layer, lifecycle, and test suites, and will be rebased once #4002 lands.

[fresh-borzoni]

@beryllw Thank you for the PR!
I looked quickly with a limited time I had, left some quick comments, PTAL