Conveyor SubProtocol

The native Conveyor subprotocol is a small JSON action protocol for direct WebSocket clients.

Enable native mode

1Constants::WEBSOCKET_SUBPROTOCOL => Constants::SOCKET_CONVEYOR

The WebSocket subprotocol value is:

1socketconveyor.com

Connection info

After a successful native WebSocket handshake, Conveyor sends:

1{
2  "action": "connection-info",
3  "data": "{\"fd\":1,\"event\":\"connection-info\"}"
4}

If acknowledgment is enabled, this message also includes an id.

Message shape

Clients send JSON messages with an action field. Most actions also require action-specific fields.

1{
2  "action": "base-action",
3  "data": "hello"
4}

Built-in actions

base-action

Echoes a message back to the current socket:

1{
2  "action": "base-action",
3  "data": "hello"
4}

channel-connect

Connects the current socket fd to one channel:

1{
2  "action": "channel-connect",
3  "channel": "orders.1"
4}

If Constants::WEBSOCKET_SERVER_TOKEN is configured, include either the server token or a temporary channel token:

1{
2  "action": "channel-connect",
3  "channel": "orders.1",
4  "auth": "temporary-token"
5}

broadcast-action

Sends data to other sockets in the current channel. If the sender is not connected to a channel, Conveyor broadcasts to sockets that are not in channels.

1{
2  "action": "broadcast-action",
3  "data": {
4    "body": "order updated"
5  }
6}

fanout-action

Sends data to every established socket:

1{
2  "action": "fanout-action",
3  "data": "hello everyone"
4}

If Constants::WEBSOCKET_SERVER_TOKEN is configured, fanout-action also requires auth with that server token.

channel-disconnect

Removes the current socket fd from its channel:

1{
2  "action": "channel-disconnect"
3}

acknowledge-action

Acknowledges receipt of a server message when native acknowledgment is enabled:

1{
2  "action": "acknowledge-action",
3  "data": "message-id"
4}

Channel flow

1. Client connects to the WebSocket server.
2. Server sends connection-info.
3. Client sends channel-connect with a channel.
4. Server records the fd-to-channel association.
5. Client sends broadcast-action with data.
6. Server wraps outbound data as { "action": "broadcast-action", "data": ..., "fd": senderFd }.
7. Server delivers the message to other established sockets in the same channel.

Custom actions

Register custom native action handlers with Constants::ACTIONS:

1use Conveyor\Constants;
2use Conveyor\ConveyorServer;
3use App\WebSocket\SampleAction;
4
5(new ConveyorServer())
6    ->port(8989)
7    ->conveyorOptions([
8        Constants::ACTIONS => [
9            new SampleAction(),
10        ],
11    ])
12    ->start();

Each action implements:

1public function execute(array $data): mixed;
2public function send(string $data, ?int $fd = null, bool $toChannel = false): void;
3public function getName(): string;