@quenty/studio-bridge 0.22.1 → 0.24.0

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

@@ -0,0 +1,47 @@
+--!strict
+--[=[
+	Compiles source by looking it up among ModuleScripts compiled ahead of time,
+	for the bridge planted into a playtest: an ordinary Script there has neither
+	`loadstring` nor the permission to set a ModuleScript's source.
+
+	The edit session plants one ModuleScript per source the playtest may run (the
+	actions and any script `playtest run` sends), each returning
+	`{ fn = function(...) <source> end, source = <source> }`. A source that was
+	not planted cannot run there.
+
+	@class PrecompiledSources
+]=]
+
+local PrecompiledSources = {}
+
+export type Entry = {
+	fn: (...any) -> ...any,
+	source: string,
+}
+
+--[=[
+	Returns a compiler for the sources planted under `folder`, for
+	`ActionRouter:SetCompiler`.
+]=]
+function PrecompiledSources.createCompiler(folder: Instance): (source: string, chunkName: string?) -> (any, string?)
+	local bySource: { [string]: (...any) -> ...any } = {}
+	for _, child in folder:GetChildren() do
+		if child:IsA("ModuleScript") then
+			local ok, entry = pcall(require, child)
+			if ok and type(entry) == "table" and type(entry.fn) == "function" and type(entry.source) == "string" then
+				bySource[entry.source] = entry.fn
+			end
+		end
+	end
+
+	return function(source: string, _chunkName: string?): (any, string?)
+		local fn = bySource[source]
+		if fn then
+			return fn, nil
+		end
+		return nil,
+			'This playtest session runs without plugin permissions, so it can only run code planted when the playtest started. Turn on Studio\'s "Load user plugins on playtest" setting to run any code in it.'
+	end
+end
+
+return PrecompiledSources

package/templates/studio-bridge-plugin/src/Shared/PrecompiledSources.spec.lua

