{"id":19665933,"url":"https://github.com/amphp/cluster","last_synced_at":"2025-04-04T19:12:47.473Z","repository":{"id":53892304,"uuid":"124773821","full_name":"amphp/cluster","owner":"amphp","description":"Building multi-core network applications with PHP.","archived":false,"fork":false,"pushed_at":"2024-12-21T02:01:00.000Z","size":319,"stargazers_count":61,"open_issues_count":9,"forks_count":9,"subscribers_count":6,"default_branch":"2.x","last_synced_at":"2025-03-28T18:15:44.131Z","etag":null,"topics":["amphp","async","cluster","cluster-watcher","multi-core","multi-processing","parallel","php","sockets"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amphp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"amphp"}},"created_at":"2018-03-11T16:04:11.000Z","updated_at":"2025-03-02T14:28:45.000Z","dependencies_parsed_at":"2023-12-19T03:04:20.557Z","dependency_job_id":"7c0f9933-27ae-4d15-9ab5-1be1023959e7","html_url":"https://github.com/amphp/cluster","commit_stats":{"total_commits":144,"total_committers":3,"mean_commits":48.0,"dds":"0.33333333333333337","last_synced_commit":"5db4718bb42e8be7214ed58413ebf2097e7bba45"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amphp%2Fcluster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amphp%2Fcluster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amphp%2Fcluster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amphp%2Fcluster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amphp","download_url":"https://codeload.github.com/amphp/cluster/tar.gz/refs/heads/2.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234923,"owners_count":20905854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amphp","async","cluster","cluster-watcher","multi-core","multi-processing","parallel","php","sockets"],"created_at":"2024-11-11T16:25:31.505Z","updated_at":"2025-04-04T19:12:47.456Z","avatar_url":"https://github.com/amphp.png","language":"PHP","readme":"# amphp/cluster\n\nAMPHP is a collection of event-driven libraries for PHP designed with fibers and concurrency in mind.\n`amphp/cluster` provides tools to transfer network sockets to independent PHP processes, as well as a lightweight framework to create a multiprocess server cluster.\n\n## Requirements\n\n- PHP 8.1+\n- [`ext-sockets`](https://php.net/sockets)\n\n## Installation\n\nThis package can be installed as a [Composer](https://getcomposer.org/) dependency.\n\n```bash\ncomposer require amphp/cluster\n```\n\n## Documentation\n\n### Transferring Sockets\n\nClusters are built by transferring sockets from a parent process to child processes, each of which listen for connections and/or handles client sockets. This library provides low-level components which may be used independent of the Cluster framework. These components allow you to write your own server logic which transfers server sockets or client sockets to child processes to distribute load or group related clients.\n\n#### Transferring Client Sockets\n\n`ClientSocketReceivePipe` and `ClientSocketSendPipe` pair of classes are used to send client sockets from one PHP process to another over an existing IPC connection between the two processes.\n\nThe example below demonstrates creating a new child process in a parent, then establishing a new IPC socket between the parent and child. That socket is used to create a `ClientSocketSendPipe` in the parent and a corresponding `ClientSocketReceivePipe` in the child. The parent then creates a socket server and listens for connections. When a connection is received, the client socket is transferred to the child process where it is handled.\n\n```php\n// parent.php\n\nuse Amp\\Cluster\\ClientSocketSendPipe;\nuse Amp\\Parallel\\Context\\ProcessContextFactory;\nuse Amp\\Parallel\\Ipc\\LocalIpcHub;\nuse Amp\\Socket;\nuse Revolt\\EventLoop;\nuse function Amp\\Socket\\listen;\n\n$ipcHub = new LocalIpcHub();\n\n// Sharing the IpcHub instance with the context factory isn't required,\n// but reduces the number of opened sockets.\n$contextFactory = new ProcessContextFactory(ipcHub: $ipcHub);\n\n$context = $contextFactory-\u003estart(__DIR__ . '/child.php');\n\n$connectionKey = $ipcHub-\u003egenerateKey();\n$context-\u003esend(['uri' =\u003e $ipcHub-\u003egetUri(), 'key' =\u003e $connectionKey]);\n\n// $socket will be a bidirectional socket to the child.\n$socket = $ipcHub-\u003eaccept($connectionKey);\n\n$socketPipe = new ClientSocketSendPipe($socket);\n\n$server = listen('127.0.0.1:1337');\n\n// Close server when SIGTERM is received.\nEventLoop::onSignal(SIGTERM, $server-\u003eclose(...));\n\n$clientId = 0;\nwhile ($client = $server-\u003eaccept()) {\n    // $clientId is an example of arbitrary data which may be\n    // associated with a transferred socket.\n    $socketPipe-\u003esend($client, ++$clientId);\n}\n```\n\n```php\n// child.php\n\nuse Amp\\Cluster\\ClientSocketReceivePipe;\nuse Amp\\Socket\\Socket;\nuse Amp\\Sync\\Channel;\n\nreturn function (Channel $channel): void {\n    ['uri' =\u003e $uri, 'key' =\u003e $connectionKey] = $channel-\u003ereceive();\n\n    // $socket will be a bidirectional socket to the parent.\n    $socket = Amp\\Parallel\\Ipc\\connect($uri, $connectionKey);\n\n    $socketPipe = new ClientSocketReceivePipe($socket);\n\n    while ($transferredSocket = $socketPipe-\u003ereceive()) {\n        // Handle client socket in a separate coroutine (fiber).\n        async(\n            function (Socket $client, int $id) { /* ... */ },\n            $transferredSocket-\u003egetSocket(), // Transferred socket\n            $transferredSocket-\u003egetData(), // Associated data\n        );\n    }\n};\n```\n\nWhile this example is somewhat contrived as there would be little reason to send all clients to a single process, it is easy to extrapolate such an example to a parent process which load balances a set of children or distributes clients based on some other factor. Reading and writing may take place on the client socket in the parent before being transferred. For example, an HTTP server may establish a WebSocket connection before transferring the socket to a child process. See [`amphp/http-server`](https://github.com/amphp/http-server) and [`amphp/websocket-server`](https://github.com/amphp/websocket-server) for additional components to build such a server.\n\n#### Transferring Server Sockets\n\nThe example below demonstrates creating a new child process in a parent, then establishing a new IPC socket between the parent and child. In the parent, the IPC socket is passed to `ServerSocketPipeProvider::provideFor()`, which listens for requests for server sockets on the IPC socket. In the child, the IPC socket is provided to an instance of `ServerSocketPipeFactory`. When the child creates a server socket using the `ServerSocketPipeFactory`, the server socket is created in the parent process, then sent to the child. If the parent created multiple children, any child that requested the same server socket would receive another reference to the same socket, allowing multiple children to listen on the same address and port. Incoming client connections are selected round-robin by the operating system. For greater control over client distribution, consider accepting clients in a single process and transferring client sockets to children instead.\n\n`ServerSocketPipeFactory` implements `ServerSocketFactory`, allowing it to be used in place of factories which create the server socket within the same process.\n\n```php\n// parent.php\n\nuse Amp\\CancelledException;\nuse Amp\\Cluster\\ClientSocketSendPipe;\nuse Amp\\Cluster\\ServerSocketPipeProvider;\nuse Amp\\Parallel\\Context\\ProcessContextFactory;\nuse Amp\\Parallel\\Ipc\\LocalIpcHub;\nuse Amp\\SignalCancellation;\nuse Revolt\\EventLoop;\nuse function Amp\\async;\nuse function Amp\\Socket\\listen;\n\n$ipcHub = new LocalIpcHub();\n\n$serverProvider = new ServerSocketPipeProvider();\n\n// Sharing the IpcHub instance with the context factory isn't required,\n// but reduces the number of opened sockets.\n$contextFactory = new ProcessContextFactory(ipcHub: $ipcHub);\n\n$context = $contextFactory-\u003estart(__DIR__ . '/child.php');\n\n$connectionKey = $ipcHub-\u003egenerateKey();\n$context-\u003esend(['uri' =\u003e $ipcHub-\u003egetUri(), 'key' =\u003e $connectionKey]);\n\n// $socket will be a bidirectional socket to the child.\n$socket = $ipcHub-\u003eaccept($connectionKey);\n\n// Listen for requests for server sockets on the given socket until cancelled by signal.\ntry {\n    $serverProvider-\u003eprovideFor($socket, new SignalCancellation(SIGTERM));\n} catch (CancelledException) {\n    // Signal cancellation expected.\n}\n```\n\n```php\n// child.php\n\nuse Amp\\Cluster\\ClientSocketReceivePipe;\nuse Amp\\Cluster\\ServerSocketPipeFactory;\nuse Amp\\Sync\\Channel;\n\nreturn function (Channel $channel): void {\n    ['uri' =\u003e $uri, 'key' =\u003e $connectionKey] = $channel-\u003ereceive();\n\n    // $socket will be a bidirectional socket to the parent.\n    $socket = Amp\\Parallel\\Ipc\\connect($uri, $connectionKey);\n\n    $serverFactory = new ServerSocketPipeFactory($socket);\n\n    // Requests the server socket from the parent process.\n    $server = $serverFactory-\u003elisten('127.0.0.1:1337');\n\n    while ($client = $server-\u003eaccept()) {\n        // Handle client socket in a separate coroutine (fiber).\n        async(function () use ($client) { /* ... */ });\n    }\n};\n```\n\n---\n\n### Clusters\n\nClusters are created from specialized scripts using static methods of `Cluster` to create components which communicate with the parent watcher process when running as part of a cluster. Some `Cluster` methods may also be called when a script is run directly, returning a standalone component which does not require a watcher process. For example, `Cluster::getServerSocketFactory()` returns an instance which creates and transfers the server socket from the watcher process when running within a cluster, or instead returns a `ResourceSocketServerFactory` when running a script directly.\n\nCluster scripts can be run using the included executable `vendor/bin/cluster` from the command line or programmatically from within an application using the `ClusterWatcher` class.\n\n```bash\nvendor/bin/cluster --workers=4 path/to/script.php\n```\n\nWhen installed as a dependency to your project, the command above will start a cluster of 4 workers, each running the script at `path/to/script.php`.\n\nAlternatively, your application can launch a cluster from code using `ClusterWatcher`.\n\n```php\nuse Amp\\Cluster\\ClusterWatcher;\nuse Revolt\\EventLoop;\n\n$watcher = new ClusterWatcher('path/to/script.php');\n$watcher-\u003estart(4); // Start cluster with 4 workers.\n\n// Using a signal to stop the cluster for this example.\nEventLoop::onSignal(SIGTERM, fn () =\u003e $watcher-\u003estop());\n\nforeach ($watcher-\u003egetMessageIterator() as $message) {\n    // Handle received message from worker.\n}\n```\n\n#### Creating a Server\n\nComponents in AMPHP which must use socket servers use instances of `Amp\\Socket\\SocketServerFactory` to create these socket severs. One such component is `Amp\\Http\\Server\\SocketHttpServer` in [`amphp/http-server`](https://github.com/amphp/http-server). Within a cluster script, `Cluster::getServerSocketFactory()` should be used to create a socket factory which will either create the socket locally or requests the server socket from the cluster watcher.\n\nThe [example HTTP server](#example-http-server) below demonstrates using `Cluster::getServerSocketFactory()` to create an instance of `ServerSocketFactory` and provide it when creating a `SocketHttpServer`.\n\n#### Logging\n\nLog entries may be sent to the cluster watcher to be logged to a single stream by using `Cluster::createLogHandler()`. This handler can be attached to a `Monolog\\Logger` instance. The [example HTTP server](#example-http-server) below creates a log handler depending upon if the script is a cluster worker or running as a standalone script.\n\n`Cluster::createLogHandler()` may only be called when running the cluster script as part of a cluster. Use `Cluster::isWorker()` to check if the script is running as a cluster worker.\n\n#### Process Termination\n\nA cluster script may await termination from a signal (one of `SIGTERM`, `SIGINT`, `SIGQUIT`, or `SIGHUP`) by using `Cluster::awaitTermination()`.\n\n#### Sending and Receiving Messages\n\nThe cluster watcher and workers may send serializable data to each other. The cluster watcher receives messages from workers via a concurrent iterator returned by `ClusterWatcher::getMessageIterator()`. The iterator emits instances of `ClusterWorkerMessage`, containing the data received and a reference to the `ClusterWorker` which sent the message which can be used to send a reply to only that worker. The cluster watcher may broadcast a message to all workers using `ClusterWatcher::broadcast()`.\n\nWorkers can send and receive messages using a `Channel` returned from `Cluster::getChannel()`. This method may only be called when running the cluster script as part of a cluster. Use `Cluster::isWorker()` to check if the script is running as a cluster worker.\n\n#### Restarting\n\n`ClusterWatcher::restart()` may be called at anytime to stop all existing workers and create new workers to replace those which were stopped. When using processes for workers (that is, not using threads via `ext-parallel`), the code running in the workers will be reloaded when the new process starts.\n\n#### Hot Reload in IntelliJ / PhpStorm\n\nWhen running the cluster using the cluster executable (`vendor/bin/cluster`), IntelliJ's file watchers can be used as trigger to send the `SIGUSR1` signal to the cluster's watcher process automatically on every file save.\nYou need to write a PID file using `--pid-file /path/to/file.pid` when starting the cluster and then set up a file watcher in the settings using the following settings:\n\n - Program: `bash`\n - Arguments: `-c \"if test -f ~/test-cluster.pid; then kill -10 $(cat ~/test-cluster.pid); fi\"`\n\n## Example HTTP Server\n\nThe example below (which can be found in the [examples](https://github.com/amphp/cluster/tree/master/examples) directory as [simple-http-server.php](https://github.com/amphp/cluster/blob/master/examples/cluster/simple-http-server.php)) uses [`amphp/http-server`](https://github.com/amphp/http-server) to create an HTTP server that can be run in any number of processes simultaneously.\n\n```php\n\u003c?php\n\nrequire __DIR__ . \"/vendor/autoload.php\";\n\nuse Amp\\ByteStream;\nuse Amp\\Cluster\\Cluster;\nuse Amp\\Http\\Server\\Driver\\ConnectionLimitingServerSocketFactory;\nuse Amp\\Http\\Server\\Driver\\SocketClientFactory;\nuse Amp\\Http\\Server\\RequestHandler\\ClosureRequestHandler;\nuse Amp\\Http\\Server\\SocketHttpServer;\nuse Amp\\Log\\ConsoleFormatter;\nuse Amp\\Log\\StreamHandler;\nuse Monolog\\Logger;\n\n$id = Cluster::getContextId() ?? getmypid();\n\n// Creating a log handler in this way allows the script to be run in a cluster or standalone.\nif (Cluster::isWorker()) {\n    $handler = Cluster::createLogHandler();\n} else {\n    $handler = new StreamHandler(ByteStream\\getStdout());\n    $handler-\u003esetFormatter(new ConsoleFormatter());\n}\n\n$logger = new Logger('worker-' . $id);\n$logger-\u003epushHandler($handler);\n$logger-\u003euseLoggingLoopDetection(false);\n\n// Cluster::getServerSocketFactory() will return a factory which creates the socket\n// locally or requests the server socket from the cluster watcher.\n$socketFactory = Cluster::getServerSocketFactory();\n$clientFactory = new SocketClientFactory($logger);\n\n$httpServer = new SocketHttpServer($logger, $socketFactory, $clientFactory);\n$httpServer-\u003eexpose('127.0.0.1:1337');\n\n// Start the HTTP server\n$httpServer-\u003estart(\n    new ClosureRequestHandler(function (): Response {\n        return new Response(HttpStatus::OK, [\n            \"content-type\" =\u003e \"text/plain; charset=utf-8\",\n        ], \"Hello, World!\");\n    }),\n    new DefaultErrorHandler(),\n);\n\n// Stop the server when the cluster watcher is terminated.\nCluster::awaitTermination();\n\n$server-\u003estop();\n```\n\n## Versioning\n\n`amphp/cluster` follows the [semver](http://semver.org/) semantic versioning specification like all other `amphp` packages.\n\n## Security\n\nIf you discover any security related issues, please use the private security issue reporter instead of using the public issue tracker.\n\n## License\n\nThe MIT License (MIT). Please see [`LICENSE`](./LICENSE) for more information.\n","funding_links":["https://github.com/sponsors/amphp"],"categories":["Multiprocessing"],"sub_categories":["Tunnel"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famphp%2Fcluster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famphp%2Fcluster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famphp%2Fcluster/lists"}