Opcode Registry

Author: sirn-se

docs/Changelog.md

@@ -8,6 +8,7 @@
 
 ### `3.8.0`
 
+ * Configurable opcode/class mapping (@sirn-se)
  * Dispach onDisconnect on remote connection close (@srebb, @sirn-se)
  * Exceptions: ControlInterface on CloseException, ReconnectException (@sirn-se)
  * Exceptions: HandlerLevelInterface on BadUriException, ClientException, RunnerException, ServerException (@sirn-se)

docs/Configuration.md

@@ -145,6 +145,33 @@ $frameSize = $server->getFrameSize();
 $server->setFrameSize($frameSize);
 ```
 
+### Opcode registry
+
+```
+type: WebSocket\Message\OpcodeRegistry
+default: Phrity\Net\OpcodeRegistry // Default mapping
+```
+
+By default, opcodes are mapped to built-in classes (text, binary, close, ping, pong).
+With the OpcodeRegistry, the library can be configured to replace or add additional opcode imlementations.
+
+```php
+// Configuration instance
+$configuration = new WebSocket\Configuration(opcodeRegistry: $opcodeRegistry);
+$configuration->setOpcodeRegistry($opcodeRegistry);
+$opcodeRegistry = $configuration->getOpcodeRegistry();
+```
+
+The `register(int $opcode, string $classname)` method will replace or add mapping.
+- `$opcode` must be integer in range 1-15
+- `$classname` must be class-string for class that extend `WebSocket\Message\Message`
+
+```php
+$opcodeRegistry = $configuration->getOpcodeRegistry();
+$opcodeRegistry->register(1, 'MyTextMessage'); // Will replace Text for opcode=1
+$opcodeRegistry->register(3, 'MyCustomMessage'); // Will add support for opcode=3
+```
+
 ### Persistent connection (Client only)
 
 ```

src/Configuration.php

@@ -15,6 +15,7 @@
     NullLogger,
 };
 use Stringable;
+use WebSocket\Message\OpcodeRegistry;
 use WebSocket\Trait\StringableTrait;
 
 /**
@@ -34,6 +35,7 @@ class Configuration implements LoggerAwareInterface, Stringable
     private bool $persistent;
     /** @var int<1, max>|null $maxConnections */
     private int|null $maxConnections;
+    private OpcodeRegistry $opcodeRegistry;
 
 
     /* ---------- Magic methods ------------------------------------------------------------------------------------ */
@@ -45,6 +47,7 @@ class Configuration implements LoggerAwareInterface, Stringable
      * @param int<1, max> $frameSize
      * @param bool $persistent
      * @param int<1, max>|null $maxConnections
+     * @param OpcodeRegistry $opcodeRegistry
      */
     public function __construct(
         LoggerInterface|null $logger = null,
@@ -53,13 +56,15 @@ public function __construct(
         int|null $frameSize = null,
         bool|null $persistent = null,
         int|null $maxConnections = null,
+        OpcodeRegistry|null $opcodeRegistry = null,
     ) {
         $this->setLogger($logger ?? new NullLogger());
         $this->setContext($context ?? new Context());
         $this->setTimeout($timeout ?? 60);
         $this->setFrameSize($frameSize ?? 4096);
         $this->setPersistent($persistent ?? false);
         $this->setMaxConnections($maxConnections);
+        $this->setOpcodeRegistry($opcodeRegistry ?? new OpcodeRegistry());
     }
 
     public function __toString(): string
@@ -151,6 +156,24 @@ public function setFrameSize(int $frameSize): void
         $this->frameSize = $frameSize;
     }
 
+    /* ---------- OpcodeRegistry methods --------------------------------------------------------------------------- */
+
+    /**
+     * @return OpcodeRegistry
+     */
+    public function getOpcodeRegistry(): OpcodeRegistry
+    {
+        return $this->opcodeRegistry;
+    }
+
+    /**
+     * @param OpcodeRegistry $opcodeRegistry
+     */
+    public function setOpcodeRegistry(OpcodeRegistry $opcodeRegistry): void
+    {
+        $this->opcodeRegistry = $opcodeRegistry;
+    }
+
 
     /* ---------- Persistent methods (Client only) ----------------------------------------------------------------- */
 

src/Connection.php

