Files
aevolution/migrations/0010_account_control.sql
dingoandClaude Opus 5.5 890c57a77f
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m50s
Foundation / checks (network) (push) Successful in 9m8s
Foundation / checks (client) (push) Successful in 12m10s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 7m33s
Foundation / checks (checks) (push) Canceled after 18m49s
Foundation / checks (tsan) (push) Canceled after 6m38s
Add M10.3c durable per-world account control (schema v10)
Migration v10 keeps, per world and account, the highest accepted grant serial and
the region session in control with a fencing generation and database-time expiry,
reachable only through claim/renew/release functions under the caller's region
lease. Serials survive restarts and apply across regions; a cross-region takeover
returns a wait so control never overlaps. RegionSessions takes durable control via
a ControlLedger before admitting a session, delays Welcome by the wait, renews, and
closes sessions whose control is fenced or cannot be confirmed in time.
PostgresControlLedger implements the ledger. ADR-0091.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 21:50:21 -04:00

157 lines
8.1 KiB
PL/PgSQL

-- M10.3c durable account control (ADR-0091). One row per (world, account): the highest
-- grant serial any region of the world accepted for the account, and the region session
-- that holds control, with a fencing generation and a database-time expiry. The runtime
-- reaches it only through the three functions below, each of which first requires the
-- caller's exact unexpired region lease (check_region_lease), so only a region's current
-- authority can grant, keep or release control.
--
-- Lock order (extends schema v9): upgrade lock (shared) -> region lease row -> account
-- control row. A claim never locks another region's lease row.
--
-- Newest grant wins across regions: a claim with a higher serial takes control even from
-- an unexpired holder in another region. It returns the remaining time of that holder's
-- expiry; the claimant must not act for the account until that wait has passed, by which
-- time the old holder has stopped (it stops before its own expiry, as with region leases)
-- and its next renewal is fenced. Control held by this region needs no wait: under the
-- current epoch the claimant closes its own session, and an older epoch's holder already
-- stopped before this epoch's region lease could be acquired.
CREATE TABLE evolution.account_controls (
world_id evolution.u64 NOT NULL,
account_id uuid NOT NULL CHECK (account_id <> '00000000-0000-0000-0000-000000000000'),
serial evolution.u64 NOT NULL CHECK (serial > 0),
generation evolution.u64 NOT NULL CHECK (generation > 0),
region_id evolution.u64,
region_epoch evolution.u64,
session_id evolution.u64,
expires_at timestamptz,
PRIMARY KEY (world_id, account_id),
CHECK ((region_id IS NULL) = (region_epoch IS NULL)),
CHECK ((region_id IS NULL) = (session_id IS NULL)),
CHECK ((region_id IS NULL) = (expires_at IS NULL))
);
REVOKE ALL ON evolution.account_controls FROM PUBLIC;
CREATE FUNCTION evolution.claim_account_control(p_world evolution.u64, p_region evolution.u64,
p_holder uuid, p_epoch evolution.u64, p_account uuid, p_serial evolution.u64,
p_session evolution.u64, p_duration_ms integer)
RETURNS TABLE (control_generation evolution.u64, wait_ms integer, granted_ms integer)
LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$
DECLARE
c evolution.account_controls%ROWTYPE;
t timestamptz;
pending interval;
BEGIN
IF p_account IS NULL OR p_account = '00000000-0000-0000-0000-000000000000'
OR p_serial IS NULL OR p_serial = 0 OR p_session IS NULL OR p_session = 0
OR p_duration_ms IS NULL OR p_duration_ms NOT BETWEEN 1000 AND 60000 THEN
RAISE EXCEPTION 'invalid control request' USING ERRCODE = '22023';
END IF;
PERFORM evolution.check_region_lease(p_world, p_region, p_holder, p_epoch);
SELECT * INTO c FROM evolution.account_controls a
WHERE a.world_id = p_world AND a.account_id = p_account FOR UPDATE;
IF NOT FOUND THEN
t := clock_timestamp();
INSERT INTO evolution.account_controls(world_id, account_id, serial, generation,
region_id, region_epoch, session_id, expires_at)
VALUES (p_world, p_account, p_serial, 1, p_region, p_epoch, p_session,
t + p_duration_ms * interval '1 millisecond')
ON CONFLICT DO NOTHING;
IF FOUND THEN
control_generation := 1;
wait_ms := 0;
granted_ms := p_duration_ms;
RETURN NEXT;
RETURN;
END IF;
-- A concurrent first claim committed meanwhile: decide against it.
SELECT * INTO c FROM evolution.account_controls a
WHERE a.world_id = p_world AND a.account_id = p_account FOR UPDATE;
END IF;
-- Read after the row lock wait, as with region leases.
t := clock_timestamp();
IF p_serial <= c.serial THEN
RAISE EXCEPTION 'stale grant' USING ERRCODE = 'EVL11';
END IF;
IF c.generation = 18446744073709551615 THEN
RAISE EXCEPTION 'control generations exhausted' USING ERRCODE = 'EVL05';
END IF;
-- Only another region's unexpired holder must be outlived (see above).
pending := CASE
WHEN c.region_id IS NULL OR c.expires_at <= t THEN interval '0'
WHEN c.region_id = p_region AND c.region_epoch <= p_epoch THEN interval '0'
ELSE c.expires_at - t END;
UPDATE evolution.account_controls a
SET serial = p_serial, generation = c.generation + 1, region_id = p_region,
region_epoch = p_epoch, session_id = p_session,
expires_at = t + pending + p_duration_ms * interval '1 millisecond'
WHERE a.world_id = p_world AND a.account_id = p_account
RETURNING a.generation INTO control_generation;
wait_ms := ceil(extract(epoch FROM pending) * 1000)::integer;
granted_ms := p_duration_ms;
RETURN NEXT;
END $$;
-- Extends the caller's control from database time; the generation, region and epoch
-- must still match and the control must be unexpired. Expiry is final, as for leases.
CREATE FUNCTION evolution.renew_account_control(p_world evolution.u64, p_region evolution.u64,
p_holder uuid, p_epoch evolution.u64, p_account uuid, p_generation evolution.u64,
p_duration_ms integer)
RETURNS integer LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$
DECLARE
c evolution.account_controls%ROWTYPE;
t timestamptz;
BEGIN
IF p_account IS NULL OR p_generation IS NULL OR p_duration_ms IS NULL
OR p_duration_ms NOT BETWEEN 1000 AND 60000 THEN
RAISE EXCEPTION 'invalid control request' USING ERRCODE = '22023';
END IF;
PERFORM evolution.check_region_lease(p_world, p_region, p_holder, p_epoch);
SELECT * INTO c FROM evolution.account_controls a
WHERE a.world_id = p_world AND a.account_id = p_account FOR UPDATE;
t := clock_timestamp();
IF NOT FOUND OR c.generation <> p_generation OR c.region_id IS DISTINCT FROM p_region
OR c.region_epoch IS DISTINCT FROM p_epoch OR c.expires_at <= t THEN
RAISE EXCEPTION 'account control fenced' USING ERRCODE = 'EVL12';
END IF;
-- Never shortens: a claim that waited out another holder keeps its later expiry.
UPDATE evolution.account_controls a
SET expires_at = greatest(c.expires_at, t + p_duration_ms * interval '1 millisecond')
WHERE a.world_id = p_world AND a.account_id = p_account;
RETURN p_duration_ms;
END $$;
-- Gives up the caller's control (the serial stays). True when released, false when the
-- control had already moved on (nothing changed).
CREATE FUNCTION evolution.release_account_control(p_world evolution.u64, p_region evolution.u64,
p_holder uuid, p_epoch evolution.u64, p_account uuid, p_generation evolution.u64)
RETURNS boolean LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$
BEGIN
IF p_account IS NULL OR p_generation IS NULL THEN
RAISE EXCEPTION 'invalid control request' USING ERRCODE = '22023';
END IF;
PERFORM evolution.check_region_lease(p_world, p_region, p_holder, p_epoch);
UPDATE evolution.account_controls a
SET region_id = NULL, region_epoch = NULL, session_id = NULL, expires_at = NULL
WHERE a.world_id = p_world AND a.account_id = p_account AND a.generation = p_generation
AND a.region_id = p_region AND a.region_epoch = p_epoch;
RETURN FOUND;
END $$;
REVOKE ALL ON FUNCTION
evolution.claim_account_control(evolution.u64, evolution.u64, uuid, evolution.u64, uuid,
evolution.u64, evolution.u64, integer),
evolution.renew_account_control(evolution.u64, evolution.u64, uuid, evolution.u64, uuid,
evolution.u64, integer),
evolution.release_account_control(evolution.u64, evolution.u64, uuid, evolution.u64, uuid,
evolution.u64)
FROM PUBLIC;
GRANT EXECUTE ON FUNCTION
evolution.claim_account_control(evolution.u64, evolution.u64, uuid, evolution.u64, uuid,
evolution.u64, evolution.u64, integer),
evolution.renew_account_control(evolution.u64, evolution.u64, uuid, evolution.u64, uuid,
evolution.u64, integer),
evolution.release_account_control(evolution.u64, evolution.u64, uuid, evolution.u64, uuid,
evolution.u64)
TO :"runtime_role";
INSERT INTO evolution.schema_migrations(version, sha256) VALUES (10, :'migration_sha_10');