@rbxts/dataforge 0.1.0 → 0.4.1

package/src/profile/lockless.luau

@@ -1,5 +1,7 @@
 local common = require "./common"
+local errors = require "../errors"
 local mutex = require "../mutex"
+local result = require "../result"
 local tx_handle = require "../tx/handle"
 local types = require "../types"
 local utils = require "../utils"
@@ -15,7 +17,7 @@ lockless_profile.__index = lockless_profile
 function lockless_profile.get_data(self: LocklessProfile)
 	common.assert_open(self)
 	if not self.fetched then
-		error(`datastore: lockless profile "{self.key}" has not been fetched`)
+		error(errors.not_fetched(self), 0)
 	end
 	return self._data
 end
@@ -67,11 +69,11 @@ local function resolve_record(self: LocklessProfile, record: DataRecord?, data:
 		return utils.deep_copy(config.template), common.all_migration_names(config.migrations)
 	end
 
-	local result = common.apply_migrations(data, applied, config.migrations)
-	if not result.success then
-		error(`datastore: failed to apply migrations for "{self.key}": {result.err}`)
+	local migrated = common.apply_migrations(self.key, data, applied, config.migrations)
+	if not migrated.success then
+		common.raise_migrations(self, migrated)
 	end
-	return result.result, result.new_migrations
+	return migrated.result, migrated.new_migrations
 end
 
 local function replay(queue: Array<types.DataDispatcher<any>>, data: any): any
@@ -108,13 +110,15 @@ local function process_lock_lost(self: LocklessProfile)
 		return
 	end
 	self.open = false
-	self._mutex:close(`datastore: profile "{self.key}" is session locked`)
+	self._mutex:close(errors.profile_closed(self, "lock_lost"))
 	fire_hooks(self, "lock_lost", self._hooks.lock_lost)
 	fire_hooks(self, "closed", self._hooks.closed)
 end
 
 type SaveState = {
 	applied: boolean,
+	--- the lock found on the record (session or transaction), nil when none
+	lock: types.Lock?,
 	--- a live transaction lock is on the record; `tx_lock_expires` says until when
 	tx_locked: boolean,
 	tx_lock_expires: number,
@@ -123,6 +127,9 @@ type SaveState = {
 	tx_lock_lost: boolean,
 	outdated: boolean,
 	unknown_pending: types.Pending?,
+	--- the transform threw (a migration or a queued dispatcher): rethrown after
+	--- the storage call instead of being retried as a storage failure
+	failure: any,
 }
 
 type WriteOptions = types.LocklessWriteOptions
@@ -135,7 +142,13 @@ type WriteOptions = types.LocklessWriteOptions
 --- `self._tx_lock`). `options.old_tx_lock` is the lock this write expects to
 --- find on the record: the write only goes through (and clears that lock) when
 --- the stored lock has the same id. If the lock is gone or belongs to someone
---- else, nothing is written and the call fails with "lock_lost".
+--- else, nothing is written and the call fails with `tx_lock_lost`.
+---
+--- Throws `lockless_locked` (a live session lock; the profile is closed),
+--- `tx_lock_lost` (closed too), `outdated` (a newer server wrote the record;
+--- nothing written), `predicate_failed` (the store's predicate rejected the
+--- stored data; nothing written), `migration_mismatch`, `roblox`, or whatever
+--- a queued dispatcher / migration threw.
 local function write_queued(self: LocklessProfile, options: WriteOptions)
 	local config = self.config
 	local scheduler = config._scheduler
@@ -146,23 +159,19 @@ local function write_queued(self: LocklessProfile, options: WriteOptions)
 
 	local state: SaveState = {
 		applied = false,
+		lock = nil,
 		tx_locked = false,
 		tx_lock_expires = 0,
 		tx_lock_lost = false,
 		session_locked = false,
 		outdated = false,
 		unknown_pending = nil,
+		failure = nil,
 	}
 
-	local function transform(old: DataRecord?): DataRecord?
-		state.applied = false
-		state.tx_locked = false
-		state.session_locked = false
-		state.tx_lock_lost = false
-		state.outdated = false
-		state.unknown_pending = nil
-
+	local function transform_body(old: DataRecord?): DataRecord?
 		local lock = if old then old.lock else nil
+		state.lock = lock
 
 		-- a live session lock means a locked profile owns this key now: the
 		-- profile lost its lockless standing, whatever else it expected on the
@@ -192,11 +201,19 @@ local function write_queued(self: LocklessProfile, options: WriteOptions)
 
 		-- more migrations applied than this server declares: a newer server
 		-- already touched the record, so this server must not write to it
-		if old and old.migrations and #old.migrations > #config.migrations then
+		if common.is_outdated(old, config) then
 			state.outdated = true
 			return nil
 		end
 
+		-- the store's predicate gates the key: a rejected record is not written
+		-- to, and no `pending` of it is resolved
+		local stored = if old then old.data else nil
+		local passed, predicate_failure = common.run_predicate(config, self.key, stored)
+		if not passed then
+			error(predicate_failure or errors.predicate_failed(self.key, "save", stored, self), 0)
+		end
+
 		-- a `pending` left by some transaction (ours after commit, or another
 		-- server's) decides which data this write builds on
 		local base: any = nil
@@ -222,22 +239,45 @@ local function write_queued(self: LocklessProfile, options: WriteOptions)
 		}
 	end
 
+	-- the body runs migrations and queued dispatchers (user code) and may raise
+	-- a `migration_mismatch`: none of those is a storage failure, so the
+	-- storage retry must not see them. They cancel the write and are rethrown.
+	local function transform(old: DataRecord?): DataRecord?
+		state.applied = false
+		state.lock = nil
+		state.tx_locked = false
+		state.session_locked = false
+		state.tx_lock_lost = false
+		state.outdated = false
+		state.unknown_pending = nil
+		state.failure = nil
+
+		local ok, new = pcall(transform_body, old)
+		if not ok then
+			state.failure = new
+			return nil
+		end
+		return new
+	end
+
 	while true do
-		local record = utils.retry(config, function()
-			return datastore.update_async(self.key, transform, self.user_ids)
-		end) :: DataRecord
+		local record = utils.update_async(config, datastore, self.key, transform, self.user_ids) :: DataRecord
+
+		if state.failure ~= nil then
+			error(state.failure, 0)
+		end
 
 		if state.session_locked then
 			self._tx_lock = nil
 			process_lock_lost(self)
-			error(`datastore: "{self.key}" is session locked`)
+			error(errors.lockless_locked(self, state.lock :: types.Lock), 0)
 		end
 
 		if state.tx_lock_lost then
 			-- whatever is on the record now is not ours; do not touch it again
 			self._tx_lock = nil
 			process_lock_lost(self)
-			error(`datastore: lock_lost for "{self.key}"`)
+			error(errors.tx_lock_lost(self, old_tx_lock :: types.Lock, state.lock), 0)
 		end
 
 		if state.tx_locked then
@@ -248,7 +288,8 @@ local function write_queued(self: LocklessProfile, options: WriteOptions)
 
 		if state.outdated then
 			error(
-				`datastore: "{self.key}" was written by a newer server (record has {#record.migrations} applied migrations, this server declares {#config.migrations})`
+				errors.outdated(self.key, record.migrations or {}, common.all_migration_names(config.migrations), self),
+				0
 			)
 		end
 
@@ -307,16 +348,21 @@ end
 
 --- Applies every queued update to the stored data in one update_async and
 --- refreshes the local data with the result. Marks the profile fetched.
---- Throws (keeping the queue) if another server holds a live session lock, or
---- if the record was already written by a newer server (more migrations applied
---- than this server declares). Neither case is retried.
-function lockless_profile.save(self: LocklessProfile)
-	common.assert_open(self)
-	-- before the mutex so hooks can still queue updates that land in this save
-	fire_hooks(self, "save", self._hooks.save)
-	common.assert_open(self)
-	self._mutex:with(function()
-		write_queued(self, {})
+--- Fails (keeping the queue) with `lockless_locked` if another server holds a
+--- live session lock (the profile is closed), `outdated` if the record was
+--- already written by a newer server, `predicate_failed` if the store's
+--- predicate rejected the stored data, `migration_mismatch`, `roblox` or
+--- `profile_closed`. An error thrown by a queued dispatcher propagates as is.
+function lockless_profile.save(self: LocklessProfile): types.Result<nil>
+	return result.capture(function()
+		common.assert_open(self)
+		-- before the mutex so hooks can still queue updates that land in this save
+		fire_hooks(self, "save", self._hooks.save)
+		common.assert_open(self)
+		self._mutex:with(function()
+			write_queued(self, {})
+		end)
+		return nil
 	end)
 end
 
@@ -326,11 +372,15 @@ function lockless_profile.unload(self: LocklessProfile)
 	end
 	-- last chance to queue updates while the profile is still open
 	fire_hooks(self, "closing", self._hooks.closing)
+	-- a closing hook may have unloaded the profile itself
+	if not self.open then
+		return
+	end
 
 	self.open = false
 	self._mutex:lock()
 	-- everything still waiting on the mutex (and anything after) is rejected
-	self._mutex:close(`datastore: profile "{self.key}" is closed`)
+	self._mutex:close(errors.profile_closed(self, "unloaded"))
 	local ok, err = utils.try(function()
 		if #self.queued_updates > 0 or self.dirty_pending then
 			write_queued(self, {})
@@ -338,7 +388,9 @@ function lockless_profile.unload(self: LocklessProfile)
 	end)
 	self._mutex:unlock()
 	if not ok then
-		self.config._hook.warn(`datastore: failed to flush "{self.key}" on unload ({#self.queued_updates} changes lost): {tostring(err)}`)
+		self.config._hook.warn(
+			`datastore: failed to flush "{self.key}" on unload ({#self.queued_updates} changes lost): {tostring(err)}`
+		)
 	end
 	fire_hooks(self, "closed", self._hooks.closed)
 end
@@ -375,24 +427,30 @@ end
 --- Reads the stored record (get_async) into the local data: migrations are
 --- applied, then the queued updates replayed on top, so `get_data()` reflects the
 --- local changes still waiting for a save. Marks the profile fetched. Throws
---- (keeping the queue) if any session lock is on the record. Caller holds the mutex.
+--- (keeping the queue) if any session lock is on the record, or if the store's
+--- predicate rejects the stored data. Caller holds the mutex.
 local function read_record(self: LocklessProfile)
 	local config = self.config
 	local datastore = self._datastore
 
-	local record = utils.retry(config, function()
-		return datastore.get_async(self.key)
-	end) :: DataRecord?
+	local record = utils.get_async(config, datastore, self.key) :: DataRecord?
 
 	local lock = if record then record.lock else nil
 	if lock and not lock.tx and lock.expires > config._scheduler.now() then
 		process_lock_lost(self)
-		error(`datastore: "{self.key}" is session locked`)
+		error(errors.lockless_locked(self, lock), 0)
 	end
 	-- an expired session lock belongs to a dead server: ignored, the next write clears it
 	-- a transaction lock does not matter for a read: the data under it is the
 	-- data until that transaction's `pending` lands (handled below)
 
+	local stored = if record then record.data else nil
+	local passed, predicate_failure = common.run_predicate(config, self.key, stored)
+	if not passed then
+		-- nothing is adopted: the profile keeps whatever it had and stays open
+		error(predicate_failure or errors.predicate_failed(self.key, "fetch", stored, self), 0)
+	end
+
 	-- a `pending` on the record: find out whether it committed (the record is
 	-- left as is; the next write folds it in)
 	local base: any = nil
@@ -414,22 +472,33 @@ local function read_record(self: LocklessProfile)
 	return self._data
 end
 
-function lockless_profile.fetch(self: LocklessProfile)
-	common.assert_open(self)
-	return self._mutex:with(function()
-		return read_record(self)
+--- Fails with `lockless_locked` (a session lock is on the record; the profile
+--- is closed), `outdated` (a newer server wrote the record), `predicate_failed`
+--- (the store's predicate rejected the stored data), `migration_mismatch`,
+--- `roblox`, `tx_marker_invalid` or `profile_closed`. An error thrown by a
+--- queued dispatcher propagates as is.
+function lockless_profile.fetch(self: LocklessProfile): types.Result<any>
+	return result.capture(function()
+		common.assert_open(self)
+		return self._mutex:with(function()
+			return read_record(self)
+		end)
 	end)
 end
 
 --- Queues `dispatcher` to run against the stored data on the next save. When
 --- the profile is fetched, the local data is advanced right away so `get_data()`
 --- reflects the queued change. A dispatcher returning `false` (or nil) is a
---- no-op and is not queued. Waits for any in-flight save/fetch on the mutex.
-function lockless_profile.update(self: LocklessProfile, dispatcher: (any) -> any): boolean
-	common.assert_open(self)
-
-	return self._mutex:with(function()
-		return queue_update(self, dispatcher)
+--- no-op and is not queued (Ok(false)). Waits for any in-flight save/fetch on
+--- the mutex. Fails with `profile_closed`; an error thrown by the dispatcher
+--- propagates as is.
+function lockless_profile.update(self: LocklessProfile, dispatcher: (any) -> any): types.Result<boolean>
+	return result.capture(function()
+		common.assert_open(self)
+
+		return self._mutex:with(function()
+			return queue_update(self, dispatcher)
+		end)
 	end)
 end
 
@@ -449,9 +518,11 @@ local function run_flush_loop(self: LocklessProfile)
 				continue
 			end
 
-			local ok, err = utils.try(self.save, self)
+			local ok, res = utils.try(self.save, self)
 			if not ok then
-				config._hook.warn(`datastore: failed to flush "{self.key}": {tostring(err)}`)
+				config._hook.warn(`datastore: failed to flush "{self.key}": {tostring(res)}`)
+			elseif not res.success then
+				config._hook.warn(`datastore: failed to flush "{self.key}": {tostring(res.error)}`)
 			end
 		end
 	end)

package/src/profile/peek.luau

@@ -1,4 +1,6 @@
 local common = require "./common"
+local errors = require "../errors"
+local result = require "../result"
 local types = require "../types"
 local utils = require "../utils"
 
@@ -16,14 +18,20 @@ peek_profile.__index = peek_profile
 
 --- Reads the record with `GetAsync` and adopts it: `lock` and `pending` are
 --- taken as stored, the data gets the declared migrations applied in memory
---- (nothing is written). A missing key resolves to the template.
+--- (nothing is written). A missing key resolves to the template. Throws
+--- `roblox`, `predicate_failed`, `outdated` or `migration_mismatch`.
 local function read(self: PeekProfile): any
 	local config = self._config
 	local datastore = self._datastore
 
-	local record = utils.retry(config, function()
-		return datastore.get_async(self.key)
-	end) :: DataRecord?
+	local record = utils.get_async(config, datastore, self.key) :: DataRecord?
+
+	-- before anything is adopted: a rejected key leaves the snapshot untouched
+	local stored = if record then record.data else nil
+	local passed, predicate_failure = common.run_predicate(config, self.key, stored)
+	if not passed then
+		error(predicate_failure or errors.predicate_failed(self.key, "peek", stored), 0)
+	end
 
 	self.lock = if record then record.lock else nil
 	self.pending = if record then record.pending else nil
@@ -34,12 +42,12 @@ local function read(self: PeekProfile): any
 		data = utils.deep_copy(config.template)
 		migrations = common.all_migration_names(config.migrations)
 	else
-		local result = common.apply_migrations(record.data, record.migrations or {}, config.migrations)
-		if not result.success then
-			error(`datastore: failed to apply migrations for "{self.key}": {result.err}`)
+		local migrated = common.apply_migrations(self.key, record.data, record.migrations or {}, config.migrations)
+		if not migrated.success then
+			error(migrated.err, 0)
 		end
-		data = result.result
-		migrations = result.new_migrations
+		data = migrated.result
+		migrations = migrated.new_migrations
 	end
 
 	self.migrations = migrations
@@ -51,14 +59,17 @@ function peek_profile.get_data(self: PeekProfile)
 	return self._data
 end
 
---- Calls `get_async` again and replaces the snapshot. Yields.
-function peek_profile.refresh(self: PeekProfile)
-	return read(self)
+--- Calls `get_async` again and replaces the snapshot. Yields. Fails with
+--- `roblox`, `predicate_failed`, `outdated` or `migration_mismatch`, leaving
+--- the previous snapshot in place.
+function peek_profile.refresh(self: PeekProfile): types.Result<any>
+	return result.capture(read, self)
 end
 
 --- Takes the first snapshot right away (yields). The profile has no mutex, no
---- loops and no hooks: it is a plain value that can be refreshed.
-function peek_profile.create(options: PeekOptions): PeekProfile
+--- loops and no hooks: it is a plain value that can be refreshed. Fails with
+--- `roblox`, `predicate_failed`, `outdated` or `migration_mismatch`.
+function peek_profile.create(options: PeekOptions): types.Result<PeekProfile>
 	local self = {} :: PeekProfile
 	self.kind = "peek"
 	self.key = options.key
@@ -70,8 +81,11 @@ function peek_profile.create(options: PeekOptions): PeekProfile
 	self._data = nil :: any
 
 	local profile = setmetatable(self, peek_profile) :: any
-	read(profile)
-	return profile
+	local first = result.capture(read, profile)
+	if not first.success then
+		return first
+	end
+	return result.ok(profile)
 end
 
 return {