@quenty/studio-bridge 0.21.1 → 0.22.0

package/src/commands/playtest/playtest-sessions.ts

@@ -0,0 +1,417 @@
+/**
+ * Starting, finding, and ending StudioTestService playtests.
+ *
+ * A playtest opens fresh server (and, in play mode, client) DataModels, and
+ * each connects to the bridge as its own session. Those sessions can't be
+ * matched to the Studio that started them by instance id, since unpublished
+ * places give every DataModel its own. Instead, `startPlaytestAsync` passes a
+ * playtest id as the StudioTestService test args, and each new session is
+ * asked for it back through `GetTestArgs`.
+ */
+
+import { randomUUID } from 'crypto';
+import type {
+  BridgeConnection,
+  BridgeSession,
+  EndPlaytestResult,
+  PlaytestEndResult,
+  PlaytestMode,
+  SessionContext,
+} from '../../bridge/index.js';
+import { ContextNotFoundError } from '../../bridge/index.js';
+import { getPluginBuildVersionAsync } from '../../plugin/plugin-build-version.js';
+import { tryReadLoadUserPluginsOnPlaytestAsync } from '../../process/studio-settings.js';
+
+/** How long a started playtest may run before its pending start request is dropped. */
+const PLAYTEST_MAX_DURATION_MS = 24 * 60 * 60 * 1000;
+
+const SESSION_WAIT_TIMEOUT_MS = 30_000;
+/** Each player of a multiplayer test boots its own Studio process. */
+const MULTIPLAYER_SESSION_WAIT_TIMEOUT_MS = 90_000;
+const SESSION_CLOSE_TIMEOUT_MS = 10_000;
+const READ_RETRY_DELAY_MS = 1_000;
+
+const PLAYTEST_PLUGINS_OFF_MESSAGE = `Studio's "Load user plugins on playtest" setting is off, so the studio-bridge plugin doesn't load into playtests and their sessions can't connect. Turn it on in Studio Settings, or run a script in a playtest's server with 'studio-bridge playtest run', which works without it.`;
+
+const READ_PLAYTEST_ID_SCRIPT = [
+  'local ok, args = pcall(function()',
+  '\treturn game:GetService("StudioTestService"):GetTestArgs()',
+  'end)',
+  'return if ok and type(args) == "table" then args.studioBridgePlaytestId else nil',
+].join('\n');
+
+export interface StartedPlaytest {
+  playtestId: string;
+  mode: PlaytestMode;
+  /** Set for a multiplayer test. */
+  players?: number;
+  /** The playtest's sessions: always `server`, plus `client` in play mode. */
+  sessions: Partial<Record<SessionContext, BridgeSession>>;
+  /** Every client session, one per player. */
+  clients: BridgeSession[];
+  /** Settles when the playtest ends. Never rejects. */
+  ended: Promise<PlaytestEndResult>;
+}
+
+/** The sessions a playtest opens, by mode. Run mode has no player, so no client. */
+export function getPlaytestContexts(mode: PlaytestMode): SessionContext[] {
+  return mode === 'play' ? ['server', 'client'] : ['server'];
+}
+
+/**
+ * Start a playtest from `editSession` and resolve once every session it opens
+ * has connected. With `players`, it is a multiplayer test with a client per
+ * player. Rejects if Studio refuses to start it, e.g. because a playtest is
+ * already running.
+ */
+export async function startPlaytestAsync(
+  connection: BridgeConnection,
+  editSession: BridgeSession,
+  mode: PlaytestMode,
+  players?: number
+): Promise<StartedPlaytest> {
+  if (editSession.context !== 'edit') {
+    throw new Error(
+      `Playtests start from an edit session, but '${editSession.info.sessionId}' is a ${editSession.context} session`
+    );
+  }
+  if (await isPlaytestPluginsOffAsync(connection)) {
+    throw new Error(PLAYTEST_PLUGINS_OFF_MESSAGE);
+  }
+  if (players !== undefined) {
+    await assertCanStartMultiplayerAsync(editSession, mode, players);
+  }
+
+  const playtestId = randomUUID();
+  const ended = editSession
+    .runPlaytestAsync(
+      mode,
+      playtestId,
+      connection.port,
+      PLAYTEST_MAX_DURATION_MS,
+      players
+    )
+    .catch(
+      (err): PlaytestEndResult => ({
+        playtestId,
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    );
+
+  const clientCount = players ?? (mode === 'play' ? 1 : 0);
+  const waitTimeoutMs =
+    players !== undefined
+      ? MULTIPLAYER_SESSION_WAIT_TIMEOUT_MS
+      : SESSION_WAIT_TIMEOUT_MS;
+  const abort = new AbortController();
+  let outcome;
+  try {
+    outcome = await Promise.race([
+      waitForPlaytestSessionsAsync(
+        connection,
+        playtestId,
+        clientCount,
+        waitTimeoutMs,
+        abort.signal
+      ).then((sessions) => ({ sessions })),
+      ended.then((result) => ({ result })),
+    ]);
+  } finally {
+    abort.abort();
+  }
+
+  if ('result' in outcome) {
+    throw new Error(
+      outcome.result.success
+        ? 'Playtest ended before its sessions connected'
+        : `Playtest failed to start: ${outcome.result.error}`
+    );
+  }
+
+  const { server, clients } = outcome.sessions;
+  const missing = [
+    ...(server ? [] : ['server']),
+    ...(clients.length < clientCount
+      ? [`${clientCount - clients.length} client`]
+      : []),
+  ];
+  if (server && missing.length === 0) {
+    return {
+      playtestId,
+      mode,
+      players,
+      sessions: { server, client: clients[0] },
+      clients,
+      ended,
+    };
+  }
+
+  const waited = `its ${missing.join(' and ')} session${
+    missing.length > 1 || clientCount - clients.length > 1 ? 's' : ''
+  } did not connect within ${waitTimeoutMs / 1000}s`;
+
+  // Without its server session the playtest can't be ended from here
+  if (!server?.isConnected) {
+    throw new Error(
+      `Playtest started, but ${waited}, so stop it in Studio. Play sessions only connect with Studio's "Load user plugins on playtest" setting on.`
+    );
+  }
+
+  await endPlaytestAsync(connection, server);
+  throw new Error(`Playtest started, but ${waited}, so it was stopped.`);
+}
+
+async function assertCanStartMultiplayerAsync(
+  editSession: BridgeSession,
+  mode: PlaytestMode,
+  players: number
+): Promise<void> {
+  if (!Number.isInteger(players) || players < 1) {
+    throw new Error(
+      `--players must be a whole number of at least 1, not ${players}`
+    );
+  }
+  if (mode !== 'play') {
+    throw new Error('A multiplayer test runs in play mode');
+  }
+
+  // Older plugins give every client the same session id, so all but one drop off
+  const expected = await getPluginBuildVersionAsync();
+  if (editSession.info.pluginVersion !== expected) {
+    throw new Error(
+      `Multiplayer tests need the current studio-bridge plugin, but '${editSession.info.placeName}' has an older one. Run 'studio-bridge plugin install' first.`
+    );
+  }
+}
+
+/**
+ * Resolve the server session of a running playtest. `target` names it or
+ * any session of its Studio; otherwise there must be exactly one connected.
+ */
+export async function resolvePlaytestServerSessionAsync(
+  connection: BridgeConnection,
+  target?: string
+): Promise<BridgeSession> {
+  if (target) {
+    try {
+      return await connection.resolveSessionAsync(target, 'server');
+    } catch (err) {
+      throw await explainMissingPlaytestContextAsync(connection, err);
+    }
+  }
+
+  const servers = connection
+    .listSessions()
+    .filter((info) => info.context === 'server');
+  if (servers.length === 0) {
+    throw new Error(await explainNoPlaytestAsync(connection));
+  }
+  if (servers.length > 1) {
+    const list = servers
+      .map((info) => `  - ${info.sessionId}: ${info.placeName}`)
+      .join('\n');
+    throw new Error(
+      `Multiple playtests are running. Use --target <id> to pick a server session.\n${list}`
+    );
+  }
+
+  const session = connection.getSession(servers[0].sessionId);
+  if (!session) {
+    throw new Error(`Session '${servers[0].sessionId}' disconnected`);
+  }
+  return session;
+}
+
+/**
+ * Explains a missing `server` or `client` session: no playtest is running, a
+ * run-mode playtest has no client, or the playtest's sessions can't connect.
+ * Other errors pass through unchanged.
+ */
+export async function explainMissingPlaytestContextAsync(
+  connection: BridgeConnection,
+  err: unknown
+): Promise<unknown> {
+  if (
+    !(err instanceof ContextNotFoundError) ||
+    (err.context !== 'server' && err.context !== 'client')
+  ) {
+    return err;
+  }
+
+  const placeName = connection
+    .listSessions()
+    .find((info) => info.instanceId === err.instanceId)?.placeName;
+  const studio = placeName ? `'${placeName}'` : `instance '${err.instanceId}'`;
+
+  if (err.context === 'client' && err.availableContexts.includes('server')) {
+    return new Error(
+      `The playtest of ${studio} runs in run mode, which has no client. Restart it in play mode with 'studio-bridge playtest restart --mode play'.`
+    );
+  }
+  return new Error(
+    await explainNoPlaytestAsync(connection, studio, err.context)
+  );
+}
+
+/**
+ * Whether this machine's Studio has "Load user plugins on playtest" off. A
+ * remote Studio's settings aren't on this machine, so they count as unknown.
+ */
+async function isPlaytestPluginsOffAsync(
+  connection: BridgeConnection
+): Promise<boolean> {
+  return (
+    !connection.isRemote &&
+    (await tryReadLoadUserPluginsOnPlaytestAsync()) === false
+  );
+}
+
+async function explainNoPlaytestAsync(
+  connection: BridgeConnection,
+  studio?: string,
+  context?: SessionContext
+): Promise<string> {
+  const of = studio ? ` of ${studio}` : '';
+  if (await isPlaytestPluginsOffAsync(connection)) {
+    return `No playtest${of} is connected. ${PLAYTEST_PLUGINS_OFF_MESSAGE}`;
+  }
+  const missing = context ? `, so there is no ${context} session` : '';
+  return `No playtest${of} is running${missing}. Start one with 'studio-bridge playtest start'.`;
+}
+
+/**
+ * End the playtest `serverSession` belongs to, resolving once the session has
+ * closed with what the playtest reported about itself.
+ */
+export async function endPlaytestAsync(
+  connection: BridgeConnection,
+  serverSession: BridgeSession
+): Promise<EndPlaytestResult> {
+  const ended = await serverSession.endPlaytestAsync();
+  await waitForSessionCloseAsync(connection, serverSession.info.sessionId);
+  return ended;
+}
+
+interface PlaytestSessions {
+  server?: BridgeSession;
+  clients: BridgeSession[];
+}
+
+async function waitForPlaytestSessionsAsync(
+  connection: BridgeConnection,
+  playtestId: string,
+  clientCount: number,
+  timeoutMs: number,
+  signal: AbortSignal
+): Promise<PlaytestSessions> {
+  return new Promise((resolve) => {
+    const found: PlaytestSessions = { clients: [] };
+    const checked = new Set<string>();
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      connection.off('session-connected', onSession);
+      signal.removeEventListener('abort', cleanup);
+    };
+
+    const onSession = (session: BridgeSession) => {
+      const { sessionId } = session.info;
+      if (session.context === 'edit' || checked.has(sessionId)) {
+        return;
+      }
+      checked.add(sessionId);
+
+      void readPlaytestIdAsync(connection, sessionId, signal).then((read) => {
+        if (signal.aborted || !read) return;
+        if (read.id !== playtestId) {
+          // The last playtest's session can linger under the same id; read its replacement too
+          checked.delete(sessionId);
+          return;
+        }
+
+        if (read.session.context === 'server') {
+          found.server = read.session;
+        } else {
+          found.clients.push(read.session);
+        }
+        if (found.server && found.clients.length >= clientCount) {
+          cleanup();
+          resolve(found);
+        }
+      });
+    };
+
+    // Resolves with whichever sessions connected; the caller reports the rest
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve(found);
+    }, timeoutMs);
+
+    signal.addEventListener('abort', cleanup);
+    connection.on('session-connected', onSession);
+
+    for (const info of connection.listSessions()) {
+      const session = connection.getSession(info.sessionId);
+      if (session) onSession(session);
+    }
+  });
+}
+
+/**
+ * Reads the playtest id a session was started under, retrying while the read
+ * fails: a playtest's DataModels are slow to answer while their Studio boots,
+ * and a session that reconnects is read again under the same id.
+ */
+async function readPlaytestIdAsync(
+  connection: BridgeConnection,
+  sessionId: string,
+  signal: AbortSignal
+): Promise<{ session: BridgeSession; id: string | undefined } | undefined> {
+  while (!signal.aborted) {
+    const session = connection.getSession(sessionId);
+    if (session) {
+      try {
+        const result = await session.execAsync(READ_PLAYTEST_ID_SCRIPT, 5_000);
+        if (result.success) {
+          const value = result.returnValues?.[0];
+          return { session, id: typeof value === 'string' ? value : undefined };
+        }
+      } catch {
+        // Retried below
+      }
+    }
+    await new Promise((resolve) => setTimeout(resolve, READ_RETRY_DELAY_MS));
+  }
+  return undefined;
+}
+
+async function waitForSessionCloseAsync(
+  connection: BridgeConnection,
+  sessionId: string
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!connection.getSession(sessionId)) {
+      resolve();
+      return;
+    }
+
+    const onDisconnected = (disconnectedId: string) => {
+      if (disconnectedId !== sessionId) return;
+      clearTimeout(timer);
+      connection.off('session-disconnected', onDisconnected);
+      resolve();
+    };
+
+    const timer = setTimeout(() => {
+      connection.off('session-disconnected', onDisconnected);
+      reject(
+        new Error(
+          `Playtest did not close within ${SESSION_CLOSE_TIMEOUT_MS / 1000}s`
+        )
+      );
+    }, SESSION_CLOSE_TIMEOUT_MS);
+
+    connection.on('session-disconnected', onDisconnected);
+  });
+}

