create-prisma-php-app 5.1.0-alpha.23 → 5.1.0-alpha.25

package/dist/tests/ConnectionManagerTest.php

@@ -0,0 +1,277 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use Lib\Auth\Auth;
+use Lib\Websocket\ConnectionManager;
+use Lib\Websocket\Socket;
+use Lib\Websocket\SocketRegistry;
+use PHPUnit\Framework\TestCase;
+use Tests\Support\FakeConnection;
+use Tests\Support\RequiresFeature;
+
+/**
+ * The named-socket wire from the server's side: where a connection must go,
+ * what the first frame is, and which failures travel as the reserved
+ * `{"error": ...}` frame.
+ *
+ * Mirrors the client runtime's SocketClient tests: name in the `name` query
+ * parameter, arguments as the first JSON object frame, refusals as an error
+ * frame followed by a close.
+ */
+final class ConnectionManagerTest extends TestCase
+{
+    use RequiresFeature;
+
+    /** @var array<string, string|false> */
+    private array $envBackup = [];
+
+    protected function setUp(): void
+    {
+        $this->requireFeature('websocket');
+        SocketRegistryTest::resetRegistry();
+    }
+
+    protected function tearDown(): void
+    {
+        SocketRegistryTest::resetRegistry();
+
+        foreach ($this->envBackup as $name => $previous) {
+            if ($previous === false) {
+                putenv($name);
+            } else {
+                putenv("$name=$previous");
+            }
+        }
+        $this->envBackup = [];
+    }
+
+    private function setEnv(string $name, string $value): void
+    {
+        if (!array_key_exists($name, $this->envBackup)) {
+            $this->envBackup[$name] = getenv($name);
+        }
+        putenv("$name=$value");
+    }
+
+    /** A connection from a dev-browser origin, upgraded and args sent. */
+    private function openWithArgs(
+        ConnectionManager $manager,
+        FakeConnection $conn,
+        array $args = [],
+    ): void {
+        $manager->onOpen($conn);
+        $manager->onMessage($conn, json_encode($args === [] ? new \stdClass() : $args));
+    }
+
+    private function devConnection(string $name): FakeConnection
+    {
+        return new FakeConnection(
+            "/__pulsepoint/ws?name=$name",
+            ['Origin' => 'http://localhost:3000'],
+        );
+    }
+
+    public function testUnknownNameIsRefusedWithAReadableErrorFrame(): void
+    {
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('nope');
+
+        $manager->onOpen($conn);
+
+        $frame = $conn->lastFrame();
+        self::assertIsArray($frame);
+        self::assertArrayHasKey('error', $frame);
+        self::assertStringContainsString('No socket named `nope`', $frame['error']);
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testMissingNameIsRefused(): void
+    {
+        $manager = new ConnectionManager();
+        $conn = new FakeConnection('/__pulsepoint/ws', ['Origin' => 'http://localhost:3000']);
+
+        $manager->onOpen($conn);
+
+        self::assertStringContainsString('named no socket', $conn->lastFrame()['error']);
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testArgumentsArriveAsTheFirstFrameAndReachTheHandler(): void
+    {
+        $received = null;
+        SocketRegistry::register('echo', function (Socket $socket, array $args) use (&$received): void {
+            $received = $args;
+            $socket->onMessage(fn (mixed $value) => $socket->send("you: $value"));
+        });
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('echo');
+
+        $this->openWithArgs($manager, $conn, ['room' => 'lobby']);
+        self::assertSame(['room' => 'lobby'], $received);
+
+        $manager->onMessage($conn, '"hello"');
+        self::assertSame('you: hello', $conn->lastFrame());
+        self::assertSame([], $conn->closeCodes, 'the conversation stays open');
+    }
+
+    public function testEmptyArgumentsObjectIsAccepted(): void
+    {
+        $received = null;
+        SocketRegistry::register('feed', function (Socket $socket, array $args) use (&$received): void {
+            $received = $args;
+        });
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('feed');
+
+        $this->openWithArgs($manager, $conn);
+
+        self::assertSame([], $received);
+        self::assertSame([], $conn->closeCodes);
+    }
+
+    public function testANonObjectFirstFrameIsRefused(): void
+    {
+        SocketRegistry::register('echo', static function (): void {});
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('echo');
+
+        $manager->onOpen($conn);
+        $manager->onMessage($conn, '[1, 2]');
+
+        self::assertStringContainsString('not a JSON object', $conn->lastFrame()['error']);
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testAnUnreadableFrameTravelsBackAsAnErrorFrame(): void
+    {
+        SocketRegistry::register('echo', function (Socket $socket): void {
+            $socket->onMessage(static function (): void {});
+        });
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('echo');
+
+        $this->openWithArgs($manager, $conn);
+        $manager->onMessage($conn, '{not json');
+
+        self::assertStringContainsString('could not read a frame', $conn->lastFrame()['error']);
+    }
+
+    public function testAnOversizedFrameClosesWith1009(): void
+    {
+        SocketRegistry::register('echo', static function (): void {});
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('echo');
+
+        $this->openWithArgs($manager, $conn);
+        $manager->onMessage($conn, json_encode(str_repeat('x', 5000)));
+
+        self::assertContains(1009, $conn->closeCodes);
+    }
+
+    public function testProductionRefusesAnUnknownOriginBeforeAnyFrame(): void
+    {
+        SocketRegistry::register('echo', static function (): void {});
+        $this->setEnv('APP_ENV', 'production');
+
+        $manager = new ConnectionManager();
+        $conn = new FakeConnection(
+            '/__pulsepoint/ws?name=echo',
+            ['Origin' => 'https://evil.example'],
+        );
+
+        $manager->onOpen($conn);
+
+        self::assertSame([], $conn->sentFrames, 'refused silently, before the wire speaks');
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testProductionAcceptsAnOriginNamedInTheAllowlist(): void
+    {
+        SocketRegistry::register('echo', static function (): void {});
+        $this->setEnv('APP_ENV', 'production');
+        $this->setEnv('WEBSOCKET_ALLOWED_ORIGINS', 'https://app.example');
+
+        $manager = new ConnectionManager();
+        $conn = new FakeConnection(
+            '/__pulsepoint/ws?name=echo',
+            ['Origin' => 'https://app.example'],
+        );
+
+        $manager->onOpen($conn);
+
+        self::assertSame([], $conn->closeCodes);
+    }
+
+    public function testRequireAuthRefusesAGuestConnection(): void
+    {
+        SocketRegistry::register('private', static function (): void {}, requireAuth: true);
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('private');
+
+        $manager->onOpen($conn);
+
+        self::assertStringContainsString('signed-in session', $conn->lastFrame()['error']);
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testAValidAuthCookieReachesTheHandlerAsThePayload(): void
+    {
+        $seenPayload = false;
+        SocketRegistry::register('private', function (Socket $socket) use (&$seenPayload): void {
+            $seenPayload = $socket->payload();
+        }, requireAuth: true);
+
+        $jwt = Auth::getInstance()->signIn('admin');
+
+        $manager = new ConnectionManager();
+        $conn = new FakeConnection('/__pulsepoint/ws?name=private', [
+            'Origin' => 'http://localhost:3000',
+            'Cookie' => Auth::$cookieName . '=' . $jwt,
+        ]);
+
+        $this->openWithArgs($manager, $conn);
+
+        self::assertSame('admin', $seenPayload);
+        self::assertSame([], $conn->closeCodes);
+    }
+
+    public function testAHandlerExceptionTravelsAsTheErrorFrame(): void
+    {
+        SocketRegistry::register('broken', static function (): void {
+            throw new \RuntimeException('boom');
+        });
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('broken');
+
+        $this->openWithArgs($manager, $conn);
+
+        $frame = $conn->lastFrame();
+        self::assertArrayHasKey('error', $frame);
+        self::assertStringContainsString('boom', $frame['error'], 'development shows the message');
+        self::assertSame([1008], $conn->closeCodes);
+    }
+
+    public function testCloseReleasesTheConnectionSlot(): void
+    {
+        SocketRegistry::register('echo', static function (): void {});
+
+        $manager = new ConnectionManager();
+        $conn = $this->devConnection('echo');
+
+        $this->openWithArgs($manager, $conn);
+        self::assertSame(1, $manager->openConnectionCount());
+
+        $manager->onClose($conn);
+        self::assertSame(0, $manager->openConnectionCount());
+    }
+}

package/dist/tests/CsrfTest.php

@@ -0,0 +1,119 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use PHPUnit\Framework\TestCase;
+use PP\Security\Csrf;
+
+/**
+ * The CSRF half of the RPC wire: the `pp_csrf` cookie family and the
+ * double-submit validation of the `X-CSRF-Token` header.
+ */
+final class CsrfTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        $this->clearCsrfCookies();
+    }
+
+    protected function tearDown(): void
+    {
+        $this->clearCsrfCookies();
+    }
+
+    private function clearCsrfCookies(): void
+    {
+        foreach (array_keys($_COOKIE) as $name) {
+            if (str_starts_with((string) $name, 'pp_csrf')) {
+                unset($_COOKIE[$name]);
+            }
+        }
+    }
+
+    public function testCookieFamilyUsesThePpCsrfNamesTheRuntimeReads(): void
+    {
+        $names = Csrf::cookieNames();
+
+        self::assertNotEmpty($names);
+        self::assertSame('pp_csrf', end($names), 'plain pp_csrf is always the fallback name');
+
+        foreach ($names as $name) {
+            self::assertStringStartsWith('pp_csrf', $name);
+        }
+    }
+
+    public function testEnsureCookieMintsASignedTokenForEveryCookieName(): void
+    {
+        Csrf::ensureCookie();
+
+        foreach (Csrf::cookieNames() as $name) {
+            self::assertArrayHasKey($name, $_COOKIE);
+            self::assertMatchesRegularExpression(
+                '/^[0-9a-f]{32}\.[0-9a-f]{64}$/',
+                $_COOKIE[$name],
+                'token is nonce.hmac-sha256'
+            );
+        }
+
+        $values = array_map(static fn (string $name) => $_COOKIE[$name], Csrf::cookieNames());
+        self::assertCount(1, array_unique($values), 'every issued name carries the same token');
+    }
+
+    public function testEnsureCookieKeepsAnExistingValidToken(): void
+    {
+        Csrf::ensureCookie();
+        $first = $_COOKIE['pp_csrf'];
+
+        Csrf::ensureCookie();
+
+        self::assertSame($first, $_COOKIE['pp_csrf']);
+    }
+
+    public function testRotateReplacesTheToken(): void
+    {
+        Csrf::ensureCookie();
+        $first = $_COOKIE['pp_csrf'];
+
+        Csrf::rotate();
+
+        self::assertNotSame($first, $_COOKIE['pp_csrf']);
+    }
+
+    public function testValidTokenRoundTrip(): void
+    {
+        Csrf::ensureCookie();
+
+        self::assertNull(Csrf::validateHeaderToken($_COOKIE['pp_csrf']));
+    }
+
+    public function testMissingHeaderTokenIsRefused(): void
+    {
+        Csrf::ensureCookie();
+
+        self::assertSame('Missing CSRF token', Csrf::validateHeaderToken(''));
+    }
+
+    public function testHeaderThatMatchesNoCookieIsRefused(): void
+    {
+        Csrf::ensureCookie();
+
+        self::assertSame(
+            'Invalid CSRF token',
+            Csrf::validateHeaderToken(str_repeat('a', 32) . '.' . str_repeat('b', 64))
+        );
+    }
+
+    public function testTamperedSignatureIsRefusedEvenWhenTheCookieMatches(): void
+    {
+        // Double-submit alone is not enough: the signature must verify, so a
+        // token an attacker planted (cookie tossing) without the secret fails.
+        $forged = str_repeat('a', 32) . '.' . str_repeat('b', 64);
+        foreach (Csrf::cookieNames() as $name) {
+            $_COOKIE[$name] = $forged;
+        }
+
+        self::assertSame('Invalid CSRF token', Csrf::validateHeaderToken($forged));
+    }
+}

package/dist/tests/FeaturesTest.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use PHPUnit\Framework\TestCase;
+use Tests\Support\Features;
+
+/**
+ * The suite's own feature awareness: flags come from `prisma-php.json`, the
+ * single source of truth for which optional scaffolds exist in this app.
+ */
+final class FeaturesTest extends TestCase
+{
+    public function testConfigIsReadFromPrismaPhpJson(): void
+    {
+        $raw = json_decode((string) file_get_contents(DOCUMENT_PATH . '/prisma-php.json'), true);
+
+        self::assertIsArray($raw);
+        self::assertSame($raw, Features::config());
+    }
+
+    public function testEnabledMirrorsTheBooleanFlags(): void
+    {
+        $config = Features::config();
+
+        foreach (['websocket', 'mcp', 'swaggerDocs', 'prisma', 'tailwindcss', 'typescript'] as $flag) {
+            self::assertSame(
+                ($config[$flag] ?? false) === true,
+                Features::enabled($flag),
+                "Features::enabled('$flag') mirrors prisma-php.json"
+            );
+        }
+    }
+
+    public function testAnUnknownFlagIsDisabled(): void
+    {
+        self::assertFalse(Features::enabled('not-a-real-feature'));
+    }
+}

package/dist/tests/README.md

@@ -0,0 +1,118 @@
+# App tests
+
+PHPUnit tests for the **application** code — `src/Lib/**`, the app's wire
+contracts, and `src/Lib/Websocket/sockets.php` registrations — not the Prisma
+PHP framework under `vendor/tsnc/prisma-php` (that package carries its own
+suite in its source repo).
+
+## The command
+
+```bash
+npm run test
+```
+
+That runs PHPUnit through `settings/run-tests.ts`, which uses the PHP binary
+from `prisma-php.json` (`phpRootPathExe`) so the suite runs with the same PHP
+the app runs on. It exits non-zero on any failure, so CI, a pre-commit hook,
+or an agent knows exactly when something broke.
+
+Narrow a run with PHPUnit's own flags after `--`:
+
+```bash
+npm run test -- --filter CsrfTest
+npm run test -- --filter testValidTokenRoundTrip
+```
+
+Running PHPUnit directly also works: `php vendor/phpunit/phpunit/phpunit`
+(configuration is picked up from `phpunit.xml` at the project root).
+
+## Layout
+
+One file per surface, flat in `tests/`:
+
+| File | Surface |
+| --- | --- |
+| `bootstrap.php` | Shared setup: autoloader, path constants, deterministic test env |
+| `Support/` | Reusable fakes (`Tests\Support\...`, autoloaded via composer `autoload-dev`) |
+| `Support/Features.php` | Feature flags read from `prisma-php.json` |
+| `Support/RequiresFeature.php` | Skip guard for tests of optional features |
+| `FeaturesTest.php` | The suite's own feature awareness mirrors `prisma-php.json` |
+| `CsrfTest.php` | The `pp_csrf` cookie family and `X-CSRF-Token` validation |
+| `RpcWireContractTest.php` | PulsePoint wire headers (`$isRpc` / `$isNavigation` / `$isWire`), including the pin that the legacy header stays dead |
+| `SocketTest.php` | One socket connection: JSON frames, reserved error shape, close semantics |
+| `SocketRegistryTest.php` | Named-socket registration and duplicate refusal |
+| `SocketPoolTest.php` | Broadcast and pruning |
+| `ConnectionManagerTest.php` | The full named-socket wire: handshake refusals, argument frame, auth, limits |
+| `SocketsRegistrationTest.php` | The app's real `sockets.php` loads and names its sockets |
+| `AuthTest.php` | JWT round trip, tamper/expiry/foreign-secret rejection |
+
+## The test environment is deterministic
+
+`tests/bootstrap.php` does **not** load the real `.env`. It loads the composer
+autoloader plus `settings/paths.php`, then sets deterministic defaults
+(`APP_ENV=development`, a 32-byte `AUTH_SECRET`, `FUNCTION_CALL_SECRET`) only
+when the variable is not already set — so the suite behaves the same on any
+machine, never depends on real secrets, and CI can still override. The Prisma
+PHP `bootstrap.php` at the project root (route resolution, rendering, CSRF
+cookie issuing) is **not** booted; tests exercise app classes directly.
+
+A test that needs a different env value must set it with `putenv(...)` and
+restore the previous value in `tearDown()` (`PP\Env` reads `getenv()` first) —
+see `ConnectionManagerTest::setEnv()` for the pattern.
+
+## Optional features are optional in the suite too
+
+`prisma-php.json` decides which optional scaffolds exist (`websocket`, `mcp`,
+`swaggerDocs`, `prisma`, ...). A test for an optional feature must guard on
+the flag, or a freshly generated app without that feature fatals instead of
+passing:
+
+```php
+use Tests\Support\RequiresFeature;
+
+final class MySocketTest extends TestCase
+{
+    use RequiresFeature;
+
+    protected function setUp(): void
+    {
+        $this->requireFeature('websocket'); // FIRST line, before touching the scaffold
+    }
+}
+```
+
+When the flag is off the test reports itself as skipped with the reason and
+the enable command — never as a failure. `tearDown()` still runs after a
+skip, so teardown code must not assume the feature's classes exist (see
+`SocketRegistryTest::resetRegistry()` for the `class_exists` guard).
+
+The websocket suites (`SocketTest`, `SocketRegistryTest`, `SocketPoolTest`,
+`ConnectionManagerTest`, `SocketsRegistrationTest`) are gated this way. Core
+surfaces — CSRF, the RPC wire headers, auth — are always-on and never gated.
+
+## Conventions
+
+- one `SomethingTest.php` per surface, in the `Tests` namespace; shared fakes
+  live in `tests/Support` under `Tests\Support`
+- static registries (`SocketRegistry`) are reset in `setUp()`/`tearDown()` via
+  reflection so tests never depend on each other's order
+- superglobals a test touches (`$_SERVER`, `$_COOKIE`, env) are backed up in
+  `setUp()` and restored in `tearDown()`
+- wire tests assert **frames and close codes**, not internals:
+  `Tests\Support\FakeConnection` records everything the server sends, so a
+  test reads the conversation the browser would have seen
+- expected framework failures are part of the contract — a refusal test
+  asserts the readable `{"error": "..."}` frame (or HTTP status), not just
+  "something failed"
+- tests cover app-level code and the wire contracts the app depends on; do
+  not test Prisma PHP internals from here — those belong to the package
+  repo's own suite (`vendor/tsnc/prisma-php/tests` when vendored)
+
+## For AI agents
+
+Read this file plus `node_modules/prisma-php/dist/docs/testing.md` before
+adding or changing tests. When you add an app feature with logic worth
+protecting — an exposed function's validation, a socket handler, an auth
+rule — add the matching `*Test.php` here in the same change, and run
+`npm run test` before declaring the work done. A red suite is a finding to
+fix, not to silence.

package/dist/tests/RpcWireContractTest.php

@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use PHPUnit\Framework\TestCase;
+use PP\Request;
+
+/**
+ * The PulsePoint wire headers, as the app depends on them.
+ *
+ * `pp.rpc(...)` posts with `X-PP-RPC: true` + `X-PP-Function`; SPA navigation
+ * fetches with `X-PP-Navigation: true`; both carry `X-PulsePoint-Wire: true`.
+ * This is a complete migration — the legacy `PP-Wire-Request` header must NOT
+ * be recognized any more, and that is pinned here on purpose.
+ */
+final class RpcWireContractTest extends TestCase
+{
+    private array $serverBackup = [];
+
+    protected function setUp(): void
+    {
+        $this->serverBackup = $_SERVER;
+    }
+
+    protected function tearDown(): void
+    {
+        $_SERVER = $this->serverBackup;
+    }
+
+    private function initRequest(array $server): void
+    {
+        $_SERVER = array_merge([
+            'HTTP_HOST' => 'example.test',
+            'SCRIPT_NAME' => '/index.php',
+            'REMOTE_ADDR' => '127.0.0.1',
+        ], $server);
+
+        Request::init();
+    }
+
+    public function testRpcPostIsDetected(): void
+    {
+        $this->initRequest([
+            'REQUEST_METHOD' => 'POST',
+            'CONTENT_TYPE' => 'application/json',
+            'HTTP_X_PULSEPOINT_WIRE' => 'true',
+            'HTTP_X_PP_RPC' => 'true',
+            'HTTP_X_PP_FUNCTION' => 'saveProfile',
+        ]);
+
+        self::assertTrue(Request::$isWire);
+        self::assertTrue(Request::$isRpc);
+        self::assertFalse(Request::$isNavigation);
+    }
+
+    public function testNavigationGetIsWireButNotRpc(): void
+    {
+        $this->initRequest([
+            'REQUEST_METHOD' => 'GET',
+            'HTTP_X_PULSEPOINT_WIRE' => 'true',
+            'HTTP_X_PP_NAVIGATION' => 'true',
+        ]);
+
+        self::assertTrue(Request::$isWire);
+        self::assertFalse(Request::$isRpc);
+        self::assertTrue(Request::$isNavigation);
+    }
+
+    public function testRpcHeaderOnAGetIsNotAnRpc(): void
+    {
+        $this->initRequest([
+            'REQUEST_METHOD' => 'GET',
+            'HTTP_X_PP_RPC' => 'true',
+        ]);
+
+        self::assertFalse(Request::$isRpc);
+    }
+
+    public function testPlainRequestCarriesNoWireFlags(): void
+    {
+        $this->initRequest(['REQUEST_METHOD' => 'GET']);
+
+        self::assertFalse(Request::$isWire);
+        self::assertFalse(Request::$isRpc);
+        self::assertFalse(Request::$isNavigation);
+    }
+
+    public function testLegacyWireHeaderIsNoLongerRecognized(): void
+    {
+        $this->initRequest([
+            'REQUEST_METHOD' => 'POST',
+            'CONTENT_TYPE' => 'application/json',
+            'HTTP_PP_WIRE_REQUEST' => 'true',
+        ]);
+
+        self::assertFalse(Request::$isWire, 'complete migration: no legacy header support');
+        self::assertFalse(Request::$isRpc);
+    }
+}