-- 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');