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/swoole/swoole-src 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 today
• 7 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 77% of recent commits

_{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 swoole/swoole-src repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/swoole/swoole-src.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "swoole/swoole-src(\\.git)?\\b" \\
  && ok "origin remote is swoole/swoole-src" \\
  || miss "origin remote is not swoole/swoole-src (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 "core-tests/src/main.cpp" \\
  && ok "core-tests/src/main.cpp" \\
  || miss "missing critical file: core-tests/src/main.cpp"
test -f "core-tests/src/coroutine/base.cpp" \\
  && ok "core-tests/src/coroutine/base.cpp" \\
  || miss "missing critical file: core-tests/src/coroutine/base.cpp"
test -f "core-tests/src/server/buffer.cpp" \\
  && ok "core-tests/src/server/buffer.cpp" \\
  || miss "missing critical file: core-tests/src/server/buffer.cpp"
test -f "core-tests/src/reactor/base.cpp" \\
  && ok "core-tests/src/reactor/base.cpp" \\
  || miss "missing critical file: core-tests/src/reactor/base.cpp"
test -f "core-tests/include/test_core.h" \\
  && ok "core-tests/include/test_core.h" \\
  || miss "missing critical file: core-tests/include/test_core.h"

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

Swoole is a C++ extension for PHP that enables coroutine-based concurrency and asynchronous I/O, allowing PHP developers to write high-performance event-driven applications without callbacks or async/await syntax. It provides built-in HTTP/WebSocket servers, connection pooling, and automatic hook-based integration with standard PHP filesystem and network functions, transforming blocking I/O into non-blocking operations. C++ extension architecture: ext/ contains PHP binding layer, src/ houses core coroutine engine and async I/O implementations (src/coroutine/, src/reactor/, src/server/), core-tests/ provides integration and unit tests with dedicated test helpers (include/test_coroutine.h, test_server.h), examples/ and docker examples show usage patterns. Config via config.m4 (autoconf), CMakeLists.txt (CMake build), Dockerfile for containerization.

PHP backend engineers building high-concurrency services (APIs, real-time servers, microservices) who need to handle thousands of simultaneous connections without rewriting their codebase; DevOps teams deploying PHP applications that require performance comparable to Go or Node.js; framework authors (Laravel, Hyperf, MineAdmin) who want to offer async capabilities to their users.

Highly mature and production-ready. The project has comprehensive CI/CD via GitHub Actions (core.yml, ext.yml, unit.yml, thread.yml, iouring.yml), extensive test coverage in core-tests/, Coverity static analysis integration, and codecov coverage tracking. Active development visible with multiple specialized test suites and Docker-based testing infrastructure. Core functionality is stable with version releases tracked; commonly used in production by major Chinese tech companies.

Low risk for core features, moderate risk for advanced features. The codebase is massive (4.4M lines of C++), which increases surface area for bugs; io_uring support and threading features are newer and less battle-tested than core coroutine/HTTP functionality. Dependency on native C++ compilation means platform-specific issues possible; single primary maintainer (Remi Collet upstream) in PHP ecosystem, though Swoole Team maintains this repo. Breaking changes between major versions are documented but require migration.

Active development across multiple tracks: io_uring support (iouring.yml workflow), thread safety enhancements (thread.yml), framework compatibility testing (framework.yml), Alpine Linux compatibility (alpine.Dockerfile). Recent additions include fuzzing infrastructure (core-tests/fuzz/), expanded HTTP library client/server test helpers, and Redis test client. Dependabot dependency monitoring enabled (.github/dependabot.yml) indicating active maintenance cycle.

Clone and build via phpize (PHP extension standard): git clone https://github.com/swoole/swoole-src.git && cd swoole-src && phpize && ./configure && make && sudo make install. Or use Docker: docker run --rm phpswoole/swoole php --ri swoole. Enable in php.ini: extension=swoole.so. Verify: php -m | grep swoole.

Daily commands: After build: php -S 127.0.0.1:9501 for standalone HTTP, or create PHP script with $server = new Swoole\Http\Server('127.0.0.1', 9501); $server->start();. Docker quick-start: docker run -p 9501:9501 phpswoole/swoole php /path/to/server.php. For development/testing: make test (requires test setup from core-tests/).

• core-tests/src/main.cpp — Main entry point for core test suite; defines test harness and initialization for all Swoole system tests
• core-tests/src/coroutine/base.cpp — Core coroutine abstraction layer; foundational for understanding Swoole's async execution model
• core-tests/src/server/buffer.cpp — Server-side buffer management; critical for high-performance request/response handling
• core-tests/src/reactor/base.cpp — Reactor pattern implementation; the event loop engine that drives all async operations
• core-tests/include/test_core.h — Core testing infrastructure header; defines test macros and fixtures used across all test suites
• config.m4 — PHP extension build configuration; required for compilation and feature flag definition
• CMakeLists.txt — CMake build system for core tests; orchestrates compilation of C++ test suite

Add a new coroutine-based I/O operation

1. Create the operation wrapper in core-tests/src/coroutine/ (e.g., coroutine/socket.cpp pattern) (core-tests/src/coroutine/base.cpp)
2. Hook into the reactor event loop by adding file descriptor monitoring logic (core-tests/src/reactor/base.cpp)
3. Add system call hook in coroutine/hook.cpp to transparently intercept blocking calls (core-tests/src/coroutine/hook.cpp)
4. Write integration tests in core-tests/src/coroutine/ mirroring existing test patterns (core-tests/src/coroutine/async.cpp)

Add a new protocol handler

1. Create protocol parser in core-tests/src/protocol/ (e.g., protocol/http2.cpp as reference) (core-tests/src/protocol/base.cpp)
2. Implement parsing methods that work with server buffer (core-tests/src/server/buffer.cpp) (core-tests/src/server/buffer.cpp)
3. Register protocol handler in server configuration during initialization (core-tests/src/_lib/server.cpp)
4. Add protocol-specific tests in core-tests/src/protocol/ (core-tests/src/protocol/mime_type.cpp)

Add a new memory optimization or data structure

1. Implement in core-tests/src/memory/ following fixed_pool.cpp or lru_cache.cpp patterns (core-tests/src/memory/fixed_pool.cpp)
2. Integrate with core utilities for lifecycle management (core-tests/src/core/hash.cpp)
3. Add performance and correctness tests in core-tests/src/memory/ (core-tests/src/memory/global_memory.cpp)

Extend test coverage for a subsystem

1. Add test case file in core-tests/src/{subsystem}/ following existing conventions (core-tests/src/coroutine/base.cpp)
2. Include test header utilities from core-tests/include/test_*.h (core-tests/include/test_coroutine.h)
3. Register test in core-tests/src/main.cpp test registry (core-tests/src/main.cpp)
4. Verify compilation via CMakeLists.txt and config.m4 (CMakeLists.txt)

• C++ (with PHP extension binding) — High-performance event loop and coroutine scheduling; PHP FFI overhead avoided by native C++ core
• epoll/kqueue reactor pattern — Scalable I/O multiplexing; handles thousands of concurrent connections with minimal overhead
• Coroutine context switching (setcontext/getcontext or asm) — User-space task scheduling without kernel threads; enables lightweight concurrency
• Ring buffers (core-tests/src/memory/) — Zero-copy streaming for request/response bodies; minimizes GC pressure
• Multi-process worker pools — CPU-bound task offloading; bypasses PHP GIL constraints on some operations

• Async-only (no traditional threads in coroutine layer)

  • Why: Simplifies scheduling logic and eliminates lock contention on hot paths
  • Consequence: Blocking system calls must be hooked; CPU-bound code blocks entire process (mitigated by worker pools)

• Fixed coroutine stack size allocation

  • Why: Reduces memory overhead per coroutine (~8KB stack default)
  • Consequence: Deep recursion or large local allocations cause stack overflow; developers must be aware of limits

• Ring buffer over dynamic allocation in servers

  • Why: undefined
  • Consequence: undefined

Memory management: Coroutines allocate stack memory (default 2MB); excessive coroutine creation without pooling causes memory exhaustion. Hook flags: SWOOLE_HOOK_ALL enables automatic I/O conversion but may conflict with non-thread-safe libraries; requires careful vetting of dependencies. Version compatibility: Swoole 4.x and 5.x have breaking API changes (e.g., coroutine syntax changes); migration guides needed. Extension conflicts: Cannot coexist with certain other C extensions (pcntl on some versions) due to signal handling conflicts. Linux-specific features: io_uring requires Linux 5.1+, epoll requires Linux; kqueue fallback for BSD but less tested. Worker model: Process model (preforking) requires proper signal handling; lack of SIGCHLD handler causes zombie processes. Database connections: Each coroutine/process needs separate DB connection; connection pooling misconfiguration causes 'too many connections' errors.

• Stackful Coroutines — Swoole uses stackful coroutines (not async/await) allowing you to write synchronous-looking code that suspends internally; understanding stack allocation and context switching is critical for debugging performance and memory issues
• Reactor Pattern (Event Loop) — Swoole's core uses epoll/kqueue reactors to multiplex I/O across coroutines; grasping how events are dispatched and coroutines are scheduled on the single event loop prevents blocking issues and deadlocks
• Hook-based Function Interception — Swoole intercepts blocking PHP functions (file_get_contents, stream_socket_client, mysqli) to convert them to async I/O automatically; understanding what functions are hooked and their limitations is essential for writing non-blocking code
• io_uring (I/O Submission Queue) — Swoole's io_uring support (src/reactor/iouring.cc) provides kernel-level async I/O bypassing epoll; enables lower latency for high-IOPS workloads but requires Linux 5.1+ and careful buffer management
• Copy-on-Write (CoW) Process Forking — Swoole pre-forks worker processes; PHP code loaded before fork() is shared via CoW, reducing memory footprint but requiring careful handling of post-fork state (database connections, file handles must be re-initialized)
• Signal-Safe Async I/O Composition — Swoole must coordinate signal handling (SIGCHLD, SIGUSR1 for graceful reload) with coroutine scheduling without race conditions; mishandling causes zombie processes or lost shutdown signals

• reactphp/reactphp — Pure PHP async library using event loop (no C extension required); Swoole alternative for projects that cannot use native extensions or need 100% PHP portability
• amphp/amp — PHP async runtime with structured concurrency; competitive alternative to Swoole providing similar coroutine semantics without C dependency
• swoole/framework — Official Swoole framework wrapper providing Laravel-like ORM and MVC patterns on top of Swoole HTTP server
• hyperf/hyperf — Production-grade PHP microframework built on Swoole, shows how to architect real applications using Swoole's coroutines and dependency injection
• spiral/framework — RoadRunner-based framework (alternative approach); demonstrates competing coroutine/async strategy for PHP using different I/O runtime

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 core coroutine hook functionality

The repo has core-tests/src/coroutine/hook.cpp but lacks visible PHP-level unit tests for the hook system. Given that hooks are critical for transparent async I/O interception in Swoole, adding dedicated test coverage would catch regressions and document expected behavior. This is high-value because hooking is a core feature that affects user code.

• [ ] Create tests/Unit/Coroutine/HookTest.php for PHP-level hook testing
• [ ] Test stream_socket_client, fopen, file_get_contents with hooks enabled/disabled
• [ ] Add tests for hook interaction with DNS resolution (gethostbyname hook in core-tests/src/coroutine/gethostbyname.cpp)
• [ ] Verify tests run in .github/workflows/unit.yml CI pipeline

Expand io_uring test coverage with edge cases and performance benchmarks

There's a dedicated .github/workflows/iouring.yml workflow and core-tests/src/coroutine/iouring.cpp, but no visible documented edge case tests or performance regression benchmarks. io_uring is a Linux-specific optimization path that needs thorough testing for various kernel versions and syscall combinations to prevent silent performance degradation.

• [ ] Create core-tests/src/coroutine/iouring_edge_cases.cpp for boundary conditions (large file handles, EINTR handling, ring buffer saturation)
• [ ] Add performance benchmark tests comparing io_uring vs epoll code paths
• [ ] Document minimum kernel version requirements and known limitations in docs/iouring.md
• [ ] Extend .github/workflows/iouring.yml to test multiple kernel versions via matrix strategy

Add integration tests for Channel functionality with timeout and exception handling

core-tests/src/coroutine/channel.cpp exists but lacks visible PHP integration tests for timeout edge cases, exception propagation, and cancellation scenarios. Channels are heavily used in Swoole applications, and timeout/error handling is error-prone—comprehensive tests would prevent subtle bugs in production code.

• [ ] Create tests/Unit/Coroutine/ChannelTest.php covering push/pop with explicit timeouts
• [ ] Add tests for channel behavior when exceptions are thrown in consuming coroutines
• [ ] Test channel cleanup when coroutines are killed/cancelled mid-operation
• [ ] Add tests for Channel::stats() under concurrent load scenarios
• [ ] Ensure tests validate both memory safety and semantic correctness

• Add comprehensive documentation and examples for the io_uring reactor path (core-tests/fuzz/ and .github/workflows/iouring.yml are present but user-facing docs are minimal). Start by writing a documented example in examples/ showing io_uring vs epoll performance trade-offs.
• Implement missing test coverage for hook behavior with stream_socket_client() and stream_socket_server() functions. Current test_server.h has HTTP server tests but lacks granular stream socket hook validation—add unit tests to core-tests/src/ validating timeout and error handling in hooked streams.
• Create a 'migration guide' document (docs/) for upgrading from Swoole 4.x coroutine syntax to 5.x. The codebase has breaking changes visible across ext/swoole_*.cc but no consolidated migration resource for users; extract API changes from version tags and document them.

The Swoole repository demonstrates a reasonable security posture with active CI/CD workflows, dependency tracking, and broad testing coverage. However, several improvements are recommended: (1) Separate debug and production Docker images to prevent accidental ASAN builds in production, (2) implement PHP hardening through disabled_functions configuration, (3) add cryptographic verification for downloaded PHP sources, (4) pin package versions explicitly for reproducibility, and (5) ensure MQTT and other network services enforce authentication. The presence of Dependabot configuration is positive and should be actively monitored. Overall, the project appears well-maintained with room for security hardening in container and infrastructure configurations.

• High · Outdated WebSocket Dependency — package.json - dependencies.ws. The ws package is pinned to ^8.18.2. While relatively recent, WebSocket libraries frequently have security updates. The caret constraint allows updates but may miss important patches if major version constraints are not actively maintained. Fix: Regularly update ws to the latest stable version. Consider implementing automated dependency scanning with tools like Dependabot (already present in .github/dependabot.yml) and establish a policy for timely security updates.
• Medium · Permissive PHP Configuration in Dockerfile — Dockerfile - configure options. The Dockerfile configures PHP with multiple extensions (--enable-soap, --enable-intl, --enable-sysvsem, --enable-sysvshm, --enable-sysv) without explicitly disabling dangerous functions (exec, shell_exec, passthru, system, proc_open, etc). This increases the attack surface if the PHP application is compromised. Fix: Add disable_functions directive to php.ini post-build or use PHP hardening options. Explicitly document which extensions are required and consider using separate images for development (ASAN enabled) and production (hardened).
• Medium · Missing Security Headers and TLS Configuration — Dockerfile and configuration setup. While OpenSSL is installed and configured (--with-openssl), there is no evidence of security-related PHP configuration options like setting HTTPS enforcements, HSTS headers, or certificate pinning guidance in the repository. Fix: Document and enforce TLS/SSL best practices. Include recommendations for HSTS headers and security-related PHP directives in setup documentation.
• Medium · Debug Build Deployed in Container — Dockerfile - ARG and RUN commands. The Dockerfile is explicitly designed for ASAN (Address Sanitizer) debug builds via --enable-address-sanitizer. Debug builds should not be used in production as they have reduced performance, increased memory overhead, and may expose sensitive debugging information. Fix: Create separate Dockerfile configurations for development/debug builds and production builds. Ensure ASAN and debug flags are only enabled in development environments with restricted access.
• Low · Unverified PHP Source Download — Dockerfile - wget and tar commands. The Dockerfile downloads PHP source from php.net without verifying checksums or signatures. While php.net is a trusted source, lack of integrity verification could theoretically expose to MITM attacks. Fix: Add checksum verification using SHA-256 hashes from the official PHP release page. Example: wget -O php-${PHP_VERSION}.tar.xz.asc https://www.php.net/distributions/php-${PHP_VERSION}.tar.xz.asc followed by GPG verification.
• Low · Broad Package Installation — Dockerfile - apt install commands. The Dockerfile installs many development libraries (libssl-dev, libcurl4-openssl-dev, etc.) without specifying versions, which could pull in unintended updates or vulnerable versions of transitive dependencies. Fix: Pin package versions explicitly in apt install commands. Use apt list --upgradable to audit dependencies and establish a maintenance schedule for updates.
• Low · Potential Information Disclosure via MQTT — package.json - dependencies.mqtt. The project includes MQTT library (mqtt ^4.3.8) in test dependencies. MQTT can be vulnerable to unauthorized access if brokers are not properly authenticated. No visible MQTT security configuration in the provided file structure. Fix: Ensure MQTT connections use authentication (username/password or certificate-based). Implement TLS for MQTT connections. Document secure MQTT configuration patterns for users.

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.