create-prisma-php-app 5.1.0-alpha.3 → 5.1.0-alpha.30

package/dist/src/Lib/Websocket/Socket.php

@@ -0,0 +1,170 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lib\Websocket;
+
+use Ratchet\ConnectionInterface;
+use InvalidArgumentException;
+
+/**
+ * One open connection, as a socket handler holds it.
+ *
+ * The server half of `pp.socket(name, args, handlers)`. A handler receives
+ * this and the argument payload once the first frame arrives, wires its
+ * callbacks, and talks JSON frames both ways:
+ *
+ * ```php
+ * SocketRegistry::register('echo', function (Socket $socket, array $args): void {
+ *     $socket->onMessage(fn (mixed $value) => $socket->send($value));
+ * });
+ * ```
+ *
+ * The frame shape `{"error": "..."}` (that key alone) is reserved by the
+ * wire: it is how the server reports a failure inside an open connection,
+ * and the client runtime routes it to `onError` followed by the close.
+ * `send()` therefore refuses to emit it as an ordinary message.
+ */
+final class Socket
+{
+    private bool $closed = false;
+
+    /** @var callable|null fn(mixed $value): void */
+    private $messageListener = null;
+
+    /** @var callable|null fn(): void */
+    private $closeListener = null;
+
+    public function __construct(
+        private readonly ConnectionInterface $conn,
+        private readonly string $name,
+        private readonly mixed $authPayload = null,
+    ) {}
+
+    public function name(): string
+    {
+        return $this->name;
+    }
+
+    /**
+     * The verified auth payload of the connection, or null for a guest.
+     */
+    public function payload(): mixed
+    {
+        return $this->authPayload;
+    }
+
+    public function isOpen(): bool
+    {
+        return !$this->closed;
+    }
+
+    /**
+     * Send one JSON value. False means nobody is listening any more — the
+     * browser navigated away or closed the tab. That is the signal to stop,
+     * not an error to report.
+     */
+    public function send(mixed $value): bool
+    {
+        if ($this->closed) {
+            return false;
+        }
+
+        if (self::isReservedErrorShape($value)) {
+            throw new InvalidArgumentException(
+                'The frame shape {"error": "..."} is reserved for failures. '
+                    . 'Wrap the value or rename the key.'
+            );
+        }
+
+        $frame = json_encode($value, JSON_UNESCAPED_UNICODE);
+        if ($frame === false) {
+            return false;
+        }
+
+        $this->conn->send($frame);
+
+        return !$this->closed;
+    }
+
+    /**
+     * Called with each decoded JSON value the browser sends.
+     */
+    public function onMessage(callable $listener): void
+    {
+        $this->messageListener = $listener;
+    }
+
+    /**
+     * Called once, when the connection closes for any reason.
+     */
+    public function onClose(callable $listener): void
+    {
+        $this->closeListener = $listener;
+    }
+
+    /**
+     * Say goodbye mid-conversation. Close code 1000, a normal closure.
+     */
+    public function close(): void
+    {
+        if ($this->closed) {
+            return;
+        }
+
+        $this->conn->close(1000);
+    }
+
+    /**
+     * The error frame, then the close. The conversation is over.
+     * Framework/handler use for failures meant to reach `onError`.
+     */
+    public function error(string $message): void
+    {
+        if ($this->closed) {
+            return;
+        }
+
+        $this->conn->send(json_encode(['error' => $message], JSON_UNESCAPED_UNICODE));
+        $this->conn->close(1008);
+    }
+
+    /** @internal Called by the connection manager on each inbound frame. */
+    public function handleMessage(mixed $value): void
+    {
+        if ($this->messageListener !== null) {
+            ($this->messageListener)($value);
+        }
+    }
+
+    /** @internal Called by the connection manager when the wire closes. */
+    public function handleClose(): void
+    {
+        if ($this->closed) {
+            return;
+        }
+
+        $this->closed = true;
+
+        if ($this->closeListener !== null) {
+            ($this->closeListener)();
+        }
+    }
+
+    /** @internal Close with a specific code without emitting a frame. */
+    public function closeWithCode(int $code): void
+    {
+        if ($this->closed) {
+            return;
+        }
+
+        $this->conn->close($code);
+    }
+
+    public static function isReservedErrorShape(mixed $value): bool
+    {
+        return is_array($value)
+            && array_keys($value) === ['error']
+            && is_string($value['error']);
+    }
+}

