without-durability-sqlite 0.0.6__tar.gz → 0.0.8__tar.gz

{without_durability_sqlite-0.0.6 → without_durability_sqlite-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: without-durability-sqlite
-Version: 0.0.6
+Version: 0.0.8
 Summary: A without-durability checkpoint store and queue backed by one SQLite file, with no server and no third-party driver.
 Author: Josh Karpel
 Author-email: Josh Karpel <josh.karpel@gmail.com>
@@ -14,8 +14,8 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
-Requires-Dist: without-async==0.0.6
-Requires-Dist: without-durability==0.0.6
+Requires-Dist: without-async==0.0.8
+Requires-Dist: without-durability==0.0.8
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 
@@ -44,8 +44,8 @@ There is one writer at a time by construction, so `BEGIN IMMEDIATE` takes the
 write lock for the whole transaction and the fence check and the write it guards
 cannot be interleaved: Postgres needs `FOR UPDATE` on the claim row to get that
 and Redis needs a Lua script, while here the transaction *is* the exclusion. And
-there is nothing to co-locate, because the datastore is a file, so `transact` and
-`arrive` reach every table an application keeps in it. That last one is the same
+there is nothing to co-locate, because the datastore is a file, so `transact`,
+`arrive`, and `deliver` reach every table an application keeps in it. That last one is the same
 guarantee DBOS gets from Postgres, for an application that never needed Postgres.
 
 What it costs is the shape of the whole thing: one machine. Every process sharing

{without_durability_sqlite-0.0.6 → without_durability_sqlite-0.0.8}/README.md

@@ -23,8 +23,8 @@ There is one writer at a time by construction, so `BEGIN IMMEDIATE` takes the
 write lock for the whole transaction and the fence check and the write it guards
 cannot be interleaved: Postgres needs `FOR UPDATE` on the claim row to get that
 and Redis needs a Lua script, while here the transaction *is* the exclusion. And
-there is nothing to co-locate, because the datastore is a file, so `transact` and
-`arrive` reach every table an application keeps in it. That last one is the same
+there is nothing to co-locate, because the datastore is a file, so `transact`,
+`arrive`, and `deliver` reach every table an application keeps in it. That last one is the same
 guarantee DBOS gets from Postgres, for an application that never needed Postgres.
 
 What it costs is the shape of the whole thing: one machine. Every process sharing

{without_durability_sqlite-0.0.6 → without_durability_sqlite-0.0.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "without-durability-sqlite"
-version = "0.0.6"
+version = "0.0.8"
 description = "A without-durability checkpoint store and queue backed by one SQLite file, with no server and no third-party driver."
 readme = "README.md"
 license = "MIT"
@@ -21,8 +21,8 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "without-async==0.0.6",
-    "without-durability==0.0.6",
+    "without-async==0.0.8",
+    "without-durability==0.0.8",
 ]
 
 [[project.authors]]

{without_durability_sqlite-0.0.6 → without_durability_sqlite-0.0.8}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "without-durability-sqlite"
-version = "0.0.6"
+version = "0.0.8"
 description = "A without-durability checkpoint store and queue backed by one SQLite file, with no server and no third-party driver."
 readme = "README.md"
 license = "MIT"
@@ -24,8 +24,8 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "without-async==0.0.6",
-    "without-durability==0.0.6",
+    "without-async==0.0.8",
+    "without-durability==0.0.8",
 ]
 
 [tool.uv.sources]

{without_durability_sqlite-0.0.6 → without_durability_sqlite-0.0.8}/src/without_durability_sqlite/store.py

@@ -11,7 +11,7 @@
 #     be interleaved with anything. Postgres needs `FOR UPDATE` on the claim row to get
 #     that, because there readers and writers run concurrently and a statement's snapshot
 #     can be stale; Redis needs a Lua script. Here the transaction *is* the exclusion.
-#   - There is nothing to co-locate. `transact` and `arrive` reach the whole datastore
+#   - There is nothing to co-locate. `transact`, `arrive`, and `deliver` reach the whole datastore
 #     because the datastore is a file, so the question the other two stores have to keep
 #     asking (are these two writes in one local commit?) has one answer and it is yes.
 #
@@ -59,6 +59,7 @@ from collections.abc import Callable
 from contextlib import closing
 from dataclasses import dataclass
 from dataclasses import field
+from datetime import UTC
 from datetime import datetime
 from datetime import timedelta
 from pathlib import Path
@@ -68,11 +69,15 @@ from typing import cast
 from without_async import Milliseconds
 from without_durability.codec import JSON
 from without_durability.codec import CheckpointCodec
