@quenty/studio-bridge 0.21.0 → 0.22.0

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

@@ -0,0 +1,239 @@
+--!strict
+--[[
+	@class StudioBridgeConnection.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local HttpService = game:GetService("HttpService")
+
+local ActionRouter = require("ActionRouter")
+local Jest = require("Jest")
+local StudioBridgeConnection = require("StudioBridgeConnection")
+local StudioBridgeLogUtils = require("StudioBridgeLogUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local REGISTER_PAYLOAD = table.freeze({
+	pluginVersion = "test",
+	state = "Edit",
+})
+
+local function createFakeSignal(): any
+	local handlers: { (...any) -> () } = {}
+	return {
+		Connect = function(_self, handler)
+			table.insert(handlers, handler)
+			return {
+				Disconnect = function()
+					local index = table.find(handlers, handler)
+					if index then
+						table.remove(handlers, index)
+					end
+				end,
+			}
+		end,
+		Fire = function(_self, ...)
+			for _, handler in table.clone(handlers) do
+				handler(...)
+			end
+		end,
+		GetHandlerCount = function()
+			return #handlers
+		end,
+	}
+end
+
+local function setup(maxMessageBytes: number?): any
+	local sentData: { string } = {}
+	local webSocket: any = {
+		closeCount = 0,
+		MessageReceived = createFakeSignal(),
+		Closed = createFakeSignal(),
+	}
+
+	function webSocket.Send(_self, data: string)
+		table.insert(sentData, data)
+	end
+
+	function webSocket.Close(self)
+		self.closeCount += 1
+	end
+
+	local router = ActionRouter.new()
+	local connection = StudioBridgeConnection.new({
+		webSocket = webSocket :: any,
+		router = router,
+		sessionId = "session-1",
+		registerPayload = REGISTER_PAYLOAD,
+		maxMessageBytes = maxMessageBytes,
+	})
+
+	local controller = {
+		webSocket = webSocket,
+		router = router,
+		connection = connection,
+		receive = function(message: { [string]: any })
+			webSocket.MessageReceived:Fire(HttpService:JSONEncode(message))
+		end,
+		getSent = function(): { any }
+			local messages = {}
+			for _, data in sentData do
+				table.insert(messages, HttpService:JSONDecode(data))
+			end
+			return messages
+		end,
+		clearSent = function()
+			table.clear(sentData)
+		end,
+		Destroy = function(_self)
+			connection:Destroy()
+		end,
+	}
+
+	return controller
+end
+
+describe("StudioBridgeConnection.new()", function()
+	it("should register, then send a heartbeat", function()
+		local controller = setup()
+
+		local sent = controller.getSent()
+
+		expect(#sent).toEqual(2)
+		expect(sent[1]).toEqual({
+			type = "register",
+			sessionId = "session-1",
+			payload = { pluginVersion = "test", state = "Edit" },
+		})
+		expect(sent[2].type).toEqual("heartbeat")
+		expect(sent[2].sessionId).toEqual("session-1")
+		expect(sent[2].payload.state).toEqual("Edit")
+		expect(sent[2].payload.pendingRequests).toEqual(0)
+		expect(type(sent[2].payload.uptimeMs)).toEqual("number")
+		expect(controller.connection:IsOpen()).toEqual(true)
+
+		controller:Destroy()
+	end)
+end)
+
+describe("StudioBridgeConnection message handling", function()
+	it("should dispatch a message and send back the response", function()
+		local controller = setup()
+		controller.router:register("ping", function(payload)
+			return { echo = payload.value }
+		end)
+		controller.clearSent()
+
+		controller.receive({ type = "ping", sessionId = "session-1", requestId = "req-1", payload = { value = 3 } })
+
+		expect(controller.getSent()).toEqual({
+			{
+				type = "pingResult",
+				sessionId = "session-1",
+				requestId = "req-1",
+				payload = { echo = 3 },
+			},
+		})
+
+		controller:Destroy()
+	end)
+
+	it("should answer a reply over the size limit with RESULT_TOO_LARGE instead", function()
+		local controller = setup(1000)
+		controller.router:register("dump", function()
+			return { data = string.rep("a", 2000) }
+		end)
+		controller.clearSent()
+
+		controller.receive({ type = "dump", sessionId = "session-1", requestId = "req-1", payload = {} })
+
+		local sent = controller.getSent()
+		expect(#sent).toEqual(1)
+		expect(sent[1].type).toEqual("error")
+		expect(sent[1].requestId).toEqual("req-1")
+		expect(sent[1].payload.code).toEqual("RESULT_TOO_LARGE")
+		expect(controller.connection:IsOpen()).toEqual(true)
+
+		controller:Destroy()
+	end)
+
+	it("should send nothing when the handler returns nil", function()
+		local controller = setup()
+		controller.router:register("quiet", function()
+			return nil
+		end)
+		controller.clearSent()
+
+		controller.receive({ type = "quiet", sessionId = "session-1", payload = {} })
+
+		expect(controller.getSent()).toEqual({})
+
+		controller:Destroy()
+	end)
+
+	it("should ignore a message that is not JSON", function()
+		local controller = setup()
+		controller.clearSent()
+
+		controller.webSocket.MessageReceived:Fire("not json")
+
+		expect(controller.getSent()).toEqual({})
+		expect(controller.connection:IsOpen()).toEqual(true)
+
+		controller:Destroy()
+	end)
+
+	it("should close the socket on shutdown and stop sending", function()
+		local controller = setup()
+		controller.clearSent()
+
+		controller.receive({ type = "shutdown", sessionId = "session-1", payload = {} })
+		controller.connection:Send({ type = "late" })
+
+		expect(controller.webSocket.closeCount).toEqual(1)
+		expect(controller.connection:IsOpen()).toEqual(false)
+		expect(controller.getSent()).toEqual({})
+
+		controller:Destroy()
+	end)
+end)
+
+describe("StudioBridgeConnection socket close", function()
+	it("should stop listening once the socket closes", function()
+		local controller = setup()
+
+		controller.webSocket.Closed:Fire()
+
+		expect(controller.connection:IsOpen()).toEqual(false)
+		expect(controller.webSocket.MessageReceived.GetHandlerCount()).toEqual(0)
+		expect(controller.webSocket.Closed.GetHandlerCount()).toEqual(0)
+
+		controller:Destroy()
+	end)
+
+	it("should end verbose logging with the command that asked for it", function()
+		local controller = setup()
+		StudioBridgeLogUtils.setVerbose(true)
+
+		controller.webSocket.Closed:Fire()
+
+		expect(StudioBridgeLogUtils.isVerbose()).toEqual(false)
+
+		controller:Destroy()
+	end)
+end)
+
+describe("StudioBridgeConnection:Destroy()", function()
+	it("should disconnect from the socket without closing it", function()
+		local controller = setup()
+
+		controller:Destroy()
+
+		expect(controller.connection:IsOpen()).toEqual(false)
+		expect(controller.webSocket.closeCount).toEqual(0)
+		expect(controller.webSocket.MessageReceived.GetHandlerCount()).toEqual(0)
+	end)
+end)

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

@@ -0,0 +1,53 @@
+--!strict
+--[=[
+	Plugin output, kept quiet unless the command talking to the plugin ran with
+	--verbose. Real failures warn regardless.
+
+	@class StudioBridgeLogUtils
+]=]
+
+local StudioBridgeLogUtils = {}
+
+--[=[
+	Prefix on every line the plugin writes, so its own output can be told
+	apart from the place's.
+
+	@prop PREFIX string
+	@within StudioBridgeLogUtils
+]=]
+StudioBridgeLogUtils.PREFIX = "[StudioBridge]"
+
+StudioBridgeLogUtils._isVerbose = false
+
+--[=[
+	Sets whether diagnostic output is printed. The bridge sends this with every
+	`syncActions`, so it follows the --verbose flag of the current command.
+]=]
+function StudioBridgeLogUtils.setVerbose(isVerbose: boolean)
+	StudioBridgeLogUtils._isVerbose = isVerbose
+end
+
+--[=[
+	Returns whether diagnostic output is printed.
+]=]
+function StudioBridgeLogUtils.isVerbose(): boolean
+	return StudioBridgeLogUtils._isVerbose
+end
+
+--[=[
+	Prints diagnostic output, only while verbose.
+]=]
+function StudioBridgeLogUtils.logVerbose(message: string)
+	if StudioBridgeLogUtils._isVerbose then
+		print(`{StudioBridgeLogUtils.PREFIX} {message}`)
+	end
+end
+
+--[=[
+	Warns about a real failure, whether or not verbose is on.
+]=]
+function StudioBridgeLogUtils.warn(message: string)
+	warn(`{StudioBridgeLogUtils.PREFIX} {message}`)
+end
+
+return StudioBridgeLogUtils

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

@@ -0,0 +1,27 @@
+--!strict
+--[[
+	@class StudioBridgeLogUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local StudioBridgeLogUtils = require("StudioBridgeLogUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("StudioBridgeLogUtils.setVerbose()", function()
+	it("should start quiet", function()
+		expect(StudioBridgeLogUtils.isVerbose()).toEqual(false)
+	end)
+
+	it("should toggle verbose output", function()
+		StudioBridgeLogUtils.setVerbose(true)
+		expect(StudioBridgeLogUtils.isVerbose()).toEqual(true)
+
+		StudioBridgeLogUtils.setVerbose(false)
+		expect(StudioBridgeLogUtils.isVerbose()).toEqual(false)
+	end)
+end)

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

@@ -0,0 +1,164 @@
+--!strict
+--[=[
+	Identifies this plugin instance to the bridge: which place it is in, which
+	DataModel context it runs in, and what it can do.
+
+	@class StudioBridgeSessionUtils
+]=]
+
+local RunService = game:GetService("RunService")
+
+local PLUGIN_VERSION = "{{PLUGIN_VERSION}}"
+local MAX_SLUG_LENGTH = 24
+local NONCE_VALUE_NAME = "StudioBridgeNonce"
+local LAUNCH_ID_ATTRIBUTE = "StudioBridgeSessionId"
+
+local StudioBridgeSessionUtils = {}
+
+export type PluginContext = "edit" | "client" | "server"
+
+export type PlaytestArgs = {
+	port: number,
+	instanceId: string,
+	multiplayer: boolean,
+}
+
+--[=[
+	Every message type the plugin can handle. Most arrive as action source pushed
+	by the bridge right after registering, but the plugin advertises them up front.
+
+	@prop CAPABILITIES { string }
+	@within StudioBridgeSessionUtils
+]=]
+StudioBridgeSessionUtils.CAPABILITIES = table.freeze({
+	"registerAction",
+	"syncActions",
+	"heartbeat",
+	"execute",
+	"queryState",
+	"captureScreenshot",
+	"queryDataModel",
+	"queryLogs",
+	"exportInstances",
+	"importInstances",
+	"findInstances",
+	"grepScripts",
+	"startPlaytest",
+	"endPlaytest",
+})
+
+--[=[
+	Returns the DataModel context this plugin instance runs in.
+]=]
+function StudioBridgeSessionUtils.getContext(): PluginContext
+	if not RunService:IsRunning() then
+		return "edit"
+	elseif RunService:IsClient() then
+		return "client"
+	else
+		return "server"
+	end
+end
+
+function StudioBridgeSessionUtils._slugify(text: string, fallback: string): string
+	local slug = string.lower(text)
+	slug = string.gsub(slug, "[^%w]+", "-")
+	slug = string.gsub(slug, "^%-+", "")
+	slug = string.sub(slug, 1, MAX_SLUG_LENGTH)
+	slug = string.gsub(slug, "%-+$", "")
+	return if slug == "" then fallback else slug
+end
+
+--[=[
+	Returns a short, readable id for the open place: its name as a slug plus
+	`nonce`, which tells apart two Studios with the same place open.
+]=]
+function StudioBridgeSessionUtils.getInstanceId(placeName: string?, nonce: string): string
+	local name = string.gsub(placeName or "", "%.rbxl[x]?$", "")
+	return `{StudioBridgeSessionUtils._slugify(name, "place")}-{nonce}`
+end
+
+--[=[
+	Returns the nonce stored under `container`, creating it on first use. The
+	value is not archivable, so it lasts as long as the DataModel: plugin reloads
+	keep their session id, and a fresh Studio gets a new one.
+]=]
+function StudioBridgeSessionUtils.getOrCreateNonce(container: Instance, createNonce: () -> string): string
+	local existing = container:FindFirstChild(NONCE_VALUE_NAME)
+	if existing and existing:IsA("StringValue") and existing.Value ~= "" then
+		return existing.Value
+	end
+
+	local value = Instance.new("StringValue")
+	value.Name = NONCE_VALUE_NAME
+	value.Archivable = false
+	value.Value = createNonce()
+	value.Parent = container
+	return value.Value
+end
+
+--[=[
+	Returns the session id for an instance id and context. The clients of a
+	multiplayer test share both, so they add their player's name.
+]=]
+function StudioBridgeSessionUtils.getSessionId(instanceId: string, context: PluginContext, playerName: string?): string
+	if playerName then
+		return `{instanceId}-{context}-{StudioBridgeSessionUtils._slugify(playerName, "player")}`
+	end
+	return `{instanceId}-{context}`
+end
+
+--[=[
+	Returns the payload of the `register` message the plugin sends on connect.
+]=]
+function StudioBridgeSessionUtils.createRegisterPayload(
+	instanceId: string,
+	context: PluginContext,
+	launchId: string?,
+	playerName: string?
+): { [string]: any }
+	return {
+		pluginVersion = PLUGIN_VERSION,
+		instanceId = instanceId,
+		context = context,
+		launchId = launchId,
+		playerName = playerName,
+		placeName = game.Name or "Unknown",
+		placeId = game.PlaceId,
+		gameId = game.GameId,
+		state = "Edit",
+		capabilities = table.clone(StudioBridgeSessionUtils.CAPABILITIES),
+	}
+end
+
+--[=[
+	Returns the launch id `process run` stamped onto the place it launched
+	Studio with, or nil for a place the user opened.
+]=]
+function StudioBridgeSessionUtils.getLaunchId(workspace: Instance): string?
+	local launchId = workspace:GetAttribute(LAUNCH_ID_ATTRIBUTE)
+	return if type(launchId) == "string" then launchId else nil
+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.
+]=]
+function StudioBridgeSessionUtils.getPlaytestArgs(testArgs: any): PlaytestArgs?
+	if
+		type(testArgs) == "table"
+		and type(testArgs.studioBridgePort) == "number"
+		and type(testArgs.studioBridgeInstanceId) == "string"
+	then
+		return {
+			port = testArgs.studioBridgePort,
+			instanceId = testArgs.studioBridgeInstanceId,
+			multiplayer = type(testArgs.studioBridgePlayers) == "number",
+		}
+	end
+	return nil
+end
+
+return StudioBridgeSessionUtils

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

@@ -0,0 +1,159 @@
+--!strict
+--[[
+	@class StudioBridgeSessionUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local StudioBridgeSessionUtils = require("StudioBridgeSessionUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("StudioBridgeSessionUtils.getInstanceId()", function()
+	it("should slug the place name and append the nonce", function()
+		expect(StudioBridgeSessionUtils.getInstanceId("My Cool  Place!", "3f9a")).toEqual("my-cool-place-3f9a")
+	end)
+
+	it("should drop a place file extension", function()
+		expect(StudioBridgeSessionUtils.getInstanceId("test-place.rbxl", "3f9a")).toEqual("test-place-3f9a")
+		expect(StudioBridgeSessionUtils.getInstanceId("Map.rbxlx", "3f9a")).toEqual("map-3f9a")
+	end)
+
+	it("should keep long names short", function()
+		expect(StudioBridgeSessionUtils.getInstanceId("An Extremely Long Place Name For Testing", "3f9a")).toEqual(
+			"an-extremely-long-place-3f9a"
+		)
+	end)
+
+	it("should fall back to place when the name has nothing usable", function()
+		expect(StudioBridgeSessionUtils.getInstanceId("!!!", "3f9a")).toEqual("place-3f9a")
+		expect(StudioBridgeSessionUtils.getInstanceId(nil, "3f9a")).toEqual("place-3f9a")
+	end)
+end)
+
+describe("StudioBridgeSessionUtils.getOrCreateNonce()", function()
+	it("should keep the first nonce for later calls", function()
+		local container = Instance.new("Folder")
+		local count = 0
+		local function createNonce(): string
+			count += 1
+			return "nonce" .. tostring(count)
+		end
+
+		expect(StudioBridgeSessionUtils.getOrCreateNonce(container, createNonce)).toEqual("nonce1")
+		expect(StudioBridgeSessionUtils.getOrCreateNonce(container, createNonce)).toEqual("nonce1")
+
+		container:Destroy()
+	end)
+
+	it("should not save the nonce with the place", function()
+		local container = Instance.new("Folder")
+
+		StudioBridgeSessionUtils.getOrCreateNonce(container, function()
+			return "3f9a"
+		end)
+
+		expect((container:FindFirstChild("StudioBridgeNonce") :: Instance).Archivable).toEqual(false)
+
+		container:Destroy()
+	end)
+end)
+
+describe("StudioBridgeSessionUtils.getLaunchId()", function()
+	it("should read the launch id stamped onto the workspace", function()
+		local container = Instance.new("Folder")
+		container:SetAttribute("StudioBridgeSessionId", "launch-1")
+
+		expect(StudioBridgeSessionUtils.getLaunchId(container)).toEqual("launch-1")
+
+		container:Destroy()
+	end)
+
+	it("should be nil for a place the user opened", function()
+		local container = Instance.new("Folder")
+
+		expect(StudioBridgeSessionUtils.getLaunchId(container)).toBeNil()
+
+		container:Destroy()
+	end)
+end)
+
+describe("StudioBridgeSessionUtils.getPlaytestArgs()", function()
+	it("should read the port and instance 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 })
+	end)
+
+	it("should report a multiplayer test", function()
+		local args = StudioBridgeSessionUtils.getPlaytestArgs({
+			studioBridgePort = 38741,
+			studioBridgeInstanceId = "test-place-3f9a",
+			studioBridgePlayers = 2,
+		})
+
+		expect(args and args.multiplayer).toEqual(true)
+	end)
+
+	it("should return nil for a playtest studio-bridge did not start", function()
+		expect(StudioBridgeSessionUtils.getPlaytestArgs(nil)).toBeNil()
+		expect(StudioBridgeSessionUtils.getPlaytestArgs({ custom = true })).toBeNil()
+	end)
+end)
+
+describe("StudioBridgeSessionUtils.getSessionId()", function()
+	it("should append the context to the instance id", function()
+		expect(StudioBridgeSessionUtils.getSessionId("test-place-3f9a", "edit")).toEqual("test-place-3f9a-edit")
+	end)
+
+	it("should append the player of a multiplayer client", function()
+		expect(StudioBridgeSessionUtils.getSessionId("test-place-3f9a", "client", "Player2")).toEqual(
+			"test-place-3f9a-client-player2"
+		)
+	end)
+end)
+
+describe("StudioBridgeSessionUtils.getContext()", function()
+	it("should be edit when the game is not running", function()
+		expect(StudioBridgeSessionUtils.getContext()).toEqual("edit")
+	end)
+end)
+
+describe("StudioBridgeSessionUtils.createRegisterPayload()", function()
+	it("should describe the plugin and the open place", function()
+		local payload = StudioBridgeSessionUtils.createRegisterPayload("test-place-3f9a", "edit")
+
+		expect(payload.instanceId).toEqual("test-place-3f9a")
+		expect(payload.context).toEqual("edit")
+		expect(payload.state).toEqual("Edit")
+		expect(payload.placeId).toEqual(game.PlaceId)
+		expect(payload.gameId).toEqual(game.GameId)
+		expect(type(payload.pluginVersion)).toEqual("string")
+		expect(payload.capabilities).toEqual(StudioBridgeSessionUtils.CAPABILITIES)
+	end)
+
+	it("should carry the launch id of a Studio that process run launched", function()
+		local payload = StudioBridgeSessionUtils.createRegisterPayload("test-place-3f9a", "edit", "launch-1")
+
+		expect(payload.launchId).toEqual("launch-1")
+	end)
+
+	it("should carry the player of a multiplayer client", function()
+		local payload = StudioBridgeSessionUtils.createRegisterPayload("test-place-3f9a", "client", nil, "Player2")
+
+		expect(payload.playerName).toEqual("Player2")
+	end)
+
+	it("should hand out a capabilities list the caller can change", function()
+		local payload = StudioBridgeSessionUtils.createRegisterPayload("test-place-3f9a", "edit")
+
+		table.insert(payload.capabilities, "extra")
+
+		expect(table.find(StudioBridgeSessionUtils.CAPABILITIES, "extra")).toBeNil()
+	end)
+end)