@quenty/studio-bridge 0.21.1 → 0.22.1

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

@@ -0,0 +1,418 @@
+--!strict
+--[[
+	@class ActionRouter.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local ActionRouter = require("ActionRouter")
+local Jest = require("Jest")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function createMessage(messageType: string, payload: { [string]: any }?, requestId: string?): ActionRouter.Message
+	return {
+		type = messageType,
+		sessionId = "session-1",
+		payload = payload or {},
+		requestId = requestId,
+	}
+end
+
+describe("ActionRouter:Dispatch()", function()
+	it("should answer an unknown message type with UNKNOWN_REQUEST", function()
+		local router = ActionRouter.new()
+
+		local response = router:Dispatch(createMessage("nope", nil, "req-1"))
+
+		expect(response).toEqual({
+			type = "error",
+			sessionId = "session-1",
+			requestId = "req-1",
+			payload = {
+				code = "UNKNOWN_REQUEST",
+				message = "Unknown message type: nope",
+			},
+		})
+	end)
+
+	it("should wrap a handler's return as <type>Result", function()
+		local router = ActionRouter.new()
+		router:register("ping", function(payload)
+			return { echo = payload.value }
+		end)
+
+		local response = router:Dispatch(createMessage("ping", { value = 5 }, "req-2"))
+
+		expect(response).toEqual({
+			type = "pingResult",
+			sessionId = "session-1",
+			requestId = "req-2",
+			payload = { echo = 5 },
+		})
+	end)
+
+	it("should use the response type set for the message type", function()
+		local router = ActionRouter.new()
+		router:register("ping", function()
+			return {}
+		end)
+		router:setResponseType("ping", "pong")
+
+		local response = router:Dispatch(createMessage("ping"))
+
+		expect(response and response.type).toEqual("pong")
+	end)
+
+	it("should pass the payload, requestId, and sessionId to the handler", function()
+		local router = ActionRouter.new()
+		local received = {}
+		router:register("ping", function(payload, requestId, sessionId)
+			received = { payload = payload, requestId = requestId, sessionId = sessionId }
+			return nil
+		end)
+
+		router:Dispatch(createMessage("ping", { value = 1 }, "req-3"))
+
+		expect(received).toEqual({ payload = { value = 1 }, requestId = "req-3", sessionId = "session-1" })
+	end)
+
+	it("should pass an empty requestId when the message has none", function()
+		local router = ActionRouter.new()
+		local receivedRequestId = nil
+		router:register("ping", function(_payload, requestId)
+			receivedRequestId = requestId
+			return nil
+		end)
+
+		router:Dispatch(createMessage("ping"))
+
+		expect(receivedRequestId).toEqual("")
+	end)
+
+	it("should send nothing when the handler returns nil", function()
+		local router = ActionRouter.new()
+		router:register("ping", function()
+			return nil
+		end)
+
+		expect(router:Dispatch(createMessage("ping"))).toBeNil()
+	end)
+
+	it("should answer a handler's failure as an error with its code", function()
+		local router = ActionRouter.new()
+		router:register("ping", function()
+			return { success = false, code = "INSTANCE_NOT_FOUND", message = "Instance not found" }
+		end)
+
+		local response = router:Dispatch(createMessage("ping", nil, "req-5"))
+
+		expect(response).toEqual({
+			type = "error",
+			sessionId = "session-1",
+			requestId = "req-5",
+			payload = {
+				code = "INSTANCE_NOT_FOUND",
+				message = "Instance not found",
+			},
+		})
+	end)
+
+	it("should answer a throwing handler with INTERNAL_ERROR", function()
+		local router = ActionRouter.new()
+		router:register("ping", function()
+			error("boom")
+		end)
+
+		local response = router:Dispatch(createMessage("ping", nil, "req-4"))
+
+		expect(response and response.type).toEqual("error")
+		expect(response and response.requestId).toEqual("req-4")
+		expect(response and response.payload.code).toEqual("INTERNAL_ERROR")
+		expect(response and response.payload.message).toContain("boom")
+	end)
+end)
+
+describe("ActionRouter:RegisterAction()", function()
+	it("should install a module through its register function", function()
+		local router = ActionRouter.new()
+
+		local ok, err = router:RegisterAction(
+			"greet",
+			[[
+				return {
+					register = function(router)
+						router:register("greet", function(payload)
+							return { greeting = "hi " .. payload.name }
+						end)
+					end,
+				}
+			]],
+			nil,
+			nil,
+			nil,
+			"hash-1"
+		)
+
+		expect(ok).toEqual(true)
+		expect(err).toBeNil()
+
+		local response = router:Dispatch(createMessage("greet", { name = "bob" }))
+		expect(response and response.payload).toEqual({ greeting = "hi bob" })
+	end)
+
+	it("should hand sendMessage and logBuffer to the module's register", function()
+		local router = ActionRouter.new()
+		local sendMessage = function() end
+		local logBuffer = {}
+		local received: { [string]: any } = {}
+		router:register("capture", function(payload)
+			received = payload
+			return nil
+		end)
+
+		router:RegisterAction(
+			"probe",
+			[[
+				return {
+					register = function(router, sendMessage, logBuffer)
+						router:Dispatch({
+							type = "capture",
+							sessionId = "s",
+							payload = { sendMessage = sendMessage, logBuffer = logBuffer },
+						})
+					end,
+				}
+			]],
+			sendMessage,
+			logBuffer
+		)
+
+		expect(received.sendMessage).toBe(sendMessage)
+		expect(received.logBuffer).toBe(logBuffer)
+	end)
+
+	it("should register a bare function under the action name", function()
+		local router = ActionRouter.new()
+
+		local ok = router:RegisterAction("double", "return function(payload) return { value = payload.value * 2 } end")
+
+		expect(ok).toEqual(true)
+
+		local response = router:Dispatch(createMessage("double", { value = 21 }))
+		expect(response and response.payload).toEqual({ value = 42 })
+	end)
+
+	it("should apply the response type override", function()
+		local router = ActionRouter.new()
+
+		router:RegisterAction("double", "return function() return {} end", nil, nil, "doubled")
+
+		local response = router:Dispatch(createMessage("double"))
+		expect(response and response.type).toEqual("doubled")
+	end)
+
+	it("should fail on source that does not compile", function()
+		local router = ActionRouter.new()
+
+		local ok, err = router:RegisterAction("broken", "return {")
+
+		expect(ok).toEqual(false)
+		expect(err).toContain("Failed to load action source")
+	end)
+
+	it("should fail on a module that throws while loading", function()
+		local router = ActionRouter.new()
+
+		local ok, err = router:RegisterAction("broken", "error('load boom')")
+
+		expect(ok).toEqual(false)
+		expect(err).toContain("Failed to execute action module")
+	end)
+
+	it("should fail on a module whose register throws", function()
+		local router = ActionRouter.new()
+
+		local ok, err = router:RegisterAction("broken", "return { register = function() error('register boom') end }")
+
+		expect(ok).toEqual(false)
+		expect(err).toContain("register() failed")
+	end)
+
+	it("should fail on a module that returns neither a table nor a function", function()
+		local router = ActionRouter.new()
+
+		local ok, err = router:RegisterAction("broken", "return 5")
+
+		expect(ok).toEqual(false)
+		expect(err).toContain("must return a table")
+	end)
+
+	it("should skip reloading when the same hash is installed", function()
+		local router = ActionRouter.new()
+		router:RegisterAction("counter", "return function() return { version = 1 } end", nil, nil, nil, "hash-1")
+
+		local ok =
+			router:RegisterAction("counter", "return function() return { version = 2 } end", nil, nil, nil, "hash-1")
+
+		expect(ok).toEqual(true)
+
+		local response = router:Dispatch(createMessage("counter"))
+		expect(response and response.payload).toEqual({ version = 1 })
+	end)
+
+	it("should replace the action and tear the old module down on a new hash", function()
+		local router = ActionRouter.new()
+		local tornDown = {}
+		router:register("recordTeardown", function(payload)
+			table.insert(tornDown, payload.name)
+			return nil
+		end)
+
+		router:RegisterAction(
+			"multi",
+			[[
+				local router
+				return {
+					register = function(r)
+						router = r
+						r:register("multiA", function() return { version = 1 } end)
+						r:register("multiB", function() return { version = 1 } end)
+					end,
+					teardown = function()
+						router:Dispatch({ type = "recordTeardown", sessionId = "s", payload = { name = "v1" } })
+					end,
+				}
+			]],
+			nil,
+			nil,
+			nil,
+			"hash-1"
+		)
+
+		router:RegisterAction(
+			"multi",
+			[[
+				return {
+					register = function(r)
+						r:register("multiA", function() return { version = 2 } end)
+					end,
+				}
+			]],
+			nil,
+			nil,
+			nil,
+			"hash-2"
+		)
+
+		expect(tornDown).toEqual({ "v1" })
+
+		local responseA = router:Dispatch(createMessage("multiA"))
+		local responseB = router:Dispatch(createMessage("multiB"))
+		expect(responseA and responseA.payload).toEqual({ version = 2 })
+		expect(responseB and responseB.payload.code).toEqual("UNKNOWN_REQUEST")
+	end)
+end)
+
+describe("ActionRouter:Compile()", function()
+	it("should compile source into a callable function", function()
+		local router = ActionRouter.new()
+
+		local fn = router:Compile("return 1 + 2")
+
+		expect(fn()).toEqual(3)
+	end)
+
+	it("should return the compile error for invalid source", function()
+		local router = ActionRouter.new()
+
+		local fn, err = router:Compile("local x = = 1", "=test")
+
+		expect(fn).toBeNil()
+		expect(err).toEqual(expect.stringContaining("Expected identifier"))
+	end)
+end)
+
+describe("ActionRouter:Destroy()", function()
+	it("should tear down every action and drop all handlers", function()
+		local router = ActionRouter.new()
+		local tornDown = {}
+		router:register("recordTeardown", function(payload)
+			table.insert(tornDown, payload.name)
+			return nil
+		end)
+
+		router:RegisterAction(
+			"action",
+			[[
+				local router
+				return {
+					register = function(r)
+						router = r
+						r:register("actionA", function() return {} end)
+					end,
+					teardown = function()
+						router:Dispatch({ type = "recordTeardown", sessionId = "s", payload = { name = "action" } })
+					end,
+				}
+			]],
+			nil,
+			nil,
+			nil,
+			"hash-1"
+		)
+
+		router:Destroy()
+
+		expect(tornDown).toEqual({ "action" })
+		expect(router:GetInstalledActions()).toEqual({})
+		local response = router:Dispatch(createMessage("actionA"))
+		expect(response and response.payload.code).toEqual("UNKNOWN_REQUEST")
+	end)
+end)
+
+describe("ActionRouter:GetInstalledActions()", function()
+	it("should map each hashed action to its hash", function()
+		local router = ActionRouter.new()
+		router:RegisterAction("a", "return function() return {} end", nil, nil, nil, "hash-a")
+		router:RegisterAction("b", "return function() return {} end", nil, nil, nil, "hash-b")
+		router:RegisterAction("unhashed", "return function() return {} end")
+
+		expect(router:GetInstalledActions()).toEqual({ a = "hash-a", b = "hash-b" })
+	end)
+end)
+
+describe("ActionRouter:GetActionHandlerNames()", function()
+	it("should list the handlers an action registered", function()
+		local router = ActionRouter.new()
+		router:RegisterAction(
+			"multi",
+			[[
+				return {
+					register = function(r)
+						r:register("multiA", function() return {} end)
+						r:register("multiB", function() return {} end)
+					end,
+				}
+			]],
+			nil,
+			nil,
+			nil,
+			"hash-1"
+		)
+
+		local handlerNames = router:GetActionHandlerNames("multi")
+		assert(handlerNames, "No handler names")
+		table.sort(handlerNames)
+
+		expect(handlerNames).toEqual({ "multiA", "multiB" })
+	end)
+
+	it("should return nil for an action that is not installed", function()
+		local router = ActionRouter.new()
+
+		expect(router:GetActionHandlerNames("missing")).toBeNil()
+	end)
+end)

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

@@ -0,0 +1,94 @@
+--!strict
+--[=[
+	The two handlers the plugin ships with. Everything else is pushed by the
+	bridge over the wire through them.
+
+	- `registerAction` installs action source, skipping it when the same content
+	  hash is already installed.
+	- `syncActions` reports which actions the bridge needs to push, by comparing
+	  its content hashes against the installed ones.
+
+	@class BuiltInActions
+]=]
+
+local StudioBridgeLogUtils = require(script.Parent.StudioBridgeLogUtils)
+
+local BuiltInActions = {}
+
+type ActionRouter = any
+
+--[=[
+	Registers both built-in handlers. `sendMessage` and `logBuffer` are handed on
+	to every action installed through `registerAction`.
+]=]
+function BuiltInActions.register(router: ActionRouter, sendMessage: (message: { [string]: any }) -> (), logBuffer: any)
+	router:register("registerAction", function(payload)
+		return BuiltInActions._registerAction(router, payload, sendMessage, logBuffer)
+	end)
+	router:setResponseType("registerAction", "registerActionResult")
+
+	router:register("syncActions", function(payload)
+		return BuiltInActions._syncActions(router, payload)
+	end)
+	router:setResponseType("syncActions", "syncActionsResult")
+end
+
+function BuiltInActions._registerAction(
+	router: ActionRouter,
+	payload: { [string]: any },
+	sendMessage: (message: { [string]: any }) -> (),
+	logBuffer: any
+): { [string]: any }
+	local name = payload.name
+	local source = payload.source
+	local hash = if type(payload.hash) == "string" then payload.hash else nil
+
+	if type(name) ~= "string" or type(source) ~= "string" then
+		return {
+			name = if type(name) == "string" then name else "unknown",
+			success = false,
+			error = "Invalid registerAction payload: name and source are required strings",
+		}
+	end
+
+	if hash and router:GetInstalledActions()[name] == hash then
+		return {
+			name = name,
+			success = true,
+			skipped = true,
+			hash = hash,
+			handlers = router:GetActionHandlerNames(name),
+		}
+	end
+
+	local success, err = router:RegisterAction(name, source, sendMessage, logBuffer, payload.responseType, hash)
+
+	return {
+		name = name,
+		success = success,
+		skipped = false,
+		hash = hash,
+		handlers = success and router:GetActionHandlerNames(name) or {},
+		error = err,
+	}
+end
+
+function BuiltInActions._syncActions(router: ActionRouter, payload: { [string]: any }): { [string]: any }
+	StudioBridgeLogUtils.setVerbose(payload.verbose == true)
+
+	local installed = router:GetInstalledActions()
+
+	local needed: { string } = {}
+	for name, bridgeHash in payload.actions or {} do
+		if installed[name] ~= bridgeHash then
+			table.insert(needed, name)
+		end
+	end
+
+	return {
+		needed = needed,
+		installed = installed,
+	}
+end
+
+return BuiltInActions

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

@@ -0,0 +1,166 @@
+--!strict
+--[[
+	@class BuiltInActions.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local ActionRouter = require("ActionRouter")
+local BuiltInActions = require("BuiltInActions")
+local Jest = require("Jest")
+local StudioBridgeLogUtils = require("StudioBridgeLogUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local ECHO_SOURCE = "return function(payload) return { echo = payload.value } end"
+
+local function setup(): any
+	local controller = {
+		router = ActionRouter.new(),
+		sent = {},
+		logBuffer = {},
+	}
+
+	BuiltInActions.register(controller.router, function(message)
+		table.insert(controller.sent, message)
+	end, controller.logBuffer)
+
+	function controller.dispatch(messageType: string, payload: { [string]: any }): ActionRouter.Message?
+		return controller.router:Dispatch({
+			type = messageType,
+			sessionId = "session-1",
+			payload = payload,
+			requestId = "req-1",
+		})
+	end
+
+	return controller
+end
+
+describe("registerAction", function()
+	it("should install the action and answer registerActionResult", function()
+		local controller = setup()
+
+		local response = controller.dispatch("registerAction", { name = "echo", source = ECHO_SOURCE, hash = "hash-1" })
+
+		expect(response and response.type).toEqual("registerActionResult")
+		expect(response and response.payload).toEqual({
+			name = "echo",
+			success = true,
+			skipped = false,
+			hash = "hash-1",
+			handlers = { "echo" },
+		})
+
+		local echoResponse = controller.dispatch("echo", { value = 7 })
+		expect(echoResponse and echoResponse.payload).toEqual({ echo = 7 })
+	end)
+
+	it("should skip an action already installed with the same hash", function()
+		local controller = setup()
+		controller.dispatch("registerAction", { name = "echo", source = ECHO_SOURCE, hash = "hash-1" })
+
+		local response =
+			controller.dispatch("registerAction", { name = "echo", source = "error('unused')", hash = "hash-1" })
+
+		expect(response and response.payload).toEqual({
+			name = "echo",
+			success = true,
+			skipped = true,
+			hash = "hash-1",
+			handlers = { "echo" },
+		})
+	end)
+
+	it("should hand its sendMessage and logBuffer to installed actions", function()
+		local controller = setup()
+
+		controller.dispatch("registerAction", {
+			name = "probe",
+			source = [[
+				return {
+					register = function(router, sendMessage, logBuffer)
+						sendMessage({ type = "probe", sawLogBuffer = logBuffer ~= nil })
+					end,
+				}
+			]],
+		})
+
+		expect(controller.sent).toEqual({ { type = "probe", sawLogBuffer = true } })
+	end)
+
+	it("should apply the requested response type", function()
+		local controller = setup()
+		controller.dispatch("registerAction", { name = "echo", source = ECHO_SOURCE, responseType = "echoed" })
+
+		local response = controller.dispatch("echo", { value = 1 })
+
+		expect(response and response.type).toEqual("echoed")
+	end)
+
+	it("should report a failed install", function()
+		local controller = setup()
+
+		local response =
+			controller.dispatch("registerAction", { name = "broken", source = "return {", hash = "hash-1" })
+
+		expect(response and response.payload.success).toEqual(false)
+		expect(response and response.payload.handlers).toEqual({})
+		expect(response and response.payload.error).toContain("Failed to load action source")
+	end)
+
+	it("should reject a payload without a name and source", function()
+		local controller = setup()
+
+		local response = controller.dispatch("registerAction", { name = "nosource" })
+
+		expect(response and response.payload).toEqual({
+			name = "nosource",
+			success = false,
+			error = "Invalid registerAction payload: name and source are required strings",
+		})
+	end)
+end)
+
+describe("syncActions", function()
+	it("should list the actions that are missing or out of date", function()
+		local controller = setup()
+		controller.dispatch("registerAction", { name = "current", source = ECHO_SOURCE, hash = "hash-current" })
+		controller.dispatch("registerAction", { name = "stale", source = ECHO_SOURCE, hash = "hash-old" })
+
+		local response = controller.dispatch("syncActions", {
+			actions = {
+				current = "hash-current",
+				stale = "hash-new",
+				missing = "hash-missing",
+			},
+		})
+
+		assert(response, "No response")
+		table.sort(response.payload.needed)
+
+		expect(response.type).toEqual("syncActionsResult")
+		expect(response.payload.needed).toEqual({ "missing", "stale" })
+		expect(response.payload.installed).toEqual({ current = "hash-current", stale = "hash-old" })
+	end)
+
+	it("should need nothing when sent no actions", function()
+		local controller = setup()
+
+		local response = controller.dispatch("syncActions", {})
+
+		expect(response and response.payload).toEqual({ needed = {}, installed = {} })
+	end)
+
+	it("should follow the bridge's verbose flag for plugin logging", function()
+		local controller = setup()
+
+		controller.dispatch("syncActions", { verbose = true })
+		expect(StudioBridgeLogUtils.isVerbose()).toEqual(true)
+
+		controller.dispatch("syncActions", {})
+		expect(StudioBridgeLogUtils.isVerbose()).toEqual(false)
+	end)
+end)