If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/scylladb/seastar shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 18 active contributors
• Distributed ownership (top contributor 25% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live scylladb/seastar repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/scylladb/seastar.

What it runs against: a local clone of scylladb/seastar — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in scylladb/seastar | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of scylladb/seastar. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/scylladb/seastar.git
#   cd seastar
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of scylladb/seastar and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "scylladb/seastar(\\.git)?\\b" \\
  && ok "origin remote is scylladb/seastar" \\
  || miss "origin remote is not scylladb/seastar (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "HACKING.md" \\
  && ok "HACKING.md" \\
  || miss "missing critical file: HACKING.md"
test -f "coding-style.md" \\
  && ok "coding-style.md" \\
  || miss "missing critical file: coding-style.md"
test -f "configure.py" \\
  && ok "configure.py" \\
  || miss "missing critical file: configure.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/scylladb/seastar"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Seastar is a high-performance, event-driven C++ framework for writing non-blocking asynchronous server applications using futures-based programming. It powers ScyllaDB and enables building low-latency, throughput-optimized network services with explicit control over scheduling, CPU affinity, and memory allocation. Monorepo structure: core framework in src/ (inferred from C++ line count), example applications in apps/ (httpd, memcached, io_tester, iotune, rpc_tester, seawreck), build orchestrated by CMakeLists.txt and configure.py wrapper. Python scripts handle configuration and testing; Ragel grammar files (e.g., apps/memcached/ascii.rl) define protocol parsers.

C++ systems engineers and database developers who need to build ultra-high-performance server applications (like ScyllaDB does) with microsecond-scale latencies and millions of concurrent operations, particularly those targeting distributed databases, caching layers, or real-time analytics platforms.

Highly mature and production-grade: 5.2M lines of C++ code, extensively tested with GitHub Actions CI (alpinelinux, docker, test suites in apps/memcached/tests/ and beyond), used as the foundation of ScyllaDB (a deployed NoSQL database). Actively maintained with comprehensive build modes (debug, release, dev, sanitize) and professional documentation.

Low risk for production use in appropriate contexts: single clear owner (ScyllaDB), but C++ introduces inherent complexity and memory safety risks (mitigated by sanitizer modes). Depends on system packages (installed via install-dependencies.sh) which requires careful environment management; breaking changes possible between major versions given C++ ABI sensitivity. Requires substantial systems knowledge from adopters.

Actively maintained with CI workflows for multiple Linux distributions (.github/workflows/alpinelinux.yaml, docker.yaml, test.yaml, tests.yaml), Python linting (python-lint.yaml), and pre-commit hooks. Recent work visible in build.ninja (Ninja build system) and comprehensive test automation for memcached protocol and RPC components.

git clone https://github.com/scylladb/seastar.git && cd seastar && sudo ./install-dependencies.sh && ./configure.py --mode=release && ninja -C build/release

Daily commands: After building: individual apps start as build/release/apps/{appname}/{binary} (e.g., build/release/apps/httpd/httpd runs the HTTP demo). Configuration via YAML files (apps/io_tester/conf.yaml, apps/rpc_tester/sample-conf.yaml) and JSON (apps/httpd/demo.json). See HACKING.md for detailed dev workflows.

• README.md — High-level introduction to Seastar's event-driven, futures-based async framework—essential context for all contributors.
• CMakeLists.txt — Root build configuration defining compilation flags, dependencies, and module structure for the entire project.
• HACKING.md — Developer workflow guide covering build procedures, testing, and contribution expectations—required reading before first commit.
• coding-style.md — Style and code conventions guide ensuring consistency across the 600-file codebase.
• configure.py — Configuration script that sets up build environment and resolves platform-specific dependencies before CMake execution.

• Event Loop (Reactor) — Multiplexes I/O events (epoll/kqueue), runs ready futures

Add a new async demo application

1. Create a new .cc file in demos/ directory (e.g., demos/my_feature_demo.cc) following async/future patterns seen in demos/tcp_demo.cc. (demos/my_feature_demo.cc)
2. Add CMake target to demos/CMakeLists.txt using add_executable() and link against seastar target. (demos/CMakeLists.txt)
3. Implement main() returning seastar::future<> and use seastar::app_template for CLI argument parsing. (demos/my_feature_demo.cc)

Add a new production application (like memcached)

1. Create new subdirectory under apps/ with its own CMakeLists.txt defining the executable target. (apps/my_service/CMakeLists.txt)
2. Implement core protocol handler in apps/my_service/my_service.cc, structuring around listener and connection-handling loops. (apps/my_service/my_service.cc)
3. Add Python test suite in apps/my_service/tests/test_my_service.py following memcached tests pattern. (apps/my_service/tests/test_my_service.py)
4. Update apps/CMakeLists.txt to include add_subdirectory(my_service). (apps/CMakeLists.txt)

Add platform-specific build logic or dependency check

1. Create new cmake/Find*.cmake module (e.g., cmake/FindMyLibrary.cmake) following the pattern in cmake/FindLibUring.cmake. (cmake/FindMyLibrary.cmake)
2. Reference the module in cmake/SeastarDependencies.cmake using find_package(MyLibrary). (cmake/SeastarDependencies.cmake)
3. Add conditional compilation in CMakeLists.txt using if(MyLibrary_FOUND) blocks as seen with DPDK/hwloc features. (CMakeLists.txt)

• C++17/C++20 (coroutines, concepts) — Enables efficient async/await syntax and zero-cost abstractions for high-performance server applications without garbage collection overhead.
• epoll/kqueue event multiplexing — Allows single-threaded event loop to handle thousands of concurrent connections with minimal CPU overhead.
• Future-based promise model — Composable abstraction for async operations enabling readable, maintainable non-blocking code in traditional imperative style.
• DPDK (optional) — Enables kernel-bypass networking for ultra-low-latency, high-throughput scenarios in data-center environments.
• CMake + Python configuration — Portable cross-platform build system supporting diverse architectures (x86, ARM) and optional dependencies gracefully.

• Single-threaded event loop per CPU core (sharded design)

  • Why: Eliminates lock contention and cache-coherency overhead; scales linearly with cores.
  • Consequence: Developers must be aware of data affinity; shared state requires explicit coordination across cores via message passing.

• Non-blocking I/O only—no synchronous blocking calls

  • Why: Prevents thread pool explosion and enables handling millions of concurrent connections on modest hardware.
  • Consequence: Cannot use libraries with blocking I/O; requires either async-compatible wrappers or re-implementation.

• Zero-copy shared memory between cores where possible

  • Why: Maximizes throughput and minimizes latency for intra-process communication.
  • Consequence: Increased complexity in memory ownership and lifetime tracking; potential for use-after-free bugs if not careful.

• Optional DPDK integration vs. kernel sockets

  • Why: Allows trading ease-of-use for raw performance; different deployment scenarios have different needs.
  • Consequence: Feature fragmentation: DPDK mode lacks some standard socket features; kernel mode sacrifices ~50% throughput for universality.

• Not a web framework—Seastar is a systems library; HTTP/RPC layers are low-level building blocks, not Django-like ORMs or auto-routing.
• Does not provide thread safety or garbage collection—manual lifetime and thread affinity management required.
• Not cross-platform for all OSes—Linux primary, some macOS/Windows support; does not target embedded/RTOS.
• Does not hide networking complexity—developers must understand TCP/IP, protocol framing, and backpressure.

Allocator selection is critical: release mode uses Seastar's custom allocator (high performance, low fragmentation) while debug uses system allocator (easier debugging); mismatches can hide bugs. Memory requirements high during compilation (4GB+ recommended, can OOM with -j parallelism). Per-core scheduling model requires understanding CPU affinity and reactor concepts. install-dependencies.sh modifies system packages and should be run with sudo; may conflict on minimal container images. Build mode (debug vs. release) affects performance by 10-100x.

• Futures and Promises — Core abstraction of Seastar; all async operations return futures, requiring deep understanding for writing non-blocking code correctly
• Lock-free Data Structures — Seastar's per-core scheduling avoids locks; contributors must understand compare-and-swap, ring buffers, and cross-core communication without mutexes
• CPU Affinity and Reactor Pattern — Seastar binds each reactor (event loop) to a CPU core; fundamental to achieving the framework's sub-microsecond latency and predictable scheduling
• Zero-Copy I/O and DMA — Seastar avoids buffer copies for network and disk I/O via direct memory access; critical for throughput in the apps/io_tester benchmark suite
• Ragel State Machine Compiler — Used for protocol parsing (apps/memcached/ascii.rl); efficient compiled parsers replace handwritten state machines and enable protocol-agnostic testing
• ASAN/UBSAN Sanitizers — Seastar's debug and sanitize modes enable detection of memory safety bugs (use-after-free, buffer overflows, UB); mandatory for C++ system code
• Custom Memory Allocators — Seastar's allocator mode in release builds optimizes for low fragmentation and predictable performance; misunderstanding allocator choice hides subtle bugs

• scylladb/scylla — Production database built on Seastar; best reference implementation of the framework at scale
• edenhill/librdkafka — Event-driven C++ networking library solving similar async I/O problem; useful comparison for architectural patterns
• boost-ext/http-client — Companion HTTP client library; often paired with Seastar's server framework for request/response testing
• abseil/abseil-cpp — Google's foundational C++ library; Seastar examples and test utilities often follow Abseil coding conventions

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for apps/memcached/ascii.rl parser

The memcached ASCII protocol parser (ascii.rl) is a critical component for the memcached app, but test coverage appears limited to only test_ascii_parser.cc. Given that Ragel-based parsers are error-prone, adding property-based tests for edge cases (malformed commands, boundary conditions, protocol violations) would prevent regressions and improve robustness.

• [ ] Review existing apps/memcached/tests/test_ascii_parser.cc to understand current coverage
• [ ] Identify missing test cases: incomplete commands, oversized payloads, invalid syntax variants
• [ ] Add property-based or fuzzing tests to apps/memcached/tests/ using seastar's testing framework
• [ ] Document test cases in apps/memcached/tests/README or inline comments

Create GitHub Actions workflow for sanitizer validation (ASAN/UBSAN/TSAN)

The repo has test.yaml and tests.yaml workflows, but no visible CI job for Address Sanitizer, UndefinedBehavior Sanitizer, or Thread Sanitizer. Given Seastar's focus on async/concurrent code, sanitizer CI would catch memory safety and concurrency bugs early. The cmake/FindSanitizers.cmake exists, indicating infrastructure is ready.

• [ ] Review cmake/FindSanitizers.cmake to understand sanitizer configuration options
• [ ] Create .github/workflows/sanitizers.yaml with separate jobs for ASAN, UBSAN, TSAN
• [ ] Configure CMakeLists.txt sanitizer flags (e.g., -DSANITIZE_ADDRESS=ON) in workflow
• [ ] Run against existing test suite (likely tests/ or check targets) and document any suppressions needed

Add integration tests for apps/io_tester with real I/O workloads and validation

The io_tester app exists with conf.yaml and sched.yaml configs, but apps/io_tester/ lacks a tests/ directory with automated validation. Adding integration tests that run io_tester against mock/real storage and verify output metrics would ensure the benchmarking tool remains reliable across refactors.

• [ ] Create apps/io_tester/tests/ directory structure mirroring apps/memcached/tests/
• [ ] Add CMakeLists.txt in tests/ to build io_tester integration tests
• [ ] Write test cases that parse conf.yaml/sched.yaml, execute io_tester, and validate output (latency, throughput metrics, error handling)
• [ ] Reference apps/io_tester/ioinfo.cc to understand output format and add assertions

• Add Python type hints to apps/memcached/tests/test_memcached.py and apps/memcached/tests/test.py—currently untyped and fail python-lint.yaml checks; helps onboard contributors to test infrastructure.
• Expand apps/httpd/demo.json documentation: add schema comments and example payloads for each HTTP endpoint to help new users understand the framework's HTTP abstraction layer.
• Create Dockerfiles for each app in apps/{httpd,io_tester,memcached}/ to match the docker.yaml CI workflow—currently only generic Dockerfile exists, limiting reproducibility for contributors.

The Seastar framework is a mature, event-driven C++ server framework with generally sound architecture. Primary security concerns are moderate-level risks around protocol parsing (Ragel-based memcached parser), RPC deserialization, and missing HTTP security headers in the demo applications. The codebase lacks visible SAST and fuzzing in CI/CD pipelines. No critical vulnerabilities were identified in the file structure analysis, but application-level security depends heavily on how developers use the framework. The project would benefit from enhanced security testing automation, comprehensive input validation documentation, and security header defaults in HTTP handling components.

• Medium · Potential Unsafe Parsing in Memcached Implementation — apps/memcached/ascii.rl. The memcached app uses Ragel-based parsing (ascii.rl) for protocol parsing. Ragel-generated parsers can be vulnerable to malformed input handling and buffer overflows if not carefully bounds-checked. The ASCII protocol parser may not properly validate all edge cases. Fix: Implement comprehensive input validation and fuzzing tests for the Ragel parser. Add bounds checking and sanitization for all parsed fields. Consider using a more robust parsing library with built-in security features.
• Medium · Missing Security Headers in HTTP Server — apps/httpd/main.cc. The httpd demo application (apps/httpd/main.cc) may not implement essential HTTP security headers such as Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, or HSTS headers by default. Fix: Add HTTP security headers to all HTTP responses. Implement Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, and HSTS headers. Document security header configuration options.
• Medium · Potential RPC Deserialization Vulnerabilities — apps/rpc_tester/rpc_tester.cc. The RPC framework (apps/rpc_tester/rpc_tester.cc) performs serialization/deserialization of objects. Without proper validation, this could lead to arbitrary code execution or object injection attacks if untrusted data is deserialized. Fix: Implement strict type validation during deserialization. Use whitelisting for allowed object types. Add integrity checking (MAC/signatures) for serialized RPC messages. Consider using version pinning for protocol compatibility.
• Low · Hardcoded Configuration in Demo Files — apps/httpd/demo.json, apps/iotune/iotune.cc, apps/rpc_tester/sample-conf.yaml. Demo configuration files (apps/httpd/demo.json, apps/iotune sample configurations) may contain example hardcoded values that could be mistakenly used in production if copied without review. Fix: Clearly mark all demo files with prominent warnings about production use. Use environment variables or secure configuration management instead of hardcoded values. Implement configuration validation to prevent demo settings in production.
• Low · Missing Security Testing Documentation — .github/workflows/. While the project has CI/CD workflows for testing, there is no visible evidence of security-focused testing (SAST, dependency scanning, fuzzing) in the workflow files. Fix: Add SAST scanning (clang-analyzer, cppcheck) to CI/CD pipelines. Integrate dependency vulnerability scanning. Add fuzzing tests for parsers (Ragel, protocol parsers). Use AddressSanitizer and MemorySanitizer in CI.
• Low · Potential TLS Configuration Weaknesses — cmake/FindGnuTLS.cmake. The codebase includes GnuTLS support (cmake/FindGnuTLS.cmake) but default TLS configurations and cipher suite selections are not visible in the provided files. Fix: Document and enforce strong TLS 1.2+ requirements. Use only modern cipher suites (AEAD ciphers). Implement certificate pinning where appropriate. Add TLS security configuration guidelines to documentation.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.