@quenty/studio-bridge 0.21.0 → 0.22.0

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

@@ -1,96 +1,83 @@
---[[
-	Fixed-capacity ring buffer for storing log entries.
+--!strict
+--[=[
+	Fixed-capacity ring buffer of log entries. Once full, each push overwrites
+	the oldest entry.
 
-	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.
+	The query-logs action pushed over the wire calls `get`, which keeps its
+	lowercase name because a persistent plugin installed from an older release
+	still runs action source pushed by a newer CLI.
 
-	No Roblox APIs. Pure logic, testable under Lune.
-]]
+	@class MessageBuffer
+]=]
+
+local DEFAULT_CAPACITY = 1000
 
 local MessageBuffer = {}
+MessageBuffer.ClassName = "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)
+export type LogEntry = {
+	level: string,
+	body: string,
+	timestamp: number,
+}
+
+export type Direction = "head" | "tail"
+
+export type BufferSnapshot = {
+	entries: { LogEntry },
+	total: number,
+	bufferCapacity: number,
+}
+
+export type MessageBuffer = typeof(setmetatable(
+	{} :: {
+		_capacity: number,
+		_buffer: { LogEntry },
+		_nextIndex: number,
+		_count: number,
+	},
+	{} :: typeof({ __index = MessageBuffer })
+))
+
+--[=[
+	Constructs a buffer holding at most `capacity` entries (default 1000).
+]=]
+function MessageBuffer.new(capacity: number?): MessageBuffer
+	local self: MessageBuffer = setmetatable({} :: any, MessageBuffer)
+
+	self._capacity = capacity or DEFAULT_CAPACITY
+	self._buffer = {}
+	self._nextIndex = 1
+	self._count = 0
+
 	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
+--[=[
+	Adds an entry, overwriting the oldest one when the buffer is full.
+]=]
+function MessageBuffer.Push(self: MessageBuffer, entry: LogEntry)
+	self._buffer[self._nextIndex] = entry
+	self._nextIndex = (self._nextIndex % self._capacity) + 1
 	if self._count < self._capacity then
-		self._count = self._count + 1
+		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"
+--[=[
+	Returns up to `count` entries in chronological order. `"head"` takes the
+	oldest entries, `"tail"` (the default) the newest.
+]=]
+function MessageBuffer.get(self: MessageBuffer, direction: Direction?, count: number?): BufferSnapshot
 	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