package/dist/src/Lib/Websocket/SocketPool.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lib\Websocket;
+
+/**
+ * A broadcast pool: one `Socket` per open connection.
+ *
+ * How a handler shares its connection with the room it belongs to: keep one
+ * pool in shared state, `add` each socket when its conversation starts, and
+ * `broadcast` fans one value out to everyone. Connections whose browser is
+ * gone are pruned on the way. Keep authenticated and guest traffic in
+ * separate pools so a private broadcast can never reach a guest connection.
+ */
+final class SocketPool
+{
+    /** @var Socket[] */
+    private array $sockets = [];
+
+    public function count(): int
+    {
+        return count($this->sockets);
+    }
+
+    public function add(Socket $socket): void
+    {
+        $this->sockets[] = $socket;
+    }
+
+    public function discard(Socket $socket): void
+    {
+        $this->sockets = array_values(array_filter(
+            $this->sockets,
+            static fn (Socket $candidate): bool => $candidate !== $socket,
+        ));
+    }
+
+    /**
+     * Send one value to everyone, pruning closed connections.
+     */
+    public function broadcast(mixed $value): void
+    {
+        foreach ($this->sockets as $socket) {
+            if (!$socket->send($value)) {
+                $this->discard($socket);
+            }
+        }
+    }
+}

package/dist/src/Lib/Websocket/SocketRegistry.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lib\Websocket;
+
+use InvalidArgumentException;
+
+/**
+ * The named-socket registry: what `pp.socket("name", ...)` connects to.
+ *
+ * The client connects with a name and nothing else, so socket names are
+ * unique application-wide and a duplicate is refused at registration time.
+ * Registrations live in `src/Lib/Websocket/sockets.php`, which the socket
+ * server loads on startup.
+ */
+final class SocketRegistry
+{
+    /**
+     * @var array<string, array{
+     *     name: string,
+     *     handler: callable,
+     *     requireAuth: bool,
+     *     allowedRoles: string[],
+     * }>
+     */
+    private static array $sockets = [];
+
+    /**
+     * Register a function as a named socket.
+     *
+     * The handler receives `(Socket $socket, array $args)`: the open
+     * connection and the argument payload from the connection's first frame.
+     *
+     * - `requireAuth: true` refuses the connection unless the handshake
+     *   carries a valid auth cookie, before the handler runs.
+     * - `allowedRoles: [...]` adds RBAC on the verified payload, the same
+     *   rule as `#[Exposed(allowedRoles: [...])]`.
+     *
+     * @param string[] $allowedRoles
+     */
+    public static function register(
+        string $name,
+        callable $handler,
+        bool $requireAuth = false,
+        array $allowedRoles = [],
+    ): void {
+        if ($name === '') {
+            throw new InvalidArgumentException('A socket needs a non-empty name.');
+        }
+
+        if (isset(self::$sockets[$name])) {
+            throw new InvalidArgumentException(
+                "Two sockets are named `$name`. The client connects with a "
+                    . 'name and nothing else, so socket names must be unique '
+                    . 'application-wide.'
+            );
+        }
+
+        self::$sockets[$name] = [
+            'name' => $name,
+            'handler' => $handler,
+            'requireAuth' => $requireAuth,
+            'allowedRoles' => array_values($allowedRoles),
+        ];
+    }
+
+    /**
+     * @return array{
+     *     name: string,
+     *     handler: callable,
+     *     requireAuth: bool,
+     *     allowedRoles: string[],
+     * }|null
+     */
+    public static function get(string $name): ?array
+    {
+        return self::$sockets[$name] ?? null;
+    }
+
+    /**
+     * @return string[]
+     */
+    public static function names(): array
+    {
+        return array_keys(self::$sockets);
+    }
+}

package/dist/src/Lib/Websocket/sockets.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Named-socket registrations: the server half of `pp.socket(...)`.
+ *
+ * This file is loaded once by `websocket-server.php` on startup. Register
+ * each socket the app serves here; the name the client connects with is the
+ * registered one, and names are unique application-wide.
+ *
+ * From the browser:
+ *
+ * ```js
+ * const sock = pp.socket("echo", { label: "you" }, {
+ *     onMessage: (value) => append(value),
+ * });
+ * sock.send("hello");
+ * ```
+ */
+
+use Lib\Websocket\Socket;
+use Lib\Websocket\SocketPool;
+use Lib\Websocket\SocketRegistry;
+
+// A minimal example: echo every frame back, prefixed with the label the
+// page opened the socket with.
+SocketRegistry::register('echo', function (Socket $socket, array $args): void {
+    $label = is_string($args['label'] ?? null) ? $args['label'] : 'echo';
+
+    $socket->onMessage(function (mixed $value) use ($socket, $label): void {
+        $text = is_string($value) ? $value : json_encode($value, JSON_UNESCAPED_UNICODE);
+        $socket->send("$label: $text");
+    });
+});
+
+// A broadcast example: everyone connected to `chat` hears everyone else.
+$chatRoom = new SocketPool();
+
+SocketRegistry::register('chat', function (Socket $socket, array $args) use ($chatRoom): void {
+    $chatRoom->add($socket);
+
+    $socket->onMessage(function (mixed $value) use ($chatRoom): void {
+        $chatRoom->broadcast($value);
+    });
+
+    $socket->onClose(function () use ($chatRoom, $socket): void {
+        $chatRoom->discard($socket);
+    });
+});

