@learncard/network-brain-service 3.18.0 → 3.19.1

package/src/accesslayer/share-link/revoke.ts

@@ -0,0 +1,197 @@
+import { SHARE_LINK_OPERATION_RETENTION_MS } from '@helpers/share-link-lifecycle';
+
+import { ensureShareLinkConstraints } from '../../models/share-link-constraints';
+import { failShareLink } from './errors';
+import {
+    deleteReservation,
+    enqueueCleanupJob,
+    generateOperationId,
+    lockShare,
+    markOperationAbandoned,
+    markOperationCommitted,
+    readOperation,
+    readReservation,
+    readShareById,
+    toShareLinkOperationRecord,
+    toShareLinkRecord,
+    toShareLinkReservationRecord,
+    writeOperationInProgress,
+    type ShareLinkOperationKey,
+} from './helpers';
+import { withShareLinkTransaction } from './transaction';
+import type { RevokeShareLinkInput, RevokeShareLinkResult } from './types';
+
+const pruneAfterFrom = (now: Date): string =>
+    new Date(now.getTime() + SHARE_LINK_OPERATION_RETENTION_MS).toISOString();
+
+/**
+ * Terminally stops a share.
+ *
+ * Revoke is serialized with finalize by the same share write lock and is
+ * idempotent: once `status = 'stopped'` a retry returns the stopped share without
+ * re-checking `expectedVersion`, so a retry after the revision changed still
+ * succeeds. Stopping does not synchronously delete bytes; it queues the visible
+ * object (and any staged replacement object) for tracked cleanup and bumps the
+ * fencing generation so an in-flight finalize can no longer commit.
+ */
+export const revokeShareLink = async (
+    input: RevokeShareLinkInput
+): Promise<RevokeShareLinkResult> => {
+    await ensureShareLinkConstraints();
+
+    if (input.clientRequestId && !input.requestHash) {
+        failShareLink('INVALID_INPUT', 'requestHash is required when clientRequestId is supplied');
+    }
+
+    const now = input.now ?? new Date();
+    const nowIso = now.toISOString();
+    const pruneAfter = pruneAfterFrom(now);
+
+    return withShareLinkTransaction(async tx => {
+        const lockedProps = await lockShare(tx, input.shareId);
+
+        if (!lockedProps) {
+            failShareLink('NOT_FOUND', 'share not found');
+        }
+
+        const share = toShareLinkRecord(lockedProps);
+
+        if (share.namespace !== input.namespace || share.ownerProfileId !== input.ownerProfileId) {
+            failShareLink('NOT_FOUND', 'share not found');
+        }
+
+        const operationKey: ShareLinkOperationKey | null =
+            input.clientRequestId && input.requestHash
+                ? {
+                      namespace: input.namespace,
+                      ownerProfileId: input.ownerProfileId,
+                      opKind: 'revoke',
+                      clientRequestId: input.clientRequestId,
+                  }
+                : null;
+
+        if (operationKey && input.requestHash) {
+            const operationProps = await readOperation(tx, operationKey);
+
+            if (operationProps) {
+                const operation = toShareLinkOperationRecord(operationProps);
+
+                if (operation.requestHash !== input.requestHash) {
+                    failShareLink(
+                        'CONFLICT',
+                        'clientRequestId was already used with a different revoke request'
+                    );
+                }
+
+                if (operation.status === 'committed') {
+                    return { outcome: 'already_stopped', share, cleanupQueuedFor: [] };
+                }
+            }
+        }
+
+        if (share.status === 'stopped') {
+            return { outcome: 'already_stopped', share, cleanupQueuedFor: [] };
+        }
+
+        if (input.expectedVersion !== undefined && share.version !== input.expectedVersion) {
+            failShareLink(
+                'CONFLICT',
+                `expectedVersion ${input.expectedVersion} does not match the current version ${share.version}`
+            );
+        }
+
+        const cleanupRefs = new Set<string>();
+        const reservationProps = await readReservation(tx, input.shareId);
+
+        if (reservationProps) {
+            const reservation = toShareLinkReservationRecord(reservationProps);
+
+            if (reservation.objectRef) {
+                await enqueueCleanupJob(tx, {
+                    objectRef: reservation.objectRef,
+                    operationId: reservation.operationId,
+                    namespace: reservation.namespace,
+                    ownerProfileId: reservation.ownerProfileId,
+                    shareId: reservation.shareId,
+                    contentVersion: reservation.contentVersion ?? reservation.baseContentVersion,
+                    reason: 'abandoned',
+                    now: nowIso,
+                });
+                cleanupRefs.add(reservation.objectRef);
+            }
+
+            await markOperationAbandoned(tx, {
+                namespace: reservation.namespace,
+                ownerProfileId: reservation.ownerProfileId,
+                opKind: reservation.opKind,
+                clientRequestId: reservation.clientRequestId,
+                now: nowIso,
+            });
+            await deleteReservation(tx, input.shareId);
+        }
+
+        if (share.activeObjectRef) {
+            await enqueueCleanupJob(tx, {
+                objectRef: share.activeObjectRef,
+                operationId: share.activeObjectOperationId!,
+                namespace: share.namespace,
+                ownerProfileId: share.ownerProfileId,
+                shareId: share.id,
+                contentVersion: share.contentVersion,
+                reason: 'stopped',
+                now: nowIso,
+            });
+            cleanupRefs.add(share.activeObjectRef);
+        }
+
+        await tx.run(
+            `MATCH (s:ShareLink {id: $shareId})
+             SET s.status = 'stopped',
+                 s.stoppedAt = $now,
+                 s.version = $version,
+                 s.generation = $generation,
+                 s.updatedAt = $now`,
+            {
+                shareId: input.shareId,
+                now: nowIso,
+                version: share.version + 1,
+                generation: share.generation + 1,
+            }
+        );
+
+        const updatedProps = await readShareById(tx, input.shareId);
+
+        if (!updatedProps) {
+            failShareLink('CONFLICT', 'share disappeared during revoke');
+        }
+
+        const updatedShare = toShareLinkRecord(updatedProps);
+
+        if (operationKey && input.requestHash) {
+            const operationId = generateOperationId();
+
+            await writeOperationInProgress(tx, {
+                ...operationKey,
+                operationId,
+                shareId: input.shareId,
+                requestHash: input.requestHash,
+                now: nowIso,
+                pruneAfter,
+            });
+            await markOperationCommitted(tx, {
+                ...operationKey,
+                operationId,
+                resultJson: JSON.stringify(updatedShare),
+                resultVersion: updatedShare.version,
+                now: nowIso,
+                pruneAfter,
+            });
+        }
+
+        return {
+            outcome: 'revoked',
+            share: updatedShare,
+            cleanupQueuedFor: [...cleanupRefs],
+        };
+    });
+};

