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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: without-durability-postgres
-Version: 0.0.6
+Version: 0.0.8
 Summary: A without-durability checkpoint store and queue backed by Postgres, where every guarantee is an ordinary transaction.
 Author: Josh Karpel
 Author-email: Josh Karpel <josh.karpel@gmail.com>
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
-Requires-Dist: without-durability==0.0.6
+Requires-Dist: without-durability==0.0.8
 Requires-Dist: psycopg[binary,pool]>=3.2
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -22,7 +22,8 @@ Description-Content-Type: text/markdown
 # without-durability-postgres
 
 [`without-durability`](https://pypi.org/project/without-durability/)'s two
-interfaces over one Postgres: three tables, and no mechanism of its own.
+interfaces over one Postgres: three tables and a sequence, and no mechanism of its
+own.
 
 ```python
 from psycopg_pool import AsyncConnectionPool

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

@@ -1,7 +1,8 @@
 # without-durability-postgres
 
 [`without-durability`](https://pypi.org/project/without-durability/)'s two
-interfaces over one Postgres: three tables, and no mechanism of its own.
+interfaces over one Postgres: three tables and a sequence, and no mechanism of its
+own.
 
 ```python
 from psycopg_pool import AsyncConnectionPool

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "without-durability-postgres"
-version = "0.0.6"
+version = "0.0.8"
 description = "A without-durability checkpoint store and queue backed by Postgres, where every guarantee is an ordinary transaction."
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "without-durability==0.0.6",
+    "without-durability==0.0.8",
     "psycopg[binary,pool]>=3.2",
 ]
 

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "without-durability-postgres"
-version = "0.0.6"
+version = "0.0.8"
 description = "A without-durability checkpoint store and queue backed by Postgres, where every guarantee is an ordinary transaction."
 readme = "README.md"
 license = "MIT"
@@ -24,7 +24,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "without-durability==0.0.6",
+    "without-durability==0.0.8",
     "psycopg[binary,pool]>=3.2",
 ]
 

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

@@ -62,11 +62,15 @@ from psycopg.rows import TupleRow
 from psycopg_pool import AsyncConnectionPool
 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
 
@@ -96,13 +100,56 @@ POLL = timedelta(milliseconds=50)
 # 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. The default is evaluated on insert
+# 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.
+#
+# It is deliberately not scoped to the workflow. Numbering per workflow would mean reading
+# the current maximum on every write, and the contract is only about the order *within* one
+# workflow, which a shared sequence satisfies with gaps.
+#
+# There is no physical order to fall back on, which is worth stating because a heap scan
+# looks like insertion order right up until it is not: the conflict update is a real MVCC
+# update, so it writes a new tuple version and moves the row.
+#
+# `written_at` is what `history` reads, and its `DEFAULT` is doing the same work `seq`'s
+# 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
+# `clock_timestamp()` and not the `now()` every other statement here reads, which is the
+# one place this file wants a time that is not the transaction's start: `transact` runs
+# its effect *inside* the transaction, so a step that spent ten seconds at a gateway would
+# be stamped ten seconds before it landed, and could carry an earlier time than a `supply`
+# that committed while it ran and took a lower `seq`, which is `history` returning its
+# records in one order and their times in another. Both are the *server's* clock, which is
+# what makes two records' times comparable across the machines that wrote them, and is the
+# same clock the claim's lease is measured by.
+#
+# `workflow_seq` is a named sequence with a `DEFAULT` rather than an identity column,
+# because `append` has to mint a key from the *same* number that becomes the row's
+# position, and an identity column is a number no statement is allowed to see. Two
+# sequences cannot do it: the inbox key and the position would be drawn separately, so two
+# concurrent appends could take them in opposite orders and `load` would render the pair
+# backwards against keys that sort the other way. One number is both, so the two orders
+# cannot disagree. `nextval` is atomic and never hands the same number out twice, which is
+# what makes an inbox key safe to mint under concurrent writers where `MAX(...) + 1` inside
+# a statement is a race two inserts can both win, with the loser's message vanishing into
+# first-writer-wins and no error to show for it. It is shared across workflows and it skips
+# numbers on rollback, so any one workflow's keys have gaps; the contract asks only that
+# they sort into append order within a workflow, which is exactly what a shared counter
+# gives.
+#
 # The index is the one query that matters for throughput, `next_ready`'s scan for the
 # oldest visible row in a namespace. The other two tables are read by primary key.
 SCHEMA = """
+CREATE SEQUENCE IF NOT EXISTS workflow_seq;
+
 CREATE TABLE IF NOT EXISTS workflow_checkpoint (
     workflow text NOT NULL,
     step text NOT NULL,
     value jsonb NOT NULL,
+    seq bigint NOT NULL DEFAULT nextval('workflow_seq'),
+    written_at timestamptz NOT NULL DEFAULT clock_timestamp(),
     PRIMARY KEY (workflow, step)
 );
 
@@ -191,6 +238,32 @@ ON CONFLICT (workflow, step) DO UPDATE SET value = recorded.value
 RETURNING recorded.value::text
 """
 
