@quenty/studio-bridge 0.21.0 → 0.22.0

package/src/server/web-socket-protocol.ts

@@ -13,12 +13,28 @@ export type StudioState =
   | 'Server'
   | 'Client';
 
+export type PluginContext = 'edit' | 'client' | 'server';
+
+/**
+ * The largest message a bridge socket accepts. The plugin refuses to send a
+ * reply over half this with RESULT_TOO_LARGE, so a large result fails its own
+ * request instead of closing the socket under every request in flight.
+ * Studio itself sends messages of at least 512 MiB.
+ */
+export const MAX_MESSAGE_BYTES = 512 * 1024 * 1024;
+
 export type Capability =
   | 'execute'
   | 'queryState'
   | 'captureScreenshot'
   | 'queryDataModel'
   | 'queryLogs'
+  | 'exportInstances'
+  | 'importInstances'
+  | 'findInstances'
+  | 'grepScripts'
+  | 'startPlaytest'
+  | 'endPlaytest'
   | 'heartbeat'
   | 'registerAction'
   | 'syncActions';
@@ -31,8 +47,10 @@ export type ErrorCode =
   | 'INSTANCE_NOT_FOUND'
   | 'PROPERTY_NOT_FOUND'
   | 'SCREENSHOT_FAILED'
+  | 'RESULT_TOO_LARGE'
   | 'SCRIPT_LOAD_ERROR'
   | 'SCRIPT_RUNTIME_ERROR'
+  | 'SCRIPT_TIMEOUT'
   | 'BUSY'
   | 'SESSION_MISMATCH'
   | 'INTERNAL_ERROR';
@@ -114,11 +132,13 @@ export interface ScriptCompleteMessage extends BaseMessage {
   payload: {
     success: boolean;
     error?: string;
+    /** Where a runtime error was thrown, as `debug.traceback` prints it. */
+    traceback?: string;
     output?: Array<{ level: string; body: string; timestamp: number }>;
     /**
      * Everything the script returned, in order, marshalled by the plugin.
-     * Absent when the plugin never reported a return channel (an older plugin
-     * build, or a script that failed before returning) — distinct from `[]`,
+     * Absent when the plugin never reported a return channel (a script that
+     * failed before returning) — distinct from `[]`,
      * which means the script ran and returned nothing.
      */
     returnValues?: SerializedReturnValue[];
@@ -133,7 +153,13 @@ export interface RegisterMessage extends PushMessage {
     placeName: string;
     placeFile?: string;
     state: StudioState;
+    /** Which DataModel the plugin runs in. Older plugins leave it out. */
+    context?: PluginContext;
     pid?: number;
+    /** Set when `process run` launched this Studio, from the place it opened. */
+    launchId?: string;
+    /** The player of a multiplayer test client. */
+    playerName?: string;
     capabilities: Capability[];
   };
 }
@@ -145,6 +171,10 @@ export interface StateResultMessage extends RequestMessage {
     placeId: number;
     placeName: string;
     gameId: number;
+    /** The camera's viewport in pixels. Absent without a camera. */
+    viewportSize?: [number, number];
+    /** Studio's version, such as `0.744.0.7440803`. Absent from older plugins. */
+    studioVersion?: string;
   };
 }
 
@@ -165,6 +195,56 @@ export interface DataModelResultMessage extends RequestMessage {
   };
 }
 