package/src/accesslayer/share-link/transaction-execution.ts

@@ -0,0 +1,72 @@
+/**
+ * Pure Neo4j transaction execution helpers.
+ *
+ * These live outside `transaction.ts` so they can be unit-tested without loading
+ * `@instance` (which requires real Neo4j environment variables at import time).
+ *
+ * The driver's managed `executeWrite` retries transient failures inline using
+ * driver-level configuration. That is correct for ordinary request callers, but a
+ * cooperative maintenance pass instead wants one bounded attempt: if it cannot
+ * commit now it leaves the durable work fenced and lets the next cadence retry.
+ * `executeExplicitTransaction` provides exactly that explicit, no-inline-retry
+ * attempt.
+ */
+
+/** Minimal structural transaction surface shared by managed and explicit paths. */
+export type ExecutableTransaction = {
+    run: (query: string, params?: Record<string, unknown>) => Promise<unknown>;
+};
+
+export type ExplicitTransaction = ExecutableTransaction & {
+    commit: () => Promise<void>;
+    rollback: () => Promise<void>;
+};
+
+/** The subset of the neo4j-driver session API this module depends on. */
+export type TransactionSession = {
+    beginTransaction: (config?: { timeout?: number }) => ExplicitTransaction;
+};
+
+export type TransactionTimeoutConfig = { timeout: number } | undefined;
+
+export const resolveTransactionConfig = (
+    timeoutMs: number | undefined
+): TransactionTimeoutConfig =>
+    typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs > 0
+        ? { timeout: Math.trunc(timeoutMs) }
+        : undefined;
+
+/**
+ * Run one explicit transaction attempt with a bounded server-side timeout.
+ *
+ * There is deliberately no retry: a transient failure propagates to the caller,
+ * which records a bounded category and leaves the durable claim/job for the next
+ * cadence. The callback must only perform graph-local work — no network I/O — so
+ * a rollback can never strand a remote mutation.
+ */
+export const executeExplicitTransaction = async <T>(
+    session: TransactionSession,
+    work: (tx: ExecutableTransaction) => Promise<T>,
+    timeoutMs?: number
+): Promise<T> => {
+    const transaction = session.beginTransaction(resolveTransactionConfig(timeoutMs));
+
+    let result: T;
+
+    try {
+        result = await work(transaction);
+    } catch (error) {
+        try {
+            await transaction.rollback();
+        } catch {
+            // The transaction may already be terminated (e.g. timeout). The
+            // original failure is authoritative.
+        }
+
+        throw error;
+    }
+
+    await transaction.commit();
+
+    return result;
+};

package/src/accesslayer/share-link/transaction.ts

