@quenty/datastore 13.51.0 → 13.52.0

package/src/Server/DataStoreTestUtils.lua

@@ -102,14 +102,83 @@ function DataStoreTestUtils.setup()
 	}
 end
 
+--[=[
+	Simulates what a real Roblox server does when it shuts down, which is the only accurate model for
+	the save path: Roblox fires PlayerRemoving for every player still in the server, giving those
+	handlers the same "hold the shutdown open for me" treatment BindToClose gets. So the removals are
+	what save and close each session; the close callback's job is only to wait for them to flush.
+
+	Destroying the manager is NOT a shutdown and never has been -- nothing in a live server destroys it.
+
+	@param manager PlayerDataStoreManager
+	@param userIds { PlayerUserId }? -- players still in the server when it began closing
+	@return Promise -- what BindToCloseService yields on, so the server cannot die until it settles
+]=]
+function DataStoreTestUtils.promiseSimulatedShutdown(manager, userIds)
+	for _, userId in userIds or {} do
+		manager:RemovePlayerDataStore(userId)
+	end
+
+	return manager:PromiseAllSaves()
+end
+
+--[=[
+	Shuts down the manager a [PlayerDataStoreService] owns, the way Roblox would, and waits for it.
+
+	Call this from the `destroy()` of any spec that injects a datastore into the service and tears down
+	by destroying its ServiceBag. `manager:Destroy()` destroys no stores -- they are only ever destroyed
+	by a removal -- and a [PlayerMock] never fires the real `Players.PlayerRemoving`, so without this
+	every store the spec loaded outlives it with its `task.spawn` auto-save loop running. In the shared
+	test place that loop later fires inside another package's window and fails it.
+
+	`userIds` is only needed to model "PlayerRemoving landed first" for an ordering assertion. For
+	cleanup, omit it: the close removes every store the manager still owns.
+
+	@param playerDataStoreService PlayerDataStoreService
+	@param userIds { PlayerUserId }?
+	@param timeout number? -- defaults to 5
+	@return boolean -- false only if a shutdown was started and did not settle in time
+]=]
+function DataStoreTestUtils.awaitServiceShutdown(playerDataStoreService, userIds, timeout)
+	local managerPromise = playerDataStoreService:PromiseManager()
+
+	-- Nothing to shut down yet, so return rather than sit out the timeout. The manager is only
+	-- constructed inside the last link of PromiseManager's chain, so a promise still pending here means
+	-- that link never ran: no manager exists, so _createDataStore was never called and no store exists to
+	-- leak. That holds whatever the promise is waiting on -- a ServiceBag that was never started, or a
+	-- real datastore still resolving. Specs that start the bag per-test would otherwise pay the full
+	-- timeout on every teardown.
+	if managerPromise:IsPending() then
+		return true
+	end
+
+	return PromiseTestUtils.awaitSettled(
+		managerPromise:Then(function(manager)
+			-- Promise runs handlers without a pcall, so calling a destroyed manager would throw straight
+			-- out of the spec's teardown rather than fail it.
+			if not manager.Destroy then
+				return nil
+			end
+
+			return DataStoreTestUtils.promiseSimulatedShutdown(manager, userIds)
+		end),
+		timeout or 5
+	)
+end
+
 --[=[
 	Builds the controller the [PlayerDataStoreManager] specs share: a session-locked manager wired to
-	a fresh [DataStoreMock] (keyed `user_<userId>`), all owned by a Maid. `destroy()` tears down the
-	manager (and the loaded stores whose auto-save loops it owns) and the service bag.
+	a fresh [DataStoreMock] (keyed `user_<userId>`), all owned by a Maid.
+
+	`destroy()` shuts the server down the way Roblox would (see
+	[DataStoreTestUtils.promiseSimulatedShutdown]) and then tears the objects down. The shutdown is not
+	optional bookkeeping: a store the spec loaded keeps its auto-save loop running until something
+	removes it, and in the shared test place that loop outlives the spec and fires inside a later
+	package's window.
 
 	Fields: `manager`, `mock`, `serviceBag`.
 	Helpers: `storeAndAwaitLock()` -> boolean -- stores a value on user 1's store and waits for the
-	session-locked load to write the lock envelope.
+	session-locked load to write the lock envelope. `promiseShutdown(userIds?)` -> Promise.
 
 	@return { manager: PlayerDataStoreManager, mock: DataStoreMock, ... }
 ]=]
@@ -123,6 +192,7 @@ function DataStoreTestUtils.setupDataStoreManager()
 		return "user_" .. tostring(userId)
 	end, true))
 
