@mpgd/cli 0.55.0 → 0.57.0

package/templates/phaser-game/src/env.d.ts

@@ -19,4 +19,9 @@ interface ImportMetaEnv {
   readonly VITE_MPGD_GAME_SERVICES_URL?: string;
   readonly VITE_MPGD_GAME_SERVICES_TARGET?: string;
   readonly VITE_MPGD_GAME_SERVICES_TRANSPORT?: string;
+  /**
+   * Local development only: `<playerId>` or `<playerId>.<installationId>`
+   * for an unauthenticated notifications session (see `serverSession.ts`).
+   */
+  readonly VITE_MPGD_DEV_NOTIFICATION_SESSION?: string;
 }

package/templates/phaser-game/src/platform/developmentServerSession.ts

@@ -0,0 +1,104 @@
+import { createDevelopmentServerSession, type DevelopmentServerSession } from '@mpgd/game-services';
+
+/**
+ * Local development only: an unauthenticated session for a game-services
+ * Worker run with `MPGD_ALLOW_INSECURE_DEVELOPMENT_NOTIFICATION_SESSIONS = "true"`
+ * (see docs/NOTIFICATIONS.md, "Try it locally"). On only when the Vite dev
+ * server runs (`dev`, `import.meta.env.DEV`), the mode is `development`, and
+ * `VITE_MPGD_DEV_NOTIFICATION_SESSION` is `<playerId>` or
+ * `<playerId>.<installationId>` (each 1 to 64 letters, digits, `_`, or `-`;
+ * the installation defaults to `dev-installation`). The session id is
+ * `dev-<installationId>`. Anyone can write such a header, so the Worker
+ * refuses the flag with its D1 store. Otherwise `undefined`; an invalid
+ * value logs why.
+ */
+export function resolveStarterDevelopmentServerSession(env: {
+  readonly dev: boolean;
+  readonly mode: string;
+  readonly value: string | undefined;
+}): DevelopmentServerSession | undefined {
+  const value = env.value?.trim();
+  // Only the development mode: a staging or release build that runs with
+  // NODE_ENV=development has `dev` set too.
+  if (!env.dev || env.mode !== 'development' || value === undefined || value === '') {
+    return undefined;
+  }
+  const [playerId = '', installationId = 'dev-installation', ...rest] = value.split('.');
+  try {
+    if (rest.length > 0) {
+      throw new Error('Expected <playerId> or <playerId>.<installationId>.');
+    }
+    const session = createDevelopmentServerSession({ mode: env.mode, playerId, installationId });
+    console.warn(
+      `[game-services] VITE_MPGD_DEV_NOTIFICATION_SESSION: signed in as ${playerId} with an `
+        + 'unauthenticated development session. Local development only.',
+    );
+    return session;
+  } catch (error) {
+    console.error('[game-services] VITE_MPGD_DEV_NOTIFICATION_SESSION is ignored.', error);
+    return undefined;
+  }
+}
+
+/**
+ * What `serverSession.ts` hands out, kept apart from `import.meta.env` so it
+ * can be tested: the game's own session once it called `set` (even with
+ * `undefined`), else the development session, read once. `once` marks the
+ * reader that keeps what it reads, the commerce client, which only ever
+ * gets the game's own session: the development session is for the
+ * notifications Worker, and a commerce backend with ingress authentication
+ * would refuse its header. A `set` that changes the session after a reader
+ * kept the old one warns: after the commerce client read it, or after the
+ * development session was handed out (a notifications backend keeps it).
+ */
+export function createStarterServerSessionSlot<Session extends object>(input: {
+  /** The development session; called at most once. */
+  readonly development: () => Session | undefined;
+  readonly warn: (message: string) => void;
+}): {
+  resolve(options?: { readonly once?: boolean }): Session | undefined;
+  set(session: Session | undefined): void;
+} {
+  let session: Session | undefined;
+  let setByGame = false;
+  let readOnce = false;
+  let development: Session | null | undefined;
+  let developmentHandedOut = false;
+  return {
+    resolve(options = {}) {
+      if (options.once === true) {
+        readOnce = true;
+      }
+      // The commerce client never gets the development session.
+      if (setByGame || options.once === true) {
+        return session;
+      }
+      if (development === undefined) {
+        development = input.development() ?? null;
+      }
+      if (development === null) {
+        return undefined;
+      }
+      developmentHandedOut = true;
+      return development;
+    },
+    set(next) {
+      if (developmentHandedOut && !setByGame) {
+        // Even `undefined`: a notifications backend that kept the development session keeps sending its header.
+        input.warn(
+          '[game-services] setStarterServerSession ran after the development session '
+            + '(VITE_MPGD_DEV_NOTIFICATION_SESSION) was in use; a notifications backend created '
+            + 'already keeps it. Unset the variable, or call setStarterServerSession before bootstrap().',
+        );
+      }
+      if (readOnce && next !== undefined && next !== session) {
+        input.warn(
+          '[game-services] setStarterServerSession ran after the commerce client was created; '
+            + "it does not send this session's header. Call it before bootstrap().",
+        );
+      }
+      session = next;
+      setByGame = true;
+    },
+  };
+}