package/src/commands/playtest/restart/restart.ts

@@ -0,0 +1,199 @@
+/**
+ * `playtest restart` — stop the running playtest and start a new one in the
+ * same mode, so it picks up code changed since it started. Starts one when
+ * none is running.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import type {
+  BridgeConnection,
+  BridgeSession,
+  PlaytestMode,
+} from '../../../bridge/index.js';
+import {
+  endPlaytestAsync,
+  startPlaytestAsync,
+  type StartedPlaytest,
+} from '../playtest-sessions.js';
+import { listPlaytestPlayersAsync } from '../player/playtest-players.js';
+import {
+  describePlaytest,
+  formatPlaytestStartText,
+  toPlaytestStartResult,
+  type PlaytestStartResult,
+} from '../start/start.js';
+
+/** Studio refuses a new playtest until the old one has fully wound down. */
+const START_ATTEMPTS = 5;
+const START_RETRY_DELAY_MS = 1_000;
+
+export interface PlaytestRestartOptions {
+  /** Defaults to the running playtest's mode, or play when none is running. */
+  mode?: PlaytestMode;
+  /** Defaults to the running multiplayer test's player count. */
+  players?: number;
+  /** Picks the Studio: any of its sessions. */
+  target?: string;
+}
+
+interface PlaytestRestartArgs {
+  mode?: PlaytestMode;
+  players?: number;
+}
+
+export async function playtestRestartHandlerAsync(
+  connection: BridgeConnection,
+  options: PlaytestRestartOptions = {}
+): Promise<PlaytestStartResult> {
+  const targetSession = options.target
+    ? await connection.resolveSessionAsync(options.target)
+    : undefined;
+  const serverSession = findServerSession(
+    connection,
+    targetSession?.info.instanceId
+  );
+
+  if (!serverSession) {
+    const editSession =
+      targetSession?.context === 'edit'
+        ? targetSession
+        : await connection.resolveSessionAsync(
+            undefined,
+            'edit',
+            targetSession?.info.instanceId
+          );
+    const playtest = await startWithRetryAsync(
+      connection,
+      editSession,
+      options.mode ?? 'play',
+      options.players
+    );
+    return toPlaytestStartResult(
+      playtest,
+      `No playtest was running; started one (${describePlaytest(playtest)})`
+    );
+  }
+
+  const editSession = await connection.resolveSessionAsync(
+    undefined,
+    'edit',
+    serverSession.info.instanceId
+  );
+
+  // Players added since the start count too, so read who is in the test now
+  const livePlayers =
+    options.players === undefined && options.mode === undefined
+      ? await tryCountMultiplayerPlayersAsync(connection, serverSession)
+      : undefined;
+  const ended = await endPlaytestAsync(connection, serverSession);
+  const mode = options.mode ?? ended.mode ?? 'play';
+  const players =
+    options.players ??
+    (options.mode === undefined && ended.players !== undefined
+      ? livePlayers || ended.players
+      : undefined);
+  const playtest = await startWithRetryAsync(
+    connection,
+    editSession,
+    mode,
+    players
+  );
+  return toPlaytestStartResult(
+    playtest,
+    `Playtest restarted (${describePlaytest(playtest)})`
+  );
+}
+
+/** How many players the running test has, or undefined when it can't tell. */
+async function tryCountMultiplayerPlayersAsync(
+  connection: BridgeConnection,
+  serverSession: BridgeSession
+): Promise<number | undefined> {
+  try {
+    return (await listPlaytestPlayersAsync(connection, serverSession)).length;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The running playtest's server session, within `instanceId` when given. */
+function findServerSession(
+  connection: BridgeConnection,
+  instanceId: string | undefined
+): BridgeSession | undefined {
+  const servers = connection
+    .listSessions()
+    .filter(
+      (info) =>
+        info.context === 'server' &&
+        (instanceId === undefined || info.instanceId === instanceId)
+    );
+
+  if (servers.length > 1) {
+    const list = servers
+      .map((info) => `  - ${info.sessionId}: ${info.placeName}`)
+      .join('\n');
+    throw new Error(
+      `Multiple playtests are running. Use --target <id> to pick one.\n${list}`
+    );
+  }
+
+  return servers.length === 1
+    ? connection.getSession(servers[0].sessionId)
+    : undefined;
+}
+
+async function startWithRetryAsync(
+  connection: BridgeConnection,
+  editSession: BridgeSession,
+  mode: PlaytestMode,
+  players: number | undefined
+): Promise<StartedPlaytest> {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await startPlaytestAsync(connection, editSession, mode, players);
+    } catch (err) {
+      const stillWindingDown =
+        err instanceof Error && err.message.includes('still in progress');
+      if (!stillWindingDown || attempt >= START_ATTEMPTS) {
+        throw err;
+      }
+      await new Promise((resolve) => setTimeout(resolve, START_RETRY_DELAY_MS));
+    }
+  }
+}
+
+export const playtestRestartCommand = defineCommand<
+  PlaytestRestartArgs,
+  PlaytestStartResult
+>({
+  group: 'playtest',
+  name: 'restart',
+  description:
+    'Stop the running playtest and start a new one in the same mode, to pick up code changes',
+  category: 'execution',
+  safety: 'mutate',
+  scope: 'connection',
+  args: {
+    mode: arg.option({
+      description:
+        "Start in this mode instead of the running playtest's (play or run)",
+      choices: ['play', 'run'],
+    }),
+    players: arg.option({
+      description:
+        "Start a multiplayer test with this many players instead of the running playtest's",
+      type: 'number',
+    }),
+  },
+  cli: {
+    format: formatPlaytestStartText,
+  },
+  handler: async (connection, args, targeting) =>
+    playtestRestartHandlerAsync(connection, {
+      mode: args.mode,
+      players: args.players,
+      target: targeting.target,
+    }),
+});