+# `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 CTE is what draws one number and spends it twice, as the key and as the row's
+# position, which is the whole of why the key order and the load order agree under
+# concurrency. `nextval` in the `SELECT` list is evaluated once for the one row it
+# produces, and both columns then read that value rather than calling the sequence again.
+# Supplying `seq` explicitly is the reason the column carries a `DEFAULT` rather than being
+# an identity: every other insert here leaves it out and takes the default.
+#
+# No `ON CONFLICT` clause, deliberately. `nextval` never repeats, so the key is fresh by
+# construction and a conflict would mean the numbering is broken; a duplicate-key error is
+# the loud version of that, where an upsert would quietly hand back somebody else's
+# message.
+APPEND = f"""
+WITH minted AS (SELECT nextval('workflow_seq') AS seq)
+INSERT INTO workflow_checkpoint AS entry (workflow, step, value, seq)
+SELECT
+    %(workflow)s,
+    '{INBOX}' || lpad(minted.seq::text, {INBOX_DIGITS}, '0'),
+    %(value)s::jsonb,
+    minted.seq
+FROM minted
+RETURNING entry.step, entry.value::text
+"""
+
 # The three statements `transact` runs between `BEGIN` and `COMMIT`, with the effect's own
 # work in the middle. They are separate strings rather than one because the effect is
 # arbitrary application SQL that this store cannot see, which is precisely what makes the
@@ -210,7 +283,22 @@ ON CONFLICT (workflow, step) DO NOTHING
 RETURNING value::text
 """
 
-LOAD = "SELECT step, value::text FROM workflow_checkpoint WHERE workflow = %s"
+LOAD = "SELECT step, value::text FROM workflow_checkpoint WHERE workflow = %s ORDER BY seq"
+HISTORY = "SELECT step, value::text, written_at FROM workflow_checkpoint WHERE workflow = %s ORDER BY seq"
+
+# 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 = %s"
+
+# 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. `held_until = now()` hands
+# the workflow back at the same time, so it is claimable again immediately: what is kept is
+# the ordering, not the claim.
+SUPERSEDE = "UPDATE workflow_claim SET token = token + 1, held_until = now() WHERE workflow = %s"
 # 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. Conditional on the
 # token for the same reason `release` is in the Redis store: a superseded pass letting go
@@ -245,12 +333,12 @@ class Supplied(Exception):
 
 async def migrate(pool: AsyncConnectionPool) -> None:
     """
-    Create the three tables, from every process, as often as it likes.
+    Create the three tables and the sequence behind `seq`, from every process, as often as it likes.
 
     Idempotent by `IF NOT EXISTS` and safe against itself by the advisory lock, which is
     the part that is easy to skip: concurrent `CREATE TABLE IF NOT EXISTS` is a
-    duplicate-key error on the system catalog rather than a no-op, and a fleet of workers
-    booting together is exactly a race. `pg_advisory_xact_lock` is held to the end of the
+    duplicate-key error on the system catalog rather than a no-op (and `CREATE SEQUENCE IF
+    NOT EXISTS` is the same), and a fleet of workers booting together is exactly a race. `pg_advisory_xact_lock` is held to the end of the
     surrounding transaction and released by the commit, so there is nothing to unlock.
 
     Schema migration as a whole is not what this is. There is no versioning and no path
