@quenty/studio-bridge 0.21.1 → 0.22.0

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

@@ -1,203 +1,184 @@
---[[
-	Pure state machine for plugin discovery and connection lifecycle.
+--!strict
+--[=[
+	State machine for finding a studio-bridge server and holding the connection
+	to it. Moves through `idle`, `searching`, `connecting` and `connected`.
 
-	Manages the states: idle, searching, connecting, connected.
-	All external I/O is performed via injected callbacks.
+	All I/O goes through the injected callbacks. The caller drives it by calling
+	[DiscoveryStateMachine.PollAsync] in a loop, passing how much of the loop's
+	time budget is left so scanning never overruns it.
 
-	The caller drives the loop by calling pollAsync(remainingExecTimeSec)
-	repeatedly. The remaining execution time threads through all async
-	operations so the entire poll cycle completes within a predictable
-	time budget.
-]]
+	@class DiscoveryStateMachine
+]=]
+
+local DEFAULT_PORT_MIN = 38741
+local DEFAULT_PORT_MAX = 38744
+local DEFAULT_POLL_INTERVAL_SEC = 2
+local DEFAULT_TIME_AVAILABLE_SEC = 10
 
 local DiscoveryStateMachine = {}
+DiscoveryStateMachine.ClassName = "DiscoveryStateMachine"
 DiscoveryStateMachine.__index = DiscoveryStateMachine
 
--- ---------------------------------------------------------------------------
--- Default configuration
--- ---------------------------------------------------------------------------
+export type DiscoveryState = "idle" | "searching" | "connecting" | "connected"
 
