@quenty/datastore 13.51.1 → 13.52.0

package/src/Server/PlayerDataStoreManager.lua

@@ -51,16 +51,21 @@
 
 local require = require(script.Parent.loader).load(script)
 
+local HttpService = game:GetService("HttpService")
 local Players = game:GetService("Players")
 local RunService = game:GetService("RunService")
 
 local BaseObject = require("BaseObject")
 local BindToCloseService = require("BindToCloseService")
 local DataStore = require("DataStore")
+local DataStoreLockUtils = require("DataStoreLockUtils")
+local DataStorePromises = require("DataStorePromises")
 local Maid = require("Maid")
 local PendingPromiseTracker = require("PendingPromiseTracker")
+local PlayerDataStoreHandle = require("PlayerDataStoreHandle")
 local PlayerMock = require("PlayerMock")
 local Promise = require("Promise")
+local PromiseRetryUtils = require("PromiseRetryUtils")
 local PromiseUtils = require("PromiseUtils")
 local ServiceBag = require("ServiceBag")
 
@@ -81,9 +86,15 @@ export type PlayerDataStoreManager =
 			_datastores: { [PlayerUserId]: DataStore.DataStore },
 			_removing: { [PlayerUserId]: boolean },
 			_removingPromises: { [PlayerUserId]: Promise.Promise<any> },
+			_handleCounts: { [PlayerUserId]: number },
 			_pendingSaves: PendingPromiseTracker.PendingPromiseTracker<any>,
 			_removingCallbacks: { RemovingCallback },
 			_disableSavingInStudio: boolean?,
+			_hasCreatedDataStore: boolean,
+			_loadRetryOptions: PromiseRetryUtils.RetryOptions?,
+			_autoSaveTimeSeconds: number?,
+			_autoSaveTimeSecondsSet: boolean,
+			_sessionMessagingCloseDelaySeconds: number?,
 		},
 		{} :: typeof({ __index = PlayerDataStoreManager })
 	))