@@ -331,6 +419,15 @@ class PostgresCheckpointer:
             await cursor.execute(LOAD, (workflow,))
             return {step: self.codec.decode(encoded) for step, encoded in await cursor.fetchall()}
 
+    async def history(self, workflow: str) -> dict[str, Written]:
+        """The same records `load` returns, each with the moment the server wrote it."""
+        async with self.pool.connection() as connection, connection.cursor() as cursor:
+            await cursor.execute(HISTORY, (workflow,))
+            return {
+                step: Written(value=self.codec.decode(encoded), at=written_at)
+                for step, encoded, written_at in await cursor.fetchall()
+            }
+
     async def claim(self, workflow: str, lease: timedelta) -> Pass | None:
         async with self.pool.connection() as connection, connection.cursor() as cursor:
             await cursor.execute(CLAIM, {"workflow": workflow, "lease": lease})
@@ -432,6 +529,31 @@ class PostgresCheckpointer:
             await cursor.execute(SUPPLY, {"workflow": workflow, "step": key, "value": self.codec.encode(value)})
             return self.codec.decode(cast(tuple[str], await cursor.fetchone())[0])
 
+    async def append(self, workflow: str, value: object) -> Entry:
+        """File `value` in this workflow's inbox, under the next key the sequence hands out."""
+        async with self.pool.connection() as connection, connection.cursor() as cursor:
+            await cursor.execute(APPEND, {"workflow": workflow, "value": self.codec.encode(value)})
+            key, encoded = cast(tuple[str, str], await cursor.fetchone())
+            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 a control-plane
+        sweep is the deployment's homework.
+        """
+        async with self.pool.connection() as connection, connection.cursor() as cursor:
+            await cursor.execute(SUPERSEDE, (workflow,))
+            await cursor.execute(DISCARD, (workflow,))
+            return cursor.rowcount
+
     async def release(self, holder: Pass) -> None:
         async with self.pool.connection() as connection:
             await connection.execute(RELEASE, (holder.workflow, holder.token))
@@ -495,6 +617,11 @@ ON CONFLICT (namespace, workflow) DO UPDATE SET visible_at = EXCLUDED.visible_at
 # wrote a different `visible_at`, so the equality is the whole check.
 FINISH = "DELETE FROM workflow_queue WHERE namespace = %s AND workflow = %s AND visible_at = %s"
 
+# 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 = %s AND workflow = %s"
+
 # 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
@@ -632,6 +759,23 @@ class PostgresScheduler:
         """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.
+        """
+        async with self.pool.connection() as connection:
+            await 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.
@@ -696,3 +840,31 @@ class PostgresDurable:
                 {"namespace": self.scheduler.namespace, "workflow": workflow, "visible_at": self.scheduler.now()},
             )
             return codec.decode(stored[0])
+
+    async def deliver(self, workflow: str, value: object) -> Entry:
+        """Append the message and make the workflow ready, together or not at all."""
+        codec = self.checkpointer.codec
+        async with self.checkpointer.pool.connection() as connection, connection.cursor() as cursor:
+            await cursor.execute(APPEND, {"workflow": workflow, "value": codec.encode(value)})
+            key, encoded = cast(tuple[str, str], await cursor.fetchone())
+            await cursor.execute(
+                SCHEDULE,
+                {"namespace": self.scheduler.namespace, "workflow": workflow, "visible_at": self.scheduler.now()},
+            )
+            return Entry(key=key, value=codec.decode(encoded))
+
+    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 datastore.
+        """
+        async with self.checkpointer.pool.connection() as connection, connection.cursor() as cursor:
+            await cursor.execute(CANCEL, (self.scheduler.namespace, workflow))
+            await cursor.execute(SUPERSEDE, (workflow,))
+            await cursor.execute(DISCARD, (workflow,))
+            return cursor.rowcount