@quenty/studio-bridge 0.21.0 → 0.22.0

package/src/test/e2e/persistent-session.test.ts

@@ -439,4 +439,141 @@ describe('persistent session e2e', () => {
     const session = await waitPromise;
     expect(session.info.sessionId).toBe(plugin.sessionId);
   });
+
+  it('client execute is relayed through the host to the plugin', async () => {
+    const host = await BridgeConnection.connectAsync({
+      port: 0,
+      keepAlive: true,
+      local: true,
+    });
+    connections.push(host);
+
+    const plugin = new MockPluginClient({
+      port: host.port,
+      instanceId: 'inst-relay',
+      capabilities: ['execute', 'syncActions'],
+    });
+    plugins.push(plugin);
+    plugin.autoRespond('syncActions', () => ({
+      type: 'syncActionsResult',
+      payload: { needed: [], installed: {} },
+    }));
+    plugin.autoRespond('execute', () => ({
+      type: 'scriptComplete',
+      payload: { success: true, output: [], returnValues: [42] },
+    }));
+    await plugin.connectAndRegisterAsync();
+    await new Promise((r) => setTimeout(r, 100));
+
+    const client = await BridgeConnection.connectAsync({
+      port: host.port,
+      local: true,
+    });
+    connections.push(client);
+    expect(client.role).toBe('client');
+
+    const session = await client.resolveSessionAsync(plugin.sessionId);
+    const result = await session.execAsync('return 42', 2_000);
+
+    expect(result.success).toBe(true);
+    expect(result.returnValues).toEqual([42]);
+  });
+
+  it('host finishes a relayed action before shutting down', async () => {
+    const host = await BridgeConnection.connectAsync({
+      port: 0,
+      keepAlive: true,
+      local: true,
+    });
+    connections.push(host);
+
+    const plugin = new MockPluginClient({
+      port: host.port,
+      instanceId: 'inst-drain',
+      capabilities: ['execute', 'syncActions'],
+    });
+    plugins.push(plugin);
+    plugin.autoRespond('syncActions', () => ({
+      type: 'syncActionsResult',
+      payload: { needed: [], installed: {} },
+    }));
+    plugin.onAnyMessage((msg) => {
+      if (msg.type === 'shutdown') {
+        void plugin.disconnectAsync();
+        return;
+      }
+      if (msg.type !== 'execute') return;
+      setTimeout(() => {
+        plugin.sendMessage({
+          type: 'scriptComplete',
+          sessionId: plugin.sessionId,
+          requestId: msg.requestId,
+          payload: { success: true, output: [], returnValues: ['late'] },
+        });
+      }, 300);
+    });
+    await plugin.connectAndRegisterAsync();
+    await new Promise((r) => setTimeout(r, 100));
+
+    const client = await BridgeConnection.connectAsync({
+      port: host.port,
+      local: true,
+    });
+    connections.push(client);
+
+    const session = await client.resolveSessionAsync(plugin.sessionId);
+    const resultPromise = session.execAsync('return "late"', 2_000);
+    await new Promise((r) => setTimeout(r, 100));
+    const hostShutdown = host.disconnectAsync();
+
+    const result = await resultPromise;
+    await hostShutdown;
+
+    expect(result.success).toBe(true);
+    expect(result.returnValues).toEqual(['late']);
+  });
+
+  it('host stops waiting on a relayed action that never finishes', async () => {
+    const host = await BridgeConnection.connectAsync({
+      port: 0,
+      keepAlive: true,
+      local: true,
+    });
+    connections.push(host);
+
+    const plugin = new MockPluginClient({
+      port: host.port,
+      instanceId: 'inst-stuck',
+      capabilities: ['execute', 'syncActions'],
+    });
+    plugins.push(plugin);
+    plugin.autoRespond('syncActions', () => ({
+      type: 'syncActionsResult',
+      payload: { needed: [], installed: {} },
+    }));
+    plugin.onAnyMessage((msg) => {
+      if (msg.type === 'shutdown') {
+        void plugin.disconnectAsync();
+      }
+    });
+    await plugin.connectAndRegisterAsync();
+    await new Promise((r) => setTimeout(r, 100));
+
+    const client = await BridgeConnection.connectAsync({
+      port: host.port,
+      local: true,
+    });
+    connections.push(client);
+
+    const session = await client.resolveSessionAsync(plugin.sessionId);
+    const stuck = session.execAsync('while true do task.wait() end', 60_000);
+    await new Promise((r) => setTimeout(r, 100));
+
+    const started = Date.now();
+    await host.disconnectAsync({ relayDrainTimeoutMs: 200 });
+
+    expect(Date.now() - started).toBeLessThan(2_000);
+    const result = await stuck;
+    expect(result.success).toBe(false);
+  });
 });