+export interface ExportInstancesResultMessage extends RequestMessage {
+  type: 'exportInstancesResult';
+  payload: {
+    /** The binary model (.rbxm), base64-encoded. */
+    data: string;
+    paths: string[];
+  };
+}
+
+export interface ImportInstancesResultMessage extends RequestMessage {
+  type: 'importInstancesResult';
+  payload: {
+    paths: string[];
+  };
+}
+
+export interface FoundInstance {
+  path: string;
+  name: string;
+  className: string;
+}
+
+export interface FindInstancesResultMessage extends RequestMessage {
+  type: 'findInstancesResult';
+  payload: {
+    instances: FoundInstance[];
+    /** How many instances were looked at. */
+    searched: number;
+    /** True when the search stopped at the limit. */
+    truncated: boolean;
+  };
+}
+
+export interface GrepMatch {
+  path: string;
+  className: string;
+  line: number;
+  text: string;
+}
+
+export interface GrepScriptsResultMessage extends RequestMessage {
+  type: 'grepScriptsResult';
+  payload: {
+    matches: GrepMatch[];
+    searched: number;
+    /** True when the search stopped at the limit. */
+    truncated: boolean;
+  };
+}
+
 export interface LogsResultMessage extends RequestMessage {
   type: 'logsResult';
   payload: {
@@ -172,6 +252,10 @@ export interface LogsResultMessage extends RequestMessage {
       level: OutputLevel;
       body: string;
       timestamp: number;
+      /** With groupRepeats: how many identical entries in a row this stands for. */
+      repeats?: number;
+      /** With groupRepeats: when the last of the repeats was logged. */
+      lastTimestamp?: number;
     }>;
     total: number;
     bufferCapacity: number;
@@ -214,6 +298,28 @@ export interface SyncActionsResultMessage extends RequestMessage {
   };
 }
 
+export type PlaytestMode = 'play' | 'run';
+
+export interface PlaytestEndedMessage extends RequestMessage {
+  type: 'playtestEnded';
+  payload: {
+    playtestId: string;
+    success: boolean;
+    error?: string;
+  };
+}
+
+export interface EndPlaytestResultMessage extends RequestMessage {
+  type: 'endPlaytestResult';
+  payload: {
+    playtestId?: string;
+    /** Absent from plugins older than this field. */
+    mode?: PlaytestMode;
+    /** How many players a multiplayer test started with. */
+    players?: number;
+  };
+}
+
 export interface PluginErrorMessage extends BaseMessage {
   type: 'error';
   requestId?: string;
@@ -230,11 +336,17 @@ export type PluginMessage =
   | StateResultMessage
   | ScreenshotResultMessage
   | DataModelResultMessage
+  | ExportInstancesResultMessage
+  | ImportInstancesResultMessage
+  | FindInstancesResultMessage
+  | GrepScriptsResultMessage
   | LogsResultMessage
   | StateChangeMessage
   | HeartbeatMessage
   | RegisterActionResultMessage
   | SyncActionsResultMessage
+  | PlaytestEndedMessage
+  | EndPlaytestResultMessage
   | PluginErrorMessage;
 
 export interface ExecuteMessage extends BaseMessage {
@@ -242,6 +354,10 @@ export interface ExecuteMessage extends BaseMessage {
   requestId?: string;
   payload: {
     script: string;
+    /** The plugin cancels the script once it runs this long. */
+    timeoutMs?: number;
+    /** Passed to the script as `...`. */
+    args?: string[];
   };
 }
 
@@ -262,6 +378,51 @@ export interface CaptureScreenshotMessage extends RequestMessage {
   };
 }
 
+export interface ExportInstancesMessage extends RequestMessage {
+  type: 'exportInstances';
+  payload: {
+    paths: string[];
+  };
+}
+
+export interface ImportInstancesMessage extends RequestMessage {
+  type: 'importInstances';
+  payload: {
+    /** The binary model (.rbxm), base64-encoded. */
+    data: string;
+    parentPath: string;
+  };
+}
+
+export interface FindInstancesMessage extends RequestMessage {
+  type: 'findInstances';
+  payload: {
+    /** Dot-separated path to search under. Defaults to the whole DataModel. */
+    root?: string;
+    /** Matched case-insensitively anywhere in the name. */
+    name?: string;
+    /** Match the whole name instead. */
+    exactName?: boolean;
+    /** Matched with IsA. */
+    className?: string;
+    tag?: string;
+    limit?: number;
+  };
+}
+
+export interface GrepScriptsMessage extends RequestMessage {
+  type: 'grepScripts';
+  payload: {
+    pattern: string;
+    /** Dot-separated path to search under. Defaults to the whole DataModel. */
+    root?: string;
+    /** Treat `pattern` as a Lua pattern instead of plain text. */
+    luaPattern?: boolean;
+    caseSensitive?: boolean;
+    limit?: number;
+  };
+}
+
 export interface QueryDataModelMessage extends RequestMessage {
   type: 'queryDataModel';
   payload: {
@@ -281,6 +442,10 @@ export interface QueryLogsMessage extends RequestMessage {
     direction?: 'head' | 'tail';
     levels?: OutputLevel[];
     includeInternal?: boolean;
+    /** Only entries logged at or after this time, in epoch seconds. */
+    since?: number;
+    /** Collapse identical consecutive entries, before `count` applies. */
+    groupRepeats?: boolean;
   };
 }
 
@@ -298,6 +463,40 @@ export interface SyncActionsMessage extends RequestMessage {
   type: 'syncActions';
   payload: {
     actions: Record<string, string>;
+    verbose?: boolean;
+  };
+}
+
+export interface StartPlaytestMessage extends RequestMessage {
+  type: 'startPlaytest';
+  payload: {
+    mode: PlaytestMode;
+    playtestId: string;
+    /** Handed to the playtest's DataModels, which can't discover the bridge themselves. */
+    bridgePort: number;
+    /** The edit session's instance id, which the playtest's sessions register under. */
+    instanceId: string;
+    /** Starts a multiplayer test, a server and a client process per player. */
+    players?: number;
+  };
+}
+
+export interface EndPlaytestMessage extends RequestMessage {
+  type: 'endPlaytest';
+  payload: Record<string, never>;
+}
+
+/** Answered with `scriptComplete`, the same reply as `execute`. */
+export interface RunPlaytestScriptMessage extends RequestMessage {
+  type: 'runPlaytestScript';
+  payload: {
+    mode: PlaytestMode;
+    script: string;
+    /** Planted in the playtest's server to run the script and end the playtest. */
+    runnerSource: string;
+    timeoutSec: number;
+    /** Passed to the script as `...`. */
+    args?: string[];
   };
 }
 
@@ -317,15 +516,36 @@ export type ServerMessage =
   | QueryStateMessage
   | CaptureScreenshotMessage
   | QueryDataModelMessage
+  | ExportInstancesMessage
+  | ImportInstancesMessage
+  | FindInstancesMessage
+  | GrepScriptsMessage
   | QueryLogsMessage
   | RegisterActionMessage
   | SyncActionsMessage
+  | StartPlaytestMessage
+  | EndPlaytestMessage
+  | RunPlaytestScriptMessage
   | ServerErrorMessage;
 
 export function encodeMessage(msg: ServerMessage): string {
   return JSON.stringify(msg);
 }
 
+function isViewportSize(value: unknown): value is [number, number] {
+  return (
+    Array.isArray(value) &&
+    value.length === 2 &&
+    value.every((item) => typeof item === 'number')
+  );
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) && value.every((item) => typeof item === 'string')
+  );
+}
+
 export function decodePluginMessage(raw: string): PluginMessage | null {
   let parsed: unknown;
   try {
@@ -390,6 +610,10 @@ export function decodePluginMessage(raw: string): PluginMessage | null {
             success: payload.success,
             error:
               typeof payload.error === 'string' ? payload.error : undefined,
+            traceback:
+              typeof payload.traceback === 'string'
+                ? payload.traceback
+                : undefined,
             output,
             returnValues,
           },
@@ -420,7 +644,19 @@ export function decodePluginMessage(raw: string): PluginMessage | null {
               ? payload.placeFile
               : undefined,
           state: stateVal as StudioState,
+          context:
+            payload.context === 'edit' ||
+            payload.context === 'client' ||
+            payload.context === 'server'
+              ? payload.context
+              : undefined,
           pid: typeof payload.pid === 'number' ? payload.pid : undefined,
+          launchId:
+            typeof payload.launchId === 'string' ? payload.launchId : undefined,
+          playerName:
+            typeof payload.playerName === 'string'
+              ? payload.playerName
+              : undefined,
           capabilities: payload.capabilities as Capability[],
         },
       };
@@ -445,6 +681,13 @@ export function decodePluginMessage(raw: string): PluginMessage | null {
           placeId: payload.placeId,
           placeName: payload.placeName,
           gameId: payload.gameId,
+          viewportSize: isViewportSize(payload.viewportSize)
+            ? payload.viewportSize
+            : undefined,
+          studioVersion:
+            typeof payload.studioVersion === 'string'
+              ? payload.studioVersion
+              : undefined,
         },
       };
 
@@ -483,6 +726,55 @@ export function decodePluginMessage(raw: string): PluginMessage | null {
         },
       };
 