@@ -119,8 +130,11 @@ function PlayerDataStoreManager.new(
 	self._datastores = {} -- [userId] = datastore
 	self._removing = {} -- [player] = true
 	self._removingPromises = {} -- [player] = removal promise
+	self._handleCounts = {} -- [userId] = outstanding PlayerDataStoreHandle count
 	self._pendingSaves = PendingPromiseTracker.new()
 	self._removingCallbacks = {} -- [func, ...]
+	self._hasCreatedDataStore = false
+	self._autoSaveTimeSecondsSet = false
 
 	self._maid:GiveTask(Players.PlayerRemoving:Connect(function(player)
 		if self._disableSavingInStudio then
@@ -155,6 +169,64 @@ function PlayerDataStoreManager.DisableSaveOnCloseStudio(self: PlayerDataStoreMa
 	self._disableSavingInStudio = true
 end
 
+--[=[
+	Overrides the load retry backoff on every datastore this manager creates. See
+	[DataStore.SetLoadRetryOptions].
+
+	This is the knob that decides how long a player waits on a lock held by a dead server: the ladder
+	runs, and only once it is exhausted is the lock stolen unconditionally. Defaults to ~49s.
+
+	:::info
+	Must be set before the first datastore is created.
+	:::
+
+	@param options RetryOptions
+]=]
+function PlayerDataStoreManager.SetLoadRetryOptions(
+	self: PlayerDataStoreManager,
+	options: PromiseRetryUtils.RetryOptions
+): ()
+	assert(not self._hasCreatedDataStore, "Must configure before the first datastore is created")
+	assert(type(options) == "table", "Bad options")
+
+	self._loadRetryOptions = options
+end
+
+--[=[
+	Sets the autosave interval on every datastore this manager creates. See
+	[DataStore.SetAutoSaveTimeSeconds]. Passing nil disables syncing entirely.
+
+	:::info
+	Must be set before the first datastore is created.
+	:::
+
+	@param autoSaveTimeSeconds number?
+]=]
+function PlayerDataStoreManager.SetAutoSaveTimeSeconds(self: PlayerDataStoreManager, autoSaveTimeSeconds: number?): ()
+	assert(not self._hasCreatedDataStore, "Must configure before the first datastore is created")
+	assert(type(autoSaveTimeSeconds) == "number" or autoSaveTimeSeconds == nil, "Bad autoSaveTimeSeconds")
+
+	self._autoSaveTimeSeconds = autoSaveTimeSeconds
+	self._autoSaveTimeSecondsSet = true
+end
+
+--[=[
+	Sets the post-graceful-close replication delay on every datastore this manager creates. See
+	[DataStore.SetSessionMessagingCloseDelaySeconds].
+
+	:::info
+	Must be set before the first datastore is created.
+	:::
+
+	@param seconds number
+]=]
+function PlayerDataStoreManager.SetSessionMessagingCloseDelaySeconds(self: PlayerDataStoreManager, seconds: number): ()
+	assert(not self._hasCreatedDataStore, "Must configure before the first datastore is created")
+	assert(type(seconds) == "number" and seconds >= 0, "Bad seconds")
+
+	self._sessionMessagingCloseDelaySeconds = seconds
+end
+
 --[=[
 	Adds a callback to be called before save on removal
 	@param callback function -- May return a promise
@@ -177,6 +249,93 @@ function PlayerDataStoreManager.RemovePlayerDataStore(
 	self:_removePlayerDataStore(userId)
 end
 
+--[=[
+	Gets the datastore for a player as a counted handle, opening a session if none is live.
+
+	Prefer this over [PlayerDataStoreManager.PromiseDataStore] for anything acting on a player who may
+	not be in this server. Opening their store takes the session lock, which kicks them from wherever
+	they were and keeps them from rejoining until it is dropped -- and destroying the handle is what
+	drops it.
+
+	Handles are counted, so several systems can hold the same player's store at once and the session
+	survives until the last handle is destroyed.
+
+	:::note
+	The join/leave path deliberately does *not* run through handles. Making a player's presence just
+	another reference would be tidier, but removal is reached from several directions already -- a
+	stolen session, a close request, a failed lock, PlayerRemoving, server shutdown -- and a handle
+	leaked on any of them would hold a player's save open instead of closing it, which is worse than
+	the asymmetry. So a handle never removes a store belonging to a player who is in this server;
+	their own path owns that.
+	:::
+
+	@param playerOrUserId Player | number
+	@return Promise<PlayerDataStoreHandle>
+]=]
+function PlayerDataStoreManager.PromiseDataStoreHandle(
+	self: PlayerDataStoreManager,
+	playerOrUserId: Player | PlayerUserId
+): Promise.Promise<PlayerDataStoreHandle.PlayerDataStoreHandle>
+	local userId = self:_toPlayerUserIdOrError(playerOrUserId)
+
+	-- Counted before the open rather than after, so a second caller arriving while this one is still
+	-- loading cannot see a count of zero and release the store out from under it.
+	self._handleCounts[userId] = (self._handleCounts[userId] or 0) + 1
+
+	return self:_promiseDataStoreByUserId(userId):Then(function(dataStore)
+		return PlayerDataStoreHandle.new(dataStore, function()
+			self:_releaseDataStoreHandle(userId)
+		end)
+	end, function(err)
+		-- The open failed, so there is no handle to be destroyed later. Give the count back.
+		self:_releaseDataStoreHandle(userId)
+		return Promise.rejected(err)
+	end)
+end
+
+function PlayerDataStoreManager._releaseDataStoreHandle(self: PlayerDataStoreManager, userId: PlayerUserId): ()
+	local count = self._handleCounts[userId]
+	if not count then
+		return
+	end
+
+	count -= 1
+	if count > 0 then
+		self._handleCounts[userId] = count
+		return
+	end
+
+	self._handleCounts[userId] = nil
+
+	-- A player in this server owns their own session through the join/leave path. Only a store opened
+	-- on behalf of someone absent is ours to close.
+	if Players:GetPlayerByUserId(userId) then
+		return
+	end
+
+	self:_removePlayerDataStore(userId)
+end
+
+--[=[
+	Resolves once any removal in flight for this player has saved and closed their session, and
+	immediately when there is nothing being removed.
+
+	Destroying the last handle for an absent player *starts* the save-and-close; it does not wait for
+	it. Tooling that reports back to an operator waits here first, so it says the lock is released
+	only once the write that releases it has actually landed.
+
+	@param playerOrUserId Player | number
+	@return Promise<()>
+]=]
+function PlayerDataStoreManager.PromiseSessionClosed(
+	self: PlayerDataStoreManager,
+	playerOrUserId: Player | PlayerUserId
+): Promise.Promise<()>
+	local userId = self:_toPlayerUserIdOrError(playerOrUserId)
+
+	return self:_promiseWaitForRemoving(userId)
+end
+
 --[=[
 	Gets the datastore for a player. If it does not exist, it will create one.
 
@@ -279,6 +438,116 @@ function PlayerDataStoreManager:_toPlayerUserIdOrError(playerOrUserId: Player |
 	) :: PlayerUserId
 end
 
+--[=[
+	Reads the session lock on a player's key without opening a session on it.
+
+	This is the read side of the tooling path: it answers "who holds this key, and how stale is that
+	claim", whether or not the player is in this server. Resolves nil when the key is unlocked or
+	absent. Reads the stored key, so for a player in this server it reflects their last save rather
+	than unsaved in-memory state.
+
+	@param playerOrUserId Player | number
+	@return Promise<LockData?>
+]=]
+function PlayerDataStoreManager.PromiseReadSessionLock(
+	self: PlayerDataStoreManager,
+	playerOrUserId: Player | PlayerUserId
+): Promise.Promise<DataStoreLockUtils.LockData?>
+	local userId = self:_toPlayerUserIdOrError(playerOrUserId)
+
+	return DataStorePromises.getAsync(self._robloxDataStore, self:_getKey(userId)):Then(function(data)
+		return DataStoreLockUtils.readLock(data)
+	end)
+end
+
+--[=[
+	Clears the session lock on a player's key with a raw write, releasing a claim left behind by a
+	server that died without closing its session.
+
+	:::warning
+	This is a soft lock. A loading session steals it anyway once its retry ladder is exhausted (see
+	[PlayerDataStoreManager.SetLoadRetryOptions]) -- clearing it early only saves the player that wait.
+	:::
+
+	:::danger
+	Permitted against a session this server holds, which desynchronizes that session from the key --
+	its next save either re-writes the lock or reads this as a theft and kicks the player. That is a
+	debug/stress-test capability, not a normal one.
+	:::
+
+	@param playerOrUserId Player | number
+	@return Promise<LockData?> -- the lock that was cleared, or nil if it was already unlocked
+]=]
+function PlayerDataStoreManager.PromiseUnlockSession(
+	self: PlayerDataStoreManager,
+	playerOrUserId: Player | PlayerUserId
+): Promise.Promise<DataStoreLockUtils.LockData?>
+	return self:_promiseWriteRawSessionLock(self:_toPlayerUserIdOrError(playerOrUserId), nil)
+end
+
+--[=[
+	Claims a player's key with a raw write, under a session this server will never answer for. Parks
+	the key so an inspection is not racing a live server.
+
+	:::warning
+	This is a soft lock, and holds only for as long as a loading session's retry ladder. It is not a
+	way to keep a player out of their data.
+	:::
+
+	:::danger
+	Permitted against a session this server holds, with the same desynchronizing effect described on
+	[PlayerDataStoreManager.PromiseUnlockSession].
+	:::
+
+	@param playerOrUserId Player | number
+	@return Promise<LockData?> -- the lock that was replaced, or nil if it was unlocked
+]=]
+function PlayerDataStoreManager.PromiseLockSession(
+	self: PlayerDataStoreManager,
+	playerOrUserId: Player | PlayerUserId
+): Promise.Promise<DataStoreLockUtils.LockData?>
+	local userId = self:_toPlayerUserIdOrError(playerOrUserId)
+
+	return self:_promiseWriteRawSessionLock(
+		userId,
+		DataStoreLockUtils.createLockData({
+			SessionId = HttpService:GenerateGUID(false),
+			PlaceId = game.PlaceId,
+			JobId = game.JobId,
+		})
+	)
+end
+
+function PlayerDataStoreManager._promiseWriteRawSessionLock(
+	self: PlayerDataStoreManager,
+	userId: PlayerUserId,
+	lockData: DataStoreLockUtils.LockData?
+): Promise.Promise<DataStoreLockUtils.LockData?>
+	-- Deliberately unguarded against a session this server owns. A raw write underneath one
+	-- desynchronizes that session from the key: on its next save it either re-writes this lock, or
+	-- reads it as a theft and kicks the player. That is precisely the failure the lock/unlock tools
+	-- exist to provoke, so stress-testing against a live local session is allowed rather than refused.
+	-- Callers reaching for this outside of debug tooling want the live [DataStore] instead.
+	local previousLock: DataStoreLockUtils.LockData? = nil
+
+	return DataStorePromises.updateAsync(self._robloxDataStore, self:_getKey(userId), function(data, datastoreKeyInfo)
+		previousLock = DataStoreLockUtils.readLock(data)
+
+		-- Nothing stored and nothing to clear, so cancel rather than create an empty entry.
+		if data == nil and lockData == nil then
+			return nil
+		end
+
+		-- UpdateAsync drops both when the transform omits them, so carry them through untouched.
+		local userIdList = if datastoreKeyInfo then datastoreKeyInfo:GetUserIds() else { userId }
+		local metadata = if datastoreKeyInfo then datastoreKeyInfo:GetMetadata() else nil
+
+		return DataStoreLockUtils.withLock(data, lockData), userIdList, metadata
+	end):Then(function()
+		return previousLock
+	end)
+end
+
 --[=[
 	Removes all player data stores, and returns a promise that
 	resolves when all pending saves are saved.
@@ -322,8 +591,21 @@ function PlayerDataStoreManager._createDataStore(
 
 	local maid = Maid.new()
 
+	self._hasCreatedDataStore = true
+
 	-- DataStore is cleaned up very carefully in _removePlayerDataStore
 	local datastore = DataStore.new(self._robloxDataStore, self:_getKey(userId))
+
+	if self._loadRetryOptions then
+		datastore:SetLoadRetryOptions(self._loadRetryOptions)
+	end
+	if self._autoSaveTimeSecondsSet then
+		datastore:SetAutoSaveTimeSeconds(self._autoSaveTimeSeconds)
+	end
+	if self._sessionMessagingCloseDelaySeconds then
+		datastore:SetSessionMessagingCloseDelaySeconds(self._sessionMessagingCloseDelaySeconds)
+	end
+
 	datastore:SetSessionLockingEnabled(true)
 	datastore:SetSessionMessagingEnabled(true, self._serviceBag)
 	datastore:SetUserIdList({ userId })

package/src/Server/PlayerDataStoreManager.spec.lua

@@ -322,3 +322,89 @@ describe("PlayerDataStoreManager server shutdown", function()
 		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

@@ -211,3 +211,68 @@ describe("PlayerDataStoreService server shutdown", function()
 		controller:destroy()
 	end)
 end)
+
+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
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		local _ok, dataStore = promise:Yield()
+
+		expect((dataStore:GetAutoSaveTimeSeconds())).toEqual(14)
+		expect((dataStore:GetLoadRetryOptions())).toEqual(retryOptions)
+		expect((dataStore:GetSessionMessagingCloseDelaySeconds())).toEqual(0.5)
+
+		controller:destroy()
+	end)
+
+	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)