feat(gateways): iggy gateway for kafka listener

.github/actions/rust/pre-merge/action.yml

@@ -279,6 +279,32 @@ runs:
         compile_duration=$((compile_end - compile_start))
         echo "::notice::Tests compiled in ${compile_duration}s ($(date -ud @${compile_duration} +'%M:%S'))"
 
+        # decode_validation_tests need gitignored wire fixtures. Generate when
+        # iggy-gateway-kafka is in the DAG test scope, or (on a full-workspace run)
+        # when gateways/** changed vs origin/master — avoid building kafka-message-gen
+        # / kafka-protocol when the gateway was not touched.
+        NEEDS_KAFKA_FIXTURES=false
+        if grep -q 'package(iggy-gateway-kafka)' <<< "$NEXTEST_FILTER"; then
+          NEEDS_KAFKA_FIXTURES=true
+        elif [[ -z "$NEXTEST_FILTER" ]]; then
+          if git diff --name-only origin/master...HEAD 2>/dev/null | grep -qE '^gateways/'; then
+            NEEDS_KAFKA_FIXTURES=true
+          elif ! git rev-parse --verify origin/master >/dev/null 2>&1; then
+            # Base ref unavailable: full suite still runs gateway tests — generate safely.
+            NEEDS_KAFKA_FIXTURES=true
+            echo "::notice::origin/master unavailable; generating Kafka fixtures for full suite"
+          else
+            echo "::notice::Skipping Kafka wire fixtures (full suite, gateways/** unchanged)"
+          fi
+        fi
+        if [[ "$NEEDS_KAFKA_FIXTURES" == true ]]; then
+          ./gateways/kafka/scripts/ci-wire-fixtures.sh generate
+          trap './gateways/kafka/scripts/ci-wire-fixtures.sh cleanup' EXIT
+          # Fixtures are expected to exist from here on; a missing one now means
+          # generation silently failed, not a legitimate local-dev skip.
+          export KAFKA_FIXTURES_REQUIRED=1
+        fi
+
         # Start D-Bus and unlock keyring right before test execution to avoid
         # gnome-keyring auto-locking the collection during the build phase.
         # Previously this ran before `cargo build`, leaving a 7+ minute idle

.github/config/components.yml

@@ -161,6 +161,7 @@ components:
       - "rust-connectors"
       - "rust-mcp"
       - "rust-integration"
+      - "rust-gateway"
       - "ci-infrastructure"
     paths:
       - "Dockerfile*"
@@ -519,3 +520,12 @@ components:
       - ".github/actions/**/*.yml"
       - ".github/ci/**/*.yml"
     tasks: ["validate"] # Could run workflow validation
+
+  # gateways are not Rust components, but we want to run them in CI
+  rust-gateway:
+    depends_on:
+      - "rust-sdk"
+      - "rust-workspace"
+      - "ci-infrastructure"
+    paths:
+      - "gateways/**"

.github/workflows/pr-title.yml

@@ -94,3 +94,4 @@ jobs:
             storage
             simulator
             configs
+            gateways

.gitignore

@@ -44,3 +44,4 @@ core/integration/tests/connectors/postgres/cdc_restart_connectors/*
 !core/integration/tests/connectors/postgres/cdc_restart_connectors/config.toml
 LICENSE-binary
 **/LICENSE-binary
+gateways/kafka/tools/kafka-tool/kafka_messages/

Cargo.toml

@@ -68,6 +68,8 @@ members = [
     "core/system_stats",
     "core/tools",
     "examples/rust",
+    "gateways/kafka",
+    "gateways/kafka/tools/kafka-tool",
 ]
 exclude = ["foreign/cpp", "foreign/php", "foreign/python"]
 resolver = "3"

gateways/README.md

@@ -0,0 +1,9 @@
+# Apache Iggy Gateways
+
+Protocol gateways that let existing clients talk to Iggy without changing the core server wire surface.
+
+| Gateway | Issue | Description |
+| --------- | ------- | ------------- |
+| [kafka](kafka/) | [#3421](https://github.com/apache/iggy/issues/3421) | Kafka wire protocol TCP listener (port 9093) |
+
+Each gateway is a separate workspace crate under `gateways/<name>/`.

gateways/kafka/Cargo.toml

@@ -0,0 +1,62 @@
+# 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.
+
+[package]
+name = "iggy-gateway-kafka"
+version = "0.1.0"
+description = "Kafka wire protocol gateway foundation for Apache Iggy"
+edition = "2024"
+license = "Apache-2.0"
+keywords = ["iggy", "kafka", "gateway", "streaming"]
+homepage = "https://iggy.apache.org"
+documentation = "https://iggy.apache.org/docs"
+repository = "https://github.com/apache/iggy"
+readme = "README.md"
+publish = false
+
+[[bin]]
+name = "iggy-gateway-kafka"
+path = "src/main.rs"
+
+[dependencies]
+bytes = { workspace = true }
+# Broker-role only: decodes requests and encodes responses. Default features also pull in
+# client-role codec paths and compression codecs (gzip/lz4/snappy/zstd) this gateway never
+# uses, since RecordBatch payloads stay opaque `Bytes` here.
+kafka-protocol = { version = "0.17", default-features = false, features = ["broker"] }
+socket2 = { workspace = true }
+thiserror = { workspace = true }
+tokio = { workspace = true, features = [
+    "rt-multi-thread",
+    "macros",
+    "net",
+    "io-util",
+    "time",
+    "sync",
+    "signal",
+] }
+tokio-util = { workspace = true, features = ["rt"] }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["rt-multi-thread", "macros", "net", "io-util", "time"] }
+
+[lints.clippy]
+enum_glob_use = "deny"
+pedantic = "deny"
+nursery = "warn"

