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/bytedance/monoio 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 3w ago
• 30+ active contributors
• Distributed ownership (top contributor 35% 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 bytedance/monoio repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bytedance/monoio.

What it runs against: a local clone of bytedance/monoio — 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 bytedance/monoio | 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 ≤ 54 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bytedance/monoio. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bytedance/monoio.git
#   cd monoio
#
# 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 bytedance/monoio and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "bytedance/monoio(\\.git)?\\b" \\
  && ok "origin remote is bytedance/monoio" \\
  || miss "origin remote is not bytedance/monoio (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 "monoio/Cargo.toml" \\
  && ok "monoio/Cargo.toml" \\
  || miss "missing critical file: monoio/Cargo.toml"
test -f "monoio/src" \\
  && ok "monoio/src" \\
  || miss "missing critical file: monoio/src"
test -f "monoio-macros/src/lib.rs" \\
  && ok "monoio-macros/src/lib.rs" \\
  || miss "missing critical file: monoio-macros/src/lib.rs"
test -f "monoio-compat/src/lib.rs" \\
  && ok "monoio-compat/src/lib.rs" \\
  || miss "missing critical file: monoio-compat/src/lib.rs"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 54 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~24d)"
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/bytedance/monoio"
  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).

Monoio is a Rust async runtime built on io-uring (with epoll/kqueue fallbacks) designed for thread-per-core server architectures. Unlike Tokio, it doesn't require tasks to be Send/Sync, enabling safe thread-local storage and eliminating work-stealing overhead for io-bound network servers like load balancers and proxies. Monorepo with workspace members: monoio/ (core runtime), monoio-macros/ (procedural macros for #[monoio::main]), monoio-compat/ (tokio ecosystem compatibility layer), and examples/. Core runtime abstracts over io-uring/epoll/kqueue drivers; thread-local task queues eliminate global synchronization.

Systems engineers and backend developers building high-performance network services (e.g., NGINX-like load balancers, API gateways) who want to maximize io-uring efficiency without the overhead of work-stealing schedulers and can target Linux kernels 5.6+.

Actively developed and production-targeted: maintained by ByteDance with comprehensive CI/CD (.github/workflows/ci.yml), codecov integration, and benchmarks in .github/resources/benchmark/. Requires Rust 1.75+ and uses unstable features intentionally. Mature enough for serious use but not at 1.0 stability yet (minor breaking changes possible).

Kernel version constraint: requires Linux 5.6+ for io-uring (docs/en/platform-support.md), otherwise degrades to epoll/kqueue. Memlock configuration required (docs/en/memlock.md). Single-org maintenance model (ByteDance). Early adoption of unstable Rust features could break on compiler updates. Smaller ecosystem compared to Tokio means fewer third-party crate integrations tested.

Active maintenance evident from CI workflows and coverage tracking (codecov.yml, .github/workflows/coverage.yml). Ongoing work on Tokio ecosystem compatibility (monoio-compat/) and documentation expansion (docs/en/ and docs/zh/ both present). PR audit workflow indicates code review discipline.

git clone https://github.com/bytedance/monoio.git && cd monoio && rustup update (ensure 1.75+) && cargo build. For io-uring, verify kernel >= 5.6 via uname -r. Check memlock limits: ulimit -l. Run tests with cargo test.

Daily commands: cargo run --example <name> (examples/ directory contains runnable demos). For benchmarks, see .github/workflows/ci.sh for test harnesses. No external services required; kernel and memlock are the constraints.