@@ -0,0 +1,57 @@
+--!strict
+--[[
+	@class PrecompiledSources.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local PrecompiledSources = require("PrecompiledSources")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function plant(folder: Instance, name: string, moduleSource: string)
+	local moduleScript = Instance.new("ModuleScript")
+	moduleScript.Name = name
+	moduleScript.Source = moduleSource
+	moduleScript.Parent = folder
+end
+
+describe("PrecompiledSources.createCompiler()", function()
+	it("should compile a planted source to its function", function()
+		local folder = Instance.new("Folder")
+		plant(folder, "1", 'return { fn = function(...) return 1 + 2\nend, source = "return 1 + 2" }')
+
+		local fn = PrecompiledSources.createCompiler(folder)("return 1 + 2")
+
+		expect(fn()).toEqual(3)
+	end)
+
+	it("should pass arguments through", function()
+		local folder = Instance.new("Folder")
+		plant(folder, "1", 'return { fn = function(...) return ...\nend, source = "return ..." }')
+
+		local fn = PrecompiledSources.createCompiler(folder)("return ...")
+
+		expect(fn("a")).toEqual("a")
+	end)
+
+	it("should explain that a source that was not planted cannot run", function()
+		local fn, err = PrecompiledSources.createCompiler(Instance.new("Folder"))("print(1)")
+
+		expect(fn).toBeNil()
+		expect(err).toContain("Load user plugins on playtest")
+	end)
+
+	it("should skip a planted module that does not load", function()
+		local folder = Instance.new("Folder")
+		plant(folder, "broken", "return {")
+		plant(folder, "1", 'return { fn = function(...) return 1\nend, source = "return 1" }')
+
+		local fn = PrecompiledSources.createCompiler(folder)("return 1")
+
+		expect(fn()).toEqual(1)
+	end)
+end)

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

@@ -0,0 +1,357 @@
+--!strict
+--[=[
+	The studio-bridge client: an action router, the log buffer `queryLogs` reads,
+	and the WebSocket to the bridge. Two entry points start it:
+
+	- The plugin (StudioBridgePlugin.server.lua), in every Studio DataModel it
+	  loads into.
+	- The bridge planted into a playtest's server (StudioBridgePlaytest.server.lua),
+	  an ordinary Script that runs whether or not Studio loads user plugins into
+	  playtests. It has no plugin permissions, so it cannot compile code; it runs
+	  the sources compiled for it ahead of time through the `compile` option.
+
+	It connects one of three ways:
+
+	- Ephemeral: `ephemeral` names the port and session id the CLI built the
+	  plugin for.
+	- Playtest: `playtestArgs` names the bridge port, handed over through the
+	  StudioTestService test args, since a playtest cannot make the HTTP requests
+	  port discovery needs.
+	- Persistent: scans for a running bridge with DiscoveryStateMachine and
+	  reconnects whenever it drops.
+
+	@class StudioBridgeClient
+]=]
+
+local HttpService = game:GetService("HttpService")
+local LogService = game:GetService("LogService")
+local Players = game:GetService("Players")
+
+local ActionRouter = require(script.Parent.ActionRouter)
+local BuiltInActions = require(script.Parent.BuiltInActions)
+local DiscoveryStateMachine = require(script.Parent.DiscoveryStateMachine)
+local MessageBuffer = require(script.Parent.MessageBuffer)
+local StudioBridgeConnection = require(script.Parent.StudioBridgeConnection)
+local StudioBridgeLogUtils = require(script.Parent.StudioBridgeLogUtils)
+local StudioBridgeSessionUtils = require(script.Parent.StudioBridgeSessionUtils)
+
+local LOG_BUFFER_CAPACITY = 1000
+local POLL_INTERVAL_SEC = 2
+
+local LOG_LEVELS: { [Enum.MessageType]: string } = {
+	[Enum.MessageType.MessageOutput] = "Print",
+	[Enum.MessageType.MessageInfo] = "Info",
+	[Enum.MessageType.MessageWarning] = "Warning",
+	[Enum.MessageType.MessageError] = "Error",
+}
+
+local StudioBridgeClient = {}
+
+export type Options = {
+	ephemeral: { port: string, sessionId: string }?,
+	playtestArgs: StudioBridgeSessionUtils.PlaytestArgs?,
+	compile: ActionRouter.Compiler?,
+	vendorPng: any?,
+}
+
+--[=[
+	Starts the client and returns a function that stops it. Socket callbacks and
+	the poll loop outlive the script that started them, so the owner must stop it
+	when it unloads.
+]=]
+function StudioBridgeClient.start(options: Options): () -> ()
+	local playtestArgs = options.playtestArgs
+
+	local function createNonce(): string
+		return string.lower(string.sub(HttpService:GenerateGUID(false), 1, 4))
+	end
+
+	local context: StudioBridgeSessionUtils.PluginContext = StudioBridgeSessionUtils.getContext()
+	local nonceOk, nonce = pcall(StudioBridgeSessionUtils.getOrCreateNonce, game:GetService("CoreGui"), createNonce)
+	if not nonceOk then
+		nonce = createNonce()
+	end
+
+	-- Read on every connect: Studio can load plugins before it names the DataModel after the place
+	local function getInstanceId(): string
+		if playtestArgs then
+			return playtestArgs.instanceId
+		end
+		return StudioBridgeSessionUtils.getInstanceId(game.Name, nonce)
+	end
+
+	local function getPlayerName(): string?
+		local player = if context == "client" then Players.LocalPlayer else nil
+		return if player then player.Name else nil
+	end
+
+	-- The clients of a multiplayer test share an instance id, so their session ids name their player
+	local function getSessionId(): string
+		local isMultiplayerClient = playtestArgs and playtestArgs.multiplayer and context == "client"
+		return StudioBridgeSessionUtils.getSessionId(
+			getInstanceId(),
+			context,
+			if isMultiplayerClient then getPlayerName() else nil
+		)
+	end
+
+	local router = ActionRouter.new()
+	local logBuffer = MessageBuffer.new(LOG_BUFFER_CAPACITY)
+	local currentConnection: StudioBridgeConnection.StudioBridgeConnection? = nil
+	local currentWebSocket: any = nil
+	local discovery: DiscoveryStateMachine.DiscoveryStateMachine? = nil
+	local pollThread: thread? = nil
+	local nameConnection: RBXScriptConnection? = nil
+	local isStopped = false
+
+	if options.vendorPng then
+		router:SetVendorPng(options.vendorPng)
+	end
+	if options.compile then
+		router:SetCompiler(options.compile)
+	end
+
+	BuiltInActions.register(router, function(message)
+		if currentConnection then
+			currentConnection:Send(message)
+		end
+	end, logBuffer)
+
+	-- Hybrid clock: the wall clock at load, then os.clock() deltas, which are cheaper per entry
+	local clockBase = os.clock()
+	local timeBase = DateTime.now().UnixTimestampMillis / 1000
+
+	local logConnection = LogService.MessageOut:Connect(function(message, messageType)
+		if string.sub(message, 1, #StudioBridgeLogUtils.PREFIX) == StudioBridgeLogUtils.PREFIX then
+			return
+		end
+
+		logBuffer:Push({
+			level = LOG_LEVELS[messageType] or "Print",
+			body = message,
+			timestamp = timeBase + (os.clock() - clockBase),
+		})
+	end)
+
+	local function openConnection(webSocket: any, sessionId: string, label: string)
+		if isStopped then
+			return
+		end
+
+		if currentConnection then
+			currentConnection:Destroy()
+		end
+
+		currentConnection = StudioBridgeConnection.new({
+			webSocket = webSocket,
+			router = router,
+			sessionId = sessionId,
+			registerPayload = StudioBridgeSessionUtils.createRegisterPayload(
+				getInstanceId(),
+				context,
+				StudioBridgeSessionUtils.getLaunchId(workspace),
+				getPlayerName(),
+				if playtestArgs then playtestArgs.playtestId else nil
+			),
+		})
+
+		StudioBridgeLogUtils.logVerbose(`Connected to {label} as {sessionId}`)
+	end
+
+	local function createWebSocket(url: string): (boolean, any)
+		local ok, webSocket = pcall(function()
+			return HttpService:CreateWebStreamClient(Enum.WebStreamClientType.WebSocket, { Url = url })
+		end)
+		if ok then
+			currentWebSocket = webSocket
+		end
+		return ok, webSocket
+	end
+
+	local function stop()
+		if isStopped then
+			return
+		end
+		isStopped = true
+		logConnection:Disconnect()
+		if nameConnection then
+			nameConnection:Disconnect()
+			nameConnection = nil
+		end
+
+		if pollThread then
+			task.cancel(pollThread)
+			pollThread = nil
+		end
+		if discovery then
+			discovery:Stop()
+		end
+		if currentConnection then
+			currentConnection:Destroy()
+			currentConnection = nil
+		end
+		if currentWebSocket then
+			pcall(function()
+				currentWebSocket:Close()
+			end)
+			currentWebSocket = nil
+		end
+
+		router:Destroy()
+	end
+
+	local function warnOnError(webSocket: any)
+		webSocket.Error:Connect(function(status, err)
+			StudioBridgeLogUtils.logVerbose(`WebSocket error ({status}): {err}`)
+		end)
+	end
+
+	local ephemeral = options.ephemeral
+	if ephemeral then
+		-- Every open Studio loads this plugin, but only the one launched for this run
+		-- has the session id stamped on its place, which may load after the plugin
+		local function connectEphemeral()
+			if StudioBridgeSessionUtils.getLaunchId(workspace) ~= ephemeral.sessionId or currentWebSocket then
+				return
+			end
+
+			local ok, webSocket = createWebSocket(`ws://localhost:{ephemeral.port}/{ephemeral.sessionId}`)
+			if not (ok and webSocket) then
+				StudioBridgeLogUtils.warn("Failed to create WebSocket client")
+				return
+			end
+
+			webSocket.Opened:Connect(function()
+				openConnection(webSocket, ephemeral.sessionId, `localhost:{ephemeral.port} (ephemeral)`)
+			end)
+			warnOnError(webSocket)
+		end
+
+		nameConnection = workspace:GetAttributeChangedSignal("StudioBridgeSessionId"):Connect(connectEphemeral)
+		connectEphemeral()
+		return stop
+	end
+
+	-- A multiplayer client's session id names its player, so wait for one
+	if playtestArgs and playtestArgs.multiplayer and context == "client" then
+		while not Players.LocalPlayer do
+			Players:GetPropertyChangedSignal("LocalPlayer"):Wait()
+		end
+	end
+
+	local playtestPort = if playtestArgs then playtestArgs.port else nil
+
+	local stateMachine: DiscoveryStateMachine.DiscoveryStateMachine
+	stateMachine = DiscoveryStateMachine.new(nil, {
+		scanPortsAsync = if playtestPort
+			then function()
+				return playtestPort, nil
+			end
+			else function(ports: { number }, timeoutSec: number)
+				return StudioBridgeClient._scanPortsAsync(ports, timeoutSec)
+			end,
+		connectWebSocket = createWebSocket,
+		onStateChange = function(oldState, newState)
+			if oldState == "idle" and newState == "searching" then
+				StudioBridgeLogUtils.logVerbose("Searching for host on ports 38741-38744...")
+			end
+		end,
+		onConnected = function(webSocket, port)
+			webSocket.Opened:Connect(function()
+				openConnection(webSocket, getSessionId(), `localhost:{port}`)
+			end)
+			webSocket.Closed:Connect(function()
+				stateMachine:HandleDisconnect("closed")
+			end)
+			warnOnError(webSocket)
+		end,
+		onDisconnected = function(reason)
+			StudioBridgeLogUtils.logVerbose(`Disconnected ({reason}), searching...`)
+		end,
+	})
+
+	discovery = stateMachine
+
+	stateMachine:Start()
+
+	-- Reconnecting re-registers under the session id for the new name. A
+	-- playtest's id comes from its test args, so a rename leaves it unchanged.
+	if not playtestArgs then
+		nameConnection = game:GetPropertyChangedSignal("Name"):Connect(function()
+			if currentWebSocket then
+				pcall(function()
+					currentWebSocket:Close()
+				end)
+			end
+		end)
+	end
+
+	-- Each cycle gets a fixed time budget, which PollAsync threads through to the port scan
+	pollThread = task.spawn(function()
+		while true do
+			local startTime = os.clock()
+			stateMachine:PollAsync(POLL_INTERVAL_SEC)
+
+			local remaining = POLL_INTERVAL_SEC - (os.clock() - startTime)
+			if remaining > 0 then
+				task.wait(remaining)
+			else
+				task.wait()
+			end
+		end
+	end)
+
+	return stop
+end
+
+--[[
+	Probes every port's /health endpoint in parallel and returns the first port
+	to answer, or nil once all fail or the timeout passes. The caller is resumed
+	with task.defer so it has reached coroutine.yield() first.
+]]
+function StudioBridgeClient._scanPortsAsync(ports: { number }, timeoutSec: number): (number?, string?)
+	local callerThread = coroutine.running()
+	local foundPort: number? = nil
+	local foundBody: string? = nil
+	local remaining = #ports
+	local settled = false
+
+	local function settle()
+		if not settled then
+			settled = true
+			task.defer(callerThread)
+		end
+	end
+
+	local threads: { thread } = {}
+	for _, port in ports do
+		table.insert(
+			threads,
+			task.spawn(function()
+				local ok, body = pcall(HttpService.GetAsync, HttpService, `http://localhost:{port}/health`)
+				if ok and not settled then
+					foundPort = port
+					foundBody = body
+					settle()
+					return
+				end
+
+				remaining -= 1
+				if remaining <= 0 then
+					settle()
+				end
+			end)
+		)
+	end
+	table.insert(threads, task.delay(timeoutSec, settle))
+
+	coroutine.yield()
+
+	for _, thread in threads do
+		pcall(task.cancel, thread)
+	end
+
+	return foundPort, foundBody
+end
+
+return StudioBridgeClient

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

@@ -12,6 +12,8 @@ local PLUGIN_VERSION = "{{PLUGIN_VERSION}}"
 local MAX_SLUG_LENGTH = 24
 local NONCE_VALUE_NAME = "StudioBridgeNonce"
 local LAUNCH_ID_ATTRIBUTE = "StudioBridgeSessionId"
+local PLANTED_BRIDGE_NAME = "StudioBridgePlaytest"
+local PLAYTEST_ID_ATTRIBUTE = "PlaytestId"
 
 local StudioBridgeSessionUtils = {}
 
@@ -21,6 +23,7 @@ export type PlaytestArgs = {
 	port: number,
 	instanceId: string,
 	multiplayer: boolean,
+	playtestId: string?,
 }
 
 --[=[
@@ -45,6 +48,7 @@ StudioBridgeSessionUtils.CAPABILITIES = table.freeze({
 	"grepScripts",
 	"startPlaytest",
 	"endPlaytest",
+	"playtestPlayers",
 })
 
 --[=[
@@ -115,7 +119,8 @@ function StudioBridgeSessionUtils.createRegisterPayload(
 	instanceId: string,
 	context: PluginContext,
 	launchId: string?,
-	playerName: string?
+	playerName: string?,
+	playtestId: string?
 ): { [string]: any }
 	return {
 		pluginVersion = PLUGIN_VERSION,
@@ -123,6 +128,7 @@ function StudioBridgeSessionUtils.createRegisterPayload(
 		context = context,
 		launchId = launchId,
 		playerName = playerName,
+		playtestId = playtestId,
 		placeName = game.Name or "Unknown",
 		placeId = game.PlaceId,
 		gameId = game.GameId,
@@ -143,8 +149,8 @@ end
 --[=[
 	Returns what studio-bridge handed a playtest through its StudioTestService
 	test args: the bridge port, the instance id of the edit session that
-	started it, and whether it is a multiplayer test. Nil when studio-bridge
-	did not start the playtest.
+	started it, whether it is a multiplayer test, and the playtest id. Nil when
+	studio-bridge did not start the playtest.
 ]=]
 function StudioBridgeSessionUtils.getPlaytestArgs(testArgs: any): PlaytestArgs?
 	if
@@ -156,9 +162,29 @@ function StudioBridgeSessionUtils.getPlaytestArgs(testArgs: any): PlaytestArgs?
 			port = testArgs.studioBridgePort,
 			instanceId = testArgs.studioBridgeInstanceId,
 			multiplayer = type(testArgs.studioBridgePlayers) == "number",
+			playtestId = if type(testArgs.studioBridgePlaytestId) == "string"
+				then testArgs.studioBridgePlaytestId
+				else nil,
 		}
 	end
 	return nil
 end
 
+--[=[
+	Returns the bridge planted under `container` for the playtest `playtestId`,
+	or nil. The edit session plants it when Studio does not load user plugins
+	into playtests, and a playtest copies it from the edit DataModel.
+]=]
+function StudioBridgeSessionUtils.findPlantedBridge(container: Instance, playtestId: string?): Instance?
+	if not playtestId then
+		return nil
+	end
+
+	local planted = container:FindFirstChild(PLANTED_BRIDGE_NAME)
+	if planted and planted:GetAttribute(PLAYTEST_ID_ATTRIBUTE) == playtestId then
+		return planted
+	end
+	return nil
+end
+
 return StudioBridgeSessionUtils

package/templates/studio-bridge-plugin/src/Shared/StudioBridgeSessionUtils.spec.lua

@@ -82,12 +82,12 @@ describe("StudioBridgeSessionUtils.getLaunchId()", function()
 end)
 
 describe("StudioBridgeSessionUtils.getPlaytestArgs()", function()
-	it("should read the port and instance id studio-bridge passed in the test args", function()
+	it("should read the port, instance id and playtest id studio-bridge passed in the test args", function()
 		expect(StudioBridgeSessionUtils.getPlaytestArgs({
 			studioBridgePlaytestId = "abc",
 			studioBridgePort = 38741,
 			studioBridgeInstanceId = "test-place-3f9a",
-		})).toEqual({ port = 38741, instanceId = "test-place-3f9a", multiplayer = false })
+		})).toEqual({ port = 38741, instanceId = "test-place-3f9a", multiplayer = false, playtestId = "abc" })
 	end)
 
 	it("should report a multiplayer test", function()
@@ -149,6 +149,12 @@ describe("StudioBridgeSessionUtils.createRegisterPayload()", function()
 		expect(payload.playerName).toEqual("Player2")
 	end)
 
+	it("should carry the playtest id of a playtest studio-bridge started", function()
+		local payload = StudioBridgeSessionUtils.createRegisterPayload("test-place-3f9a", "server", nil, nil, "abc")
+
+		expect(payload.playtestId).toEqual("abc")
+	end)
+
 	it("should hand out a capabilities list the caller can change", function()
 		local payload = StudioBridgeSessionUtils.createRegisterPayload("test-place-3f9a", "edit")
 
@@ -157,3 +163,30 @@ describe("StudioBridgeSessionUtils.createRegisterPayload()", function()
 		expect(table.find(StudioBridgeSessionUtils.CAPABILITIES, "extra")).toBeNil()
 	end)
 end)
+
+describe("StudioBridgeSessionUtils.findPlantedBridge()", function()
+	local function plant(playtestId: string): Folder
+		local container = Instance.new("Folder")
+		local planted = Instance.new("Folder")
+		planted.Name = "StudioBridgePlaytest"
+		planted:SetAttribute("PlaytestId", playtestId)
+		planted.Parent = container
+		return container
+	end
+
+	it("should find the bridge planted for the playtest", function()
+		local container = plant("abc")
+
+		expect(StudioBridgeSessionUtils.findPlantedBridge(container, "abc")).toBe(
+			container:FindFirstChild("StudioBridgePlaytest")
+		)
+	end)
+
+	it("should ignore a bridge planted for another playtest", function()
+		expect(StudioBridgeSessionUtils.findPlantedBridge(plant("old"), "abc")).toBeNil()
+	end)
+
+	it("should find nothing without a playtest id", function()
+		expect(StudioBridgeSessionUtils.findPlantedBridge(plant("abc"), nil)).toBeNil()
+	end)
+end)