+from without_durability.interfaces import INBOX
+from without_durability.interfaces import INBOX_DIGITS
 from without_durability.interfaces import LEASE
 from without_durability.interfaces import Delivery
+from without_durability.interfaces import Entry
 from without_durability.interfaces import Fenced
 from without_durability.interfaces import Pass
 from without_durability.interfaces import Recorded
+from without_durability.interfaces import Written
 from without_durability.interfaces import check_duration
 from without_durability.stepwise import now_utc
 
@@ -89,19 +94,49 @@ BUSY_TIMEOUT = Milliseconds(5_000)
 # `value` is TEXT rather than a richer type, which is the same shape the Redis store's
 # hash field has and leaves the same question open: what goes *in* the text is the
 # store's injected `CheckpointCodec`, defaulting to JSON because that is what makes a
-# checkpoint readable by anything that can open the file. `WITHOUT ROWID` because every
-# one of these tables is addressed by its primary key and never by a rowid, so the extra
-# indirection would be pure overhead.
+# checkpoint readable by anything that can open the file.
 #
 # `NOT NULL` on `value` keeps "no row" and "a row holding JSON null" distinguishable, so
 # a step that legitimately records `None` is not read back as a step that never ran.
+#
+# `seq` is what `load`'s ordering guarantee rests on, and it is the same column Postgres
+# names: assigned on insert, in insertion order, and left alone by the conflict update
+# below, which is exactly the property the guarantee needs. The writer that first recorded
+# a step decides where it sits, and a later write that loses moves neither the value nor
+# the position. Nothing else here is a candidate, since the only other order on offer is
+# the unique index's, which is step name: a different question with a plausible enough
+# answer to pass a careless test.
+#
+# `INTEGER PRIMARY KEY` makes it an alias for the rowid rather than a column beside one,
+# so it costs no storage and needs no sequence. Naming it is not decoration either. SQLite
+# reserves the right to renumber rowids in "any tables that do not have an explicit INTEGER
+# PRIMARY KEY" when a database is `VACUUM`ed, and this store hands an operator a file it
+# invites any tool to open, so the guarantee would otherwise rest on a promise SQLite
+# declines to make. Declaring the column is what puts this table outside that sentence.
+#
+# `written_at` is what `history` reads, and its `DEFAULT` does the same work `seq` does:
+# evaluated on insert, and left alone by every conflict update below, so a losing write
+# moves the value, the position, and the time equally not at all. The clock is SQL's for
+# the reason the claim's is, which here is consistency with the other two stores rather
+# than a guarantee: SQLite *is* the caller's machine, so there are no two clocks to
+# disagree.
+#
+# `(workflow, step)` is `UNIQUE` rather than the primary key because a table gets one
+# primary key and `seq` is now it. Nothing else changes: both columns are `NOT NULL`, so
+# the constraint admits exactly the rows the primary key did, and it is still what the
+# upserts below name as their conflict target.
+#
+# The claim and queue tables stay `WITHOUT ROWID` because each is addressed by its primary
+# key and never by a position, so for those the indirection would be pure overhead.
 SCHEMA = """
 CREATE TABLE IF NOT EXISTS workflow_checkpoint (
+    seq INTEGER PRIMARY KEY,
     workflow TEXT NOT NULL,
     step TEXT NOT NULL,
     value TEXT NOT NULL,
-    PRIMARY KEY (workflow, step)
-) WITHOUT ROWID;
+    written_at REAL NOT NULL DEFAULT (unixepoch('now', 'subsec')),
+    UNIQUE (workflow, step)
+);
 
 CREATE TABLE IF NOT EXISTS workflow_claim (
     workflow TEXT PRIMARY KEY,
@@ -169,14 +204,59 @@ ON CONFLICT (workflow, step) DO UPDATE SET value = workflow_checkpoint.value
 RETURNING value
 """
 