+	local takeCount = math.min(count or #all, #all)
+
+	local entries: { LogEntry }
+	if direction == "head" then
+		entries = table.move(all, 1, takeCount, 1, {})
 	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
+		entries = table.move(all, #all - takeCount + 1, #all, 1, {})
 	end
 
 	return {
@@ -100,45 +87,29 @@ function MessageBuffer.get(
 	}
 end
 
--- ---------------------------------------------------------------------------
--- Clear the buffer
--- ---------------------------------------------------------------------------
-
-function MessageBuffer.clear(self: any)
-	self._buffer = {}
-	self._head = 1
+--[=[
+	Removes every entry.
+]=]
+function MessageBuffer.Clear(self: MessageBuffer)
+	table.clear(self._buffer)
+	self._nextIndex = 1
 	self._count = 0
 end
 
--- ---------------------------------------------------------------------------
--- Get the number of entries
--- ---------------------------------------------------------------------------
-
-function MessageBuffer.size(self: any): number
+--[=[
+	Returns the number of entries currently stored.
+]=]
+function MessageBuffer.GetCount(self: MessageBuffer): 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 = {}
+function MessageBuffer._toArray(self: MessageBuffer): { LogEntry }
 	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
+		return table.move(self._buffer, 1, self._count, 1, {})
 	end
-	return result
+
+	local result = table.move(self._buffer, self._nextIndex, self._capacity, 1, {})
+	return table.move(self._buffer, 1, self._nextIndex - 1, #result + 1, result)
 end
 
 return MessageBuffer

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

@@ -0,0 +1,116 @@
+--!strict
+--[[
+	@class MessageBuffer.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MessageBuffer = require("MessageBuffer")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function pushBodies(buffer: MessageBuffer.MessageBuffer, bodies: { string })
+	for index, body in bodies do
+		buffer:Push({ level = "Print", body = body, timestamp = index })
+	end
+end
+
+local function getBodies(entries: { MessageBuffer.LogEntry }): { string }
+	local bodies = {}
+	for _, entry in entries do
+		table.insert(bodies, entry.body)
+	end
+	return bodies
+end
+
+describe("MessageBuffer.new()", function()
+	it("should default to a capacity of 1000", function()
+		local buffer = MessageBuffer.new()
+
+		expect(buffer:get().bufferCapacity).toEqual(1000)
+		expect(buffer:GetCount()).toEqual(0)
+	end)
+end)
+
+describe("MessageBuffer:get()", function()
+	it("should return entries oldest first for either direction", function()
+		local buffer = MessageBuffer.new(10)
+		pushBodies(buffer, { "a", "b", "c", "d" })
+
+		expect(getBodies(buffer:get("head", 2).entries)).toEqual({ "a", "b" })
+		expect(getBodies(buffer:get("tail", 2).entries)).toEqual({ "c", "d" })
+	end)
+
+	it("should default to every entry from the tail", function()
+		local buffer = MessageBuffer.new(10)
+		pushBodies(buffer, { "a", "b", "c" })
+
+		expect(getBodies(buffer:get().entries)).toEqual({ "a", "b", "c" })
+	end)
+
+	it("should clamp a count larger than the buffer", function()
+		local buffer = MessageBuffer.new(10)
+		pushBodies(buffer, { "a", "b" })
+
+		expect(getBodies(buffer:get("head", 50).entries)).toEqual({ "a", "b" })
+		expect(getBodies(buffer:get("tail", 50).entries)).toEqual({ "a", "b" })
+	end)
+
+	it("should return nothing for a count of zero", function()
+		local buffer = MessageBuffer.new(10)
+		pushBodies(buffer, { "a", "b" })
+
+		expect(buffer:get("head", 0).entries).toEqual({})
+		expect(buffer:get("tail", 0).entries).toEqual({})
+	end)
+
+	it("should report the stored count and capacity", function()
+		local buffer = MessageBuffer.new(5)
+		pushBodies(buffer, { "a", "b", "c" })
+
+		local snapshot = buffer:get("tail", 1)
+
+		expect(snapshot.total).toEqual(3)
+		expect(snapshot.bufferCapacity).toEqual(5)
+	end)
+end)
+
+describe("MessageBuffer:Push()", function()
+	it("should overwrite the oldest entries once full", function()
+		local buffer = MessageBuffer.new(3)
+		pushBodies(buffer, { "a", "b", "c", "d", "e" })
+
+		expect(buffer:GetCount()).toEqual(3)
+		expect(getBodies(buffer:get().entries)).toEqual({ "c", "d", "e" })
+	end)
+
+	it("should keep chronological order after wrapping many times", function()
+		local buffer = MessageBuffer.new(4)
+		local bodies = {}
+		for index = 1, 23 do
+			table.insert(bodies, tostring(index))
+		end
+		pushBodies(buffer, bodies)
+
+		expect(getBodies(buffer:get().entries)).toEqual({ "20", "21", "22", "23" })
+	end)
+end)
+
+describe("MessageBuffer:Clear()", function()
+	it("should remove every entry and accept new ones", function()
+		local buffer = MessageBuffer.new(3)
+		pushBodies(buffer, { "a", "b", "c", "d" })
+
+		buffer:Clear()
+
+		expect(buffer:GetCount()).toEqual(0)
+		expect(buffer:get().entries).toEqual({})
+
+		pushBodies(buffer, { "x" })
+
+		expect(getBodies(buffer:get().entries)).toEqual({ "x" })
+	end)
+end)

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

@@ -0,0 +1,233 @@
+--!strict
+--[=[
+	One open WebSocket to the bridge. Registers the plugin, dispatches incoming
+	messages through an [ActionRouter] and sends back the responses, and sends a
+	heartbeat every 15 seconds until destroyed.
+
+	A `shutdown` message closes the socket, and a closed socket destroys this.
+
+	A reply over `maxMessageBytes` (256 MiB by default) is replaced with a
+	`RESULT_TOO_LARGE` error for its request. Studio sends far larger messages,
+	but the bridge closes a socket that sends it more than it accepts, which
+	would fail every request in flight.
+
+	@class StudioBridgeConnection
+]=]
+
+local HttpService = game:GetService("HttpService")
+
+local StudioBridgeLogUtils = require(script.Parent.StudioBridgeLogUtils)
+
+local HEARTBEAT_INTERVAL_SEC = 15
+local DEFAULT_MAX_MESSAGE_BYTES = 256 * 1024 * 1024
+
+local StudioBridgeConnection = {}
+StudioBridgeConnection.ClassName = "StudioBridgeConnection"
+StudioBridgeConnection.__index = StudioBridgeConnection
+
+--[=[
+	The members of a WebStreamClient this uses. Specs pass a fake shaped like it.
+
+	@interface WebSocket
+	.Send (self, data: string) -> ()
+	.Close (self) -> ()
+	.MessageReceived RBXScriptSignal
+	.Closed RBXScriptSignal
+	@within StudioBridgeConnection
+]=]
+export type WebSocket = {
+	Send: (self: any, data: string) -> (),
+	Close: (self: any) -> (),
+	MessageReceived: any,
+	Closed: any,
+}
+
+export type StudioBridgeConnectionOptions = {
+	webSocket: WebSocket,
+	router: any,
+	sessionId: string,
+	registerPayload: { [string]: any },
+	maxMessageBytes: number?,
+}
+
+export type StudioBridgeConnection = typeof(setmetatable(
+	{} :: {
+		_webSocket: WebSocket,
+		_router: any,
+		_sessionId: string,
+		_registerPayload: { [string]: any },
+		_maxMessageBytes: number,
+		_isOpen: boolean,
+		_startClock: number,
+		_signalConnections: { any },
+		_heartbeatThread: thread?,
+	},
+	{} :: typeof({ __index = StudioBridgeConnection })
+))
+
+--[=[
+	Wires an opened WebSocket and sends the `register` message.
+]=]
+function StudioBridgeConnection.new(options: StudioBridgeConnectionOptions): StudioBridgeConnection
+	local self: StudioBridgeConnection = setmetatable({} :: any, StudioBridgeConnection)
+
+	self._webSocket = assert(options.webSocket, "No webSocket")
+	self._router = assert(options.router, "No router")
+	self._sessionId = assert(options.sessionId, "No sessionId")
+	self._registerPayload = assert(options.registerPayload, "No registerPayload")
+	self._maxMessageBytes = options.maxMessageBytes or DEFAULT_MAX_MESSAGE_BYTES
+	self._isOpen = true
+	self._startClock = os.clock()
+	self._signalConnections = {}
+
+	table.insert(
+		self._signalConnections,
+		self._webSocket.MessageReceived:Connect(function(rawData: string)
+			self:_handleRawMessage(rawData)
+		end)
+	)
+	table.insert(
+		self._signalConnections,
+		self._webSocket.Closed:Connect(function()
+			self:Destroy()
+		end)
+	)
+
+	self:Send({
+		type = "register",
+		sessionId = self._sessionId,
+		payload = self._registerPayload,
+	})
+
+	self._heartbeatThread = task.spawn(function()
+		while self._isOpen do
+			self:_sendHeartbeat()
+			task.wait(HEARTBEAT_INTERVAL_SEC)
+		end
+	end)
+
+	return self
+end
+
+--[=[
+	Returns whether the socket is still open.
+]=]
+function StudioBridgeConnection.IsOpen(self: StudioBridgeConnection): boolean
+	return self._isOpen
+end
+
+--[=[
+	Encodes and sends a message. Does nothing once the socket is closed, and
+	never throws, since action handlers call this from their own threads.
+]=]
+function StudioBridgeConnection.Send(self: StudioBridgeConnection, message: { [string]: any })
+	if not self._isOpen then
+		return
+	end
+
+	local ok, err = pcall(function()
+		self._webSocket:Send(self:_encode(message))
+	end)
+	if not ok then
+		StudioBridgeLogUtils.warn(`Failed to send {tostring(message.type)}: {tostring(err)}`)
+	end
+end
+
+function StudioBridgeConnection._sendHeartbeat(self: StudioBridgeConnection)
+	self:Send({
+		type = "heartbeat",
+		sessionId = self._sessionId,
+		payload = {
+			uptimeMs = math.floor((os.clock() - self._startClock) * 1000),
+			state = self._registerPayload.state,
+			pendingRequests = 0,
+		},
+	})
+end
+
+function StudioBridgeConnection._handleRawMessage(self: StudioBridgeConnection, rawData: string)
+	local ok, err = pcall(StudioBridgeConnection._dispatchRawMessage, self, rawData)
+	if not ok then
+		StudioBridgeLogUtils.warn(`MessageReceived handler error: {tostring(err)}`)
+	end
+end
+
+function StudioBridgeConnection._dispatchRawMessage(self: StudioBridgeConnection, rawData: string)
+	local decodeOk, message = pcall(HttpService.JSONDecode, HttpService, rawData)
+	if not decodeOk or type(message) ~= "table" or type(message.type) ~= "string" then
+		StudioBridgeLogUtils.warn(`Failed to decode message: {string.sub(tostring(rawData), 1, 200)}`)
+		return
+	end
+
+	StudioBridgeLogUtils.logVerbose(
+		`Received: {message.type} (requestId={string.sub(tostring(message.requestId), 1, 8)}...)`
+	)
+
+	if message.type == "shutdown" then
+		self:_close()
+		return
+	end
+
+	local response = self._router:Dispatch(message)
+	if not response then
+		StudioBridgeLogUtils.logVerbose(`No response for: {message.type}`)
+		return
+	end
+
+	local encoded = self:_encode(response)
+	StudioBridgeLogUtils.logVerbose(`Sending: {response.type} ({#encoded} bytes)`)
+	self._webSocket:Send(encoded)
+end
+
+--[[
+	Encodes `message`, or a RESULT_TOO_LARGE error for its request when it is
+	over the limit.
+]]
+function StudioBridgeConnection._encode(self: StudioBridgeConnection, message: { [string]: any }): string
+	local encoded = HttpService:JSONEncode(message)
+	if #encoded <= self._maxMessageBytes or message.requestId == nil then
+		return encoded
+	end
+
+	local megabytes = function(bytes: number): string
+		return string.format("%.1f MB", bytes / (1024 * 1024))
+	end
+	return HttpService:JSONEncode({
+		type = "error",
+		sessionId = message.sessionId,
+		requestId = message.requestId,
+		payload = {
+			code = "RESULT_TOO_LARGE",
+			message = `The {message.type} reply is {megabytes(#encoded)}, over the {megabytes(self._maxMessageBytes)} a reply can carry. Return less, or narrow the request.`,
+		},
+	})
+end
+
+function StudioBridgeConnection._close(self: StudioBridgeConnection)
+	self._isOpen = false
+	pcall(function()
+		self._webSocket:Close()
+	end)
+end
+
+--[=[
+	Stops the heartbeat and stops listening to the socket. Does not close the
+	socket, since by then it is usually already closed.
+]=]
+function StudioBridgeConnection.Destroy(self: StudioBridgeConnection)
+	self._isOpen = false
+	StudioBridgeLogUtils.setVerbose(false)
+
+	for _, connection in self._signalConnections do
+		connection:Disconnect()
+	end
+	table.clear(self._signalConnections)
+
+	local heartbeatThread = self._heartbeatThread
+	self._heartbeatThread = nil
+	if heartbeatThread and coroutine.status(heartbeatThread) == "suspended" then
+		task.cancel(heartbeatThread)
+	end
+end
+
+return StudioBridgeConnection