gateways/kafka/README.md

@@ -0,0 +1,63 @@
+# Kafka gateway (`iggy-gateway-kafka`)
+
+Foundation layer for [apache/iggy#3421](https://github.com/apache/iggy/issues/3421): a TCP listener on the Kafka wire port that decodes requests, validates scoped API keys and versions, and returns stub responses.
+
+> **Stub warning:** no API persists or reads real data yet. Produce, Fetch, and ListOffsets return retriable `NOT_LEADER_OR_FOLLOWER` (6) so clients keep data locally / retry elsewhere instead of trusting a fake success. CreateTopics does **not** create topics; valid requests return `NOT_CONTROLLER` (41). Metadata still reports requested topics as unknown. Persistence lands with the Iggy bridge (see [docs/SCOPE.md](docs/SCOPE.md)).
+
+## Run
+
+```bash
+cargo run -p iggy-gateway-kafka
+```
+
+Default bind: `127.0.0.1:9093`. Environment variables:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `IGGY_KAFKA_BIND_ADDR` | `127.0.0.1:9093` | TCP address to listen on |
+| `IGGY_KAFKA_ADVERTISED_HOST` | bind IP | Hostname/IP clients use to reach this broker (required when binding to `0.0.0.0`/`::`) |
+| `IGGY_KAFKA_ADVERTISED_PORT` | bind port | Port advertised in Metadata responses |
+| `IGGY_KAFKA_MAX_CONNECTIONS` | `1024` | Maximum concurrent connections before new ones are rejected |
+| `IGGY_KAFKA_MAX_FRAME_SIZE` | `8388608` | Maximum accepted request frame size in bytes |
+| `IGGY_KAFKA_IDLE_TIMEOUT_SECS` | `600` | Seconds a connection may sit idle before the next frame's length prefix arrives |
+| `IGGY_KAFKA_READ_TIMEOUT_SECS` | `15` | Seconds allowed to read a frame body once its length prefix arrives |
+| `IGGY_KAFKA_WRITE_TIMEOUT_SECS` | `10` | Seconds allowed to write a response frame |
+| `IGGY_KAFKA_SHUTDOWN_DRAIN_TIMEOUT_SECS` | `25` | Seconds graceful shutdown waits for in-flight connections before abandoning them |
+
+## Test
+
+```bash
+cargo test -p iggy-gateway-kafka
+```
+
+259 regression tests across 12 suites — see [docs/TEST_SUITE.md](docs/TEST_SUITE.md) for the full catalog.
+
+`decode_validation_tests` require wire fixtures under `tools/kafka-tool/kafka_messages/` (gitignored locally; CI generates them via `scripts/ci-wire-fixtures.sh`):
+
+```bash
+./gateways/kafka/scripts/ci-wire-fixtures.sh generate
+cargo test -p iggy-gateway-kafka
+./gateways/kafka/scripts/ci-wire-fixtures.sh cleanup   # optional
+```
+
+Or generate only the keys the tests need:
+
+```bash
+for key in 0 1 2 19; do
+  cargo run -p kafka-message-gen -- generate \
+    --output gateways/kafka/tools/kafka-tool/kafka_messages \
+    --api-key "$key"
+done
+```
+
+## Manual testing
+
+Before check-in, run the procedure in [docs/MANUAL_TESTING.md](docs/MANUAL_TESTING.md) (smoke, version firewall, kcat, adversarial cases).
+
+## Scoped APIs
+
+See [docs/SCOPE.md](docs/SCOPE.md) for [#3421](https://github.com/apache/iggy/issues/3421) deliverables, supported API key/version table, and post-foundation TODO backlog.
+
+## Wire fixture tool
+
+See [tools/kafka-tool/README.md](tools/kafka-tool/README.md).