+	-- Returns exactly one value: specs call this straight through expect(), which rejects a second arg.
 	local function storeAndAwaitLock()
 		local dataStore = manager:GetDataStore(1)
 		dataStore:Store("coins", 5)
@@ -133,12 +203,18 @@ function DataStoreTestUtils.setupDataStoreManager()
 		end, 10)
 	end
 
+	local function promiseShutdown(userIds)
+		return DataStoreTestUtils.promiseSimulatedShutdown(manager, userIds)
+	end
+
 	return {
 		manager = manager,
 		mock = mock,
 		serviceBag = serviceBag,
 		storeAndAwaitLock = storeAndAwaitLock,
+		promiseShutdown = promiseShutdown,
 		destroy = function()
+			PromiseTestUtils.awaitSettled(promiseShutdown(), 5)
 			maid:DoCleaning()
 		end,
 	}

package/src/Server/Modules/DataStoreLockUtils.lua

@@ -0,0 +1,139 @@
+--!strict
+--[=[
+	Pure reading and writing of the session-lock envelope a [DataStore] keeps under the `lock` field.
+
+	[DataStoreLockHelper] owns the live path, where the lock is only ever touched by the session that
+	holds it. Tooling needs the other path: inspect or clear the lock on a key belonging to a player
+	who is not in this server, through a raw datastore write with no session at all. Both go through
+	here so there is one definition of the envelope.
+
+	@server
+	@class DataStoreLockUtils
+]=]
+
+local DataStoreLockUtils = {}
+
+export type LockedSessionData = {
+	SessionId: string,
+	PlaceId: number,
+	JobId: string,
+}
+
+export type LockData = {
+	LastUpdateTime: number?,
+	ActiveSession: LockedSessionData?,
+}
+
+--[=[
+	Reads session data back out of whatever the datastore returned, rejecting anything malformed.
+
+	@param sessionData any
+	@return LockedSessionData?
+]=]
+function DataStoreLockUtils.deserializeSessionData(sessionData: any): LockedSessionData?
+	if type(sessionData) ~= "table" then
+		return nil
+	end
+
+	if type(sessionData.SessionId) ~= "string" then
+		return nil
+	end
+
+	if type(sessionData.PlaceId) ~= "number" then
+		return nil
+	end
+
+	if type(sessionData.JobId) ~= "string" then
+		return nil
+	end
+
+	return {
+		SessionId = sessionData.SessionId,
+		PlaceId = sessionData.PlaceId,
+		JobId = sessionData.JobId,
+	}
+end
+
+--[=[
+	Reads a lock envelope back out of whatever the datastore returned.
+
+	@param lockData any
+	@return LockData?
+]=]
+function DataStoreLockUtils.deserializeLockData(lockData: any): LockData?
+	if type(lockData) ~= "table" then
+		return nil
+	end
+
+	return {
+		LastUpdateTime = if type(lockData.LastUpdateTime) == "number" then lockData.LastUpdateTime else nil,
+		ActiveSession = DataStoreLockUtils.deserializeSessionData(lockData.ActiveSession),
+	}
+end
+
+--[=[
+	Reads the lock off a whole stored profile.
+
+	@param data any -- the raw value stored at the key
+	@return LockData?
+]=]
+function DataStoreLockUtils.readLock(data: any): LockData?
+	if type(data) ~= "table" then
+		return nil
+	end
+
+	return DataStoreLockUtils.deserializeLockData(data.lock)
+end
+
+--[=[
+	Builds the envelope a session writes to claim the key.
+
+	@param sessionData LockedSessionData
+	@param lastUpdateTime number? -- defaults to now
+	@return LockData
+]=]
+function DataStoreLockUtils.createLockData(sessionData: LockedSessionData, lastUpdateTime: number?): LockData
+	return {
+		LastUpdateTime = lastUpdateTime or os.time(),
+		ActiveSession = sessionData,
+	}
+end
+
+--[=[
+	Returns a copy of the profile with the lock set to `lockData`, or cleared when it is nil.
+
+	@param data any -- the raw value stored at the key
+	@param lockData LockData?
+	@return any
+]=]
+function DataStoreLockUtils.withLock(data: any, lockData: LockData?): any
+	if data == nil then
+		return if lockData == nil then {} else { lock = lockData }
+	elseif type(data) ~= "table" then
+		warn("[DataStoreLockUtils] - Data session locking is not available for non-table entries")
+		return data
+	end
+
+	local copy = table.clone(data)
+	copy.lock = lockData
+	return copy
+end
+
+--[=[
+	Renders a lock for a human reading command output.
+
+	@param lockData LockData?
+	@return string
+]=]
+function DataStoreLockUtils.toHumanReadable(lockData: LockData?): string
+	if lockData == nil or lockData.ActiveSession == nil then
+		return "unlocked"
+	end
+
+	local session = lockData.ActiveSession
+	local age = if lockData.LastUpdateTime then `{os.time() - lockData.LastUpdateTime}s ago` else "unknown age"
+
+	return `locked by PlaceId {session.PlaceId}, JobId {session.JobId}, SessionId {session.SessionId} (updated {age})`
+end
+
+return DataStoreLockUtils