package/dist/src/Lib/Websocket/websocket-server.php

@@ -54,7 +54,10 @@ if ($probe === false) {
 fclose($probe);
 
 // ── Build app ────────────────────────────────────────────────────────────────
-$manager = new ConnectionManager(); // your app component
+// Named-socket registrations: the functions `pp.socket("name", ...)` reaches.
+require __DIR__ . '/sockets.php';
+
+$manager = new ConnectionManager(); // The PulsePoint named-socket wire.
 $server  = IoServer::factory(
     new HttpServer(new WsServer($manager)),
     $port,
@@ -73,14 +76,18 @@ echo "   Port:       {$port}" . PHP_EOL;
 echo "   URL:        {$url}" . PHP_EOL;
 echo "   PID:        {$pid}" . PHP_EOL;
 echo "   Started:    {$ts}" . PHP_EOL;
+echo "   Sockets:    " . (implode(', ', \Lib\Websocket\SocketRegistry::names()) ?: '(none registered)') . PHP_EOL;
 
 // ── Graceful shutdown & periodic logs (if loop available) ────────────────────
 $loop = property_exists($server, 'loop') ? $server->loop : null;
 if ($loop instanceof LoopInterface) {
+    // First-frame timeout and idle sweep need the loop's timers.
+    $manager->attachLoop($loop);
+
     // Periodic stats every 60s
-    $loop->addPeriodicTimer(60, function () use ($ok) {
+    $loop->addPeriodicTimer(60, function () use ($ok, $manager) {
         $mem = function_exists('memory_get_usage') ? number_format(memory_get_usage(true) / 1048576, 2) . ' MB' : 'n/a';
-        $msg = "✓ Heartbeat — memory: {$mem}";
+        $msg = "✓ Heartbeat — connections: {$manager->openConnectionCount()}, memory: {$mem}";
         echo $ok($msg) . PHP_EOL;
     });
 

package/dist/src/app/globals.css

@@ -1,4 +1,6 @@
-@import "tailwindcss";
+@import "tailwindcss" source(none);
+@source "../";
+@source "../../ts";
 
 :root {
   --background: #ffffff;

package/dist/src/app/layout.php

@@ -15,7 +15,7 @@ MainLayout::$description = !empty(MainLayout::$description) ? MainLayout::$descr
     <!-- Dynamic Header Scripts -->
 </head>
 
-<body pp-spa="true" style="opacity:0;pointer-events:none;user-select:none;transition:opacity .18s ease-out;">
+<body style="opacity:0;pointer-events:none;user-select:none;transition:opacity .18s ease-out;">
     <?= MainLayout::$children; ?>
     <!-- Dynamic Footer Scripts -->
 </body>

package/dist/tests/AuthTest.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use Firebase\JWT\JWT;
+use Lib\Auth\Auth;
+use PHPUnit\Framework\TestCase;
+use PP\Env;
+
+/**
+ * The JWT session tokens both wires trust: RPC auth reads them through the
+ * request session, and the socket server verifies the handshake cookie with
+ * `verifyToken(...)` alone.
+ */
+final class AuthTest extends TestCase
+{
+    public function testSignInReturnsATokenThatVerifiesBackToThePayload(): void
+    {
+        $auth = Auth::getInstance();
+
+        $jwt = $auth->signIn('admin');
+
+        self::assertSame('admin', $auth->verifyToken($jwt));
+    }
+
+    public function testATamperedTokenVerifiesToNull(): void
+    {
+        $auth = Auth::getInstance();
+        $jwt = $auth->signIn('admin');
+
+        self::assertNull($auth->verifyToken($jwt . 'x'));
+        self::assertNull($auth->verifyToken('not-a-jwt'));
+        self::assertNull($auth->verifyToken(null));
+    }
+
+    public function testAnExpiredTokenVerifiesToNull(): void
+    {
+        $expired = JWT::encode(
+            [Auth::PAYLOAD_NAME => 'admin', 'exp' => time() - 60],
+            Env::string('AUTH_SECRET', ''),
+            'HS256'
+        );
+
+        self::assertNull(Auth::getInstance()->verifyToken($expired));
+    }
+
+    public function testATokenSignedWithADifferentSecretVerifiesToNull(): void
+    {
+        $forged = JWT::encode(
+            [Auth::PAYLOAD_NAME => 'admin', 'exp' => time() + 3600],
+            'a-different-32-byte-signing-secret-key',
+            'HS256'
+        );
+
+        self::assertNull(Auth::getInstance()->verifyToken($forged));
+    }
+}