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

.github/workflows/ci.yaml

@@ -26,12 +26,14 @@ on:
       - 'website/**'
       - 'helm/**'
       - 'fluss-rust/**'
+      - 'fluss-gateway/**'
       - '**/*.md'
   pull_request:
     paths-ignore:
       - 'website/**'
       - 'helm/**'
       - 'fluss-rust/**'
+      - 'fluss-gateway/**'
       - '**/*.md'
 
 concurrency:

.github/workflows/license-check.yml

@@ -21,11 +21,13 @@ on:
   push:
     paths-ignore:
       - 'fluss-rust/**'
+      - 'fluss-gateway/**'
       - 'website/**'
       - '**/*.md'
   pull_request:
     paths-ignore:
       - 'fluss-rust/**'
+      - 'fluss-gateway/**'
       - 'website/**'
       - '**/*.md'
 

.github/workflows/rust-build-and-test.yml

@@ -28,6 +28,7 @@ on:
       - 'fluss-rust/rust-toolchain.toml'
       - 'fluss-rust/.cargo/**'
       - 'fluss-rpc/src/main/proto/**'
+      - 'fluss-gateway/**'
       - '.github/workflows/rust-build-and-test.yml'
   pull_request:
     branches:
@@ -39,6 +40,7 @@ on:
       - 'fluss-rust/rust-toolchain.toml'
       - 'fluss-rust/.cargo/**'
       - 'fluss-rpc/src/main/proto/**'
+      - 'fluss-gateway/**'
       - '.github/workflows/rust-build-and-test.yml'
   workflow_dispatch:
 
@@ -80,3 +82,117 @@ jobs:
         env:
           RUST_LOG: DEBUG
           RUST_BACKTRACE: full
+
+  gateway-build-and-unit-test:
+    name: "Gateway Build and Tests"
+    timeout-minutes: 60
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest
+    # fluss-gateway is its own Cargo workspace, so this job must override the
+    # workflow-level fluss-rust working directory. Without this it would silently
+    # build the client workspace and pass without testing the gateway at all.
+    defaults:
+      run:
+        working-directory: fluss-gateway
+    steps:
+      - uses: actions/checkout@v6
+
+      # The dockerized cluster fixture is an unconditional dev-dependency, so it is part of the
+      # `--all-targets` graph and its proto codegen runs even when the e2e suites are compiled away.
+      - name: Install protoc
+        uses: arduino/setup-protoc@c65c819552d16ad3c9b72d9dfd5ba5237b9c906b # v3.0.0
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Rust Cache
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        with:
+          workspaces: fluss-gateway
+
+      - name: Build
+        run: cargo build --all-targets
+
+      - name: Unit Test
+        run: cargo test --all-targets
+        env:
+          RUST_LOG: DEBUG
+          RUST_BACKTRACE: full
+
+      - name: OpenAPI drift check
+        run: |
+          cargo test --lib protocol::rest::openapi::tests::export_checked_in_document -- --ignored --exact
+          git diff --exit-code openapi.yaml
+
+      - name: OpenAPI external validation
+        run: npx --yes @redocly/cli@1 lint openapi.yaml
+
+  gateway-msrv:
+    name: "Gateway MSRV (1.88)"
+    # The rust-toolchain.toml floats to stable, so a plain build never catches use of features newer
+    # than the declared rust-version. Pin the MSRV explicitly here; `+toolchain` overrides the file.
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: fluss-gateway
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install protoc
+        uses: arduino/setup-protoc@c65c819552d16ad3c9b72d9dfd5ba5237b9c906b # v3.0.0
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install the MSRV toolchain
+        run: rustup toolchain install 1.88.0 --profile minimal
+
+      - name: Rust Cache
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        with:
+          workspaces: fluss-gateway
+
+      - name: Check on the declared MSRV
+        run: cargo +1.88.0 check --all-targets
+
+  gateway-e2e-cluster:
+    name: "Gateway E2E (dockerized Fluss cluster)"
+    # Not a pull-request gate yet: the gateway does not talk to Fluss until the FlussBackend capability
+    # lands, so the suite would spend minutes pulling a Docker image to check the startup and draining the
+    # process suite already covers without one. Run it from the Actions tab meanwhile; to make it a
+    # required gate later, delete the `if:` below.
+    if: github.event_name == 'workflow_dispatch'
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: fluss-gateway
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install protoc
+        uses: arduino/setup-protoc@c65c819552d16ad3c9b72d9dfd5ba5237b9c906b # v3.0.0
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Rust Cache
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        with:
+          workspaces: fluss-gateway
+
+      # A selected scenario must exist: an empty test list means the suite was compiled away, which is a
+      # silent skip and therefore a failure.
+      - name: Assert the cluster scenarios are selected
+        run: |
+          count=$(cargo test --features integration_tests --test e2e_cluster -- --list 2>/dev/null | grep -c ': test$')
+          echo "selected scenarios: $count"
+          test "$count" -ge 1
+
+      - name: Run the cluster suite
+        run: cargo test --features integration_tests --test e2e_cluster
+        env:
+          RUST_LOG: DEBUG
+          RUST_BACKTRACE: full