@@ -89,8 +89,12 @@ public function __construct(
         Configuration|null $configuration = null,
     ) {
         $this->stream = $stream;
+        $this->initConfiguration($configuration);
         $this->httpHandler = new HttpHandler($this->stream, $ssl, $httpFactory);
-        $this->messageHandler = new MessageHandler(new FrameHandler($this->stream, $pushMasked, $pullMaskedRequired));
+        $this->messageHandler = new MessageHandler(
+            new FrameHandler($this->stream, $pushMasked, $pullMaskedRequired),
+            $this->configuration
+        );
         $this->middlewareHandler = new MiddlewareHandler($this->messageHandler, $this->httpHandler);
         $this->localName = $this->stream->getLocalName() ?? '<unknown>';
         $this->remoteName = $this->stream->getRemoteName() ?? '<unknown>';
@@ -99,7 +103,6 @@ public function __construct(
             $this->getIdentityPart($this->localName),
             $this->getIdentityPart($this->remoteName),
         );
-        $this->initConfiguration($configuration);
         $this->stream->setTimeout($this->configuration->getTimeout());
     }
 

src/Frame/Frame.php

@@ -18,15 +18,19 @@ class Frame implements Stringable
 {
     use StringableTrait;
 
-    private string $opcode;
+    /** @var int<0, 15> $opcode */
+    private int $opcode;
     private string $payload;
     private bool $final;
     private bool $rsv1;
     private bool $rsv2;
     private bool $rsv3;
 
+    /**
+     * @param int<0, 15> $opcode
+     */
     public function __construct(
-        string $opcode,
+        int $opcode,
         string $payload,
         bool $final,
         bool $rsv1 = false,
@@ -68,10 +72,13 @@ public function getRsv3(): bool
 
     public function isContinuation(): bool
     {
-        return $this->opcode === 'continuation';
+        return $this->opcode === 0;
     }
 
-    public function getOpcode(): string
+    /**
+     * @return int<0, 15>
+     */
+    public function getOpcode(): int
     {
         return $this->opcode;
     }

src/Frame/FrameHandler.php

@@ -18,7 +18,6 @@
 use WebSocket\Exception\CloseException;
 use WebSocket\Trait\{
     ConfigurationTrait,
-    OpcodeTrait,
     StringableTrait
 };
 
@@ -29,7 +28,6 @@
 class FrameHandler implements LoggerAwareInterface, Stringable
 {
     use ConfigurationTrait;
-    use OpcodeTrait;
     use StringableTrait;
 
     private const SCOPE = 'frame-handler';
@@ -75,9 +73,7 @@ public function pull(): Frame
         $rsv3 = (bool)($byte1 & 0b00010000);
 
         // Parse opcode
-        $opcodeInt = $byte1 & 0b00001111;
-        $opcodeInts = array_flip(self::$opcodes);
-        $opcode = array_key_exists($opcodeInt, $opcodeInts) ? $opcodeInts[$opcodeInt] : strval($opcodeInt);
+        $opcode = $byte1 & 0b00001111;
 
         // Masking bit
         $masked = (bool)($byte2 & 0b10000000);
@@ -144,7 +140,7 @@ public function push(Frame $frame): int
         $byte1 |= $frame->getRsv1() ? 0b01000000 : 0b00000000; // RSV1 bit.
         $byte1 |= $frame->getRsv2() ? 0b00100000 : 0b00000000; // RSV2 bit.
         $byte1 |= $frame->getRsv3() ? 0b00010000 : 0b00000000; // RSV3 bit.
-        $byte1 |= self::$opcodes[$frame->getOpcode()]; // Set opcode.
+        $byte1 |= $frame->getOpcode(); // Set opcode.
         $data .= pack('C', $byte1);
 
         $byte2 = $this->pushMasked ? 0b10000000 : 0b00000000; // Masking bit marker.

src/Message/Message.php

@@ -89,18 +89,20 @@ public function setCompress(bool $compress): void
     /**
      * Split messages into frames
      * @param int<1, max> $frameSize
+     * @param OpcodeRegistry|null $opcodeRegistry
      * @return array<Frame>
      */
-    public function getFrames(int $frameSize = 4096): array
+    public function getFrames(int $frameSize = 4096, OpcodeRegistry|null $opcodeRegistry = null): array
     {
+        $opcodeRegistry = $opcodeRegistry ?? new OpcodeRegistry();
         $frames = [];
         $split = str_split($this->getPayload(), $frameSize);
         if (empty($split)) {
             $split = [''];
         }
         foreach ($split as $i => $payload) {
             $frames[] = new Frame(
-                $i === 0 ? $this->opcode : 'continuation',
+                $i === 0 ? $opcodeRegistry->getOpcode(static::class) : 0,
                 $payload,
                 $i === array_key_last($split)
             );

src/Message/MessageHandler.php

@@ -13,13 +13,13 @@
 };
 use Stringable;
 use WebSocket\Configuration;
-use WebSocket\Exception\BadOpcodeException;
 use WebSocket\Frame\{
     Frame,
     FrameHandler,
 };
 use WebSocket\Trait\{
     ConfigurationTrait,
+    OpcodeTrait,
     StringableTrait,
 };
 
@@ -30,6 +30,7 @@
 class MessageHandler implements LoggerAwareInterface, Stringable
 {
     use ConfigurationTrait;
+    use OpcodeTrait;
     use StringableTrait;
 
     private const DEFAULT_SIZE = 4096;
@@ -65,7 +66,7 @@ public function setLogger(LoggerInterface $logger): void
      */
     public function push(Message $message, int $size = self::DEFAULT_SIZE): Message
     {
-        $frames = $message->getFrames($size);
+        $frames = $message->getFrames($size, $this->configuration->getOpcodeRegistry());
         foreach ($frames as $frame) {
             $this->frameHandler->push($frame);
         }
@@ -100,19 +101,13 @@ public function pull(): Message
 
     /**
      * @param non-empty-array<Frame> $frames
-     * @throws BadOpcodeException
      */
     private function createMessage(array $frames): Message
     {
-        $opcode = $frames[0]->getOpcode() ?? null;
-        $message = match ($opcode) {
-            'text' => new Text(),
-            'binary' => new Binary(),
-            'ping' => new Ping(),
-            'pong' => new Pong(),
-            'close' => new Close(),
-            default => throw new BadOpcodeException("Invalid opcode '{$opcode}' provided"),
-        };
+        /** @var int<1, 15> $opcode */
+        $opcode = $frames[0]->getOpcode();
+        $message = $this->configuration->getOpcodeRegistry()->createMessage($opcode);
+
         $message->setPayload(array_reduce($frames, function (string $carry, Frame $item) {
             return $carry . $item->getPayload();
         }, ''));

src/Message/OpcodeRegistry.php

@@ -0,0 +1,100 @@
+<?php
+
+/**
+ * Copyright (C) 2014-2026 Textalk and contributors.
+ * This file is part of Websocket PHP and is free software under the ISC License.
+ */
+
+namespace WebSocket\Message;
+
+use DomainException;
+use InvalidArgumentException;
+use RangeException;
+use WebSocket\Exception\BadOpcodeException;
+
+/**
+ * WebSocket\Message\OpcodeRegistry class.
+ * Mapping opcode <-> Message implementation class
+ */
+class OpcodeRegistry
+{
+    /** @var array<int<1, 15>, class-string> $map */
+    private array $map = [
+        1 => Text::class,
+        2 => Binary::class,
+        8 => Close::class,
+        9 => Ping::class,
+        10 => Pong::class,
+    ];
+
+    /**
+     * @param class-string $classname
+     * @return int<1, 15>
+     * @throws BadOpcodeException
+     */
+    public function getOpcode(string $classname): int
+    {
+        $opcode = array_search($classname, $this->map);
+        if (!is_int($opcode) || $opcode < 1 || $opcode > 15) {
+            throw new BadOpcodeException(sprintf(
+                'Opcode must be integer in range 1-15, %s provided',
+                json_encode($opcode)
+            ));
+        }
+        return $opcode;
+    }
+
+    /**
+     * @param int<1, 15> $opcode
+     * @return Message
+     * @throws BadOpcodeException
+     */
+    public function createMessage(int $opcode): Message
+    {
+        if ($opcode < 1 || $opcode > 15) {
+            throw new BadOpcodeException(sprintf(
+                'Opcode must be integer in range 1-15, %s provided',
+                json_encode($opcode)
+            ));
+        }
+        $classname = $this->map[$opcode] ?? null;
+        if (!is_string($classname) || !class_exists($classname)) {
+            throw new BadOpcodeException(sprintf(
+                'Implementation class %s for opcode %s not found',
+                json_encode($classname),
+                $opcode
+            ));
+        }
+        return new $classname();
+    }
+
+    /**
+     * @param int<1, 15> $opcode
+     * @param class-string $classname
+     * @throws BadOpcodeException
+     */
+    public function register(int $opcode, string $classname): void
+    {
+        if ($opcode < 1 || $opcode > 15) {
+            throw new RangeException(sprintf(
+                'Opcode must be integer in range 1-15, %s provided',
+                json_encode($opcode)
+            ));
+        }
+        if (empty($classname) || !class_exists($classname)) {
+            throw new DomainException(sprintf(
+                'Implementation class %s not found',
+                json_encode($classname)
+            ));
+        }
+        $class = new $classname();
+        if (!$class instanceof Message) {
+            throw new DomainException(sprintf(
+                'Implementation class %s must extend %s',
+                $class::class,
+                Message::class,
+            ));
+        }
+        $this->map[$opcode] = $classname;
+    }
+}

tests/suites/client/ClientErrorTest.php

@@ -108,7 +108,7 @@ public function testReceiveBadOpcode(): void
             return 'Test message';
         });
         $this->expectException(BadOpcodeException::class);
-        $this->expectExceptionMessage("Invalid opcode '15' provided");
+        $this->expectExceptionMessage("Implementation class null for opcode 15 not found");
         $message = $client->receive();
     }