@@ -0,0 +1,126 @@
+import { neogma } from '@instance';
+
+import { ShareLinkRepositoryError } from './errors';
+import {
+    executeExplicitTransaction,
+    resolveTransactionConfig,
+    type TransactionSession,
+} from './transaction-execution';
+
+/** Neo4j signals a uniqueness race as a client error; map it to a typed conflict. */
+const isNeo4jConstraintViolation = (error: unknown): boolean => {
+    const code = (error as { code?: string } | undefined)?.code;
+
+    return (
+        code === 'Neo.ClientError.Schema.ConstraintValidationFailed' ||
+        code === 'Neo.ClientError.Statement.ConstraintVerificationFailed'
+    );
+};
+
+/** Minimal structural result shape used by the lifecycle Cypher helpers. */
+export type Neo4jQueryResult = {
+    records: Array<{
+        get: (key: string) => unknown;
+    }>;
+};
+
+/** The subset of the neo4j-driver transaction API the repository depends on. */
+export interface ShareLinkTransaction {
+    run: (query: string, params?: Record<string, unknown>) => Promise<Neo4jQueryResult>;
+}
+
+/**
+ * Narrow, opt-in transaction bounds.
+ *
+ * When omitted (every existing caller), the managed write transaction keeps the
+ * driver defaults exactly as before. A maintenance caller may set `timeoutMs` so
+ * a single transaction cannot outlive its declared pass budget; it does not
+ * change the retry behaviour or any other caller.
+ */
+export type ShareLinkTransactionOptions = {
+    /** Neo4j managed-transaction timeout in milliseconds. */
+    timeoutMs?: number;
+    /**
+     * Maintenance-only mode: run a single explicit transaction with the supplied
+     * timeout and NO driver-managed inline retry. Ordinary callers omit this and
+     * keep the existing managed retry defaults; a maintenance pass leaves retry to
+     * the next scheduler cadence.
+     */
+    noInlineRetry?: boolean;
+};
+
+/**
+ * Runs a read unit either through the shared auto-commit query runner (ordinary
+ * callers, unchanged) or, when a maintenance bound is supplied, through a single
+ * explicit read transaction with that timeout. No inline retry is used in the
+ * bounded path.
+ */
+export const withShareLinkRead = async <T>(
+    work: (runner: ShareLinkTransaction) => Promise<T>,
+    options?: ShareLinkTransactionOptions
+): Promise<T> => {
+    if (options?.noInlineRetry !== true && options?.timeoutMs === undefined) {
+        return work(neogma.queryRunner as unknown as ShareLinkTransaction);
+    }
+
+    const session = neogma.queryRunner.getDriver().session();
+
+    try {
+        return await executeExplicitTransaction<T>(
+            session as unknown as TransactionSession,
+            tx => work(tx as unknown as ShareLinkTransaction),
+            options?.timeoutMs
+        );
+    } finally {
+        await session.close();
+    }
+};
+
+/**
+ * Runs a unit of share-link lifecycle work inside one managed Neo4j write transaction.
+ *
+ * The repository deliberately uses a managed write transaction rather than a sequence
+ * of auto-committed statements: the share write lock acquired by the first
+ * statement must cover every subsequent read of status/version/reservation state
+ * and the final writes. A rollback aborts the whole unit, so a partial finalize
+ * (metadata swapped without the cleanup job, or vice versa) is impossible.
+ *
+ * Reads that only need a committed snapshot use the auto-committed `queryRunner`
+ * helpers instead; this wrapper is for mutations.
+ */
+export const withShareLinkTransaction = async <T>(
+    work: (tx: ShareLinkTransaction) => Promise<T>,
+    options?: ShareLinkTransactionOptions
+): Promise<T> => {
+    const session = neogma.queryRunner.getDriver().session();
+    try {
+        if (options?.noInlineRetry === true) {
+            // One explicit, bounded attempt with no inline retry.
+            return await executeExplicitTransaction<T>(
+                session as unknown as TransactionSession,
+                tx => work(tx as unknown as ShareLinkTransaction),
+                options.timeoutMs
+            );
+        }
+
+        // Managed writes retry transient Neo4j deadlocks. Callback work must be
+        // graph-local: no remote uploads or deletes inside the transaction.
+        const transactionConfig = resolveTransactionConfig(options?.timeoutMs);
+
+        return await session.executeWrite(
+            tx => work(tx as unknown as ShareLinkTransaction),
+            transactionConfig
+        );
+    } catch (error) {
+        if (isNeo4jConstraintViolation(error)) {
+            throw new ShareLinkRepositoryError(
+                'CONFLICT',
+                'a concurrent share-link write violated a uniqueness rule'
+            );
+        }
+
+        throw error;
+    } finally {
+        await session.close();
+    }
+};