+# `supply` under a key this statement mints instead of one the caller brought: the append
+# that puts a message in a workflow's inbox.
+#
+# The number is the highest `seq` in the table plus one, which is global rather than per
+# workflow and so leaves gaps in any one workflow's run of keys. That is what the contract
+# allows and what makes this a single statement: a per-workflow count would be a second
+# read, and reading a maximum and then inserting against it is the exact race that would
+# need a transaction to close. There are no concurrent writers here to lose it to, since
+# SQLite admits one, but the store that has them (Postgres) reaches for the same shape and
+# the two are easier to hold in one head this way.
+#
+# There is no `ON CONFLICT` clause and deliberately none: the key is fresh by construction,
+# so a collision means the numbering is broken and a `UNIQUE` violation is the loud version
+# of that. An upsert here would quietly hand back somebody else's message instead.
+APPEND = f"""
+INSERT INTO workflow_checkpoint (workflow, step, value)
+SELECT
+    :workflow,
+    '{INBOX}' || printf('%0{INBOX_DIGITS}d', COALESCE((SELECT MAX(seq) FROM workflow_checkpoint), 0) + 1),
+    :value
+RETURNING step, value
+"""
+
 FENCE = "SELECT token FROM workflow_claim WHERE workflow = ?"
 ALREADY = "SELECT value FROM workflow_checkpoint WHERE workflow = ? AND step = ?"
 WRITE = "INSERT INTO workflow_checkpoint (workflow, step, value) VALUES (?, ?, ?)"
-LOAD = "SELECT step, value FROM workflow_checkpoint WHERE workflow = ?"
+# `ORDER BY seq` is the whole of the ordering guarantee, and it is load-bearing rather
+# than a formality: `WHERE workflow = ?` is served by the unique index on
+# `(workflow, step)`, so without it the rows come back sorted by step name.
+LOAD = "SELECT step, value FROM workflow_checkpoint WHERE workflow = ? ORDER BY seq"
+HISTORY = "SELECT step, value, written_at FROM workflow_checkpoint WHERE workflow = ? ORDER BY seq"
 # Hand the workflow back early, but keep the token, so the next claim gets the next
 # number up and a pass that comes back from the dead still loses.
 RELEASE = "UPDATE workflow_claim SET held_until = unixepoch('now', 'subsec') WHERE workflow = ? AND token = ?"
 
+# Forget every record a workflow has. Paired with `SUPERSEDE` below and never run without
+# it, which is what the transaction in `discard` is for.
+DISCARD = "DELETE FROM workflow_checkpoint WHERE workflow = ?"
+
+# Take the fencing token *up*, so a pass still holding one is refused at its next write.
+#
+# An `UPDATE` rather than the upsert `CLAIM` is, and the difference is what it declines to
+# do: a workflow with no claim row has no `Pass` outstanding, since a `Pass` is only ever
+# handed out by a `claim` that wrote one, so there is nothing to fence and a row minted
+# here would be a tombstone for a workflow nobody ever claimed. The deadline is moved to
+# now at the same time, so the workflow is claimable again immediately: what is kept is the
+# ordering, not the claim.
+SUPERSEDE = """
+UPDATE workflow_claim
+SET token = token + 1, held_until = unixepoch('now', 'subsec')
+WHERE workflow = ?
+"""
+
 # Take the oldest visible workflow and push it a lease into the future. There is no
 # `SKIP LOCKED` here and none is wanted: it exists so one poller does not queue behind
 # another's row lock, and SQLite has no concurrent writers to step over.
@@ -204,6 +284,11 @@ ON CONFLICT (namespace, workflow) DO UPDATE SET visible_at = excluded.visible_at
 # different `visible_at`, so the equality is the whole check.
 FINISH = "DELETE FROM workflow_queue WHERE namespace = ? AND workflow = ? AND visible_at = ?"
 
+# Withdraw the workflow's right to run, whatever its row currently means. Unconditional
+# where `FINISH` compares the receipt, which is the difference between finishing a pass
+# (leave anything that asked for another) and cancelling the workflow (leave nothing).
+CANCEL = "DELETE FROM workflow_queue WHERE namespace = ? AND workflow = ?"
+
 # Suspend until a deadline, under the same comparison and for the same reason. A workflow
 # holds one row here, so writing the deadline unconditionally would land on top of a
 # `make_ready` that arrived while the pass was ending and push a confirmation out to a
@@ -416,6 +501,14 @@ class SqliteCheckpointer:
         rows = await self.database.run(lambda connection: connection.execute(LOAD, (workflow,)).fetchall())
         return {step: self.codec.decode(encoded) for step, encoded in rows}
 
