@fadhilp/stateql 0.2.0 → 0.3.0

package/dist/src/stateql.js

@@ -9,9 +9,12 @@ import { operationData, paginationWarnings, profileData, rowsToCsv, sessionData,
 import { analyzeSql } from "./sql.js";
 import { StateStore, } from "./store.js";
 import { compactRows, defaultHome, hash, parseJson, redact, } from "./util.js";
+const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
+const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
 export class StateQL {
     store;
     sessionName;
+    actorId;
     previewRows;
     cacheTtlSeconds;
     resultTtlSeconds;
@@ -24,6 +27,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;
@@ -36,7 +43,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();
@@ -111,6 +118,7 @@ export class StateQL {
             }
             const connection = this.store.addConnection({
                 sessionId: session.id,
+                actorId: this.actorId,
                 name: draft.name,
                 driver,
                 databaseName,
@@ -118,6 +126,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,
@@ -204,10 +215,73 @@ 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 };
         });
     }
+    snapshot(options = {}) {
+        const session = this.store
+            .listSessions()
+            .find((candidate) => candidate.name === this.sessionName);
+        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)
+            : undefined;
+        const historyLimit = positiveInteger(options.historyLimit ?? DEFAULT_SNAPSHOT_HISTORY_LIMIT, "historyLimit");
+        if (historyLimit > MAX_SNAPSHOT_HISTORY_LIMIT) {
+            throw new StateQLError("INVALID_COMMAND", `historyLimit cannot exceed ${MAX_SNAPSHOT_HISTORY_LIMIT}.`);
+        }
+        return {
+            session: {
+                session_id: session.id,
+                name: session.name,
+                status: session.status,
+            },
+            actor_id: this.actorId,
+            connection: connection
+                ? {
+                    connection_id: connection.id,
+                    name: connection.name,
+                    status: "connected",
+                    driver: connection.driver,
+                    database: connection.database_name,
+                    read_only: Boolean(connection.read_only),
+                }
+                : null,
+            transaction: transaction
+                ? {
+                    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,
+            recent_results: this.store.knownResults(session.id, 10).map((result) => ({
+                alias: result.alias,
+                handle: result.id,
+                rows: result.row_count,
+            })),
+            recent_operations: this.store
+                .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,
+            })),
+            history: this.store.history(session.id, historyLimit).map(historyEntry),
+        };
+    }
     async status() {
         return this.run("status", async (session) => {
             const connection = this.store.activeConnection(session);
@@ -218,6 +292,7 @@ export class StateQL {
                 data: {
                     session_id: session.id,
                     session_name: session.name,
+                    actor_id: this.actorId,
                     connection: connection
                         ? {
                             connection_id: connection.id,
@@ -228,7 +303,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,
                 },
@@ -237,6 +316,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()) {
@@ -245,7 +396,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,
@@ -295,6 +446,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,
@@ -310,7 +462,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,
@@ -578,10 +732,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,
@@ -618,15 +775,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);
@@ -634,7 +792,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);
                         }
@@ -642,14 +800,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.",
@@ -660,6 +818,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,
@@ -668,7 +827,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.",
@@ -702,7 +861,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,
@@ -757,6 +918,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 ?? [],
@@ -784,6 +946,7 @@ export class StateQL {
                                 : []),
                         ],
                         state_version: plan.state_version,
+                        owner_actor_id: plan.owner_actor_id,
                         expires_at: plan.expires_at,
                     },
                     handle: plan.id,
@@ -810,6 +973,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 },
@@ -818,38 +984,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) {
@@ -857,17 +1040,7 @@ export class StateQL {
             data: {
                 history: this.store
                     .history(session.id, positiveInteger(limit, "limit"))
-                    .map((item) => ({
-                    command_id: item.id,
-                    timestamp: item.timestamp,
-                    session_id: item.session_id,
-                    command: item.command,
-                    handle: item.handle,
-                    executed: Boolean(item.executed),
-                    cached: Boolean(item.cached),
-                    success: Boolean(item.success),
-                    error_code: item.error_code,
-                })),
+                    .map(historyEntry),
             },
         }));
     }
@@ -1038,7 +1211,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." });
         }
@@ -1071,9 +1244,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,
@@ -1085,6 +1262,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 &&
@@ -1143,8 +1331,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),
@@ -1241,8 +1444,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);
     }
@@ -1276,12 +1495,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,
@@ -1291,7 +1523,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: {
@@ -1310,6 +1542,7 @@ export class StateQL {
             this.store.addHistory({
                 id: commandId,
                 sessionId: session.id,
+                actorId: this.actorId,
                 command,
                 executed: stateqlError.details.executed,
                 cached: false,
@@ -1328,9 +1561,23 @@ export class StateQL {
         }
     }
 }
-function markTransactionOutcomeUnknown(store, transactionId, sessionId) {
+function historyEntry(item) {
+    return {
+        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),
+        cached: Boolean(item.cached),
+        success: Boolean(item.success),
+        error_code: item.error_code,
+    };
+}
+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.