@quenty/studio-bridge 0.7.0 → 0.8.0

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

@@ -0,0 +1,245 @@
+--[[
+	Action dispatch module for routing incoming protocol messages to handlers.
+
+	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.
+
+	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
+
+	No Roblox APIs. Pure logic, testable under Lune.
+]]
+
+local ActionRouter = {}
+ActionRouter.__index = ActionRouter
+
+-- ---------------------------------------------------------------------------
+-- Constructor
+-- ---------------------------------------------------------------------------
+
+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 }?
+)
+	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]
+
+	if handler == nil then
+		return {
+			type = "error",
+			sessionId = message.sessionId,
+			requestId = message.requestId,
+			payload = {
+				code = "UNKNOWN_REQUEST",
+				message = "Unknown message type: " .. tostring(message.type),
+			},
+		}
+	end
+
+	local requestId = message.requestId or ""
+	local ok, result = pcall(handler, message.payload, requestId, message.sessionId)
+
+	if not ok then
+		return {
+			type = "error",
+			sessionId = message.sessionId,
+			requestId = message.requestId,
+			payload = {
+				code = "INTERNAL_ERROR",
+				message = "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")
+
+	return {
+		type = responseType,
+		sessionId = message.sessionId,
+		requestId = message.requestId,
+		payload = result,
+	}
+end
+
+-- ---------------------------------------------------------------------------
+-- Set a custom response type for a message type
+-- ---------------------------------------------------------------------------
+
+function ActionRouter.setResponseType(self: any, messageType: string, responseType: string)
+	self._responseTypes[messageType] = responseType
+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,
+	name: string,
+	source: string,
+	sendMessage: ((msg: { [string]: any }) -> ())?,
+	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
+		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
+			pcall(oldAction.module.teardown)
+		end
+		for _, handlerName in oldAction.handlerNames do
+			self._handlers[handlerName] = nil
+			self._responseTypes[handlerName] = nil
+		end
+	end
+
+	-- Snapshot handler keys before registration
+	local beforeHandlers = {}
+	for k, _ in self._handlers do
+		beforeHandlers[k] = 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"}`
+	end
+
+	-- Execute the loaded chunk to get the module table
+	local execOk, moduleTable = pcall(moduleOrErr)
+	if not execOk then
+		return false, `Failed to execute action module: {moduleTable}`
+	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}`
+		end
+	elseif type(moduleTable) == "function" then
+		-- Simple handler function
+		self:register(name, moduleTable)
+	else
+		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)
+		end
+	end
+
+	-- Store in _actions for hash tracking
+	if hash then
+		self._actions[name] = {
+			module = moduleTable,
+			hash = hash,
+			handlerNames = registeredNames,
+		}
+	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
+	end
+	return result
+end
+
+return ActionRouter

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

@@ -0,0 +1,203 @@
+--[[
+	Pure state machine for plugin discovery and connection lifecycle.
+
+	Manages the states: idle, searching, connecting, connected.
+	All external I/O is performed via injected callbacks.
+
+	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.
+]]
+
+local DiscoveryStateMachine = {}
+DiscoveryStateMachine.__index = DiscoveryStateMachine
+
+-- ---------------------------------------------------------------------------
+-- Default configuration
+-- ---------------------------------------------------------------------------
+
+local DEFAULT_CONFIG = {
+	portRange = { min = 38741, max = 38744 },
+	pollIntervalSec = 2,
+}
+
+-- ---------------------------------------------------------------------------
+-- 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
+
+	local self = setmetatable({
+		_config = resolvedConfig,
+		_callbacks = callbacks,
+		_state = "idle" :: string,
+		_nextPollAt = 0, -- os.clock() time for next scan
+		_connection = nil :: any?,
+	}, DiscoveryStateMachine)
+
+	return self
+end
+
+-- ---------------------------------------------------------------------------
+-- State accessors
+-- ---------------------------------------------------------------------------
+
+function DiscoveryStateMachine.getState(self: any): string
+	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)
+	if self._state ~= "idle" then
+		return
+	end
+	self._nextPollAt = 0
+	self:_transitionTo("searching")
+end
+
+function DiscoveryStateMachine.stop(self: any)
+	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?)
+	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
+		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)
+	end
+end
+
+-- ---------------------------------------------------------------------------
+-- Internal: port scanning
+-- ---------------------------------------------------------------------------
+
+function DiscoveryStateMachine._scanPortsAsync(self: any, timeoutSec: number)
+	local portMin = self._config.portRange.min
+	local portMax = self._config.portRange.max
+
+	-- 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
+		table.insert(ports, port)
+	end
+
+	local foundPort, foundBody = self._callbacks.scanPortsAsync(ports, timeoutSec)
+
+	if foundPort then
+		self:_transitionTo("connecting")
+		self:_attemptConnect(foundPort, foundBody)
+		return
+	end
+
+	-- All ports failed. Schedule next scan at the regular poll interval.
+	self._nextPollAt = os.clock() + self._config.pollIntervalSec
+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
+		self:_transitionTo("searching")
+	end
+end
+
+return DiscoveryStateMachine

package/templates/studio-bridge-plugin/src/Shared/MessageBuffer.luau

@@ -0,0 +1,144 @@
+--[[
+	Fixed-capacity ring buffer for storing log entries.
+
+	Entries are added via push(). When the buffer reaches capacity, new entries
+	overwrite the oldest. Retrieval via get() supports both "head" (oldest first)
+	and "tail" (newest first) directions with an optional count limit.
+
+	No Roblox APIs. Pure logic, testable under Lune.
+]]
+
+local MessageBuffer = {}
+MessageBuffer.__index = MessageBuffer
+
+-- ---------------------------------------------------------------------------
+-- Constructor
+-- ---------------------------------------------------------------------------
+
+--[[
+	Create a new MessageBuffer with the given capacity.
+
+	@param capacity Maximum number of entries (default 1000).
+]]
+function MessageBuffer.new(capacity: number?)
+	local cap = capacity or 1000
+	local self = setmetatable({
+		_capacity = cap,
+		_buffer = {} :: { { level: string, body: string, timestamp: number } },
+		_head = 1, -- next write position (1-indexed)
+		_count = 0, -- number of entries currently stored
+	}, MessageBuffer)
+	return self
+end
+
+-- ---------------------------------------------------------------------------
+-- Push an entry into the buffer
+-- ---------------------------------------------------------------------------
+
+--[[
+	Add an entry to the buffer. Overwrites the oldest entry if at capacity.
+
+	@param entry Table with level, body, timestamp fields.
+]]
+function MessageBuffer.push(
+	self: any,
+	entry: {
+		level: string,
+		body: string,
+		timestamp: number,
+	}
+)
+	self._buffer[self._head] = entry
+	self._head = (self._head % self._capacity) + 1
+	if self._count < self._capacity then
+		self._count = self._count + 1
+	end
+end
+
+-- ---------------------------------------------------------------------------
+-- Get entries from the buffer
+-- ---------------------------------------------------------------------------
+
+--[[
+	Retrieve entries from the buffer.
+
+	@param direction "head" for oldest first, "tail" for newest first (default "tail").
+	@param count Maximum number of entries to return (default: all).
+	@return Table with entries, total, and bufferCapacity.
+]]
+function MessageBuffer.get(
+	self: any,
+	direction: string?,
+	count: number?
+): {
+	entries: { { level: string, body: string, timestamp: number } },
+	total: number,
+	bufferCapacity: number,
+}
+	local dir = direction or "tail"
+	local all = self:_toArray()
+	local maxCount = count or #all
+	local entries = {}
+
+	if dir == "head" then
+		-- Oldest first, take from the start
+		for i = 1, math.min(maxCount, #all) do
+			table.insert(entries, all[i])
+		end
+	else
+		-- Newest first (tail), take from the end
+		local start = math.max(1, #all - maxCount + 1)
+		for i = start, #all do
+			table.insert(entries, all[i])
+		end
+	end
+
+	return {
+		entries = entries,
+		total = self._count,
+		bufferCapacity = self._capacity,
+	}
+end
+
+-- ---------------------------------------------------------------------------
+-- Clear the buffer
+-- ---------------------------------------------------------------------------
+
+function MessageBuffer.clear(self: any)
+	self._buffer = {}
+	self._head = 1
+	self._count = 0
+end
+
+-- ---------------------------------------------------------------------------
+-- Get the number of entries
+-- ---------------------------------------------------------------------------
+
+function MessageBuffer.size(self: any): number
+	return self._count
+end
+
+-- ---------------------------------------------------------------------------
+-- Internal: convert ring buffer to a chronological array
+-- ---------------------------------------------------------------------------
+
+function MessageBuffer._toArray(self: any): { { level: string, body: string, timestamp: number } }
+	local result = {}
+	if self._count < self._capacity then
+		-- Buffer not full: entries are at indices 1..count
+		for i = 1, self._count do
+			table.insert(result, self._buffer[i])
+		end
+	else
+		-- Buffer full: oldest entry is at _head, wrap around
+		for i = self._head, self._capacity do
+			table.insert(result, self._buffer[i])
+		end
+		for i = 1, self._head - 1 do
+			table.insert(result, self._buffer[i])
+		end
+	end
+	return result
+end
+
+return MessageBuffer