+    case 'exportInstancesResult':
+      if (requestId === undefined) return null;
+      if (typeof payload.data !== 'string' || !isStringArray(payload.paths))
+        return null;
+      return {
+        type: 'exportInstancesResult',
+        sessionId,
+        requestId,
+        payload: { data: payload.data, paths: payload.paths },
+      };
+
+    case 'importInstancesResult':
+      if (requestId === undefined) return null;
+      if (!isStringArray(payload.paths)) return null;
+      return {
+        type: 'importInstancesResult',
+        sessionId,
+        requestId,
+        payload: { paths: payload.paths },
+      };
+
+    case 'findInstancesResult':
+      if (requestId === undefined) return null;
+      if (!Array.isArray(payload.instances)) return null;
+      return {
+        type: 'findInstancesResult',
+        sessionId,
+        requestId,
+        payload: {
+          instances: payload.instances as FoundInstance[],
+          searched: typeof payload.searched === 'number' ? payload.searched : 0,
+          truncated: payload.truncated === true,
+        },
+      };
+
+    case 'grepScriptsResult':
+      if (requestId === undefined) return null;
+      if (!Array.isArray(payload.matches)) return null;
+      return {
+        type: 'grepScriptsResult',
+        sessionId,
+        requestId,
+        payload: {
+          matches: payload.matches as GrepMatch[],
+          searched: typeof payload.searched === 'number' ? payload.searched : 0,
+          truncated: payload.truncated === true,
+        },
+      };
+
     case 'logsResult':
       if (requestId === undefined) return null;
       if (
@@ -497,11 +789,7 @@ export function decodePluginMessage(raw: string): PluginMessage | null {
         sessionId,
         requestId,
         payload: {
-          entries: payload.entries as Array<{
-            level: OutputLevel;
-            body: string;
-            timestamp: number;
-          }>,
+          entries: payload.entries as LogsResultMessage['payload']['entries'],
           total: payload.total,
           bufferCapacity: payload.bufferCapacity,
         },
@@ -580,6 +868,44 @@ export function decodePluginMessage(raw: string): PluginMessage | null {
         },
       };
 
+    case 'playtestEnded':
+      if (requestId === undefined) return null;
+      if (
+        typeof payload.playtestId !== 'string' ||
+        typeof payload.success !== 'boolean'
+      )
+        return null;
+      return {
+        type: 'playtestEnded',
+        sessionId,
+        requestId,
+        payload: {
+          playtestId: payload.playtestId,
+          success: payload.success,
+          error: typeof payload.error === 'string' ? payload.error : undefined,
+        },
+      };
+
+    case 'endPlaytestResult':
+      if (requestId === undefined) return null;
+      return {
+        type: 'endPlaytestResult',
+        sessionId,
+        requestId,
+        payload: {
+          playtestId:
+            typeof payload.playtestId === 'string'
+              ? payload.playtestId
+              : undefined,
+          mode:
+            payload.mode === 'play' || payload.mode === 'run'
+              ? payload.mode
+              : undefined,
+          players:
+            typeof payload.players === 'number' ? payload.players : undefined,
+        },
+      };
+
     case 'error':
       if (
         typeof payload.code !== 'string' ||
@@ -642,7 +968,13 @@ export function decodeServerMessage(raw: string): ServerMessage | null {
           type: 'execute',
           sessionId,
           ...(requestId !== undefined ? { requestId } : {}),
-          payload: { script: payload.script },
+          payload: {
+            script: payload.script,
+            ...(typeof payload.timeoutMs === 'number'
+              ? { timeoutMs: payload.timeoutMs }
+              : {}),
+            ...(isStringArray(payload.args) ? { args: payload.args } : {}),
+          },
         };
       }
       return null;
@@ -674,6 +1006,74 @@ export function decodeServerMessage(raw: string): ServerMessage | null {
         },
       };
 