+    async def history(self, workflow: str) -> dict[str, Written]:
+        """The same records `load` returns, each with the moment it was written."""
+        rows = await self.database.run(lambda connection: connection.execute(HISTORY, (workflow,)).fetchall())
+        return {
+            step: Written(value=self.codec.decode(encoded), at=datetime.fromtimestamp(written_at, UTC))
+            for step, encoded, written_at in rows
+        }
+
     async def claim(self, workflow: str, lease: timedelta) -> Pass | None:
         taken = await self.database.run(
             lambda connection: connection.execute(
@@ -485,6 +578,37 @@ class SqliteCheckpointer:
         )
         return self.codec.decode(cast(tuple[str], stored)[0])
 
+    async def append(self, workflow: str, value: object) -> Entry:
+        """File `value` in this workflow's inbox, under the next key in the table."""
+        stored = await self.database.run(
+            lambda connection: connection.execute(
+                APPEND,
+                {"workflow": workflow, "value": self.codec.encode(value)},
+            ).fetchone()
+        )
+        key, encoded = cast(tuple[str, str], stored)
+        return Entry(key=key, value=self.codec.decode(encoded))
+
+    async def discard(self, workflow: str) -> int:
+        """
+        Forget every record this workflow has, and raise its fence, in one transaction.
+
+        One commit rather than two statements, because the two are only right together: a
+        crash between them either leaves the records deleted with the fence unraised, so
+        the pass that was mid-flight writes them back one at a time, or the reverse, which
+        fences a live pass for a deletion that never happened.
+
+        What is left behind is one claim row carrying a number. Nothing here sweeps it, in
+        keeping with the rest of this store, where nothing expires and tidying the file is
+        the deployment's homework.
+        """
+
+        def one_commit(cursor: sqlite3.Cursor) -> int:
+            cursor.execute(SUPERSEDE, (workflow,))
+            return cursor.execute(DISCARD, (workflow,)).rowcount
+
+        return await self.database.run(lambda connection: transacted(connection, one_commit))
+
     async def release(self, holder: Pass) -> None:
         await self.database.run(lambda connection: connection.execute(RELEASE, (holder.workflow, holder.token)))
 
@@ -593,6 +717,22 @@ class SqliteScheduler:
         """Nothing to take over by hand: an abandoned workflow becomes visible on its own."""
         return None
 
+    async def cancel(self, workflow: str) -> None:
+        """
+        Drop the workflow's row, whichever of the three things its `visible_at` means.
+
+        One `DELETE` covers queued, sleeping, and out with a worker, because this table
+        holds one row per workflow and the visibility is the only thing that differs
+        between them. That is the same collapse that leaves `wake_due` and `reclaim` with
+        nothing to do.
+
+        The half of `cancel` a queue sweep cannot reach comes free with it: a pass still in
+        flight answers with `wake_at`, which is an `UPDATE` conditional on the visibility
+        still being the one it took, and a deleted row has none. So the deadline it was
+        about to write updates nothing and a deleted workflow is not put back to sleep.
+        """
+        await self.database.run(lambda connection: connection.execute(CANCEL, (self.namespace, workflow)))
+
     async def done(self, delivery: Delivery) -> None:
         """
         Drop the workflow, unless something asked for another pass while this one ran.
@@ -644,3 +784,39 @@ class SqliteDurable:
             return self.checkpointer.codec.decode(cast(tuple[str], stored)[0])
 
         return await self.checkpointer.database.run(lambda connection: transacted(connection, one_commit))
+
+    async def deliver(self, workflow: str, value: object) -> Entry:
+        """Append the message and make the workflow ready, together or not at all."""
+        visible_at = self.scheduler.now().timestamp()
+
+        def one_commit(cursor: sqlite3.Cursor) -> Entry:
+            stored = cursor.execute(
+                APPEND,
+                {"workflow": workflow, "value": self.checkpointer.codec.encode(value)},
+            ).fetchone()
+            cursor.execute(
+                SCHEDULE,
+                {"namespace": self.scheduler.namespace, "workflow": workflow, "visible_at": visible_at},
+            )
+            key, encoded = cast(tuple[str, str], stored)
+            return Entry(key=key, value=self.checkpointer.codec.decode(encoded))
+
+        return await self.checkpointer.database.run(lambda connection: transacted(connection, one_commit))
+
+    async def delete(self, workflow: str) -> int:
+        """
+        Cancel the workflow's wakeups and forget its records, together or not at all.
+
+        Three statements in one commit, so the ordering `SplitDurable` has to reason about
+        does not arise: there is no window in which the records are gone and a wakeup is
+        not, and none in which the fence has been raised for a deletion that did not
+        happen. Which is the same thing `arrive` gets from this store and for the same
+        reason, one file.
+        """
+
+        def one_commit(cursor: sqlite3.Cursor) -> int:
+            cursor.execute(CANCEL, (self.scheduler.namespace, workflow))
+            cursor.execute(SUPERSEDE, (workflow,))
+            return cursor.execute(DISCARD, (workflow,)).rowcount
+
+        return await self.checkpointer.database.run(lambda connection: transacted(connection, one_commit))