@fadhilp/stateql 0.2.2 → 0.3.1

package/dist/src/stateql.js

@@ -12,8 +12,26 @@ import { compactRows, defaultHome, hash, parseJson, redact, } from "./util.js";
 const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
 const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
 export class StateQL {
+    static forActor(options) {
+        if (!options.actor.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Actor ID is required.");
+        }
+        const now = options.now ?? (() => new Date());
+        const store = new StateStore(options.home ?? defaultHome(), now);
+        try {
+            const session = store.resolveActor(options.actor);
+            if (session)
+                return new StateQL({ ...options, session: session.name });
+            const { actor, ...legacyOptions } = options;
+            return new StateQL({ ...legacyOptions, session: actor });
+        }
+        finally {
+            store.close();
+        }
+    }
     store;
     sessionName;
+    actorId;
     previewRows;
     cacheTtlSeconds;
     resultTtlSeconds;
@@ -26,6 +44,10 @@ export class StateQL {
     constructor(options = {}) {
         this.now = options.now ?? (() => new Date());
         this.sessionName = options.session ?? env.STQL_SESSION ?? "default";
+        this.actorId = options.actor ?? this.sessionName;
+        if (!this.actorId.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Actor ID is required.");
+        }
         this.previewRows = options.previewRows ?? 5;
         this.cacheTtlSeconds = options.cacheTtlSeconds ?? 300;
         this.resultTtlSeconds = options.resultTtlSeconds ?? 86_400;
@@ -38,7 +60,7 @@ export class StateQL {
             throw new StateQLError("INVALID_COMMAND", "maxResultRows is too large.");
         }
         this.store = new StateStore(options.home ?? defaultHome(), this.now);
-        this.store.ensureSession(this.sessionName);
+        this.store.bootstrapSession(this.sessionName, this.actorId, options.actor === undefined);
     }
     close() {
         this.store.close();
@@ -113,6 +135,7 @@ export class StateQL {
             }
             const connection = this.store.addConnection({
                 sessionId: session.id,
+                actorId: this.actorId,
                 name: draft.name,
                 driver,
                 databaseName,
@@ -120,6 +143,9 @@ export class StateQL {
                 ...(secretEnv ? { secretEnv } : {}),
                 readOnly,
             });
+            if (!connection) {
+                throw new StateQLError("TRANSACTION_FAILED", "A transaction became active while changing the connection.");
+            }
             return {
                 data: {
                     connection_id: connection.id,
@@ -206,7 +232,9 @@ export class StateQL {
             if (session.active_transaction_id) {
                 throw new StateQLError("TRANSACTION_FAILED", "Commit or roll back the active transaction before disconnecting.");
             }
-            this.store.disconnect(session.id);
+            if (!this.store.disconnect(session.id, this.actorId)) {
+                throw new StateQLError("TRANSACTION_FAILED", "A transaction became active while disconnecting.");
+            }
             return { data: { disconnected: true }, executed: true };
         });
     }
@@ -217,6 +245,9 @@ export class StateQL {
         if (!session) {
             throw new StateQLError("INVALID_COMMAND", "The active session was not found.");
         }
+        if (!this.store.isSessionMember(session.id, this.actorId)) {
+            throw new StateQLError("PERMISSION_DENIED", `Actor "${this.actorId}" is not attached to session "${session.name}".`);
+        }
         const connection = this.store.activeConnection(session);
         const transaction = session.active_transaction_id
             ? this.store.getTransaction(session.active_transaction_id)
@@ -231,6 +262,7 @@ export class StateQL {
                 name: session.name,
                 status: session.status,
             },
+            actor_id: this.actorId,
             connection: connection
                 ? {
                     connection_id: connection.id,
@@ -242,7 +274,11 @@ export class StateQL {
                 }
                 : null,
             transaction: transaction
-                ? { transaction_id: transaction.id, state: transaction.state }
+                ? {
+                    transaction_id: transaction.id,
+                    owner_actor_id: transaction.owner_actor_id,
+                    state: transaction.state,
+                }
                 : null,
             state_version: connection ? version(connection) : null,
             state_confidence: connection ? confidence(connection) : null,
@@ -255,6 +291,7 @@ export class StateQL {
                 .recentOperations(session.id, 10)
                 .map((operation) => ({
                 handle: operation.id,
+                actor_id: operation.actor_id,
                 type: operation.statement_type,
                 affected_rows: operation.affected_rows,
                 status: operation.status,
@@ -272,6 +309,7 @@ export class StateQL {
                 data: {
                     session_id: session.id,
                     session_name: session.name,
+                    actor_id: this.actorId,
                     connection: connection
                         ? {
                             connection_id: connection.id,
@@ -282,7 +320,11 @@ export class StateQL {
                         }
                         : null,
                     transaction: transaction
-                        ? { transaction_id: transaction.id, state: transaction.state }
+                        ? {
+                            transaction_id: transaction.id,
+                            owner_actor_id: transaction.owner_actor_id,
+                            state: transaction.state,
+                        }
                         : null,
                     state_version: connection ? version(connection) : null,
                 },
@@ -291,6 +333,78 @@ export class StateQL {
             };
         });
     }
+    async linkActor(session, actorId) {
+        return this.run("actor.link", async (current) => {
+            this.requireSelectedSession(current, session);
+            this.validateActorId(actorId);
+            const result = this.store.linkActor(current.id, this.actorId, actorId);
+            if (result === "actor_conflict") {
+                throw new StateQLError("PERMISSION_DENIED", `Actor "${actorId}" is already attached to another session.`);
+            }
+            if (result === "denied")
+                this.throwMembershipDenied(current);
+            return {
+                data: {
+                    session_id: current.id,
+                    actor_id: actorId,
+                    linked: result === "linked",
+                },
+                executed: result === "linked",
+            };
+        });
+    }
+    async unlinkActor(session, actorId) {
+        return this.run("actor.unlink", async (current) => {
+            this.requireSelectedSession(current, session);
+            this.validateActorId(actorId);
+            const result = this.store.unlinkActor(current.id, this.actorId, actorId);
+            if (result === "owns_transaction") {
+                throw new StateQLError("TRANSACTION_FAILED", `Actor "${actorId}" owns the active transaction.`);
+            }
+            if (result === "denied")
+                this.throwMembershipDenied(current);
+            return {
+                data: {
+                    session_id: current.id,
+                    actor_id: actorId,
+                    unlinked: result === "unlinked",
+                },
+                executed: result === "unlinked",
+            };
+        });
+    }
+    async listActors(session) {
+        return this.run("actor.list", async (current) => {
+            this.requireSelectedSession(current, session);
+            return {
+                data: {
+                    session_id: current.id,
+                    actors: this.store.listActors(current.id).map((member) => ({
+                        actor_id: member.actor_id,
+                        attached_at: member.attached_at,
+                    })),
+                },
+            };
+        });
+    }
+    async resolveActor(actorId) {
+        return this.run("actor.resolve", async () => {
+            this.validateActorId(actorId);
+            const session = this.store.resolveActor(actorId);
+            return {
+                data: {
+                    actor_id: actorId,
+                    session: session
+                        ? {
+                            session_id: session.id,
+                            name: session.name,
+                            status: session.status,
+                        }
+                        : null,
+                },
+            };
+        });
+    }
     async startSession(name) {
         return this.run("session.start", async () => {
             if (!name.trim()) {
@@ -299,7 +413,7 @@ export class StateQL {
             if (this.store.getSessionByName(name)) {
                 throw new StateQLError("INVALID_COMMAND", `Active session "${name}" already exists.`);
             }
-            const session = this.store.ensureSession(name);
+            const session = this.store.bootstrapSession(name, name, true);
             return {
                 data: sessionData(session),
                 handle: session.id,
@@ -349,6 +463,7 @@ export class StateQL {
                         .recentOperations(session.id, 10)
                         .map((operation) => ({
                         handle: operation.id,
+                        actor_id: operation.actor_id,
                         type: operation.statement_type,
                         affected_rows: operation.affected_rows,
                         status: operation.status,
@@ -364,7 +479,9 @@ export class StateQL {
             if (session.active_transaction_id) {
                 throw new StateQLError("TRANSACTION_FAILED", "Roll back or commit the active transaction first.");
             }
-            this.store.closeSession(session.id);
+            if (!this.store.closeSession(session.id, this.actorId)) {
+                throw new StateQLError("TRANSACTION_FAILED", "A transaction became active while closing the session.");
+            }
             return {
                 data: { session_id: session.id, state: "closed" },
                 handle: session.id,
@@ -632,10 +749,13 @@ export class StateQL {
             const normalizedIsolation = normalizeIsolation(isolation, connection.driver);
             const transaction = this.store.createTransaction({
                 sessionId: session.id,
+                actorId: this.actorId,
                 connectionId: connection.id,
                 isolation: normalizedIsolation,
-                startVersion: version(connection),
             });
+            if (!transaction) {
+                throw new StateQLError("TRANSACTION_FAILED", "Another actor acquired the active transaction.");
+            }
             return {
                 data: transactionData(transaction, 0),
                 handle: transaction.id,
@@ -672,15 +792,16 @@ export class StateQL {
             if (version(connection) !== transaction.start_version) {
                 throw new StateQLError("TRANSACTION_FAILED", "Connection state changed after the transaction began.", { suggestedAction: "Roll back and begin a new transaction." });
             }
-            const operations = this.store.transactionOperations(transaction.id);
-            if (operations.some((operation) => operation.connection_id !== connection.id)) {
-                throw new StateQLError("TRANSACTION_FAILED", "Transaction contains writes staged for another connection.", { suggestedAction: "Roll back the transaction." });
-            }
             const adapter = await createAdapter(connection, this.executionContext(options));
             try {
-                if (!this.store.markTransactionCommitting(transaction.id)) {
+                if (!this.store.markTransactionCommitting(transaction.id, session.id, this.actorId)) {
                     throw new StateQLError("TRANSACTION_FAILED", "Transaction is no longer active.");
                 }
+                const operations = this.store.transactionOperations(transaction.id);
+                if (operations.some((operation) => operation.connection_id !== connection.id)) {
+                    this.store.finishTransaction(transaction.id, session.id, this.actorId, "failed");
+                    throw new StateQLError("TRANSACTION_FAILED", "Transaction contains writes staged for another connection.");
+                }
                 let results;
                 try {
                     results = await adapter.writeBatch(operations, transaction.isolation_level);
@@ -688,7 +809,7 @@ export class StateQL {
                 catch (error) {
                     if ((error instanceof BatchWriteError && !error.outcomeUnknown) ||
                         (error instanceof AdapterExecutionError && !error.outcomeUnknown)) {
-                        this.store.finishTransaction(transaction.id, session.id, "failed");
+                        this.store.finishTransaction(transaction.id, session.id, this.actorId, "failed");
                         if (error instanceof AdapterExecutionError) {
                             throw stoppedStateQLError(error, false);
                         }
@@ -696,14 +817,14 @@ export class StateQL {
                             retryable: true,
                         });
                     }
-                    markTransactionOutcomeUnknown(this.store, transaction.id, session.id);
+                    markTransactionOutcomeUnknown(this.store, transaction.id, session.id, this.actorId);
                     throw new StateQLError("OUTCOME_UNKNOWN", errorMessage(error), {
                         executed: true,
                         suggestedAction: "Inspect database state before issuing any replacement write.",
                     });
                 }
                 if (results.length !== operations.length) {
-                    markTransactionOutcomeUnknown(this.store, transaction.id, session.id);
+                    markTransactionOutcomeUnknown(this.store, transaction.id, session.id, this.actorId);
                     throw new StateQLError("OUTCOME_UNKNOWN", "Database returned an incomplete transaction result.", {
                         executed: true,
                         suggestedAction: "Inspect database state before issuing any replacement write.",
@@ -714,6 +835,7 @@ export class StateQL {
                     stateVersion = this.store.commitTransactionMetadata({
                         transactionId: transaction.id,
                         sessionId: session.id,
+                        actorId: this.actorId,
                         connectionId: connection.id,
                         operations: operations.map((operation, index) => ({
                             id: operation.id,
@@ -722,7 +844,7 @@ export class StateQL {
                     });
                 }
                 catch (error) {
-                    markTransactionOutcomeUnknown(this.store, transaction.id, session.id);
+                    markTransactionOutcomeUnknown(this.store, transaction.id, session.id, this.actorId);
                     throw new StateQLError("OUTCOME_UNKNOWN", errorMessage(error), {
                         executed: true,
                         suggestedAction: "Inspect database state before issuing any replacement write.",
@@ -756,7 +878,9 @@ export class StateQL {
         return this.run("transaction.rollback", async (session) => {
             const transaction = this.requireActiveTransaction(session, id);
             const count = this.store.transactionOperations(transaction.id).length;
-            this.store.finishTransaction(transaction.id, session.id, "rolled_back");
+            if (!this.store.finishTransaction(transaction.id, session.id, this.actorId, "rolled_back")) {
+                throw new StateQLError("TRANSACTION_FAILED", "Transaction is no longer active.");
+            }
             return {
                 data: {
                     transaction_id: transaction.id,
@@ -811,6 +935,7 @@ export class StateQL {
                 const expiresAt = new Date(this.now().getTime() + 10 * 60_000).toISOString();
                 const plan = this.store.savePlan({
                     sessionId: session.id,
+                    ownerActorId: this.actorId,
                     connectionId: connection.id,
                     sql,
                     parameters: options.params ?? [],
@@ -838,6 +963,7 @@ export class StateQL {
                                 : []),
                         ],
                         state_version: plan.state_version,
+                        owner_actor_id: plan.owner_actor_id,
                         expires_at: plan.expires_at,
                     },
                     handle: plan.id,
@@ -864,6 +990,9 @@ export class StateQL {
             if (!plan || plan.session_id !== session.id) {
                 throw new StateQLError("STALE_PLAN", `Plan "${planId}" was not found.`);
             }
+            if (plan.owner_actor_id !== this.actorId) {
+                throw new StateQLError("PERMISSION_DENIED", "Only the actor that created this plan may apply it.");
+            }
             if (plan.applied_operation_id) {
                 throw new StateQLError("STALE_PLAN", "Plan was already applied.", {
                     extra: { previous_operation_id: plan.applied_operation_id },
@@ -872,38 +1001,55 @@ export class StateQL {
             if (Date.parse(plan.expires_at) <= this.now().getTime()) {
                 throw new StateQLError("STALE_PLAN", "Plan has expired.");
             }
-            const connection = this.requireConnection(session);
-            if (connection.id !== plan.connection_id ||
-                version(connection) !== plan.state_version) {
-                throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
+            const claimToken = this.store.nextId("claim");
+            const claimed = this.store.claimPlan(plan.id, session.id, this.actorId, claimToken);
+            if (!claimed) {
+                throw new StateQLError("STALE_PLAN", "Plan is already being applied.");
             }
-            const context = this.executionContext(options);
-            const adapter = await createAdapter(connection, context);
+            let retainClaim = false;
             try {
-                if ((await adapter.signature()) !== plan.state_signature) {
+                const connection = this.requireConnection(session);
+                if (connection.id !== claimed.connection_id ||
+                    version(connection) !== claimed.state_version) {
                     throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
                 }
+                const context = this.executionContext(options);
+                const adapter = await createAdapter(connection, context);
+                try {
+                    if ((await adapter.signature()) !== claimed.state_signature) {
+                        throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
+                    }
+                }
+                catch (error) {
+                    if (error instanceof AdapterExecutionError) {
+                        throw stoppedStateQLError(error, true);
+                    }
+                    throw error;
+                }
+                finally {
+                    await adapter.close();
+                }
+                const result = await this.performExec(session, connection, claimed.sql, {
+                    params: parseJson(claimed.parameters, []),
+                    allowUnbounded: Boolean(claimed.allow_unbounded),
+                    allowDestructive: Boolean(claimed.allow_destructive),
+                }, context, { planId: claimed.id, claimToken });
+                return {
+                    ...result,
+                    data: { plan_id: claimed.id, ...result.data },
+                };
             }
             catch (error) {
-                if (error instanceof AdapterExecutionError) {
-                    throw stoppedStateQLError(error, true);
+                if (error instanceof StateQLError &&
+                    error.details.code === "OUTCOME_UNKNOWN") {
+                    retainClaim = true;
                 }
                 throw error;
             }
             finally {
-                await adapter.close();
+                if (!retainClaim)
+                    this.store.releasePlanClaim(plan.id, claimToken);
             }
-            const result = await this.performExec(session, connection, plan.sql, {
-                params: parseJson(plan.parameters, []),
-                allowUnbounded: Boolean(plan.allow_unbounded),
-                allowDestructive: Boolean(plan.allow_destructive),
-            }, context);
-            const operationId = String(result.data.operation_id);
-            this.store.markPlanApplied(plan.id, operationId);
-            return {
-                ...result,
-                data: { plan_id: plan.id, ...result.data },
-            };
         });
     }
     async history(limit = 20) {
@@ -1082,7 +1228,7 @@ export class StateQL {
                 return;
         }
     }
-    async performExec(session, connection, sql, options, context) {
+    async performExec(session, connection, sql, options, context, planClaim) {
         if (connection.read_only) {
             throw new StateQLError("READ_ONLY_CONNECTION", "Connection is read-only.", { suggestedAction: "Reconnect with --read-write." });
         }
@@ -1115,9 +1261,13 @@ export class StateQL {
                 transaction.connection_id !== connection.id) {
                 throw new StateQLError("TRANSACTION_FAILED", "Active transaction does not match the active connection.");
             }
+            if (transaction.owner_actor_id !== this.actorId) {
+                throw new StateQLError("PERMISSION_DENIED", "Only the transaction owner may stage writes.");
+            }
         }
         const reservation = this.store.reserveOperation({
             sessionId: session.id,
+            actorId: this.actorId,
             connectionId: connection.id,
             fingerprint,
             sql,
@@ -1129,6 +1279,17 @@ export class StateQL {
             idempotencyKey: options.idempotencyKey,
             stateVersionBefore: version(connection),
         });
+        if (reservation.denied === "membership") {
+            throw new StateQLError("PERMISSION_DENIED", "Actor membership changed before the write was reserved.");
+        }
+        if (reservation.denied === "transaction") {
+            const active = this.store.getSession(session.id)?.active_transaction_id;
+            const transaction = active ? this.store.getTransaction(active) : undefined;
+            if (transaction && transaction.owner_actor_id !== this.actorId) {
+                throw new StateQLError("PERMISSION_DENIED", "Only the transaction owner may stage writes.");
+            }
+            throw new StateQLError("TRANSACTION_FAILED", "The active transaction changed before the write was reserved.");
+        }
         const previous = reservation.previous;
         if (previous &&
             options.idempotencyKey &&
@@ -1187,8 +1348,23 @@ export class StateQL {
         try {
             const write = await adapter.write(sql, parameters);
             try {
-                const after = this.store.bumpVersion(connection.id);
-                const committed = this.store.finishOperation(operation.id, write.affectedRows, after);
+                const finalized = planClaim
+                    ? this.store.finishPlannedOperation({
+                        planId: planClaim.planId,
+                        claimToken: planClaim.claimToken,
+                        operationId: operation.id,
+                        connectionId: connection.id,
+                        affectedRows: write.affectedRows,
+                    })
+                    : (() => {
+                        const stateVersion = this.store.bumpVersion(connection.id);
+                        return {
+                            operation: this.store.finishOperation(operation.id, write.affectedRows, stateVersion),
+                            stateVersion,
+                        };
+                    })();
+                const committed = finalized.operation;
+                const after = finalized.stateVersion;
                 return {
                     data: {
                         ...operationData(committed),
@@ -1285,8 +1461,24 @@ export class StateQL {
             session.active_transaction_id !== transaction.id) {
             throw new StateQLError("TRANSACTION_NOT_FOUND", `Active transaction "${transactionId}" was not found.`);
         }
+        if (transaction.owner_actor_id !== this.actorId) {
+            throw new StateQLError("PERMISSION_DENIED", "Only the transaction owner may control it.");
+        }
         return transaction;
     }
+    requireSelectedSession(current, selected) {
+        if (selected !== current.id && selected !== current.name) {
+            throw new StateQLError("PERMISSION_DENIED", "Membership can only be managed for the selected session.");
+        }
+    }
+    validateActorId(actorId) {
+        if (!actorId.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Actor ID is required.");
+        }
+    }
+    throwMembershipDenied(session) {
+        throw new StateQLError("PERMISSION_DENIED", `Actor "${this.actorId}" is not attached to session "${session.name}".`);
+    }
     executionContext(options) {
         return createAdapterContext(executionTimeout(options.timeoutMs ?? this.timeoutMs), options.signal ?? this.signal);
     }
@@ -1320,12 +1512,25 @@ export class StateQL {
         const started = performance.now();
         let session = this.store.ensureSession(this.sessionName);
         const commandId = this.store.nextId("cmd");
+        if (!this.store.isSessionMember(session.id, this.actorId)) {
+            const error = new StateQLError("PERMISSION_DENIED", `Actor "${this.actorId}" is not attached to session "${session.name}".`);
+            return {
+                ok: false,
+                command_id: commandId,
+                session_id: session.id,
+                error: error.details,
+                meta: {
+                    duration_ms: Math.round((performance.now() - started) * 1000) / 1000,
+                },
+            };
+        }
         try {
             const result = await action(session);
-            session = result.session ?? session;
+            const responseSession = result.session ?? session;
             this.store.addHistory({
                 id: commandId,
                 sessionId: session.id,
+                actorId: this.actorId,
                 command,
                 ...(result.handle ? { handle: result.handle } : {}),
                 executed: result.executed ?? false,
@@ -1335,7 +1540,7 @@ export class StateQL {
             return {
                 ok: true,
                 command_id: commandId,
-                session_id: session.id,
+                session_id: responseSession.id,
                 data: result.data,
                 warnings: result.warnings ?? [],
                 meta: {
@@ -1354,6 +1559,7 @@ export class StateQL {
             this.store.addHistory({
                 id: commandId,
                 sessionId: session.id,
+                actorId: this.actorId,
                 command,
                 executed: stateqlError.details.executed,
                 cached: false,
@@ -1377,6 +1583,7 @@ function historyEntry(item) {
         command_id: item.id,
         timestamp: item.timestamp,
         session_id: item.session_id,
+        actor_id: item.actor_id,
         command: item.command,
         handle: item.handle,
         executed: Boolean(item.executed),
@@ -1385,9 +1592,9 @@ function historyEntry(item) {
         error_code: item.error_code,
     };
 }
-function markTransactionOutcomeUnknown(store, transactionId, sessionId) {
+function markTransactionOutcomeUnknown(store, transactionId, sessionId, actorId) {
     try {
-        store.markTransactionOutcomeUnknown(transactionId, sessionId);
+        store.markTransactionOutcomeUnknown(transactionId, sessionId, actorId);
     }
     catch {
         // A stale committing transaction is recovered as unknown after five minutes.