+    case 'exportInstances':
+      if (requestId === undefined) return null;
+      if (!isStringArray(payload.paths)) return null;
+      return {
+        type: 'exportInstances',
+        sessionId,
+        requestId,
+        payload: { paths: payload.paths },
+      };
+
+    case 'importInstances':
+      if (requestId === undefined) return null;
+      if (
+        typeof payload.data !== 'string' ||
+        typeof payload.parentPath !== 'string'
+      )
+        return null;
+      return {
+        type: 'importInstances',
+        sessionId,
+        requestId,
+        payload: { data: payload.data, parentPath: payload.parentPath },
+      };
+
+    case 'findInstances':
+      if (requestId === undefined) return null;
+      return {
+        type: 'findInstances',
+        sessionId,
+        requestId,
+        payload: {
+          root: typeof payload.root === 'string' ? payload.root : undefined,
+          name: typeof payload.name === 'string' ? payload.name : undefined,
+          exactName:
+            typeof payload.exactName === 'boolean'
+              ? payload.exactName
+              : undefined,
+          className:
+            typeof payload.className === 'string'
+              ? payload.className
+              : undefined,
+          tag: typeof payload.tag === 'string' ? payload.tag : undefined,
+          limit: typeof payload.limit === 'number' ? payload.limit : undefined,
+        },
+      };
+
+    case 'grepScripts':
+      if (requestId === undefined) return null;
+      if (typeof payload.pattern !== 'string') return null;
+      return {
+        type: 'grepScripts',
+        sessionId,
+        requestId,
+        payload: {
+          pattern: payload.pattern,
+          root: typeof payload.root === 'string' ? payload.root : undefined,
+          luaPattern:
+            typeof payload.luaPattern === 'boolean'
+              ? payload.luaPattern
+              : undefined,
+          caseSensitive:
+            typeof payload.caseSensitive === 'boolean'
+              ? payload.caseSensitive
+              : undefined,
+          limit: typeof payload.limit === 'number' ? payload.limit : undefined,
+        },
+      };
+
     case 'queryDataModel':
       if (requestId === undefined) return null;
       if (typeof payload.path !== 'string') return null;
