Postgres engine: named locks — try_lock (validated entry, duration guard, opportunistic expiry-delete + insert-or-reacquire + holder read-back over the locks table), PgLockHandle (full-window renew, consuming owner-scoped release with both boolean arms), same-owner re-acquire matched to the SQLite arm, silent-lapse posture pinned, second open re-acquires after expiry (task pg-engine-locks)

2026-10-09 09:17:39 +00:00
1 parent 3dd83791ff
commit c3591c2d44
@@ -0,0 +1,236 @@
+//! The named-lock mechanism's Postgres arm (`pg-engine-locks`) — the
+//! substrate's lock-op semantics re-derived over the schema task's
+//! locks table (the POC's lock probe pinned acquire/release/renew with
+//! TTL and expiry re-acquisition directly):
+//!
+//! - `try_lock(name, owner, ttl)` — shared-namespace + non-empty
+//!   owner validation, the **duration guard (ADR-023 §2)** on `ttl <=
+//!   0` at the entry (opaque `Err(Database)`, detail in the source
+//!   chain — an exclusion mechanism must not silently hand back a
+//!   lease the caller believes it holds), the closed-store check,
+//!   then the acquire op on a pool connection: opportunistic-
+//!   expiry-delete + insert-or-reacquire + read-back. `Ok(None)` =
+//!   held elsewhere (no-work is a value); `Ok(Some(..))` = the boxed
+//!   [`Lock`] handle.
+//! - `Lock::renew(ttl)` — the same duration guard; the new **full**
+//!   TTL window from now (not additive); `false` = lost it (expired
+//!   and re-acquired elsewhere — exclusion lapses silently at TTL
+//!   expiry, no revocation event, ADR-008 §7).
+//! - `Lock::release(self: Box<Self>)` — consuming (the RAII shape,
+//!   ADR-019 §1); deletes only the owner's row (`false` = already
+//!   expired/re-acquired — a no-op, not an error). No handle-local
+//!   "held" flag caching: the row-scoped delete is the truth-teller.
+//!
+//! No `lock_tx` exists — deliberate (core-contract.md's named-locks
+//! section): acquisition is a separate auto-commit op; the TTL
+//! discipline governs. There is no general expiry sweeper either:
+//! expired rows hang until the next acquire's opportunistic delete
+//! deletes them (the inherited substrate posture, documented) — the
+//! `locks_expiry_idx` index keeps that delete cheap.
+
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use deadpool_postgres::Pool;
+
+use alkstore::{BoxedFuture, Lock, Result, validate_local_name, validate_shared_name};
+
+use crate::resolution::now_unix;
+use crate::schema::{QualifiedTable, tables};
+use crate::seam::{database_error, pg_error, pool_error};
+
+/// The duration guard's message (ADR-023 §2's engine detail — rides
+/// the source chain, `Database`'s Display is opaque).
+fn duration_error(ttl: i64) -> alkstore::Error {
+    database_error(format!(
+        "ttl must be a positive duration (seconds), got {ttl}"
+    ))
+}
+
+/// Qualified table reference for this engine-owned schema.
+fn table(schema: &str, name: &str) -> String {
+    QualifiedTable { schema, name }.to_string()
+}
+
+/// The acquire op (see the module docs): the opportunistic
+/// expired-row delete for this name, then the insert-or-reacquire
+/// (the PK on `name` prevents dual acquisition — `ON CONFLICT DO
+/// NOTHING` keeps the incumbent row exactly as-is, so a same-owner
+/// re-acquire keeps the original row with its TTL *not* refreshed,
+/// the substrate's `INSERT OR IGNORE` shape), then the read-back —
+/// the holder column decides, not the insert's row count (the D-4
+/// swallow's lesson: never trust a write result for ownership).
+///
+/// One statement sequence on one pool connection's implicit
+/// transaction (auto-committed as a unit on return-to-pool; the
+/// expiry-delete + insert + read-back race window is closed by the
+/// PK constraint — a concurrent grant of the same name either
+/// lands first or reads as foreign).
+async fn lock_acquire(
+    client: &tokio_postgres::Client,
+    schema: &str,
+    name: &str,
+    owner: &str,
+    ttl: i64,
+) -> Result<bool> {
+    let now = now_unix();
+    client
+        .execute(
+            &format!(
+                "DELETE FROM {locks} WHERE name = $1 AND expires_at <= $2",
+                locks = table(schema, tables::LOCKS)
+            ),
+            &[&name, &now],
+        )
+        .await
+        .map_err(pg_error)?;
+    client
+        .execute(
+            &format!(
+                "INSERT INTO {locks} (name, owner, expires_at)
+                 VALUES ($1, $2, $3::bigint + $4::bigint)
+                 ON CONFLICT (name) DO NOTHING",
+                locks = table(schema, tables::LOCKS)
+            ),
+            &[&name, &owner, &now, &ttl],
+        )
+        .await
+        .map_err(pg_error)?;
+    let holder: Option<String> = client
+        .query_opt(
+            &format!(
+                "SELECT owner FROM {locks} WHERE name = $1",
+                locks = table(schema, tables::LOCKS)
+            ),
+            &[&name],
+        )
+        .await
+        .map_err(pg_error)?
+        .map(|row| row.get(0));
+    Ok(holder.as_deref() == Some(owner))
+}
+
+/// The acquire path (see the module docs): validation, duration
+/// guard, closed-store check, then the acquire op on a pool
+/// connection. `Ok(None)` is the held-by-someone-else arm.
+pub(crate) fn try_lock(
+    pool: Pool,
+    schema: String,
+    closed: Arc<AtomicBool>,
+    name: String,
+    owner: String,
+    ttl: i64,
+) -> BoxedFuture<'static, Result<Option<Box<dyn Lock>>>> {
+    if let Err(e) = validate_shared_name(&name) {
+        return Box::pin(async move { Err(e) });
+    }
+    if let Err(e) = validate_local_name(&owner) {
+        return Box::pin(async move { Err(e) });
+    }
+    if ttl <= 0 {
+        return Box::pin(async move { Err(duration_error(ttl)) });
+    }
+    if closed.load(Ordering::Acquire) {
+        return Box::pin(async { Err(database_error("the store is closed")) });
+    }
+    Box::pin(async move {
+        let client = pool.get().await.map_err(pool_error)?;
+        let granted = lock_acquire(&client, &schema, &name, &owner, ttl).await?;
+        Ok(granted.then(|| {
+            Box::new(PgLockHandle {
+                name,
+                owner,
+                pool,
+                schema,
+                closed,
+            }) as Box<dyn Lock>
+        }))
+    })
+}
+
+/// The held named-lock handle (see the module docs). [`Lock::release`]
+/// consumes it; `renew` is the repeatable `&self` case.
+pub struct PgLockHandle {
+    name: String,
+    owner: String,
+    pool: Pool,
+    schema: String,
+    closed: Arc<AtomicBool>,
+}
+
+impl std::fmt::Debug for PgLockHandle {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("PgLockHandle")
+            .field("name", &self.name)
+            .finish_non_exhaustive()
+    }
+}
+
+impl Lock for PgLockHandle {
+    fn name(&self) -> &str {
+        &self.name
+    }
+
+    fn renew<'a>(&'a self, ttl: i64) -> BoxedFuture<'a, Result<bool>> {
+        if ttl <= 0 {
+            return Box::pin(async move { Err(duration_error(ttl)) });
+        }
+        if self.closed.load(Ordering::Acquire) {
+            return Box::pin(async { Err(database_error("the store is closed")) });
+        }
+        let name = self.name.clone();
+        let owner = self.owner.clone();
+        let pool = self.pool.clone();
+        let schema = self.schema.clone();
+        Box::pin(async move {
+            let now = now_unix();
+            let client = pool.get().await.map_err(pool_error)?;
+            // The owner-scoped update: 0 rows = expired-and-gone or
+            // re-acquired by another owner — `false`, the lost-it arm.
+            let n = client
+                .execute(
+                    &format!(
+                        "UPDATE {locks} SET expires_at = $3::bigint + $4::bigint
+                         WHERE name = $1 AND owner = $2",
+                        locks = table(&schema, tables::LOCKS)
+                    ),
+                    &[&name, &owner, &now, &ttl],
+                )
+                .await
+                .map_err(pg_error)?;
+            Ok(n > 0)
+        })
+    }
+
+    fn release(self: Box<Self>) -> BoxedFuture<'static, Result<bool>> {
+        let PgLockHandle {
+            name,
+            owner,
+            pool,
+            schema,
+            closed,
+        } = *self;
+        Box::pin(async move {
+            if closed.load(Ordering::Acquire) {
+                return Err(database_error("the store is closed"));
+            }
+            let client = pool.get().await.map_err(pool_error)?;
+            // The owner-scoped delete — row-scoped truth-teller: `true`
+            // = the row was there and is gone by this owner's hand
+            // (including the stale row past its TTL, which no sweeper
+            // has touched); `false` = row-less or foreign (the
+            // no-op arm).
+            let n = client
+                .execute(
+                    &format!(
+                        "DELETE FROM {locks} WHERE name = $1 AND owner = $2",
+                        locks = table(&schema, tables::LOCKS)
+                    ),
+                    &[&name, &owner],
+                )
+                .await
+                .map_err(pg_error)?;
+            Ok(n > 0)
+        })
+    }
+}