@quenty/datastore 13.51.0 → 13.52.0

package/src/Server/PlayerDataStoreManager.spec.lua

@@ -8,6 +8,7 @@ local DataStoreTestUtils = require("DataStoreTestUtils")
 local Jest = require("Jest")
 local PlayerMock = require("PlayerMock")
 local PromiseTestUtils = require("PromiseTestUtils")
+local PromiseUtils = require("PromiseUtils")
 
 local describe = Jest.Globals.describe
 local expect = Jest.Globals.expect
@@ -189,94 +190,115 @@ describe("PlayerDataStoreManager.PromiseAllSaves", function()
 	end)
 end)
 
-describe("PlayerDataStoreManager teardown", function()
-	it("destroys the datastores it still owns when the manager is destroyed", function()
+-- Models a closing server the way Roblox actually behaves: PlayerRemoving fires for everyone still in
+-- the server and does the save-and-close, and the close is held open until those removals flush.
+describe("PlayerDataStoreManager server shutdown", function()
+	it("saves the staged data and releases the lock for the leaving player", function()
 		local controller = DataStoreTestUtils.setupDataStoreManager()
 
-		local dataStore = controller.manager:GetDataStore(1)
-		if not expectSettled(dataStore:PromiseLoadSuccessful(), 10) then
+		if not controller.storeAndAwaitLock() then
+			expect("lock was never acquired").toEqual("lock was acquired")
 			controller:destroy()
 			return
 		end
 
-		controller.manager:Destroy()
+		if not expectSettled(controller.promiseShutdown({ 1 }), 10) then
+			controller:destroy()
+			return
+		end
 
-		expect(getmetatable(dataStore)).toBeNil()
+		local raw = controller.mock:GetRaw("user_1")
+		expect(raw.coins).toEqual(5)
+		expect(raw.lock).toEqual(nil)
 
 		controller:destroy()
 	end)
 
-	it("flushes staged data synchronously to the underlying store when destroyed", function()
+	it("releases the lock for every player still in the server", function()
 		local controller = DataStoreTestUtils.setupDataStoreManager()
 
-		local dataStore = controller.manager:GetDataStore(1)
-		if not expectSettled(dataStore:PromiseLoadSuccessful(), 10) then
+		controller.manager:GetDataStore(1):Store("coins", 1)
+		controller.manager:GetDataStore(2):Store("coins", 2)
+
+		local locked = PromiseTestUtils.awaitValue(function()
+			local rawOne = controller.mock:GetRaw("user_1")
+			local rawTwo = controller.mock:GetRaw("user_2")
+			return rawOne ~= nil and rawOne.lock ~= nil and rawTwo ~= nil and rawTwo.lock ~= nil
+		end, 10)
+		if not locked then
+			expect("both locks were never acquired").toEqual("both locks were acquired")
 			controller:destroy()
 			return
 		end
 
-		dataStore:Store("coins", 5)
-
-		controller.manager:Destroy()
+		if not expectSettled(controller.promiseShutdown({ 1, 2 }), 10) then
+			controller:destroy()
+			return
+		end
 
-		local raw = controller.mock:GetRaw("user_1")
-		expect(raw).never.toBeNil()
-		expect(raw.coins).toEqual(5)
+		expect(controller.mock:GetRaw("user_1").lock).toEqual(nil)
+		expect(controller.mock:GetRaw("user_2").lock).toEqual(nil)
+		expect(controller.mock:GetRaw("user_1").coins).toEqual(1)
+		expect(controller.mock:GetRaw("user_2").coins).toEqual(2)
 
 		controller:destroy()
 	end)
 
-	it("releases the session lock when destroyed, not just the staged data", function()
+	it("destroys each store once its removal has flushed", function()
 		local controller = DataStoreTestUtils.setupDataStoreManager()
 
-		if not controller.storeAndAwaitLock() then
-			expect("lock was never acquired").toEqual("lock was acquired")
+		local dataStore = controller.manager:GetDataStore(1)
+		if not expectSettled(dataStore:PromiseLoadSuccessful(), 10) then
 			controller:destroy()
 			return
 		end
 
-		controller.manager:Destroy()
+		if not expectSettled(controller.promiseShutdown({ 1 }), 10) then
+			controller:destroy()
+			return
+		end
 
-		expect(PromiseTestUtils.awaitValue(function()
-			local raw = controller.mock:GetRaw("user_1")
-			return raw ~= nil and raw.lock == nil
-		end, 5)).toEqual(true)
-		expect(controller.mock:GetRaw("user_1").coins).toEqual(5)
+		expect(getmetatable(dataStore)).toBeNil()
 
 		controller:destroy()
 	end)
 
-	it("releases the lock for every store it still owns", function()
+	it("does not resolve the close while a PlayerRemoving save is still in flight", function()
 		local controller = DataStoreTestUtils.setupDataStoreManager()
 
-		controller.manager:GetDataStore(1):Store("coins", 1)
-		controller.manager:GetDataStore(2):Store("coins", 2)
+		-- An async removing callback pushes the write past the moment the close is requested, which is
+		-- exactly the window where waiting on pending saves alone finds nothing to wait for.
+		controller.manager:AddRemovingCallback(function()
+			return PromiseUtils.delayed(0.5)
+		end)
 
-		local locked = PromiseTestUtils.awaitValue(function()
-			local rawOne = controller.mock:GetRaw("user_1")
-			local rawTwo = controller.mock:GetRaw("user_2")
-			return rawOne ~= nil and rawOne.lock ~= nil and rawTwo ~= nil and rawTwo.lock ~= nil
-		end, 10)
-		if not locked then
-			expect("both locks were never acquired").toEqual("both locks were acquired")
+		if not controller.storeAndAwaitLock() then
+			expect("lock was never acquired").toEqual("lock was acquired")
 			controller:destroy()
 			return
 		end
 
-		controller.manager:Destroy()
+		-- PlayerRemoving lands first, then the server begins closing.
+		controller.manager:RemovePlayerDataStore(1)
 
-		expect(PromiseTestUtils.awaitValue(function()
-			local rawOne = controller.mock:GetRaw("user_1")
-			local rawTwo = controller.mock:GetRaw("user_2")
-			return rawOne ~= nil and rawOne.lock == nil and rawTwo ~= nil and rawTwo.lock == nil
-		end, 5)).toEqual(true)
-		expect(controller.mock:GetRaw("user_1").coins).toEqual(1)
-		expect(controller.mock:GetRaw("user_2").coins).toEqual(2)
+		local closePromise = controller.manager:PromiseAllSaves()
+		expect(closePromise:IsPending()).toEqual(true)
+
+		if not expectSettled(closePromise, 10) then
+			controller:destroy()
+			return
+		end
+
+		-- The close resolving has to mean the write landed. If it can resolve first, the real server
+		-- dies here with the session still locked and no other server able to release it.
+		local raw = controller.mock:GetRaw("user_1")
+		expect(raw.coins).toEqual(5)
+		expect(raw.lock).toEqual(nil)
 
 		controller:destroy()
 	end)
 
-	it("tears down cleanly when a store's load failed, leaking no rejection and writing no lock", function()
+	it("closes cleanly when a store's load failed, leaking no rejection and writing no lock", function()
 		local controller = DataStoreTestUtils.setupDataStoreManager()
 
 		controller.mock:FailAllRequests()
@@ -290,10 +312,99 @@ describe("PlayerDataStoreManager teardown", function()
 		end
 		expect((loaded:Wait())).toEqual(false)
 
-		controller.manager:Destroy()
+		if not expectSettled(controller.promiseShutdown({ 1 }), 10) then
+			controller:destroy()
+			return
+		end
 
 		expect(controller.mock:GetRaw("user_1")).toBeNil()
 
 		controller:destroy()
 	end)
 end)
+
+describe("PlayerDataStoreManager datastore configuration", function()
+	it("applies the configured autosave interval to created datastores", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.manager:SetAutoSaveTimeSeconds(14)
+
+		local dataStore = controller.manager:GetDataStore(1)
+		expect((dataStore:GetAutoSaveTimeSeconds())).toEqual(14)
+
+		controller:destroy()
+	end)
+
+	it("leaves the datastore default alone when unconfigured", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local dataStore = controller.manager:GetDataStore(1)
+		expect((dataStore:GetAutoSaveTimeSeconds())).toEqual(60 * 5)
+
+		controller:destroy()
+	end)
+
+	it("applies nil autosave (syncing disabled) rather than treating it as unconfigured", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.manager:SetAutoSaveTimeSeconds(nil)
+
+		local dataStore = controller.manager:GetDataStore(1)
+		expect(dataStore:GetAutoSaveTimeSeconds()).toBeNil()
+
+		controller:destroy()
+	end)
+
+	it("configures every datastore it creates, not just the first", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.manager:SetAutoSaveTimeSeconds(14)
+
+		controller.manager:GetDataStore(1)
+		local second = controller.manager:GetDataStore(2)
+		expect((second:GetAutoSaveTimeSeconds())).toEqual(14)
+
+		controller:destroy()
+	end)
+
+	it("rejects configuration once a datastore has been created", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.manager:GetDataStore(1)
+
+		expect(function()
+			controller.manager:SetAutoSaveTimeSeconds(14)
+		end).toThrow()
+		expect(function()
+			controller.manager:SetLoadRetryOptions({ initialWaitTime = 1, maxAttempts = 2, printWarning = false })
+		end).toThrow()
+		expect(function()
+			controller.manager:SetSessionMessagingCloseDelaySeconds(0.5)
+		end).toThrow()
+
+		controller:destroy()
+	end)
+
+	it("forwards load retry options to created datastores", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local retryOptions = { exponential = 1, initialWaitTime = 0.1, maxAttempts = 2, printWarning = false }
+		controller.manager:SetLoadRetryOptions(retryOptions)
+
+		local dataStore = controller.manager:GetDataStore(1)
+		expect((dataStore:GetLoadRetryOptions())).toEqual(retryOptions)
+
+		controller:destroy()
+	end)
+
+	it("forwards the session messaging close delay to created datastores", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.manager:SetSessionMessagingCloseDelaySeconds(0.5)
+
+		local dataStore = controller.manager:GetDataStore(1)
+		expect((dataStore:GetSessionMessagingCloseDelaySeconds())).toEqual(0.5)
+
+		controller:destroy()
+	end)
+end)

package/src/Server/PlayerDataStoreService.lua

@@ -11,8 +11,10 @@ local require = require(script.Parent.loader).load(script)
 local DataStore = require("DataStore")
 local DataStorePromises = require("DataStorePromises")
 local Maid = require("Maid")
+local PlayerDataStoreHandle = require("PlayerDataStoreHandle")
 local PlayerDataStoreManager = require("PlayerDataStoreManager")
 local Promise = require("Promise")
+local PromiseRetryUtils = require("PromiseRetryUtils")
 local ServiceBag = require("ServiceBag")
 
 local PlayerDataStoreService = {}
@@ -28,6 +30,10 @@ export type PlayerDataStoreService = typeof(setmetatable(
 		_bindToCloseService: any,
 		_promiseStarted: Promise.Promise<()>,
 		_robloxDataStoreOverride: any?,
+		_loadRetryOptions: PromiseRetryUtils.RetryOptions?,
+		_autoSaveTimeSeconds: number?,
+		_autoSaveTimeSecondsSet: boolean,
+		_sessionMessagingCloseDelaySeconds: number?,
 	},
 	{} :: typeof({ __index = PlayerDataStoreService })
 ))
@@ -44,10 +50,14 @@ function PlayerDataStoreService.Init(self: PlayerDataStoreService, serviceBag: S
 	self._bindToCloseService = self._serviceBag:GetService(require("BindToCloseService"))
 	self._serviceBag:GetService(require("PlaceMessagingService"))
 
+	-- Internal
+	self._serviceBag:GetService(require("DataStoreCmdrService"))
+
 	-- State
 	self._promiseStarted = self._maid:Add(Promise.new())
 	self._dataStoreName = "PlayerData"
 	self._dataStoreScope = "SaveData"
+	self._autoSaveTimeSecondsSet = false
 end
 
 --[=[
@@ -92,6 +102,65 @@ function PlayerDataStoreService.SetDataStoreScope(self: PlayerDataStoreService,
 	self._dataStoreScope = dataStoreScope
 end
 
+--[=[
+	Overrides the load retry backoff on every player datastore. See
+	[PlayerDataStoreManager.SetLoadRetryOptions] -- this is what decides how long a player waits on a
+	lock held by a dead server before it is stolen.
+
+	:::info
+	Must be done before start and after init.
+	:::
+
+	@param options RetryOptions
+]=]
+function PlayerDataStoreService.SetLoadRetryOptions(
+	self: PlayerDataStoreService,
+	options: PromiseRetryUtils.RetryOptions
+): ()
+	assert(type(options) == "table", "Bad options")
+	assert(self._promiseStarted, "Not initialized")
+	assert(self._promiseStarted:IsPending(), "Already started, cannot configure")
+
+	self._loadRetryOptions = options
+end
+
+--[=[
+	Sets the autosave interval on every player datastore. See
+	[PlayerDataStoreManager.SetAutoSaveTimeSeconds].
+
+	:::info
+	Must be done before start and after init.
+	:::
+
+	@param autoSaveTimeSeconds number?
+]=]
+function PlayerDataStoreService.SetAutoSaveTimeSeconds(self: PlayerDataStoreService, autoSaveTimeSeconds: number?): ()
+	assert(type(autoSaveTimeSeconds) == "number" or autoSaveTimeSeconds == nil, "Bad autoSaveTimeSeconds")
+	assert(self._promiseStarted, "Not initialized")
+	assert(self._promiseStarted:IsPending(), "Already started, cannot configure")
+
+	self._autoSaveTimeSeconds = autoSaveTimeSeconds
+	self._autoSaveTimeSecondsSet = true
+end
+
+--[=[
+	Sets the post-graceful-close replication delay on every player datastore. See
+	[PlayerDataStoreManager.SetSessionMessagingCloseDelaySeconds].
+
+	:::info
+	Must be done before start and after init.
+	:::
+
+	@param seconds number
+]=]
+function PlayerDataStoreService.SetSessionMessagingCloseDelaySeconds(self: PlayerDataStoreService, seconds: number): ()
+	assert(type(seconds) == "number" and seconds >= 0, "Bad seconds")
+	assert(self._promiseStarted, "Not initialized")
+	assert(self._promiseStarted:IsPending(), "Already started, cannot configure")
+
+	self._sessionMessagingCloseDelaySeconds = seconds
+end
+
 --[=[
 	Injects the underlying datastore the manager wraps, instead of resolving a real one. Accepts
 	a real datastore or a [DataStoreMock]. Intended for testing; must be called before the manager
@@ -126,6 +195,39 @@ function PlayerDataStoreService.PromiseDataStore(
 	end)
 end
 
+--[=[
+	Borrows the player's [DataStore] as a [PlayerDataStoreHandle], which releases the session when
+	destroyed. Prefer this over [PlayerDataStoreService.PromiseDataStore] when acting on a player by
+	userId, since it is what makes the release hard to forget -- see [PlayerDataStoreHandle].
+
+	@param playerOrUserId Player | number
+	@return Promise<PlayerDataStoreHandle>
+]=]
+function PlayerDataStoreService.PromiseDataStoreHandle(
+	self: PlayerDataStoreService,
+	playerOrUserId: Player | number
+): Promise.Promise<PlayerDataStoreHandle.PlayerDataStoreHandle>
+	return self:PromiseManager():Then(function(manager)
+		return manager:PromiseDataStoreHandle(playerOrUserId)
+	end)
+end
+
+--[=[
+	Resolves once any removal in flight for this player has saved and closed their session -- see
+	[PlayerDataStoreManager.PromiseSessionClosed].
+
+	@param playerOrUserId Player | number
+	@return Promise<()>
+]=]
+function PlayerDataStoreService.PromiseSessionClosed(
+	self: PlayerDataStoreService,
+	playerOrUserId: Player | number
+): Promise.Promise<()>
+	return self:PromiseManager():Then(function(manager)
+		return manager:PromiseSessionClosed(playerOrUserId)
+	end)
+end
+
 --[=[
 	Adds a removing callback to the manager.
 	@param callback function -- May return a promise
@@ -167,6 +269,16 @@ function PlayerDataStoreService.PromiseManager(
 				end
 			end, true))
 
+			if self._loadRetryOptions then
+				manager:SetLoadRetryOptions(self._loadRetryOptions)
+			end
+			if self._autoSaveTimeSecondsSet then
+				manager:SetAutoSaveTimeSeconds(self._autoSaveTimeSeconds)
+			end
+			if self._sessionMessagingCloseDelaySeconds then
+				manager:SetSessionMessagingCloseDelaySeconds(self._sessionMessagingCloseDelaySeconds)
+			end
+
 			-- A lot safer if we're hot reloading or need to monitor bind to close calls
 			self._maid:GiveTask(self._bindToCloseService:RegisterPromiseOnCloseCallback(function()
 				return manager:PromiseAllSaves()

package/src/Server/PlayerDataStoreService.spec.lua

@@ -5,8 +5,10 @@
 local require = require(script.Parent.loader).load(script)
 
 local DataStoreMock = require("DataStoreMock")
+local DataStoreTestUtils = require("DataStoreTestUtils")
 local Jest = require("Jest")
 local Maid = require("Maid")
+local Promise = require("Promise")
 local PromiseTestUtils = require("PromiseTestUtils")
 local ServiceBag = require("ServiceBag")
 
@@ -26,10 +28,26 @@ local function setup(mock)
 		serviceBag:Start()
 	end
 
+	-- Drives the real close path: the manager the service owns, shut down the way Roblox does. Without a
+	-- mock the bag was never started, so there is no manager to reach and nothing to shut down.
+	local function promiseShutdown(userIds)
+		if not mock then
+			return Promise.resolved()
+		end
+
+		return service:PromiseManager():Then(function(manager)
+			return DataStoreTestUtils.promiseSimulatedShutdown(manager, userIds)
+		end)
+	end
+
 	return {
 		service = service,
 		mock = mock,
+		promiseShutdown = promiseShutdown,
 		destroy = function()
+			-- Otherwise a store the spec loaded outlives it with its auto-save loop running, and fires
+			-- inside a later package's window in the shared test place.
+			PromiseTestUtils.awaitSettled(promiseShutdown(), 5)
 			maid:DoCleaning()
 		end,
 	}
@@ -157,8 +175,10 @@ describe("PlayerDataStoreService failure handling", function()
 	end)
 end)
 
-describe("PlayerDataStoreService teardown", function()
-	it("destroys the datastore its manager owns when the service is destroyed", function()
+-- The service registers manager:PromiseAllSaves() as its BindToClose callback, so a closing server is
+-- PlayerRemoving doing the save-and-close with that callback held open until it flushes.
+describe("PlayerDataStoreService server shutdown", function()
+	it("saves the staged data and destroys the store when the server closes", function()
 		local controller = setup(DataStoreMock.new())
 
 		local promise = controller.service:PromiseDataStore(1)
@@ -175,13 +195,55 @@ describe("PlayerDataStoreService teardown", function()
 			return
 		end
 
-		controller:destroy()
+		dataStore:Store("coins", 7)
 
+		if not PromiseTestUtils.awaitSettled(controller.promiseShutdown({ 1 }), 10) then
+			expect("shutdown never flushed").toEqual("shutdown flushed")
+			controller:destroy()
+			return
+		end
+
+		local raw = controller.mock:GetRaw("1")
+		expect(raw).never.toBeNil()
+		expect(raw.coins).toEqual(7)
 		expect(getmetatable(dataStore)).toBeNil()
+
+		controller:destroy()
 	end)
+end)
 
-	it("flushes staged data synchronously to the underlying store when destroyed", function()
-		local controller = setup(DataStoreMock.new())
+describe("PlayerDataStoreService datastore configuration", function()
+	-- The shared setup() starts the bag as soon as it has a mock, and these setters must land between
+	-- Init and Start -- the same window SetDataStoreName uses.
+	local function setupConfigured(configure)
+		local maid = Maid.new()
+
+		local mock = DataStoreMock.new()
+		local serviceBag = maid:Add(ServiceBag.new())
+		local service = serviceBag:GetService(require("PlayerDataStoreService"))
+		serviceBag:Init()
+
+		service:SetRobloxDataStore(mock)
+		configure(service)
+		serviceBag:Start()
+
+		return {
+			service = service,
+			mock = mock,
+			destroy = function()
+				DataStoreTestUtils.awaitServiceShutdown(service)
+				maid:DoCleaning()
+			end,
+		}
+	end
+
+	it("forwards configuration through to the datastores the manager creates", function()
+		local retryOptions = { exponential = 1, initialWaitTime = 0.1, maxAttempts = 2, printWarning = false }
+		local controller = setupConfigured(function(service)
+			service:SetAutoSaveTimeSeconds(14)
+			service:SetLoadRetryOptions(retryOptions)
+			service:SetSessionMessagingCloseDelaySeconds(0.5)
+		end)
 
 		local promise = controller.service:PromiseDataStore(1)
 		if not PromiseTestUtils.awaitSettled(promise, 10) then
@@ -191,18 +253,26 @@ describe("PlayerDataStoreService teardown", function()
 		end
 		local _ok, dataStore = promise:Yield()
 
-		if not PromiseTestUtils.awaitSettled(dataStore:PromiseLoadSuccessful(), 10) then
-			expect("load hung").toEqual("load settled")
-			controller:destroy()
-			return
-		end
-
-		dataStore:Store("coins", 7)
+		expect((dataStore:GetAutoSaveTimeSeconds())).toEqual(14)
+		expect((dataStore:GetLoadRetryOptions())).toEqual(retryOptions)
+		expect((dataStore:GetSessionMessagingCloseDelaySeconds())).toEqual(0.5)
 
 		controller:destroy()
+	end)
 
-		local raw = controller.mock:GetRaw("1")
-		expect(raw).never.toBeNil()
-		expect(raw.coins).toEqual(7)
+	it("rejects configuration after start", function()
+		local controller = setupConfigured(function() end)
+
+		expect(function()
+			controller.service:SetAutoSaveTimeSeconds(14)
+		end).toThrow()
+		expect(function()
+			controller.service:SetLoadRetryOptions({ initialWaitTime = 1, maxAttempts = 2, printWarning = false })
+		end).toThrow()
+		expect(function()
+			controller.service:SetSessionMessagingCloseDelaySeconds(0.5)
+		end).toThrow()
+
+		controller:destroy()
 	end)
 end)

package/src/Shared/Cmdr/DataStoreCmdrUtils.lua

@@ -0,0 +1,57 @@
+--!strict
+--[=[
+	Shared plumbing for the datastore Cmdr commands. Runs on both realms, so nothing here may reach
+	for a store -- those live on the server.
+
+	@class DataStoreCmdrUtils
+]=]
+
+local DataStoreCmdrUtils = {}
+
+--[=[
+	Splits a slash-delimited sub-store path into its segments, dropping empty ones so a stray or
+	trailing slash is forgiving rather than an error. An empty path means the root store.
+
+	@param text string
+	@return { string }
+]=]
+function DataStoreCmdrUtils.parsePath(text: string): { string }
+	assert(type(text) == "string", "Bad text")
+
+	local path = {}
+	for segment in string.gmatch(text, "[^/]+") do
+		table.insert(path, segment)
+	end
+
+	return path
+end
+
+--[=[
+	Registers the sub-store path type.
+
+	Cmdr resolves types against the executor, who cannot see another player's stores, so a path is
+	accepted as typed rather than completed against anything.
+
+	@param cmdr Cmdr
+]=]
+function DataStoreCmdrUtils.registerSubStoreType(cmdr: any): ()
+	local subStore = {
+		Transform = function(text: string)
+			if text ~= "" then
+				return { text }
+			end
+
+			return {}
+		end,
+		Validate = function(keys: { string })
+			return #keys > 0, "Not a sub-store path."
+		end,
+		Parse = function(keys: { string })
+			return DataStoreCmdrUtils.parsePath(keys[1])
+		end,
+	}
+
+	cmdr.Registry:RegisterType("dataStoreSubStore", subStore)
+end
+
+return DataStoreCmdrUtils