nexus-actors/http-server-swoole-threads

Thread-mode HTTP server built on Swoole 6 native SWOOLE_THREAD; cross-thread pool-singleton actors via WorkerNode.

v0.1.0 2026-07-21 18:21 UTC

Requires

• php: >=8.5.7
• ext-swoole: >=6.2.1
• nexus-actors/core: ^0.1
• nexus-actors/http: ^0.1
• nexus-actors/http-server-swoole: ^0.1
• nexus-actors/http-ws: ^0.1
• nexus-actors/runtime: ^0.1
• nexus-actors/runtime-swoole: ^0.1
• nexus-actors/worker-pool: ^0.1
• nexus-actors/worker-pool-swoole: ^0.1
• psr/http-message: ^2.0
• psr/log: ^3.0

Requires (Dev)

• phpunit/phpunit: ^13.0

MIT

Published on Packagist.org on 2026-07-21 18:22 UTC

README

Thread-mode (Swoole 6 SWOOLE_THREAD) HTTP+WebSocket runner. Same DSL as the worker package — see nexus-http-ws. Uses Swoole's native thread mode for shared-memory pool-singleton actors.

Requires Swoole ≥ 6.0 with --enable-swoole-thread (ZTS PHP 8.5+).

Install

composer require nexus-actors/http-server-swoole-threads

HTTP quickstart

use Monadial\Nexus\Core\Actor\ActorSystem;
use Monadial\Nexus\Http\Server\Swoole\Threads\Server\SwooleThreadConfig;
use Monadial\Nexus\Http\Server\Swoole\Threads\Server\SwooleThreadServer;
use Monadial\Nexus\Http\Ws\CompiledApplication;
use Monadial\Nexus\Http\Ws\WsApplication;
use Monadial\Nexus\WorkerPool\WorkerNode;

SwooleThreadServer::run(
    SwooleThreadConfig::bind('0.0.0.0', 8080)->threads(8),
    static function (ActorSystem $system, WorkerNode $node): CompiledApplication {
        $app = WsApplication::create($system);
        $app->get('/api/users', UsersController::class);
        return $app->compile();
    },
);

Pool-singleton actors

Across N HTTP-serving threads, declare an actor as PoolSingleton and the framework places it on whichever thread the hash ring assigns. All other threads' handlers reach it through a WorkerActorRef.

use Monadial\Nexus\Http\Server\Swoole\Threads\Actor\WorkerNodePoolSingletonSpawner;

$app->withPoolSingletonSpawner(new WorkerNodePoolSingletonSpawner($node));
$app->actor('store', $storeProps)->poolSingleton();

WebSocket — handler mode only in v1

Enable via ->enableWebSocket(true) on the config. Channel-mode routes (channel(...)) are rejected at boot: the channel-actor message payload is not serialization-safe across Thread\Queue, so accepting them under thread-distributed load would violate the per-channel-key actor guarantee. Use handler-mode WebSocket here, or switch to nexus-actors/http-server-swoole (worker mode) for channel actors.

Configuration

SwooleThreadConfig::bind('0.0.0.0', 8080)
    ->threads(8)
    ->maxRequest(10_000)
    ->shutdownTimeout(Duration::seconds(10))
    ->enableWebSocket(true)
    ->logger($psrLogger);

Status

Thread-mode HTTP + handler-mode WebSocket — stable. Channel-mode WebSocket — rejected at boot in v1 (see above).

Repository

Read-only subtree split of nexus-actors/nexus. Report issues and send pull requests to the monorepo — this repository only receives automated pushes and release tags.