package/src/test/e2e/split-server.test.ts

@@ -4,11 +4,9 @@
  * that multiple clients can coexist with the host without interfering
  * with plugin sessions.
  *
- * Note: The current BridgeHost does not implement full host-protocol
- * message routing (list-sessions, host-envelope relay). These tests
- * exercise the real transport layer and connection lifecycle, not the
- * relay protocol. Split-server relay is tested via BridgeConnection
- * with a mock host (see bridge-connection-remote.test.ts).
+ * These tests exercise the real transport layer and connection lifecycle,
+ * not the relay protocol. Relay through a real host is covered in
+ * persistent-session.test.ts.
  */
 
 import { describe, it, expect, afterEach } from 'vitest';

package/templates/studio-bridge-plugin/default.project.json

@@ -1,5 +1,8 @@
 {
   "name": "StudioBridgePlugin",
+  "globIgnorePaths": [
+    "**/*.spec.lua"
+  ],
   "tree": {
     "$path": "src"
   }

package/templates/studio-bridge-plugin/src/Shared/ActionRouter.lua

@@ -1,164 +1,215 @@
---[[
-	Action dispatch module for routing incoming protocol messages to handlers.
+--!strict
+--[=[
+	Routes incoming studio-bridge messages to handlers by message type, and wraps
+	whatever a handler returns into the response message.
 
-	Maintains a registry of handler functions keyed by message type. When a
-	message is dispatched, the router looks up the handler, calls it with
-	(payload, requestId, sessionId), and constructs a response message if
-	the handler returns a payload table.
+	- An unknown message type answers with an `UNKNOWN_REQUEST` error.
+	- A handler that throws answers with an `INTERNAL_ERROR` error.
+	- A handler that returns nil sends nothing, which is how an action that
+	  replies on its own (through `sendMessage`) opts out.
 
-	Error handling:
-	- Unknown message type: returns error response with code UNKNOWN_REQUEST
-	- Handler throws: returns error response with code INTERNAL_ERROR
-	- Handler returns nil: no response is generated
+	Action modules pushed over the wire call `register` and `setResponseType` on
+	the router. Those two keep their lowercase names because a persistent plugin
+	installed from an older release still runs action source pushed by a newer CLI.
 
-	No Roblox APIs. Pure logic, testable under Lune.
-]]
+	@class ActionRouter
+]=]
 
 local ActionRouter = {}
+ActionRouter.ClassName = "ActionRouter"
 ActionRouter.__index = ActionRouter
 
--- ---------------------------------------------------------------------------
--- Constructor
--- ---------------------------------------------------------------------------
+export type Message = {
+	type: string,
+	sessionId: string,
+	payload: { [string]: any },
+	requestId: string?,
+}
+
+export type Handler = (payload: { [string]: any }, requestId: string, sessionId: string) -> { [string]: any }?
+
+export type SendMessage = (message: { [string]: any }) -> ()
+
+export type ActionInfo = {
+	module: any,
+	hash: string,
+	handlerNames: { string },
+}
+
+export type ActionRouter = typeof(setmetatable(
+	{} :: {
+		_handlers: { [string]: Handler },
+		_responseTypes: { [string]: string },
+		_actions: { [string]: ActionInfo },
+		_vendorPng: any?,
+	},
+	{} :: typeof({ __index = ActionRouter })
+))
+
+--[=[
+	Constructs a new router with no handlers.
+]=]
+function ActionRouter.new(): ActionRouter
+	local self: ActionRouter = setmetatable({} :: any, ActionRouter)
+
+	self._handlers = {}
+	self._responseTypes = {}
+	self._actions = {}
+
+	-- The screenshot action reads its PNG encoder off this field
+	self._vendorPng = nil
 
-function ActionRouter.new()
-	local self = setmetatable({
-		_handlers = {} :: {
-			[string]: (payload: { [string]: any }, requestId: string, sessionId: string) -> { [string]: any }?,
-		},
-		_responseTypes = {} :: { [string]: string },
-		_actions = {} :: { [string]: { module: any, hash: string, handlerNames: { string } } },
-	}, ActionRouter)
 	return self
 end
 
--- ---------------------------------------------------------------------------
--- Register a handler for a message type
--- ---------------------------------------------------------------------------
-
-function ActionRouter.register(
-	self: any,
-	messageType: string,
-	handler: (
-		payload: { [string]: any },
-		requestId: string,
-		sessionId: string
-	) -> { [string]: any }?
-)
+--[=[
+	Sets the handler for a message type, replacing any previous one.
+]=]
+function ActionRouter.register(self: ActionRouter, messageType: string, handler: Handler)
 	self._handlers[messageType] = handler
 end
 
--- ---------------------------------------------------------------------------
--- Dispatch an incoming message
--- ---------------------------------------------------------------------------
-
---[[
-	Dispatch an incoming message to the appropriate handler.
-
-	@param message Table with fields: type, sessionId, payload, requestId?
-	@return A response message table, or nil if the handler returns nil.
-]]
-function ActionRouter.dispatch(
-	self: any,
-	message: {
-		type: string,
-		sessionId: string,
-		payload: { [string]: any },
-		requestId: string?,
-	}
-): { [string]: any }?
-	local handler = self._handlers[message.type]
+--[=[
+	Overrides the response type for a message type. Defaults to `<messageType>Result`.
+]=]
+function ActionRouter.setResponseType(self: ActionRouter, messageType: string, responseType: string)
+	self._responseTypes[messageType] = responseType
+end
+
+--[=[
+	Sets the PNG encoder handed to the screenshot action.
+]=]
+function ActionRouter.SetVendorPng(self: ActionRouter, png: any)
+	self._vendorPng = png
+end
 
+--[=[
+	Dispatches a message to its handler and returns the response message, if any.
+]=]
+function ActionRouter.Dispatch(self: ActionRouter, message: Message): Message?
+	local handler = self._handlers[message.type]
 	if handler == nil then
-		return {
-			type = "error",
-			sessionId = message.sessionId,
-			requestId = message.requestId,
-			payload = {
-				code = "UNKNOWN_REQUEST",
-				message = "Unknown message type: " .. tostring(message.type),
-			},
-		}
+		return ActionRouter._errorResponse(message, "UNKNOWN_REQUEST", `Unknown message type: {tostring(message.type)}`)
 	end
 
-	local requestId = message.requestId or ""
-	local ok, result = pcall(handler, message.payload, requestId, message.sessionId)
-
+	local ok, result = pcall(handler, message.payload, message.requestId or "", message.sessionId)
 	if not ok then
-		return {
-			type = "error",
-			sessionId = message.sessionId,
-			requestId = message.requestId,
-			payload = {
-				code = "INTERNAL_ERROR",
-				message = "Handler error: " .. tostring(result),
-			},
-		}
+		return ActionRouter._errorResponse(message, "INTERNAL_ERROR", `Handler error: {tostring(result)}`)
 	end
 
 	if result == nil then
 		return nil
 	end
 
-	-- Construct response with the appropriate response type
-	local responseType = self._responseTypes[message.type] or (message.type .. "Result")
+	if result.success == false and type(result.code) == "string" and type(result.message) == "string" then
+		return ActionRouter._errorResponse(message, result.code, result.message)
+	end
 
 	return {
-		type = responseType,
+		type = self._responseTypes[message.type] or `{message.type}Result`,
 		sessionId = message.sessionId,
 		requestId = message.requestId,
 		payload = result,
 	}
 end
 
--- ---------------------------------------------------------------------------
--- Set a custom response type for a message type
--- ---------------------------------------------------------------------------
+--[=[
+	Tears down every installed action and drops all handlers.
+]=]
+function ActionRouter.Destroy(self: ActionRouter)
+	for _, action in self._actions do
+		if type(action.module) == "table" and type(action.module.teardown) == "function" then
+			pcall(action.module.teardown)
+		end
+	end
 
-function ActionRouter.setResponseType(self: any, messageType: string, responseType: string)
-	self._responseTypes[messageType] = responseType
+	table.clear(self._actions)
+	table.clear(self._handlers)
+	table.clear(self._responseTypes)
+end
+
+--[=[
+	Compiles Luau source into a function, like `loadstring`. A playtest's client
+	has no `loadstring`, so there the source compiles through a ModuleScript
+	instead. Returns nil and the compile error when the source does not compile.
+]=]
+function ActionRouter.Compile(_self: ActionRouter, source: string, chunkName: string?): (any, string?)
+	local loadstringOk, fn, compileErr = pcall(loadstring :: any, source, chunkName)
+	if loadstringOk then
+		return fn, compileErr
+	end
+
+	return ActionRouter._compileWithModuleScript(source, chunkName)
+end
+
+function ActionRouter._compileWithModuleScript(source: string, chunkName: string?): (any, string?)
+	local moduleName = if chunkName then string.gsub(chunkName, "^[@=]", "") else "compiled"
+
+	local moduleScript = Instance.new("ModuleScript")
+	moduleScript.Name = moduleName
+	-- Wrapping on the first line keeps a top-level `return` legal and line numbers unchanged
+	moduleScript.Source = `return function(...) {source}\nend`
+
+	-- require only reports that the module failed to load; the compile error
+	-- itself reaches the output a frame later
+	local compileErrors: { string } = {}
+	local logConnection = game:GetService("LogService").MessageOut:Connect(function(message, messageType)
+		if messageType == Enum.MessageType.MessageError and string.find(message, moduleName, 1, true) == 1 then
+			table.insert(compileErrors, message)
+		end
+	end)
+
+	local requireOk, result = pcall(require, moduleScript)
+	if not requireOk then
+		task.wait()
+	end
+
+	logConnection:Disconnect()
+	moduleScript:Destroy()
+
+	if requireOk then
+		return result, nil
+	end
+	return nil, compileErrors[1] or tostring(result)
+end
+
+function ActionRouter._errorResponse(message: Message, code: string, errorMessage: string): Message
+	return {
+		type = "error",
+		sessionId = message.sessionId,
+		requestId = message.requestId,
+		payload = {
+			code = code,
+			message = errorMessage,
+		},
+	}
 end
 
--- ---------------------------------------------------------------------------
--- Register a dynamic action from source code
--- ---------------------------------------------------------------------------
-
---[[
-	Dynamically register an action from Luau source code received over the wire.
-
-	The source is expected to be a module that returns a table with a `register`
-	function: `function(router, sendMessage?, logBuffer?)`. This mirrors the
-	static action module convention.
-
-	If the source defines a simple handler function instead, it is registered
-	directly as the handler for the given action name.
-
-	@param name The action name (used as the message type if not registered otherwise).
-	@param source The Luau source code string.
-	@param sendMessage Optional callback for actions that send their own responses.
-	@param logBuffer Optional log buffer instance.
-	@param responseType Optional response type override.
-	@param hash Optional content hash for skip-on-same-hash optimization.
-	@return success, error?
-]]
-function ActionRouter.registerAction(
-	self: any,
+--[=[
+	Installs an action from Luau source received over the wire.
+
+	The source returns either a table with `register(router, sendMessage?, logBuffer?)`
+	(and optionally `teardown()`), or a bare handler function registered under `name`.
+
+	Re-registering a name tears the previous module down and removes its handlers
+	first. With a `hash`, the same hash installed twice is a no-op.
+]=]
+function ActionRouter.RegisterAction(
+	self: ActionRouter,
 	name: string,
 	source: string,
-	sendMessage: ((msg: { [string]: any }) -> ())?,
+	sendMessage: SendMessage?,
 	logBuffer: any?,
 	responseType: string?,
 	hash: string?
 ): (boolean, string?)
-	-- Hash-based skip: if the same hash is already installed, skip re-registration
-	if hash and self._actions[name] and self._actions[name].hash == hash then
+	local oldAction = self._actions[name]
+	if hash and oldAction and oldAction.hash == hash then
 		return true, nil
 	end
 
-	-- If an old module exists, tear it down and remove its handlers
-	local oldAction = self._actions[name]
 	if oldAction then
-		if type(oldAction.module.teardown) == "function" then
+		if type(oldAction.module) == "table" and type(oldAction.module.teardown) == "function" then
 			pcall(oldAction.module.teardown)
 		end
 		for _, handlerName in oldAction.handlerNames do
@@ -167,77 +218,75 @@ function ActionRouter.registerAction(
 		end
 	end
 
-	-- Snapshot handler keys before registration
-	local beforeHandlers = {}
-	for k, _ in self._handlers do
-		beforeHandlers[k] = true
+	local handlersBefore: { [string]: boolean } = {}
+	for handlerName in self._handlers do
+		handlersBefore[handlerName] = true
 	end
 
-	-- Load the source code
-	local loadOk, moduleOrErr = pcall(function()
-		return (loadstring :: any)(source, `@action/{name}`)
-	end)
-
-	if not loadOk or not moduleOrErr then
-		return false, `Failed to load action source: {moduleOrErr or "loadstring returned nil"}`
+	local loadOk, chunkOrErr, compileErr = pcall(self.Compile, self, source, `@action/{name}`)
+	if not loadOk or not chunkOrErr then
+		return false, `Failed to load action source: {compileErr or chunkOrErr or "compile returned nil"}`
 	end
 
-	-- Execute the loaded chunk to get the module table
-	local execOk, moduleTable = pcall(moduleOrErr)
+	local execOk, moduleOrErr = pcall(chunkOrErr)
 	if not execOk then
-		return false, `Failed to execute action module: {moduleTable}`
+		return false, `Failed to execute action module: {moduleOrErr}`
 	end
 
-	-- If the module has a register function, call it
-	if type(moduleTable) == "table" and type(moduleTable.register) == "function" then
-		local regOk, regErr = pcall(moduleTable.register, self, sendMessage, logBuffer)
-		if not regOk then
-			return false, `register() failed: {regErr}`
+	if type(moduleOrErr) == "table" and type(moduleOrErr.register) == "function" then
+		local registerOk, registerErr = pcall(moduleOrErr.register, self, sendMessage, logBuffer)
+		if not registerOk then
+			return false, `register() failed: {registerErr}`
 		end
-	elseif type(moduleTable) == "function" then
-		-- Simple handler function
-		self:register(name, moduleTable)
+	elseif type(moduleOrErr) == "function" then
+		self:register(name, moduleOrErr)
 	else
-		return false, `Action module must return a table with .register() or a function`
+		return false, "Action module must return a table with .register() or a function"
 	end
 
-	-- Set custom response type if provided
 	if responseType then
 		self._responseTypes[name] = responseType
 	end
 
-	-- Diff handler keys to find newly registered handler names
-	local registeredNames = {}
-	for k, _ in self._handlers do
-		if not beforeHandlers[k] then
-			table.insert(registeredNames, k)
+	local handlerNames: { string } = {}
+	for handlerName in self._handlers do
+		if not handlersBefore[handlerName] then
+			table.insert(handlerNames, handlerName)
 		end
 	end
 
-	-- Store in _actions for hash tracking
 	if hash then
 		self._actions[name] = {
-			module = moduleTable,
+			module = moduleOrErr,
 			hash = hash,
-			handlerNames = registeredNames,
+			handlerNames = handlerNames,
 		}
 	end
 
 	return true, nil
 end
 
--- ---------------------------------------------------------------------------
--- Get installed actions with their hashes
--- ---------------------------------------------------------------------------
-
---[[
-	Returns a map of action name -> content hash for all installed actions.
-	Used by the syncActions protocol to determine which actions need updating.
-]]
-function ActionRouter.getInstalledActions(self: any): { [string]: string }
-	local result = {}
-	for name, info in self._actions do
-		result[name] = info.hash
+--[=[
+	Returns the handler names an installed action registered, or nil when no
+	action with a hash is installed under `name`.
+]=]
+function ActionRouter.GetActionHandlerNames(self: ActionRouter, name: string): { string }?
+	local action = self._actions[name]
+	if not action then
+		return nil
+	end
+
+	return table.clone(action.handlerNames)
+end
+
+--[=[
+	Returns action name to content hash for every installed action. The bridge
+	compares this against its own hashes to decide which actions to push.
+]=]
+function ActionRouter.GetInstalledActions(self: ActionRouter): { [string]: string }
+	local result: { [string]: string } = {}
+	for name, action in self._actions do
+		result[name] = action.hash
 	end
 	return result
 end