@zlink-systems/framework 0.10.0

package/dist/runtime/foundation/service-stateful-registry.js

@@ -0,0 +1,465 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceTerminalOperationRegistry = exports.ServiceStatefulRegistry = exports.ServiceStaleGenerationError = void 0;
+const operation_registry_1 = require("./operation-registry");
+class ServiceStaleGenerationError extends Error {
+    objectKind;
+    key;
+    constructor(objectKind, key) {
+        super(`${objectKind} '${key}' generation is stale.`);
+        this.objectKind = objectKind;
+        this.key = key;
+        this.name = 'ServiceStaleGenerationError';
+    }
+}
+exports.ServiceStaleGenerationError = ServiceStaleGenerationError;
+/**
+ * Owns the stateful identity and fencing rules that used to be split across
+ * Core service tables. Network transport and application materialization stay
+ * outside this module.
+ */
+class ServiceStatefulRegistry {
+    nodeRid;
+    nodeGeneration;
+    spots = new Map();
+    spotTypes = new Map();
+    actors = new Map();
+    actorTypes = new Map();
+    bindings = new Map();
+    reservations = new Map();
+    spotGenerations = new Map();
+    actorGenerations = new Map();
+    reservationAttempts = new Map();
+    turns = new Map();
+    nextReservationId = 1n;
+    nextBindingGeneration = 1n;
+    constructor(nodeRid, nodeGeneration) {
+        this.nodeRid = nodeRid;
+        this.nodeGeneration = nodeGeneration;
+        requireText(nodeRid, 'nodeRid');
+        requirePositive(nodeGeneration, 'nodeGeneration');
+    }
+    createEntrySpot(spotId = this.nodeRid) {
+        return this.createEntrySpotCore(spotId);
+    }
+    createEntrySpotCore(spotId = this.nodeRid) {
+        const current = this.spots.get(spotId);
+        if (current !== undefined)
+            return current;
+        return this.restoreSpotCore({ spotId, generation: this.nodeGeneration }, 'entry', 'entry', this.nodeGeneration);
+    }
+    createSpot(spotId, kind = 'user', stableType = kind) {
+        return this.createSpotCore(spotId, kind, stableType);
+    }
+    createSpotCore(spotId, kind = 'user', stableType = kind) {
+        requireText(spotId, 'spotId');
+        requireText(stableType, 'stableType');
+        const current = this.spots.get(spotId);
+        if (current !== undefined) {
+            if (current.kind !== kind || current.stableType !== stableType) {
+                throw new TypeError(`Spot '${spotId}' is already registered with another kind or type.`);
+            }
+            return current;
+        }
+        const assigned = this.spotTypes.get(spotId);
+        if (assigned !== undefined && (assigned.kind !== kind || assigned.stableType !== stableType)) {
+            throw new TypeError(`Spot '${spotId}' is assigned to another kind or type.`);
+        }
+        const generation = (this.spotGenerations.get(spotId) ?? 0n) + 1n;
+        this.spotGenerations.set(spotId, generation);
+        const created = createSpotState({ spotId, generation }, kind, stableType, generation);
+        this.spotTypes.set(spotId, Object.freeze({ kind, stableType }));
+        this.spots.set(spotId, created);
+        return created;
+    }
+    spot(spotId) {
+        return this.spots.get(spotId);
+    }
+    restoreSpot(ref, kind, stableType, authorityOwnerGeneration) {
+        return this.restoreSpotCore(ref, kind, stableType, authorityOwnerGeneration);
+    }
+    restoreSpotCore(ref, kind, stableType, authorityOwnerGeneration) {
+        requireText(ref.spotId, 'spotId');
+        requirePositive(ref.generation, 'spot.generation');
+        requireText(stableType, 'stableType');
+        requirePositive(authorityOwnerGeneration, 'authorityOwnerGeneration');
+        if (kind === 'entry'
+            && (ref.spotId !== this.nodeRid
+                || ref.generation !== this.nodeGeneration
+                || stableType !== 'entry')) {
+            throw new TypeError('Entry Spot identity is fixed by the owning node lifecycle.');
+        }
+        const current = this.spots.get(ref.spotId);
+        if (current !== undefined && current.ref.generation > ref.generation) {
+            throw new ServiceStaleGenerationError('spot', ref.spotId);
+        }
+        const assigned = this.spotTypes.get(ref.spotId);
+        if (assigned !== undefined && (assigned.kind !== kind || assigned.stableType !== stableType)) {
+            throw new TypeError(`Spot '${ref.spotId}' is assigned to another kind or type.`);
+        }
+        const restored = createSpotState(ref, kind, stableType, authorityOwnerGeneration);
+        this.spotGenerations.set(ref.spotId, max(this.spotGenerations.get(ref.spotId) ?? 0n, ref.generation));
+        this.spotTypes.set(ref.spotId, Object.freeze({ kind, stableType }));
+        this.spots.set(ref.spotId, restored);
+        return restored;
+    }
+    requireSpot(ref) {
+        return this.requireSpotCore(ref);
+    }
+    requireSpotCore(ref) {
+        const current = this.spots.get(ref.spotId);
+        if (current === undefined || current.ref.generation !== ref.generation || current.state !== 'ready') {
+            throw new ServiceStaleGenerationError('spot', ref.spotId);
+        }
+        return current;
+    }
+    closeSpot(ref) {
+        const current = this.requireSpotCore(ref);
+        if (current.kind === 'entry')
+            return false;
+        for (const actor of this.actors.values()) {
+            if (actor.spot.spotId === ref.spotId
+                && actor.spot.generation === ref.generation) {
+                return false;
+            }
+        }
+        this.spots.set(ref.spotId, Object.freeze({ ...current, state: 'closing' }));
+        this.spots.delete(ref.spotId);
+        return true;
+    }
+    createActor(actorId, stableType = 'actor', initialSpot) {
+        return this.createActorCore(actorId, stableType, initialSpot);
+    }
+    createActorCore(actorId, stableType = 'actor', initialSpot = this.createEntrySpotCore().ref) {
+        requireText(actorId, 'actorId');
+        requireText(stableType, 'stableType');
+        this.requireSpotCore(initialSpot);
+        const current = this.actors.get(actorId);
+        if (current !== undefined) {
+            if (this.actorTypes.get(actorId) !== stableType) {
+                throw new TypeError(`Actor '${actorId}' is already registered with another type.`);
+            }
+            return current;
+        }
+        const assignedType = this.actorTypes.get(actorId);
+        if (assignedType !== undefined && assignedType !== stableType) {
+            throw new TypeError(`Actor '${actorId}' is assigned to another type.`);
+        }
+        const generation = (this.actorGenerations.get(actorId) ?? 0n) + 1n;
+        this.actorGenerations.set(actorId, generation);
+        const created = Object.freeze({
+            ref: Object.freeze({
+                nodeRid: this.nodeRid,
+                actorId,
+                generation
+            }),
+            authorityOwnerGeneration: generation,
+            spot: Object.freeze({ ...initialSpot }),
+            membershipEpoch: 1n
+        });
+        this.actorTypes.set(actorId, stableType);
+        this.actors.set(actorId, created);
+        return created;
+    }
+    restoreActor(actor, stableType, spot, membershipEpoch, authorityOwnerGeneration = actor.generation) {
+        this.requireSpotCore(spot);
+        requirePositive(actor.generation, 'actor.generation');
+        requirePositive(membershipEpoch, 'membershipEpoch');
+        requirePositive(authorityOwnerGeneration, 'authorityOwnerGeneration');
+        const current = this.actors.get(actor.actorId);
+        if (current !== undefined && current.ref.generation > actor.generation) {
+            throw new ServiceStaleGenerationError('actor', actor.actorId);
+        }
+        const assignedType = this.actorTypes.get(actor.actorId);
+        if (assignedType !== undefined && assignedType !== stableType) {
+            throw new TypeError(`Actor '${actor.actorId}' is assigned to another type.`);
+        }
+        const restored = Object.freeze({
+            ref: Object.freeze({ ...actor, nodeRid: this.nodeRid }),
+            authorityOwnerGeneration,
+            spot: Object.freeze({ ...spot }),
+            membershipEpoch
+        });
+        this.actorGenerations.set(actor.actorId, max(this.actorGenerations.get(actor.actorId) ?? 0n, actor.generation));
+        this.actorTypes.set(actor.actorId, stableType);
+        this.actors.set(actor.actorId, restored);
+        return restored;
+    }
+    actor(actorId) {
+        return this.actors.get(actorId);
+    }
+    requireActor(ref) {
+        return this.requireActorCore(ref);
+    }
+    requireActorCore(ref) {
+        const current = this.actors.get(ref.actorId);
+        if (current === undefined
+            || current.ref.generation !== ref.generation
+            || current.ref.nodeRid !== ref.nodeRid) {
+            throw new ServiceStaleGenerationError('actor', ref.actorId);
+        }
+        return current;
+    }
+    joinActor(actor, target) {
+        return this.joinActorCore(actor, target);
+    }
+    joinActorCore(actor, target) {
+        const current = this.requireActorCore(actor);
+        this.requireSpotCore(target);
+        const next = Object.freeze({
+            ...current,
+            spot: Object.freeze({ ...target }),
+            membershipEpoch: current.membershipEpoch + 1n
+        });
+        this.actors.set(actor.actorId, next);
+        this.updateBindingMembership(next);
+        return {
+            actor: next,
+            previousSpot: current.spot,
+            currentSpot: next.spot,
+            previousMembershipEpoch: current.membershipEpoch,
+            currentMembershipEpoch: next.membershipEpoch
+        };
+    }
+    leaveActor(actor, expectedMembershipEpoch) {
+        const entry = this.createEntrySpotCore().ref;
+        const current = this.requireActorCore(actor);
+        if (current.membershipEpoch !== expectedMembershipEpoch) {
+            throw new ServiceStaleGenerationError('actor', actor.actorId);
+        }
+        return this.joinActorCore(actor, entry);
+    }
+    destroyActor(actor) {
+        const current = this.requireActorCore(actor);
+        this.actors.delete(actor.actorId);
+        this.bindings.delete(actorKey(actor));
+        return current;
+    }
+    bindSession(actor, sessionRid, sessionOwnerNodeRid, sessionOwnerNodeGeneration, sessionOwnerId, sessionOwnerLeaseGeneration) {
+        const current = this.requireActorCore(actor);
+        requireText(sessionRid, 'sessionRid');
+        requireText(sessionOwnerNodeRid, 'sessionOwnerNodeRid');
+        const binding = Object.freeze({
+            actor: Object.freeze({ ...current.ref }),
+            sessionRid,
+            sessionOwnerNodeRid,
+            ...(sessionOwnerNodeGeneration === undefined ? {} : { sessionOwnerNodeGeneration }),
+            ...(sessionOwnerId === undefined ? {} : { sessionOwnerId }),
+            ...(sessionOwnerLeaseGeneration === undefined ? {} : { sessionOwnerLeaseGeneration }),
+            bindingGeneration: this.nextBindingGeneration++,
+            membershipEpoch: current.membershipEpoch
+        });
+        this.bindings.set(actorKey(actor), binding);
+        return binding;
+    }
+    installSessionBinding(binding) {
+        this.requireActorCore(binding.actor);
+        requirePositive(binding.bindingGeneration, 'bindingGeneration');
+        const current = this.bindings.get(actorKey(binding.actor));
+        if (current !== undefined
+            && current.sessionOwnerNodeRid === binding.sessionOwnerNodeRid
+            && current.sessionOwnerNodeGeneration === binding.sessionOwnerNodeGeneration
+            && current.sessionOwnerId === binding.sessionOwnerId
+            && current.sessionOwnerLeaseGeneration === binding.sessionOwnerLeaseGeneration
+            && current.bindingGeneration >= binding.bindingGeneration) {
+            throw new ServiceStaleGenerationError('binding', binding.actor.actorId);
+        }
+        this.nextBindingGeneration = max(this.nextBindingGeneration, binding.bindingGeneration + 1n);
+        this.bindings.set(actorKey(binding.actor), Object.freeze({ ...binding }));
+    }
+    binding(actor) {
+        return this.bindingCore(actor);
+    }
+    bindingCore(actor) {
+        const binding = this.bindings.get(actorKey(actor));
+        return binding?.actor.generation === actor.generation ? binding : undefined;
+    }
+    unbindSession(actor, expectedBindingGeneration, expectedSessionRid, expectedSessionOwnerNodeRid) {
+        const key = actorKey(actor);
+        const binding = this.bindings.get(key);
+        if (binding === undefined)
+            return false;
+        if (binding.bindingGeneration !== expectedBindingGeneration
+            || expectedSessionRid !== undefined && binding.sessionRid !== expectedSessionRid
+            || expectedSessionOwnerNodeRid !== undefined
+                && binding.sessionOwnerNodeRid !== expectedSessionOwnerNodeRid) {
+            throw new ServiceStaleGenerationError('binding', actor.actorId);
+        }
+        this.bindings.delete(key);
+        return true;
+    }
+    validateBoundSession(actor, expectedBindingGeneration) {
+        const binding = this.bindingCore(actor);
+        if (binding === undefined || binding.bindingGeneration !== expectedBindingGeneration) {
+            throw new ServiceStaleGenerationError('binding', actor.actorId);
+        }
+        return binding;
+    }
+    reserve(objectKind, key, stableType, attempt) {
+        requireText(key, 'key');
+        requireText(stableType, 'stableType');
+        requirePositive(attempt, 'attempt');
+        const reservationKey = `${objectKind}:${key}`;
+        const currentAttempt = this.reservationAttempts.get(reservationKey) ?? 0n;
+        if (attempt < currentAttempt)
+            return { kind: 'attemptStale' };
+        if (objectKind === 'actor') {
+            const actor = this.actors.get(key);
+            if (actor !== undefined) {
+                return this.actorTypes.get(key) === stableType
+                    ? { kind: 'existing', actor }
+                    : { kind: 'typeMismatch' };
+            }
+            const assignedType = this.actorTypes.get(key);
+            if (assignedType !== undefined && assignedType !== stableType) {
+                return { kind: 'typeMismatch' };
+            }
+        }
+        else {
+            const spot = this.spots.get(key);
+            const expectedKind = objectKind === 'userSpot' ? 'user' : 'instance';
+            if (spot !== undefined) {
+                return spot.kind === expectedKind && spot.stableType === stableType
+                    ? { kind: 'existing', spot }
+                    : { kind: 'typeMismatch' };
+            }
+            const assigned = this.spotTypes.get(key);
+            if (assigned !== undefined
+                && (assigned.kind !== expectedKind || assigned.stableType !== stableType)) {
+                return { kind: 'typeMismatch' };
+            }
+        }
+        const active = this.reservations.get(reservationKey);
+        if (active !== undefined) {
+            if (active.stableType !== stableType)
+                return { kind: 'typeMismatch' };
+            if (attempt < active.attempt)
+                return { kind: 'attemptStale' };
+            if (attempt === active.attempt)
+                return { kind: 'reserved', reservation: active };
+        }
+        const generation = objectKind === 'actor'
+            ? (this.actorGenerations.get(key) ?? 0n) + 1n
+            : (this.spotGenerations.get(key) ?? 0n) + 1n;
+        const reservation = Object.freeze({
+            id: this.nextReservationId++,
+            objectKind,
+            key,
+            stableType,
+            generation,
+            attempt
+        });
+        this.reservationAttempts.set(reservationKey, attempt);
+        this.reservations.set(reservationKey, reservation);
+        return { kind: 'reserved', reservation };
+    }
+    commitReservation(reservation) {
+        const key = `${reservation.objectKind}:${reservation.key}`;
+        if (this.reservations.get(key)?.id !== reservation.id) {
+            throw new ServiceStaleGenerationError(reservation.objectKind === 'actor' ? 'actor' : 'spot', reservation.key);
+        }
+        this.reservations.delete(key);
+        if (reservation.objectKind === 'actor') {
+            return this.createActorCore(reservation.key, reservation.stableType);
+        }
+        const spotKind = reservation.objectKind === 'instanceSpot' ? 'instance' : 'user';
+        return this.createSpotCore(reservation.key, spotKind, reservation.stableType);
+    }
+    abortReservation(reservation) {
+        const key = `${reservation.objectKind}:${reservation.key}`;
+        if (this.reservations.get(key)?.id !== reservation.id)
+            return false;
+        this.reservations.delete(key);
+        return true;
+    }
+    async runTurn(owner, work) {
+        requireText(owner, 'owner');
+        const previous = this.turns.get(owner) ?? Promise.resolve();
+        let release;
+        const barrier = new Promise(resolve => {
+            release = resolve;
+        });
+        const tail = previous.then(() => barrier);
+        this.turns.set(owner, tail);
+        await previous;
+        try {
+            return await work();
+        }
+        finally {
+            release();
+            if (this.turns.get(owner) === tail)
+                this.turns.delete(owner);
+        }
+    }
+    updateBindingMembership(actor) {
+        const key = actorKey(actor.ref);
+        const binding = this.bindings.get(key);
+        if (binding === undefined)
+            return;
+        this.bindings.set(key, Object.freeze({
+            ...binding,
+            actor: actor.ref,
+            membershipEpoch: actor.membershipEpoch
+        }));
+    }
+}
+exports.ServiceStatefulRegistry = ServiceStatefulRegistry;
+function createSpotState(ref, kind, stableType, authorityOwnerGeneration) {
+    const base = {
+        ref: Object.freeze({ ...ref }),
+        authorityOwnerGeneration,
+        state: 'ready'
+    };
+    switch (kind) {
+        case 'entry':
+            if (stableType !== 'entry') {
+                throw new TypeError('Entry Spot stable type must be entry.');
+            }
+            return Object.freeze({ ...base, kind, stableType });
+        case 'user':
+            return Object.freeze({ ...base, kind, stableType });
+        case 'instance':
+            return Object.freeze({ ...base, kind, stableType });
+    }
+}
+class ServiceTerminalOperationRegistry {
+    operations;
+    constructor(operations = new operation_registry_1.OperationRegistry()) {
+        this.operations = operations;
+    }
+    reserve(timeoutMs, timeoutOwner = 'registry') {
+        return this.operations.reserve(timeoutMs, timeoutOwner);
+    }
+    reply(id, value) {
+        return this.operations.complete(id, value);
+    }
+    fail(id, error) {
+        return this.operations.fail(id, error);
+    }
+    cancel(id) {
+        return this.operations.cancel(id);
+    }
+    isPending(id) {
+        return this.operations.isPending(id);
+    }
+    close() {
+        this.operations.close('Stateful runtime closed.');
+    }
+}
+exports.ServiceTerminalOperationRegistry = ServiceTerminalOperationRegistry;
+function actorKey(actor) {
+    return `${actor.actorId}\0${actor.generation}`;
+}
+function requireText(value, name) {
+    const bytes = Buffer.byteLength(value);
+    if (bytes < 1 || bytes > 255 || value.includes('\0')) {
+        throw new RangeError(`${name} must be 1..255 UTF-8 bytes without NUL.`);
+    }
+}
+function requirePositive(value, name) {
+    if (value < 1n)
+        throw new RangeError(`${name} must be positive.`);
+}
+function max(left, right) {
+    return left > right ? left : right;
+}