@@ -721,6 +1121,11 @@ export function decodeServerMessage(raw: string): ServerMessage | null {
             typeof payload.includeInternal === 'boolean'
               ? payload.includeInternal
               : undefined,
+          since: typeof payload.since === 'number' ? payload.since : undefined,
+          groupRepeats:
+            typeof payload.groupRepeats === 'boolean'
+              ? payload.groupRepeats
+              : undefined,
         },
       };
 
@@ -759,6 +1164,61 @@ export function decodeServerMessage(raw: string): ServerMessage | null {
         },
       };
 
+    case 'startPlaytest':
+      if (requestId === undefined) return null;
+      if (
+        (payload.mode !== 'play' && payload.mode !== 'run') ||
+        typeof payload.playtestId !== 'string' ||
+        typeof payload.bridgePort !== 'number' ||
+        typeof payload.instanceId !== 'string'
+      )
+        return null;
+      return {
+        type: 'startPlaytest',
+        sessionId,
+        requestId,
+        payload: {
+          mode: payload.mode,
+          playtestId: payload.playtestId,
+          bridgePort: payload.bridgePort,
+          instanceId: payload.instanceId,
+          ...(typeof payload.players === 'number'
+            ? { players: payload.players }
+            : {}),
+        },
+      };
+
+    case 'endPlaytest':
+      if (requestId === undefined) return null;
+      return {
+        type: 'endPlaytest',
+        sessionId,
+        requestId,
+        payload: {} as Record<string, never>,
+      };
+
+    case 'runPlaytestScript':
+      if (requestId === undefined) return null;
+      if (
+        (payload.mode !== 'play' && payload.mode !== 'run') ||
+        typeof payload.script !== 'string' ||
+        typeof payload.runnerSource !== 'string' ||
+        typeof payload.timeoutSec !== 'number'
+      )
+        return null;
+      return {
+        type: 'runPlaytestScript',
+        sessionId,
+        requestId,
+        payload: {
+          mode: payload.mode,
+          script: payload.script,
+          runnerSource: payload.runnerSource,
+          timeoutSec: payload.timeoutSec,
+          ...(isStringArray(payload.args) ? { args: payload.args } : {}),
+        },
+      };
+
     case 'error':
       if (
         typeof payload.code !== 'string' ||