[gateway] Introduce the fluss-gateway module

.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/gateway-ci.yml

@@ -0,0 +1,127 @@
+# 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.
+
+# CI gates for the fluss-gateway module. The gateway is its own Cargo workspace,
+# so it gets its own workflow: triggering on gateway changes never builds the
+# fluss-rust workspace, and fluss-rust changes never build the gateway. `uses:`
+# step inputs stay relative to the repository root.
+name: Gateway CI
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'fluss-gateway/**'
+      - '.github/workflows/gateway-ci.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'fluss-gateway/**'
+      - '.github/workflows/gateway-ci.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    working-directory: fluss-gateway
+
+jobs:
+  build-and-unit-test:
+    name: "Gateway Build and Tests"
+    timeout-minutes: 60
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - 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
+
+  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
+    steps:
+      - uses: actions/checkout@v6
+
+      - 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
+
+  check-license-and-formatting:
+    name: "Gateway License and Formatting Check"
+    runs-on: ubuntu-latest
+    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
+
+      - 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

.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'
 

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

fluss-gateway/Cargo.toml

@@ -0,0 +1,48 @@
+# 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.
+
+# The gateway is its own Cargo workspace and deliberately stays out of the
+# workspace rooted at ../fluss-rust so that gateway dependencies never touch
+# that workspace's lock file or its generated dependency inventories.
+[workspace]
+resolver = "3"
+
+[package]
+name = "fluss-gateway"
+edition = "2024"
+version = "1.0.0"
+license = "Apache-2.0"
+# Keep in sync with the `gateway-msrv` CI job, which pins this exact toolchain.
+rust-version = "1.88"
+authors = ["Apache Fluss <dev@fluss.apache.org>"]
+repository = "https://github.com/apache/fluss"
+# The gateway ships as an executable, not a library on crates.io.
+publish = false
+description = "Stateless REST gateway for Apache Fluss"
+
+[[bin]]
+name = "fluss-gateway"
+path = "src/main.rs"
+
+# Internal testability boundary for the executable; this is not a published or supported Rust SDK.
+[lib]
+name = "fluss_gateway"
+
+# This change only introduces the module scaffolding: manifest, toolchain, lint
+# and license configuration, and placeholder targets, with no dependencies.
+# The runtime (configuration, lifecycle, HTTP layer, and tests) arrives with
+# the Gateway foundation change (FIP-49) and brings its dependencies with it.

fluss-gateway/README.md

@@ -0,0 +1,74 @@
+<!--
+ 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.
+-->
+
+# Apache Fluss Gateway
+
+A stateless REST gateway for Apache Fluss. It exposes REST APIs for writing to
+Fluss tables and performing DDL operations, while keeping no session, cursor,
+or replay state: any instance can serve any request behind a plain load
+balancer.
+
+The gateway is an executable, not a library on crates.io, and it is its own
+Cargo workspace so its dependencies never touch the `fluss-rust` workspace's
+lock file or its generated dependency inventories.
+
+## Status
+
+This module currently contains only the scaffolding: the manifest with
+placeholder bin/lib targets, the pinned toolchain, lint and license
+configuration, and the developer recipes. The runtime — configuration,
+lifecycle management, the REST layer, and the test suites — lands in follow-up
+pull requests.
+
+## Prerequisites
+
+- Rust toolchain managed by [rustup](https://rustup.rs); the workspace pins the
+  channel in `rust-toolchain.toml` (stable with `rustfmt` and `clippy`)
+- The declared minimum supported Rust version is 1.88, enforced by the
+  `gateway-msrv` CI job
+- [`just`](https://github.com/casey/just) for the recipes below
+
+## Build and test
+
+Run everything from this directory, or use the `just` recipes:
+
+```bash
+just build        # cargo build --all-targets
+just test         # cargo test --all-targets
+just fmt-check    # cargo fmt --all -- --check
+just clippy       # cargo clippy --all-targets -- -D warnings
+just doc          # RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
+just licenses     # cargo deny check licenses
+```
+
+The MSRV can be verified locally with `cargo +1.88.0 check --all-targets`.
+
+## CI
+
+Gateway changes are gated by a dedicated workflow, `.github/workflows/gateway-ci.yml`
+(build and tests on Linux/macOS, MSRV 1.88, license headers, dependency
+licenses via `cargo-deny`, formatting, clippy, rustdoc). Gateway-only changes
+are excluded from the Java CI, mirroring `fluss-rust`, and the gateway workflow
+never builds the `fluss-rust` workspace.
+
+## License enforcement
+
+Like `fluss-rust`, the gateway carries its own license enforcement: source
+headers are checked by `skywalking-eyes` (`.licenserc.yaml`) and dependency
+licenses by `cargo-deny` (`deny.toml`). Both run in CI.

fluss-gateway/copyright.txt

@@ -0,0 +1,17 @@
+/*
+ * 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.
+ */

fluss-gateway/deny.toml

@@ -0,0 +1,36 @@
+# 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.
+
+[licenses]
+allow = [
+    "Apache-2.0",
+    "Apache-2.0 WITH LLVM-exception",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "CC0-1.0",
+    "ISC",
+    "MIT",
+    "Unicode-3.0",
+    "Zlib",
+]
+
+exceptions = [
+    # open data licenses that SHOULD be OK
+    { crate = "webpki-roots", allow = [
+        "CDLA-Permissive-2.0",
+    ] },
+]