.github/workflows/rust-license-and-format.yml

@@ -31,6 +31,7 @@ on:
       - 'fluss-rust/rustfmt.toml'
       - 'fluss-rust/rust-toolchain.toml'
       - 'fluss-rpc/src/main/proto/**'
+      - 'fluss-gateway/**'
       - '.github/workflows/rust-license-and-format.yml'
   pull_request:
     branches:
@@ -45,6 +46,7 @@ on:
       - 'fluss-rust/rustfmt.toml'
       - 'fluss-rust/rust-toolchain.toml'
       - 'fluss-rpc/src/main/proto/**'
+      - 'fluss-gateway/**'
       - '.github/workflows/rust-license-and-format.yml'
   workflow_dispatch:
 
@@ -96,3 +98,52 @@ jobs:
         run: cargo doc --workspace --no-deps --exclude fluss_python
         env:
           RUSTDOCFLAGS: -D warnings
+
+  gateway-check-license-and-formatting:
+    name: "Gateway License and Formatting Check"
+    runs-on: ubuntu-latest
+    # fluss-gateway is its own Cargo workspace, so this job must override the
+    # workflow-level fluss-rust working directory. Without this it would silently
+    # lint the client workspace and pass without checking the gateway at all.
+    # `uses:` step inputs stay relative to the repository root.
+    defaults:
+      run:
+        working-directory: fluss-gateway
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Check License Header
+        uses: apache/skywalking-eyes/header@61275cc80d0798a405cb070f7d3a8aaf7cf2c2c1 # v0.8.0
+        with:
+          config: fluss-gateway/.licenserc.yaml
+
+      - name: Install cargo-deny
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-deny@0.14.22
+
+      - name: Check dependency licenses (Apache-compatible)
+        run: cargo deny check licenses
+
+      # The dockerized cluster fixture is an unconditional dev-dependency, so `--all-targets` builds its
+      # proto codegen even when the e2e suites are compiled away.
+      - name: Install protoc
+        uses: arduino/setup-protoc@c65c819552d16ad3c9b72d9dfd5ba5237b9c906b # v3.0.0
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Rust Cache
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        with:
+          workspaces: fluss-gateway
+
+      - name: Format
+        run: cargo fmt --all -- --check
+
+      - name: Clippy
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: Rustdoc
+        run: cargo doc --no-deps
+        env:
+          RUSTDOCFLAGS: -D warnings

fluss-gateway/.gitignore

@@ -0,0 +1,15 @@
+.DS_Store
+
+# Generated by Cargo
+debug/
+target/
+
+# Backup files generated by rustfmt
+**/*.rs.bk
+
+# Debug information generated by MSVC builds of rustc
+*.pdb
+
+# Editors
+.idea/
+.vscode/

fluss-gateway/.licenserc.yaml

@@ -0,0 +1,37 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+header:
+  license:
+    spdx-id: Apache-2.0
+    copyright-owner: Apache Software Foundation
+
+  paths:
+    - 'fluss-gateway/**'
+
+  paths-ignore:
+    # bare (gitignore-style) patterns match the basename at any depth
+    - '.gitignore'
+    - 'Cargo.lock'
+    - 'LICENSE'
+    - 'NOTICE'
+    - 'DISCLAIMER'
+    - '**/*.md'
+    - 'fluss-gateway/DEPENDENCIES.*.tsv'
+    # The checked-in OpenAPI document is generated from the typed contract (`just openapi`).
+    - 'fluss-gateway/openapi.yaml'
+  comment: on-failure