@quenty/datastore 13.51.1 → 13.52.1

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.SessionLockTools.spec.lua

@@ -0,0 +1,228 @@
+--!strict
+--[[
+	The raw session-lock path: reading and writing the lock on a key without opening a session on it.
+	Usually the target is a player who is not in this server, but the write is deliberately permitted
+	against a live local session too -- see the last describe block.
+
+	@class PlayerDataStoreManager.SessionLockTools.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
+
+local FOREIGN_SESSION = {
+	SessionId = "foreign-session",
+	PlaceId = 123,
+	JobId = "foreign-job",
+}
+
+local function seedForeignLock(mock, key: string, profile: { [string]: any }?)
+	local data: { [string]: any } = profile or {}
+	data.lock = {
+		LastUpdateTime = os.time(),
+		ActiveSession = FOREIGN_SESSION,
+	}
+	mock:SetRaw(key, data)
+end
+
+-- 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
+
+describe("PlayerDataStoreManager.PromiseReadSessionLock", function()
+	it("resolves nil for a key that was never written", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local lock = awaitValue(controller.manager:PromiseReadSessionLock(1), "read")
+		expect(lock).toBeNil()
+
+		controller:destroy()
+	end)
+
+	it("reports the session holding a foreign lock", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		seedForeignLock(controller.mock, "user_1", { coins = 5 })
+
+		local lock = awaitValue(controller.manager:PromiseReadSessionLock(1), "read")
+		expect(lock).never.toBeNil()
+		expect(lock.ActiveSession).toEqual(FOREIGN_SESSION)
+
+		controller:destroy()
+	end)
+
+	it("resolves nil for a stored profile with no lock", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.mock:SetRaw("user_1", { coins = 5 })
+
+		local lock = awaitValue(controller.manager:PromiseReadSessionLock(1), "read")
+		expect(lock).toBeNil()
+
+		controller:destroy()
+	end)
+end)
+
+describe("PlayerDataStoreManager.PromiseUnlockSession", function()
+	it("clears a foreign lock and reports what it cleared", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		seedForeignLock(controller.mock, "user_1", { coins = 5 })
+
+		local previous = awaitValue(controller.manager:PromiseUnlockSession(1), "unlock")
+		expect(previous).never.toBeNil()
+		expect(previous.ActiveSession).toEqual(FOREIGN_SESSION)
+
+		expect(controller.mock:GetRaw("user_1").lock).toBeNil()
+
+		controller:destroy()
+	end)
+
+	it("leaves the rest of the profile untouched", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		seedForeignLock(controller.mock, "user_1", { coins = 5, level = 3 })
+
+		awaitValue(controller.manager:PromiseUnlockSession(1), "unlock")
+
+		local raw = controller.mock:GetRaw("user_1")
+		expect(raw.coins).toEqual(5)
+		expect(raw.level).toEqual(3)
+
+		controller:destroy()
+	end)
+
+	it("resolves nil on an already-unlocked key", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.mock:SetRaw("user_1", { coins = 5 })
+
+		local previous = awaitValue(controller.manager:PromiseUnlockSession(1), "unlock")
+		expect(previous).toBeNil()
+
+		controller:destroy()
+	end)
+
+	it("does not create an entry for a key that was never written", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		awaitValue(controller.manager:PromiseUnlockSession(1), "unlock")
+
+		expect(controller.mock:GetRaw("user_1")).toBeNil()
+
+		controller:destroy()
+	end)
+end)
+
+describe("PlayerDataStoreManager.PromiseLockSession", function()
+	it("claims an unlocked key", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.mock:SetRaw("user_1", { coins = 5 })
+
+		local previous = awaitValue(controller.manager:PromiseLockSession(1), "lock")
+		expect(previous).toBeNil()
+
+		local lock = awaitValue(controller.manager:PromiseReadSessionLock(1), "read")
+		expect(lock).never.toBeNil()
+		expect(lock.ActiveSession.PlaceId).toEqual(game.PlaceId)
+		expect(controller.mock:GetRaw("user_1").coins).toEqual(5)
+
+		controller:destroy()
+	end)
+
+	it("reports the lock it replaced", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		seedForeignLock(controller.mock, "user_1", { coins = 5 })
+
+		local previous = awaitValue(controller.manager:PromiseLockSession(1), "lock")
+		expect(previous).never.toBeNil()
+		expect(previous.ActiveSession).toEqual(FOREIGN_SESSION)
+
+		controller:destroy()
+	end)
+
+	it("claims a key that was never written", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		awaitValue(controller.manager:PromiseLockSession(1), "lock")
+
+		local lock = awaitValue(controller.manager:PromiseReadSessionLock(1), "read")
+		expect(lock).never.toBeNil()
+
+		controller:destroy()
+	end)
+end)
+
+describe("PlayerDataStoreManager raw lock writes against a live session", function()
+	-- Allowed on purpose: pulling the key out from under a live local session is the failure the
+	-- lock/unlock debug tools exist to provoke. See PlayerDataStoreManager._promiseWriteRawSessionLock.
+	it("writes the lock while this server holds a session for that user", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		if not controller.storeAndAwaitLock() then
+			expect("lock was never acquired").toEqual("lock was acquired")
+			controller:destroy()
+			return
+		end
+
+		local previous = awaitValue(controller.manager:PromiseUnlockSession(1), "unlock")
+		expect(previous).never.toBeNil()
+		expect(previous.ActiveSession.JobId).toEqual(game.JobId)
+		expect(controller.mock:GetRaw("user_1").lock).toBeNil()
+
+		controller:destroy()
+	end)
+
+	it("still serves a read while this server holds a session", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		if not controller.storeAndAwaitLock() then
+			expect("lock was never acquired").toEqual("lock was acquired")
+			controller:destroy()
+			return
+		end
+
+		local lock = awaitValue(controller.manager:PromiseReadSessionLock(1), "read")
+		expect(lock).never.toBeNil()
+		expect(lock.ActiveSession.JobId).toEqual(game.JobId)
+
+		controller:destroy()
+	end)
+
+	it("writes once the session has been removed", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		if not controller.storeAndAwaitLock() then
+			expect("lock was never acquired").toEqual("lock was acquired")
+			controller:destroy()
+			return
+		end
+
+		if not PromiseTestUtils.awaitSettled(controller.promiseShutdown({ 1 }), 10) then
+			expect("shutdown hung").toEqual("shutdown settled")
+			controller:destroy()
+			return
+		end
+
+		awaitValue(controller.manager:PromiseLockSession(1), "lock")
+		expect(controller.mock:GetRaw("user_1").lock).never.toBeNil()
+
+		controller:destroy()
+	end)
+end)