• monoio/Cargo.toml — Workspace root and primary crate configuration; defines runtime features (io-uring vs epoll/kqueue), dependencies, and build settings that all contributors must understand.
• monoio/src — Core runtime implementation directory; contains the async executor, I/O driver abstraction, and task scheduling—essential for understanding the thread-per-core architecture.
• monoio-macros/src/lib.rs — Entry-point macros (#[monoio::main], #[monoio::test], select!) that bootstrap the runtime; contributors adding new macro features or examples must modify this.
• monoio-compat/src/lib.rs — Compatibility layer for ecosystem integration (Hyper, Tower); critical for understanding how Monoio bridges with external async libraries.
• README.md — Design goals, feature overview, and platform support matrix; defines scope and use cases for all contributions.
• docs/en/platform-support.md — Platform-specific I/O driver selection logic (io-uring on Linux, epoll fallback, kqueue on macOS/BSD); essential for cross-platform work.
• Cargo.toml — Workspace-level configuration managing all member crates and resolver version; must be updated for any new workspace additions.

Add a New Example Demonstrating a Runtime Feature

1. Create a new .rs file in examples/ (e.g., examples/my_feature.rs) with a #[monoio::main] entry point. (examples/)
2. Add your example binary to examples/Cargo.toml [[bin]] section. (examples/Cargo.toml)
3. Use core monoio APIs (TcpListener, TcpStream, spawn, select!, etc.) from monoio/src. (monoio/src)
4. Run with 'cargo run --example my_feature' to verify integration. (examples/my_feature.rs)

Add Support for a New Ecosystem Library (e.g., Hyper, Tower)

1. Create a new module in monoio-compat/src/ (e.g., monoio-compat/src/my_lib.rs) implementing adapter traits. (monoio-compat/src/)
2. Export the new module from monoio-compat/src/lib.rs via 'pub mod my_lib;'. (monoio-compat/src/lib.rs)
3. Implement AsyncRead/AsyncWrite or custom runtime traits to bridge Monoio I/O with the target library. (monoio-compat/src/)
4. Add example in examples/my_lib_integration.rs showing how to use the compat layer. (examples/)
5. Update monoio-compat/Cargo.toml with the target library as an optional dependency. (monoio-compat/Cargo.toml)

Add a New Platform or I/O Driver (io-uring fallback to epoll, etc.)

1. Extend monoio/src/driver to detect and initialize the new backend (e.g., detect kqueue on BSD). (monoio/src)
2. Implement the driver trait for the new I/O backend (poll, submit, wait semantics). (monoio/src)
3. Update docs/en/platform-support.md with the new platform's detection logic and limitations. (docs/en/platform-support.md)
4. Add platform-specific feature flags to monoio/Cargo.toml (e.g., feature = 'kqueue'). (monoio/Cargo.toml)
5. Add a platform-specific example (e.g., examples/tcp_kqueue.rs) to verify the driver works. (examples/)

Add a New Buffer Type for Zero-Copy I/O

1. Create a new struct in monoio/src/buf/ implementing the IoBuf trait. (monoio/src/buf/)
2. Implement required methods: as_slice(), as_mut_slice(), into_inner(), and metadata if needed. (monoio/src/buf/io_buf.rs)
3. Export the new buffer type from monoio/src/buf/mod.rs. (monoio/src/buf/mod.rs)
4. Add example usage in examples/ showing zero-copy read/write with the new buffer type. (examples/)

• io-uring (Linux) — Provides efficient kernel-level async I/O with submission/completion queues, enabling zero-copy buffers and high throughput on modern Linux kernels (5.1+).
• epoll (Linux fallback), kqueue (BSD/macOS) — Fallback I/O multiplexing for older kernels or non-Linux platforms; allows Monoio to run across Unix-like systems with graceful degradation.
• Thread-per-core architecture — Eliminates lock contention and context switching by pinning executor threads to CPU cores; improves cache locality and throughput for I/O-bound workloads.
• Tokio ecosystem compatibility (hyper, h2, tower) — Enables reuse of mature HTTP/networking libraries without rewrite; monoio-compat provides adapter traits to bridge runtime differences.
• Procedural macros (#[monoio::main], select!) — Provides familiar async/await syntax and control flow abstractions similar to Tokio; lowers learning curve for existing Rust async developers.

• Thread-per-core design instead of work-stealing like Tokio

  • Why: Avoids global task queue contention and improves per-core throughput; reduces scheduler complexity.
  • Consequence: Requires explicit thread pinning and careful load distribution; less flexible for heterogeneous workloads with unpredictable per-core load.

• io-uring as primary driver (Linux-only at first)

  • Why: Achieves highest throughput and lowest latency on modern Linux; synchronous, zero-copy semantics reduce allocations.
  • Consequence: Requires Linux 5.1+ and elevated capabilities (memlock); limits portability; adds fallback complexity for older kernels.

• IoBuf trait requiring mutable exclusive access during I/O

  • Why: Ensures safety of zero-copy buffers without runtime overhead; prevents data races.
  • Consequence: API is stricter than Tokio (which uses reference counting); may require refactoring to use 'async-rent' patterns

io-uring requires memlock ulimit configuration (ulimit -l) — common first-time failure. Kernel must be 5.6+ on Linux; no io-uring on older systems (falls back to epoll, performance degrades). Unstable Rust features used (#![feature(...)]) — compiler updates can break builds. Thread-per-core model means tasks cannot safely move between threads (no Send/Sync required but enforced by design). Legacy driver mode (epoll/kqueue) has different performance characteristics — benchmarks are io-uring specific.

• io-uring — Core I/O multiplexing API on Linux 5.6+; understanding its benefits (batch syscalls, memory-mapped queues) explains Monoio's performance claims and kernel constraints
• Thread-per-core execution model — Fundamental design choice enabling lock-free thread-local state; eliminates Send/Sync requirements and work-stealing overhead but constrains task mobility
• Epoll (Linux) / Kqueue (macOS/BSD) — Fallback I/O multiplexers when io-uring unavailable; Monoio abstracts over all three (io-uring/epoll/kqueue) via feature flags
• Procedural macros (proc-macros) — monoio-macros implements #[monoio::main] and #[monoio::test] attributes; understanding macro expansion is essential for runtime initialization
• Async cancellation — docs/en/io-cancel.md indicates Monoio has explicit cancellation semantics; differs from Tokio's Drop-based cancellation, critical for correctness in io-uring contexts
• Generic Associated Types (GAT) — docs/en/why-GAT.md suggests Monoio's IO abstraction relies on GATs for zero-copy/lifetime-bound operations; important for API design understanding
• Memory locking (mlockall/mlock) — docs/en/memlock.md indicates io-uring ring buffers must be resident in RAM; misconfiguration causes runtime panics or degraded performance

• tokio-rs/tokio — Work-stealing async runtime that Monoio is explicitly designed as an alternative to for thread-per-core architectures
• tokio-rs/tokio-uring — Predecessor that ran io-uring on top of Tokio; Monoio abandons the layering for direct io-uring integration
• epolkc/epolkc — Alternative io-uring Rust runtime (if it exists); research comparable approaches
• bytedance/cloudwego — ByteDance's broader cloud-native ecosystem; potential integration point for Monoio-based services
• hyperium/hyper — HTTP library ecosystem; Monoio aims compatibility via monoio-compat and integration examples in docs/en/http.md

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 integration tests for Tower middleware compatibility

The repo has a doc file (docs/en/how-integrate-with-tower.md) explaining Tower integration, but there are no visible integration tests validating this compatibility. Given that Tower is a critical ecosystem component for Rust async services, adding concrete tests would prevent regressions and provide examples for users. This is especially valuable since monoio claims tokio-ecosystem compatibility.

• [ ] Create tests/tower_integration.rs with examples testing tower Service trait implementations
• [ ] Add test cases for common middleware (logging, metrics, timeout) on monoio runtime
• [ ] Verify the hyper_server.rs example still works and add regression tests
• [ ] Document test setup in CONTRIBUTING.md for running integration tests

Add platform-specific tests for io_uring fallback and legacy driver behavior

The docs mention platform support (docs/en/platform-support.md) and legacy driver usage (docs/en/use-legacy-driver.md), but the CI workflow (ci.yml) likely only tests on Linux with io_uring. New contributors need clear examples of testing fallback scenarios (epoll, kqueue) and the legacy driver path. This ensures cross-platform reliability.

• [ ] Create tests/platform_support.rs with conditional compilation tests for different drivers
• [ ] Add GitHub Actions job in .github/workflows/ci.yml to test with legacy driver enabled (uring disabled)
• [ ] Add test verifying correct driver initialization based on platform/config in monoio/src/
• [ ] Document platform-specific testing steps in CONTRIBUTING.md

Expand error handling and cancel operation examples with production patterns

docs/en/io-cancel.md exists but examples/echo.rs, examples/echo_poll.rs, and examples/echo_tfo.rs lack comprehensive error handling and cancellation patterns. The io-cancel documentation deserves concrete runnable examples showing timeout handling, graceful shutdown, and partial operation cancellation—critical for production services.

• [ ] Create examples/echo_with_cancellation.rs demonstrating io_cancel with timeout patterns
• [ ] Create examples/graceful_shutdown.rs showing clean server shutdown with in-flight request handling
• [ ] Add error recovery patterns to examples/echo.rs with try-catch-like patterns for async ops
• [ ] Update docs/en/io-cancel.md with links to these new examples and cross-reference CONTRIBUTING.md

• Add integration examples in examples/ for common patterns not yet covered (e.g., HTTP client patterns, TLS integration) — reference docs/en/http.md to see what's documented but not exemplified.
• Expand docs/en/platform-support.md with explicit OS-by-OS driver selection tables and fallback behavior, currently only mentioned in README.
• Write unit tests for driver abstraction layer to ensure epoll/kqueue code paths are exercised in CI (currently benchmarks focus on io-uring).

The monoio project demonstrates reasonable security awareness with a dedicated SECURITY.md file and use of security tools (cargo-deny.yml, codecov.yml). However, the analysis is limited by lack of source code visibility. The project's primary security concerns relate to: (1) unsafe FFI code required for io-uring integration, which requires careful auditing, (2) dependency management and supply chain security, and (3) thread-per-core runtime model which requires careful handling of shared state. The presence of CI/CD workflows with coverage and security scanning is positive. No obvious hardcoded secrets, injection vulnerabilities, or misconfigurations are apparent from the file structure alone.

• Low · Security Contact Email Exposed in Public Repository — SECURITY.md. The SECURITY.md file contains a plaintext email address (chihai.hain@bytedance.com) for security vulnerability reporting. While this is intentional for security contact purposes, it may increase exposure to spam or social engineering attempts. Fix: Consider using a security contact form or PGP key instead of plaintext email, or use a security@ subdomain alias to reduce direct exposure of individual email addresses.
• Low · Incomplete Static Analysis Coverage — monoio/, monoio-macros/, monoio-compat/src/. File listing shows partial directory structure only. The actual Rust source code in monoio/, monoio-macros/, and monoio-compat/src/ directories was not provided for analysis, limiting vulnerability assessment. Fix: Perform detailed code review of all source files, focusing on: unsafe code blocks, FFI interactions with io-uring, memory management, and concurrency primitives.
• Medium · Unsafe FFI Usage (Suspected) — monoio/src/ (presumed FFI bindings). This project is a runtime built on io-uring, which requires low-level FFI bindings. Without reviewing the actual source code, unsafe Rust code that interfaces with kernel APIs is likely present. Such code requires careful auditing for memory safety issues. Fix: Conduct thorough security audit of all unsafe blocks, especially those interfacing with io-uring syscalls. Use tools like miri, clippy, and AddressSanitizer for testing. Document safety invariants clearly.
• Medium · Dependency Supply Chain Risk — Cargo.toml (dependencies section not provided). The workspace includes multiple crates (monoio, monoio-macros, monoio-compat) with external dependencies not shown in the provided Cargo.toml snippet. These transitive dependencies may introduce vulnerabilities. Fix: Regularly run 'cargo audit' and 'cargo deny' to identify known vulnerabilities. Review the full deny.toml configuration and ensure all dependencies are from trusted sources. Keep dependencies updated.
• Low · Missing Security Headers in Documentation — SECURITY.md. While SECURITY.md exists, it is minimal and lacks additional security best practices guidance for users of the library. Fix: Expand SECURITY.md to include: supported/unsupported versions, security patches timeline, known limitations, and safe usage patterns for async/concurrency scenarios.

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.