-local DEFAULT_CONFIG = {
-	portRange = { min = 38741, max = 38744 },
-	pollIntervalSec = 2,
+export type DiscoveryConfig = {
+	portRange: { min: number?, max: number? }?,
+	pollIntervalSec: number?,
 }
 
--- ---------------------------------------------------------------------------
--- Constructor
--- ---------------------------------------------------------------------------
-
-function DiscoveryStateMachine.new(
-	config: {
-		portRange: { min: number, max: number }?,
-		pollIntervalSec: number?,
-	}?,
-	callbacks: {
-		scanPortsAsync: (ports: { number }, timeoutSec: number) -> (number?, string?),
-		connectWebSocket: (url: string) -> (boolean, any?),
-		onStateChange: (oldState: string, newState: string) -> (),
-		onConnected: (connection: any, port: number) -> (),
-		onDisconnected: (reason: string?) -> (),
-	}
-)
-	local resolvedConfig = {}
-	local userConfig = config or {}
-	for key, default in DEFAULT_CONFIG do
-		if key == "portRange" then
-			local userRange = (userConfig :: any).portRange
-			if userRange then
-				resolvedConfig.portRange = {
-					min = userRange.min or default.min,
-					max = userRange.max or default.max,
-				}
-			else
-				resolvedConfig.portRange = { min = default.min, max = default.max }
-			end
-		else
-			resolvedConfig[key] = (userConfig :: any)[key] or default
-		end
-	end
+export type DiscoveryCallbacks = {
+	scanPortsAsync: (ports: { number }, timeoutSec: number) -> (number?, string?),
+	connectWebSocket: (url: string) -> (boolean, any?),
+	onStateChange: (oldState: DiscoveryState, newState: DiscoveryState) -> (),
+	onConnected: (connection: any, port: number) -> (),
+	onDisconnected: (reason: string?) -> (),
+}
 
-	local self = setmetatable({
-		_config = resolvedConfig,
-		_callbacks = callbacks,
-		_state = "idle" :: string,
-		_nextPollAt = 0, -- os.clock() time for next scan
-		_connection = nil :: any?,
-	}, DiscoveryStateMachine)
+export type DiscoveryStateMachine = typeof(setmetatable(
+	{} :: {
+		_portMin: number,
+		_portMax: number,
+		_pollIntervalSec: number,
+		_callbacks: DiscoveryCallbacks,
+		_state: DiscoveryState,
+		_nextPollAt: number,
+		_connection: any?,
+	},
+	{} :: typeof({ __index = DiscoveryStateMachine })
+))
+
+--[=[
+	Constructs a state machine in the `idle` state. Scans ports 38741-38744 every
+	2 seconds unless `config` says otherwise.
+]=]
+function DiscoveryStateMachine.new(config: DiscoveryConfig?, callbacks: DiscoveryCallbacks): DiscoveryStateMachine
+	local self: DiscoveryStateMachine = setmetatable({} :: any, DiscoveryStateMachine)
+
+	local portRange = config and config.portRange
+	self._portMin = portRange and portRange.min or DEFAULT_PORT_MIN
+	self._portMax = portRange and portRange.max or DEFAULT_PORT_MAX
+	self._pollIntervalSec = config and config.pollIntervalSec or DEFAULT_POLL_INTERVAL_SEC
+
+	self._callbacks = assert(callbacks, "No callbacks")
+	self._state = "idle"
+	self._nextPollAt = 0
+	self._connection = nil
 
 	return self
 end
 
--- ---------------------------------------------------------------------------
--- State accessors
--- ---------------------------------------------------------------------------
-
-function DiscoveryStateMachine.getState(self: any): string
+--[=[
+	Returns the current state.
+]=]
+function DiscoveryStateMachine.GetState(self: DiscoveryStateMachine): DiscoveryState
 	return self._state
 end
 
--- ---------------------------------------------------------------------------
--- Internal state transition
--- ---------------------------------------------------------------------------
-
-function DiscoveryStateMachine._transitionTo(self: any, newState: string)
-	local oldState = self._state
-	if oldState == newState then
-		return
-	end
-	self._state = newState
-	self._callbacks.onStateChange(oldState, newState)
-end
-
--- ---------------------------------------------------------------------------
--- Public methods
--- ---------------------------------------------------------------------------
-
-function DiscoveryStateMachine.start(self: any)
+--[=[
+	Starts searching. Does nothing unless idle.
+]=]
+function DiscoveryStateMachine.Start(self: DiscoveryStateMachine)
 	if self._state ~= "idle" then
 		return
 	end
+
 	self._nextPollAt = 0
 	self:_transitionTo("searching")
 end
 
-function DiscoveryStateMachine.stop(self: any)
+--[=[
+	Returns to idle, reporting a `"stopped"` disconnect if a connection was held.
+]=]
+function DiscoveryStateMachine.Stop(self: DiscoveryStateMachine)
 	if self._state == "idle" then
 		return
 	end
+
 	local wasConnected = self._state == "connected"
 	self._connection = nil
 	self._nextPollAt = 0
 	self:_transitionTo("idle")
+
 	if wasConnected then
 		self._callbacks.onDisconnected("stopped")
 	end
 end
 
-function DiscoveryStateMachine.onDisconnect(self: any, reason: string?)
+--[=[
+	Reports that the held connection dropped, and resumes searching right away.
+]=]
+function DiscoveryStateMachine.HandleDisconnect(self: DiscoveryStateMachine, reason: string?)
 	if self._state ~= "connected" then
 		return
 	end
+
 	self._connection = nil
 	self._nextPollAt = 0
 	self._callbacks.onDisconnected(reason)
 	self:_transitionTo("searching")
 end
 
---[[
-	Run one poll cycle. remainingExecTimeSec is the number of seconds this
-	call is allowed to spend on async work (port scanning, connecting).
-	The caller subtracts elapsed time before each call so the entire loop
-	iteration stays within its time budget.
-
-	Returns immediately if not time to scan yet, or if in idle/connected state.
-	May yield during port scanning and WebSocket connection.
-]]
-function DiscoveryStateMachine.pollAsync(self: any, remainingExecTimeSec: number?)
-	if self._state == "idle" or self._state == "connected" then
+--[=[
+	Runs one poll cycle, spending at most `remainingExecTimeSec` (default 10) on
+	scanning. Returns immediately while idle, connected, or before the next scan
+	is due. May yield.
+]=]
+function DiscoveryStateMachine.PollAsync(self: DiscoveryStateMachine, remainingExecTimeSec: number?)
+	if self._state ~= "searching" then
 		return
 	end
 
-	local now = os.clock()
-	local timeAvailable = remainingExecTimeSec or 10
-
-	if self._state == "searching" then
-		if now < self._nextPollAt then
-			return
-		end
-		if timeAvailable <= 0 then
-			return
-		end
-		self:_scanPortsAsync(timeAvailable)
+	if os.clock() < self._nextPollAt then
+		return
 	end
+
+	local timeAvailable = remainingExecTimeSec or DEFAULT_TIME_AVAILABLE_SEC
+	if timeAvailable <= 0 then
+		return
+	end
+
+	self:_scanPortsAsync(timeAvailable)
 end
 
--- ---------------------------------------------------------------------------
--- Internal: port scanning
--- ---------------------------------------------------------------------------
+function DiscoveryStateMachine._transitionTo(self: DiscoveryStateMachine, newState: DiscoveryState)
+	local oldState: DiscoveryState = self._state
+	if oldState == newState then
+		return
+	end
 
-function DiscoveryStateMachine._scanPortsAsync(self: any, timeoutSec: number)
-	local portMin = self._config.portRange.min
-	local portMax = self._config.portRange.max
+	self._state = newState
+	self._callbacks.onStateChange(oldState, newState)
+end
 
-	-- scanPortsAsync probes every port in parallel and returns whichever
-	-- responds first, so the order is irrelevant. (An earlier version
-	-- rotated the starting port via self._currentPort, but the field was
-	-- never advanced after a failed scan, making the rotation a no-op.)
-	local ports = {}
-	for port = portMin, portMax do
+function DiscoveryStateMachine._scanPortsAsync(self: DiscoveryStateMachine, timeoutSec: number)
+	-- Every port is probed in parallel and the first to answer wins, so order is irrelevant
+	local ports: { number } = {}
+	for port = self._portMin, self._portMax do
 		table.insert(ports, port)
 	end
 
-	local foundPort, foundBody = self._callbacks.scanPortsAsync(ports, timeoutSec)
-
-	if foundPort then
-		self:_transitionTo("connecting")
-		self:_attemptConnect(foundPort, foundBody)
+	local foundPort = self._callbacks.scanPortsAsync(ports, timeoutSec)
+	if not foundPort then
+		self._nextPollAt = os.clock() + self._pollIntervalSec
 		return
 	end
 
-	-- All ports failed. Schedule next scan at the regular poll interval.
-	self._nextPollAt = os.clock() + self._config.pollIntervalSec
+	self:_transitionTo("connecting")
+	self:_attemptConnect(foundPort)
 end
 
--- ---------------------------------------------------------------------------
--- Internal: WebSocket connection attempt
--- ---------------------------------------------------------------------------
-
-function DiscoveryStateMachine._attemptConnect(self: any, port: number, _healthResponse: string?)
-	local wsUrl = "ws://localhost:" .. tostring(port) .. "/plugin"
-	local success, connection = self._callbacks.connectWebSocket(wsUrl)
-
-	if success and connection then
-		self._connection = connection
-		self._nextPollAt = 0
-		self:_transitionTo("connected")
-		self._callbacks.onConnected(connection, port)
-	else
-		self._nextPollAt = os.clock() + self._config.pollIntervalSec
+function DiscoveryStateMachine._attemptConnect(self: DiscoveryStateMachine, port: number)
+	local success, connection = self._callbacks.connectWebSocket(`ws://localhost:{port}/plugin`)
+	if not (success and connection) then
+		self._nextPollAt = os.clock() + self._pollIntervalSec
 		self:_transitionTo("searching")
+		return
 	end
+
+	self._connection = connection
+	self._nextPollAt = 0
+	self:_transitionTo("connected")
+	self._callbacks.onConnected(connection, port)
 end
 
 return DiscoveryStateMachine

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

@@ -0,0 +1,228 @@
+--!strict
+--[[
+	@class DiscoveryStateMachine.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local DiscoveryStateMachine = require("DiscoveryStateMachine")
+local Jest = require("Jest")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function setup(config: DiscoveryStateMachine.DiscoveryConfig?): any
+	local controller
+	controller = {
+		foundPort = nil :: number?,
+		connectSucceeds = true,
+		scans = {} :: { { ports: { number }, timeoutSec: number } },
+		connectUrls = {} :: { string },
+		stateChanges = {} :: { string },
+		connected = {} :: { { connection: any, port: number } },
+		disconnectReasons = {} :: { string },
+	}
+
+	controller.machine = DiscoveryStateMachine.new(config, {
+		scanPortsAsync = function(ports, timeoutSec)
+			table.insert(controller.scans, { ports = ports, timeoutSec = timeoutSec })
+			return controller.foundPort, nil
+		end,
+		connectWebSocket = function(url)
+			table.insert(controller.connectUrls, url)
+			if controller.connectSucceeds then
+				return true, { url = url }
+			end
+			return false, nil
+		end,
+		onStateChange = function(oldState, newState)
+			table.insert(controller.stateChanges, `{oldState}->{newState}`)
+		end,
+		onConnected = function(connection, port)
+			table.insert(controller.connected, { connection = connection, port = port })
+		end,
+		onDisconnected = function(reason)
+			table.insert(controller.disconnectReasons, reason or "nil")
+		end,
+	})
+
+	return controller
+end
+
+describe("DiscoveryStateMachine.new()", function()
+	it("should start idle", function()
+		local controller = setup()
+
+		expect(controller.machine:GetState()).toEqual("idle")
+	end)
+end)
+
+describe("DiscoveryStateMachine:Start()", function()
+	it("should move from idle to searching", function()
+		local controller = setup()
+
+		controller.machine:Start()
+
+		expect(controller.machine:GetState()).toEqual("searching")
+		expect(controller.stateChanges).toEqual({ "idle->searching" })
+	end)
+
+	it("should do nothing when already started", function()
+		local controller = setup()
+		controller.machine:Start()
+
+		controller.machine:Start()
+
+		expect(controller.stateChanges).toEqual({ "idle->searching" })
+	end)
+end)
+
+describe("DiscoveryStateMachine:PollAsync()", function()
+	it("should not scan while idle", function()
+		local controller = setup()
+
+		controller.machine:PollAsync(1)
+
+		expect(#controller.scans).toEqual(0)
+	end)
+
+	it("should scan the default port range with the remaining time", function()
+		local controller = setup()
+		controller.machine:Start()
+
+		controller.machine:PollAsync(1.5)
+
+		expect(controller.scans).toEqual({
+			{ ports = { 38741, 38742, 38743, 38744 }, timeoutSec = 1.5 },
+		})
+	end)
+
+	it("should scan a configured port range", function()
+		local controller = setup({ portRange = { min = 5000, max = 5001 } })
+		controller.machine:Start()
+
+		controller.machine:PollAsync(1)
+
+		expect(controller.scans[1].ports).toEqual({ 5000, 5001 })
+	end)
+
+	it("should not scan without time left", function()
+		local controller = setup()
+		controller.machine:Start()
+
+		controller.machine:PollAsync(0)
+
+		expect(#controller.scans).toEqual(0)
+	end)
+
+	it("should wait the poll interval before scanning again after a miss", function()
+		local controller = setup({ pollIntervalSec = 60 })
+		controller.machine:Start()
+
+		controller.machine:PollAsync(1)
+		controller.machine:PollAsync(1)
+
+		expect(#controller.scans).toEqual(1)
+		expect(controller.machine:GetState()).toEqual("searching")
+	end)
+
+	it("should connect to the port that answered", function()
+		local controller = setup()
+		controller.foundPort = 38743
+		controller.machine:Start()
+
+		controller.machine:PollAsync(1)
+
+		expect(controller.machine:GetState()).toEqual("connected")
+		expect(controller.connectUrls).toEqual({ "ws://localhost:38743/plugin" })
+		expect(controller.stateChanges).toEqual({ "idle->searching", "searching->connecting", "connecting->connected" })
+		expect(controller.connected[1].port).toEqual(38743)
+		expect(controller.connected[1].connection).toEqual({ url = "ws://localhost:38743/plugin" })
+	end)
+
+	it("should go back to searching when the connection fails", function()
+		local controller = setup({ pollIntervalSec = 60 })
+		controller.foundPort = 38741
+		controller.connectSucceeds = false
+		controller.machine:Start()
+
+		controller.machine:PollAsync(1)
+		controller.machine:PollAsync(1)
+
+		expect(controller.machine:GetState()).toEqual("searching")
+		expect(#controller.scans).toEqual(1)
+		expect(#controller.connected).toEqual(0)
+	end)
+
+	it("should not scan while connected", function()
+		local controller = setup()
+		controller.foundPort = 38741
+		controller.machine:Start()
+		controller.machine:PollAsync(1)
+
+		controller.machine:PollAsync(1)
+
+		expect(#controller.scans).toEqual(1)
+	end)
+end)
+
+describe("DiscoveryStateMachine:HandleDisconnect()", function()
+	it("should report the reason and scan again right away", function()
+		local controller = setup({ pollIntervalSec = 60 })
+		controller.foundPort = 38741
+		controller.machine:Start()
+		controller.machine:PollAsync(1)
+
+		controller.machine:HandleDisconnect("closed")
+		controller.machine:PollAsync(1)
+
+		expect(controller.disconnectReasons).toEqual({ "closed" })
+		expect(#controller.scans).toEqual(2)
+		expect(controller.machine:GetState()).toEqual("connected")
+	end)
+
+	it("should do nothing unless connected", function()
+		local controller = setup()
+		controller.machine:Start()
+
+		controller.machine:HandleDisconnect("closed")
+
+		expect(controller.disconnectReasons).toEqual({})
+		expect(controller.machine:GetState()).toEqual("searching")
+	end)
+end)
+
+describe("DiscoveryStateMachine:Stop()", function()
+	it("should return to idle from searching without reporting a disconnect", function()
+		local controller = setup()
+		controller.machine:Start()
+
+		controller.machine:Stop()
+
+		expect(controller.machine:GetState()).toEqual("idle")
+		expect(controller.disconnectReasons).toEqual({})
+	end)
+
+	it("should report a stopped disconnect when connected", function()
+		local controller = setup()
+		controller.foundPort = 38741
+		controller.machine:Start()
+		controller.machine:PollAsync(1)
+
+		controller.machine:Stop()
+
+		expect(controller.machine:GetState()).toEqual("idle")
+		expect(controller.disconnectReasons).toEqual({ "stopped" })
+	end)
+
+	it("should allow starting again", function()
+		local controller = setup()
+		controller.machine:Start()
+		controller.machine:Stop()
+
+		controller.machine:Start()
+
+		expect(controller.machine:GetState()).toEqual("searching")
+	end)
+end)