package/src/Server/PlayerDataStoreHandle.lua

@@ -0,0 +1,103 @@
+--!strict
+--[=[
+	A borrowed [DataStore] for a player, and the obligation to put it back.
+
+	Opening a store for a player who is not in this server takes their session lock, which kicks them
+	from wherever they were playing. Until that lock is dropped again they cannot rejoin, so releasing
+	it is the part that matters -- and a release the caller has to remember to perform is one that
+	eventually gets missed on an error path.
+
+	Handing back a handle makes it a [Maid]-shaped obligation instead: give it to a maid, or destroy
+	it, and the session is released once nothing is using it. Destroying twice is safe.
+
+	Handles are counted, so three systems loading the same player each get their own and the session
+	survives until the last one is destroyed.
+
+	A player in this server is not represented by a handle -- their session is owned by the join and
+	leave path, which reaches removal from several directions a handle could not model safely. So
+	destroying a handle never closes a live player's session; it only releases one this tooling
+	opened on behalf of someone absent.
+
+	```lua
+	local handle = manager:PromiseDataStoreHandle(userId):Yield()
+	local data = handle:GetDataStore():LoadAll({}):Yield()
+	handle:Destroy()
+	```
+
+	@server
+	@class PlayerDataStoreHandle
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local DataStore = require("DataStore")
+
+local PlayerDataStoreHandle = {}
+PlayerDataStoreHandle.ClassName = "PlayerDataStoreHandle"
+PlayerDataStoreHandle.__index = PlayerDataStoreHandle
+
+export type PlayerDataStoreHandle = typeof(setmetatable(
+	{} :: {
+		_dataStore: DataStore.DataStore?,
+		_release: (() -> ())?,
+	},
+	{} :: typeof({ __index = PlayerDataStoreHandle })
+))
+
+--[=[
+	Constructs a new handle over a datastore.
+
+	@param dataStore DataStore
+	@param release (() -> ())? -- invoked on destroy, when this handle is the one that borrowed the store
+	@return PlayerDataStoreHandle
+]=]
+function PlayerDataStoreHandle.new(dataStore: DataStore.DataStore, release: (() -> ())?): PlayerDataStoreHandle
+	local self: PlayerDataStoreHandle = setmetatable({} :: any, PlayerDataStoreHandle)
+
+	self._dataStore = assert(dataStore, "No dataStore")
+	self._release = release
+
+	return self
+end
+
+--[=[
+	Returns whether the value is a handle.
+
+	@param value any
+	@return boolean
+]=]
+function PlayerDataStoreHandle.isPlayerDataStoreHandle(value: any): boolean
+	return type(value) == "table" and getmetatable(value) == PlayerDataStoreHandle
+end
+
+--[=[
+	Returns the datastore this handle holds. Errors once destroyed, since the session behind it may
+	already be closed.
+
+	@return DataStore
+]=]
+function PlayerDataStoreHandle.GetDataStore(self: PlayerDataStoreHandle): DataStore.DataStore
+	-- Bound to one value rather than returned straight out of the assert, which would hand back its
+	-- message as a second return and quietly widen every call site into a multiple-value expression.
+	local dataStore = self._dataStore
+	assert(dataStore, "Handle is destroyed")
+
+	return dataStore
+end
+
+--[=[
+	Drops this handle's reference to the session. The session itself is released once no handle and
+	no player in this server is still holding it.
+]=]
+function PlayerDataStoreHandle.Destroy(self: PlayerDataStoreHandle): ()
+	local release = self._release
+
+	self._dataStore = nil
+	self._release = nil
+
+	if release then
+		release()
+	end
+end
+
+return PlayerDataStoreHandle

package/src/Server/PlayerDataStoreManager.Handles.spec.lua

@@ -0,0 +1,136 @@
+--!strict
+--[[
+	Counted datastore handles. Opening a store for an absent player takes their session lock, so the
+	thing worth pinning down is that the session is released once nothing is holding it -- and not
+	before, while another holder is still using it.
+
+	@class PlayerDataStoreManager.Handles.spec.lua
+]]
+local require = require(script.Parent.loader).load(script)
+
+local DataStoreTestUtils = require("DataStoreTestUtils")
+local Jest = require("Jest")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+-- Returns the resolved value, or fails the spec and returns nil.
+local function awaitValue(promise, label: string): any
+	if not PromiseTestUtils.awaitSettled(promise, 10) then
+		expect(`{label} hung`).toEqual(`{label} settled`)
+		return nil
+	end
+
+	local ok, value = promise:Yield()
+	expect(ok).toEqual(true)
+	return value
+end
+
+-- Drains the removals a test left in flight, so none of them settle during teardown. Note that this
+-- also *removes* every remaining store, so it belongs at the end of a test and nowhere else.
+local function settleSaves(controller): ()
+	if not PromiseTestUtils.awaitSettled(controller.manager:PromiseAllSaves(), 10) then
+		expect("saves hung").toEqual("saves settled")
+	end
+end
+
+describe("PlayerDataStoreManager.PromiseDataStoreHandle", function()
+	it("hands back the store for the player", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.mock:SetRaw("user_1", { coins = 5 })
+
+		local handle = awaitValue(controller.manager:PromiseDataStoreHandle(1), "handle")
+		expect(handle).never.toBeNil()
+		expect(handle:GetDataStore()).never.toBeNil()
+
+		handle:Destroy()
+		settleSaves(controller)
+
+		controller:destroy()
+	end)
+
+	-- Whether the session is still open is read through store identity rather than the stored lock:
+	-- the lock is written asynchronously as the load settles, so asserting on it here would be timing
+	-- dependent. A released session is gone, so the next handle has to build a new store object.
+	it("releases the session once the handle is destroyed", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.mock:SetRaw("user_1", { coins = 5 })
+
+		local first = awaitValue(controller.manager:PromiseDataStoreHandle(1), "first")
+		local released = first:GetDataStore()
+
+		first:Destroy()
+
+		local second = awaitValue(controller.manager:PromiseDataStoreHandle(1), "second")
+		expect(second:GetDataStore() == released).toEqual(false)
+
+		second:Destroy()
+		settleSaves(controller)
+
+		controller:destroy()
+	end)
+
+	it("holds the session while another handle is still open", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.mock:SetRaw("user_1", { coins = 5 })
+
+		local first = awaitValue(controller.manager:PromiseDataStoreHandle(1), "first")
+		local second = awaitValue(controller.manager:PromiseDataStoreHandle(1), "second")
+
+		local shared = first:GetDataStore()
+
+		-- Both name the same session rather than opening a second one.
+		expect(second:GetDataStore() == shared).toEqual(true)
+
+		first:Destroy()
+
+		-- Still the same store, because the second handle never let go of it.
+		local third = awaitValue(controller.manager:PromiseDataStoreHandle(1), "third")
+		expect(third:GetDataStore() == shared).toEqual(true)
+
+		second:Destroy()
+		third:Destroy()
+
+		local fourth = awaitValue(controller.manager:PromiseDataStoreHandle(1), "fourth")
+		expect(fourth:GetDataStore() == shared).toEqual(false)
+
+		fourth:Destroy()
+		settleSaves(controller)
+
+		controller:destroy()
+	end)
+
+	it("survives being destroyed twice", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.mock:SetRaw("user_1", { coins = 5 })
+
+		local handle = awaitValue(controller.manager:PromiseDataStoreHandle(1), "handle")
+		handle:Destroy()
+		handle:Destroy()
+		settleSaves(controller)
+
+		controller:destroy()
+	end)
+
+	it("refuses to hand back a store once destroyed", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.mock:SetRaw("user_1", { coins = 5 })
+
+		local handle = awaitValue(controller.manager:PromiseDataStoreHandle(1), "handle")
+		handle:Destroy()
+		settleSaves(controller)
+
+		expect(function()
+			handle:GetDataStore()
+		end).toThrow()
+
+		controller:destroy()
+	end)
+end)

package/src/Server/PlayerDataStoreManager.RemovalCallbacks.spec.lua

@@ -57,6 +57,7 @@ describe("PlayerDataStoreManager removal matrix (misbehaving removing callbacks)
 				error("removing callback boom")
 			end)
 
+			local dataStore = controller.manager:GetDataStore(1)
 			expect(controller.storeAndAwaitLock()).toEqual(true)
 
 			expect(function()
@@ -64,6 +65,10 @@ describe("PlayerDataStoreManager removal matrix (misbehaving removing callbacks)
 			end).toThrow("removing callback boom")
 			expect(controller.mock:GetRaw("user_1").lock ~= nil).toEqual(true)
 
+			-- The throw latched _removing before the store left _datastores, so no later removal can
+			-- reach it and nothing else destroys it. Kill its auto-save loop by hand, or it outlives this
+			-- spec and fires inside a later package's window.
+			dataStore:Destroy()
 			controller:destroy()
 		end)