package/templates/phaser-game/src/platform/serverSession.ts

@@ -1,19 +1,37 @@
 import type { GameServicesHeaderResolver } from '@mpgd/game-services';
 
+import {
+  createStarterServerSessionSlot,
+  resolveStarterDevelopmentServerSession,
+} from './developmentServerSession';
+
 /**
  * The game's server-backed session: who is signed in to the game backend,
  * and the `Authorization` header for that session. The starter has none, so
  * `resolveStarterServerSession` returns `undefined`. Set yours with
- * `setStarterServerSession`, over your own session holder and identity
- * service. The commerce client then sends its header. In a game created with
- * `--providers notifications`, the notifications runtime uses the same
- * session and header for the game-services Worker's notification routes.
+ * `setStarterServerSession`. The commerce client then sends its header. In
+ * a game created with `--providers notifications`, the notifications
+ * runtime uses the same session and header for the game-services Worker's
+ * notification routes.
+ *
+ * With a guest-session backend, `createGuestServerSession` from
+ * `@mpgd/game-services` reads a `GuestSessionCoordinator` as this session:
+ *
+ * ```ts
+ * const guest = createGuestSessionCoordinator({ backend, credentials, installationId });
+ * setStarterServerSession(createGuestServerSession(guest));
+ * void guest.start();
+ * ```
+ *
+ * `sessionId` must be the stable session-family id: the same across token
+ * refreshes, and the session your identity service answers to the Worker's
+ * `authenticateNotificationSession` for this session's header. Do not pass
+ * a per-token or rotating id: `createGuestServerSession` answers the
+ * coordinator's `sessionFamilyId`, never a view's `sessionId`, which may
+ * rotate on refresh. With another session holder, pass its family id.
  *
- * `sessionId` must be the stable session-family id: the `sessionId` your
- * identity service answers to the Worker's `authenticateNotificationSession`
- * for this session's header, the same across token refreshes. Do not pass a
- * per-token or rotating id: a `GuestSessionCoordinator` view's `sessionId`
- * may rotate on refresh, so it is not that id.
+ * For local development without an identity service, see
+ * `developmentServerSession.ts`.
  */
 export interface StarterServerSession {
   /**
@@ -29,22 +47,31 @@ export interface StarterServerSession {
   readonly getHeaders: GameServicesHeaderResolver;
 }
 
-let serverSession: StarterServerSession | undefined;
-/** Whether the commerce client read the session already: it reads it once. */
-let readOnce = false;
+/** The game's session, or the development one (see `developmentServerSession.ts`). */
+const slot = createStarterServerSessionSlot<StarterServerSession>({
+  // `import.meta.env.DEV` is false in a normal `vite build`, which drops this branch.
+  development: () =>
+    import.meta.env.DEV
+      ? resolveStarterDevelopmentServerSession({
+          dev: import.meta.env.DEV,
+          mode: import.meta.env.MODE,
+          value: import.meta.env.VITE_MPGD_DEV_NOTIFICATION_SESSION,
+        })
+      : undefined,
+  warn: (message) => console.warn(message),
+});
 
 /**
  * The game's server-backed session; `undefined` until the game sets one with
- * `setStarterServerSession`. `once` marks a reader that keeps what it reads
- * (the commerce client), so a later change warns.
+ * `setStarterServerSession`, unless a development session is on (see
+ * `developmentServerSession.ts`). `once` marks the reader that keeps what
+ * it reads, the commerce client, so a later change warns; it gets only the
+ * game's own session, never the development one.
  */
 export function resolveStarterServerSession(
   options: { readonly once?: boolean } = {},
 ): StarterServerSession | undefined {
-  if (options.once === true) {
-    readOnce = true;
-  }
-  return serverSession;
+  return slot.resolve(options);
 }
 
 /**
@@ -53,14 +80,10 @@ export function resolveStarterServerSession(
  * notification settings and opens read it until a backend exists. Its
  * `current()` may answer `undefined` until the player signs in. A session
  * set after the commerce client was created does not reach that client,
- * which this warns about.
+ * which this warns about. Any call, `undefined` included, turns the
+ * development session off; the first call after the development session
+ * was handed out warns, `undefined` included.
  */
 export function setStarterServerSession(session: StarterServerSession | undefined): void {
-  if (readOnce && session !== undefined && session !== serverSession) {
-    console.warn(
-      '[game-services] setStarterServerSession ran after the commerce client was created; '
-        + "it does not send this session's header. Call it before bootstrap().",
-    );
-  }
-  serverSession = session;
+  slot.set(session);
 }