@learncard/network-brain-service 3.19.0 → 4.0.0

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

@@ -0,0 +1,271 @@
+import { int } from 'neo4j-driver';
+
+import {
+    SHARE_LINK_CLEANUP_DEFAULT_BATCH,
+    SHARE_LINK_CLEANUP_DEFAULT_CLAIM_MS,
+    SHARE_LINK_CLEANUP_MAX_BATCH,
+    SHARE_LINK_CLEANUP_MAX_CLAIM_MS,
+    SHARE_LINK_CLEANUP_MIN_CLAIM_MS,
+    computeCleanupBackoffMs,
+    computeLeaseExpiry,
+} from '@helpers/share-link-lifecycle';
+import { neogma } from '@instance';
+
+import { ensureShareLinkConstraints } from '../../models/share-link-constraints';
+import { failShareLink } from './errors';
+import { generateClaimToken, readNodeProperties, toShareContentCleanupJobRecord } from './helpers';
+import { withShareLinkTransaction, type ShareLinkTransaction } from './transaction';
+import type {
+    ClaimCleanupJobsInput,
+    ClaimCleanupJobsResult,
+    CompleteCleanupJobInput,
+    CompleteCleanupJobResult,
+    ShareContentCleanupJobRecord,
+} from './types';
+
+const clampLimit = (limit: number | undefined): number => {
+    if (!Number.isSafeInteger(limit) || (limit as number) < 1)
+        return SHARE_LINK_CLEANUP_DEFAULT_BATCH;
+
+    return Math.min(limit as number, SHARE_LINK_CLEANUP_MAX_BATCH);
+};
+
+const clampClaimMs = (claimMs: number | undefined): number => {
+    if (!Number.isSafeInteger(claimMs)) return SHARE_LINK_CLEANUP_DEFAULT_CLAIM_MS;
+
+    return Math.min(
+        Math.max(claimMs as number, SHARE_LINK_CLEANUP_MIN_CLAIM_MS),
+        SHARE_LINK_CLEANUP_MAX_CLAIM_MS
+    );
+};
+
+/**
+ * Require an explicit namespace before any graph access. This is intentionally
+ * only an exact, non-empty-string check: the scheduler additionally enforces the
+ * C1 opaque-identifier rule, while the reviewed lifecycle tests keep their
+ * legacy `localhost%3A3000` namespace at the repository layer.
+ */
+const assertExplicitNamespace = (namespace: unknown): string => {
+    if (typeof namespace !== 'string' || namespace.length === 0) {
+        failShareLink('INVALID_INPUT', 'an explicit cleanup namespace is required');
+    }
+
+    return namespace;
+};
+
+const readCleanupJob = async (
+    tx: ShareLinkTransaction,
+    objectRef: string
+): Promise<ShareContentCleanupJobRecord | null> => {
+    const result = await tx.run(
+        'MATCH (c:ShareContentCleanupJob {objectRef: $objectRef}) RETURN c LIMIT 1',
+        { objectRef }
+    );
+    const props = readNodeProperties(result, 'c');
+
+    return props ? toShareContentCleanupJobRecord(props) : null;
+};
+
+/**
+ * Claims a bounded batch of due cleanup jobs for one explicit namespace.
+ *
+ * The candidate scan and the post-lock reread both filter on the exact
+ * namespace, so a worker never claims a foreign namespace's job. Every clock read
+ * used for eligibility and for the new claim expiry happens *inside* the managed
+ * transaction after the job write lock is taken (and therefore afresh on each
+ * driver retry); production callers omit `now`, tests inject it.
+ *
+ * The claim is fenced: `completeCleanupJob` only accepts the unique `claimToken`
+ * returned here, so a claim whose bounded lease expired cannot complete a job that
+ * another worker has since claimed. Jobs are returned in due order; the caller
+ * performs the actual exact-object LearnCloud deletion and then completes the job.
+ */
+export const claimCleanupJobs = async (
+    input: ClaimCleanupJobsInput
+): Promise<ClaimCleanupJobsResult> => {
+    const namespace = assertExplicitNamespace(input.namespace);
+
+    await ensureShareLinkConstraints();
+
+    const limit = clampLimit(input.limit);
+    const claimMs = clampClaimMs(input.claimMs);
+
+    return withShareLinkTransaction(
+        async tx => {
+            // Discovery prefilter only. Eligibility is re-checked against the
+            // post-lock clock below, so this timestamp cannot authorise a claim.
+            const discoveryNow = (input.now ?? new Date()).toISOString();
+            const candidates = await tx.run(
+                `MATCH (c:ShareContentCleanupJob)
+                 WHERE c.namespace = $namespace
+                   AND ((c.status = 'queued' AND c.nextAttemptAt <= $discoveryNow)
+                        OR (c.status = 'claimed' AND c.claimExpiresAt <= $discoveryNow))
+                 RETURN c.objectRef AS objectRef ORDER BY c.objectRef LIMIT $limit`,
+                { namespace, discoveryNow, limit: int(limit) }
+            );
+            const claimToken = generateClaimToken();
+            const jobs: ShareContentCleanupJobRecord[] = [];
+            for (const candidate of candidates.records) {
+                const objectRef = candidate.get('objectRef');
+                const locked = await tx.run(
+                    `MATCH (c:ShareContentCleanupJob {objectRef: $objectRef})
+                     SET c.lockTick = coalesce(c.lockTick, 0) + 1 RETURN c`,
+                    { objectRef }
+                );
+                const props = readNodeProperties(locked, 'c');
+                if (!props) continue;
+
+                // Fresh clock after the lock (and on every managed retry).
+                const now = input.now ?? new Date();
+                const nowIso = now.toISOString();
+                const job = toShareContentCleanupJobRecord(props);
+                if (job.namespace !== namespace) continue;
+                if (!(
+                    (job.status === 'queued' && job.nextAttemptAt <= nowIso) ||
+                    (job.status === 'claimed' && job.claimExpiresAt && job.claimExpiresAt <= nowIso)
+                ))
+                    continue;
+
+                const claimExpiresAt = computeLeaseExpiry(now, claimMs);
+                const updated = await tx.run(
+                    `MATCH (c:ShareContentCleanupJob {objectRef: $objectRef, namespace: $namespace})
+                     SET c.status = 'claimed', c.claimedBy = $claimant, c.claimToken = $claimToken,
+                         c.claimExpiresAt = $claimExpiresAt, c.updatedAt = $now RETURN c`,
+                    {
+                        objectRef,
+                        namespace,
+                        claimant: input.claimant,
+                        claimToken,
+                        claimExpiresAt,
+                        now: nowIso,
+                    }
+                );
+                const updatedProps = readNodeProperties(updated, 'c');
+                if (updatedProps) jobs.push(toShareContentCleanupJobRecord(updatedProps));
+            }
+
+            return { claimToken, jobs };
+        },
+        { timeoutMs: input.transactionTimeoutMs, noInlineRetry: input.noInlineRetry }
+    );
+};
+
+/**
+ * Completes a claimed cleanup job (`completed`) or returns it to the queue with
+ * exponential backoff (`retry`). A missing/mismatched claim token yields
+ * `claim_lost`; this repository never deletes LearnCloud content itself.
+ */
+export const completeCleanupJob = async (
+    input: CompleteCleanupJobInput
+): Promise<CompleteCleanupJobResult> => {
+    await ensureShareLinkConstraints();
+
+    return withShareLinkTransaction(
+        async tx => {
+            const jobProps = await (async () => {
+                const result = await tx.run(
+                    `MATCH (c:ShareContentCleanupJob {objectRef: $objectRef})
+                     SET c.lockTick = coalesce(c.lockTick, 0) + 1
+                     RETURN c LIMIT 1`,
+                    { objectRef: input.objectRef, claimToken: input.claimToken }
+                );
+
+                return readNodeProperties(result, 'c');
+            })();
+
+            if (!jobProps) return { outcome: 'claim_lost' };
+
+            // Sample the clock only after the job write lock is held (and afresh on
+            // each managed retry). A worker that was blocked on the lock past its
+            // claim expiry therefore observes the lapsed lease and fails completion
+            // instead of committing with a stale pre-lock timestamp.
+            const now = input.now ?? new Date();
+            const nowIso = now.toISOString();
+            const job = toShareContentCleanupJobRecord(jobProps);
+            if (
+                job.status !== 'claimed' ||
+                job.claimToken !== input.claimToken ||
+                !job.claimExpiresAt ||
+                job.claimExpiresAt <= nowIso
+            )
+                return { outcome: 'claim_lost' };
+
+            if (input.outcome === 'completed') {
+                await tx.run(
+                    `MATCH (c:ShareContentCleanupJob {objectRef: $objectRef})
+                     SET c.status = 'completed',
+                         c.completedAt = $now,
+                         c.claimToken = null,
+                         c.claimedBy = null,
+                         c.claimExpiresAt = null,
+                         c.updatedAt = $now`,
+                    { objectRef: input.objectRef, now: nowIso }
+                );
+
+                const updated = await readCleanupJob(tx, input.objectRef);
+
+                return { outcome: 'completed', job: updated ?? job };
+            }
+
+            const attempts = job.attempts + 1;
+            const nextAttemptAt = new Date(
+                now.getTime() + computeCleanupBackoffMs(job.attempts)
+            ).toISOString();
+
+            await tx.run(
+                `MATCH (c:ShareContentCleanupJob {objectRef: $objectRef})
+                 SET c.status = 'queued',
+                     c.attempts = $attempts,
+                     c.nextAttemptAt = $nextAttemptAt,
+                     c.claimToken = null,
+                     c.claimedBy = null,
+                     c.claimExpiresAt = null,
+                     c.lastError = $lastError,
+                     c.updatedAt = $now`,
+                {
+                    objectRef: input.objectRef,
+                    attempts,
+                    nextAttemptAt,
+                    lastError: input.errorMessage ?? null,
+                    now: nowIso,
+                }
+            );
+
+            const updated = await readCleanupJob(tx, input.objectRef);
+
+            return { outcome: 'retry', job: updated ?? job };
+        },
+        { timeoutMs: input.transactionTimeoutMs, noInlineRetry: input.noInlineRetry }
+    );
+};
+
+/** Observability/test read: the durable cleanup job for one exact object. */
+export const getCleanupJob = async (
+    objectRef: string
+): Promise<ShareContentCleanupJobRecord | null> => {
+    const result = await neogma.queryRunner.run(
+        'MATCH (c:ShareContentCleanupJob {objectRef: $objectRef}) RETURN c LIMIT 1',
+        { objectRef }
+    );
+    const props = readNodeProperties(result, 'c');
+
+    return props ? toShareContentCleanupJobRecord(props) : null;
+};
+
+/** Observability/test read: all durable cleanup jobs queued for one share. */
+export const listCleanupJobsForShare = async (
+    shareId: string
+): Promise<ShareContentCleanupJobRecord[]> => {
+    const result = await neogma.queryRunner.run(
+        'MATCH (c:ShareContentCleanupJob {shareId: $shareId}) RETURN c ORDER BY c.createdAt ASC',
+        { shareId }
+    );
+
+    return result.records
+        .map(record => {
+            const props = (record.get('c') as { properties?: Record<string, unknown> })?.properties;
+
+            return props ? toShareContentCleanupJobRecord(props) : null;
+        })
+        .filter((job): job is ShareContentCleanupJobRecord => job !== null);
+};

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

@@ -0,0 +1,32 @@
+/**
+ * Typed failures raised by the share-link lifecycle repository.
+ *
+ * Expected races are surfaced as codes rather than free-form strings so routes and
+ * the reconciliation worker can map them to tRPC/HTTP responses without parsing
+ * messages, and so tests can assert the exact failure class.
+ */
+export type ShareLinkRepositoryErrorCode =
+    | 'NOT_FOUND'
+    | 'CONFLICT'
+    | 'OPERATION_IN_FLIGHT'
+    | 'LEASE_EXPIRED'
+    | 'STALE_GENERATION'
+    | 'PRECONDITION_FAILED'
+    | 'INVALID_INPUT';
+
+export class ShareLinkRepositoryError extends Error {
+    readonly code: ShareLinkRepositoryErrorCode;
+
+    constructor(code: ShareLinkRepositoryErrorCode, message: string) {
+        super(message);
+        this.name = 'ShareLinkRepositoryError';
+        this.code = code;
+    }
+}
+
+export const isShareLinkRepositoryError = (error: unknown): error is ShareLinkRepositoryError =>
+    error instanceof ShareLinkRepositoryError;
+
+export function failShareLink(code: ShareLinkRepositoryErrorCode, message: string): never {
+    throw new ShareLinkRepositoryError(code, message);
+}

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

@@ -0,0 +1,313 @@
+import { SHARE_LINK_OPERATION_RETENTION_MS, isLeaseActive } from '@helpers/share-link-lifecycle';
+import { mergeShareLinkPolicyConservatively } from '@helpers/share-link-policy/resolver';
+import { DEFAULT_SHARE_LINK_POLICY } from '@helpers/share-link-policy/types';
+import type { ShareLinkPolicySnapshot } from '@helpers/share-link-policy/types';
+
+import { ensureShareLinkConstraints } from '../../models/share-link-constraints';
+import { failShareLink } from './errors';
+import { verifyPinnedShareAttachment, queueShareAttachmentCleanup } from './attachment';
+import {
+    deleteReservation,
+    enqueueCleanupJob,
+    lockShare,
+    markOperationCommitted,
+    readOperationByOperationId,
+    readReservation,
+    readShareById,
+    toShareLinkOperationRecord,
+    toShareLinkRecord,
+    toShareLinkReservationRecord,
+} from './helpers';
+import { withShareLinkTransaction } from './transaction';
+import type { FinalizeReservationInput, FinalizeReservationResult } from './types';
+
+const pruneAfterFrom = (now: Date): string =>
+    new Date(now.getTime() + SHARE_LINK_OPERATION_RETENTION_MS).toISOString();
+
+/**
+ * Commits a reserved revision: consumes the reservation under the share write
+ * lock, updates the visible fields/version, records the exact operation result and
+ * enqueues cleanup for the superseded immutable object — all in ONE transaction.
+ *
+ * PRECONDITION (enforced by the caller, never by this repository): the external
+ * coordinator has already verified that the immutable LearnCloud object for
+ * `objectRef` exists and its payloadHash matches the reserved contentHash. `verifiedContentHash`
+ * is re-checked here as defense in depth, but this module performs no network I/O
+ * and cannot itself attest remote existence.
+ *
+ * A stale worker is fenced three ways: the reservation must still match the share,
+ * its bounded lease must be active, and its generation must equal the share's
+ * current generation. A metadata-only reservation leaves `activeObjectRef`
+ * untouched and enqueues no cleanup.
+ */
+export const finalizeReservation = async (
+    input: FinalizeReservationInput
+): Promise<FinalizeReservationResult> => {
+    await ensureShareLinkConstraints();
+
+    const now = input.now ?? new Date();
+    const nowIso = now.toISOString();
+
+    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');
+            }
+
+            if (
+                share.lastOperationId === input.operationId &&
+                (share.activeObjectRef ?? null) === (input.objectRef ?? null) &&
+                share.contentState === 'finalized'
+            ) {
+                return { outcome: 'already_finalized', share };
+            }
+
+            const reservationProps = await readReservation(tx, input.shareId);
+
+            if (!reservationProps) {
+                const operationProps = await readOperationByOperationId(tx, input.operationId);
+
+                if (
+                    operationProps &&
+                    toShareLinkOperationRecord(operationProps).status === 'committed' &&
+                    operationProps.shareId === input.shareId &&
+                    operationProps.namespace === input.namespace &&
+                    operationProps.ownerProfileId === input.ownerProfileId
+                ) {
+                    return { outcome: 'already_finalized', share };
+                }
+
+                failShareLink('CONFLICT', 'reservation is absent or already consumed');
+            }
+
+            const reservation = toShareLinkReservationRecord(reservationProps);
+
+            if (
+                reservation.operationId !== input.operationId ||
+                (reservation.objectRef ?? null) !== (input.objectRef ?? null) ||
+                reservation.generation !== input.generation ||
+                reservation.leaseOwner !== input.leaseOwner ||
+                reservation.namespace !== input.namespace ||
+                reservation.ownerProfileId !== input.ownerProfileId
+            ) {
+                failShareLink('CONFLICT', 'finalize does not match the in-flight reservation');
+            }
+
+            if (share.status === 'stopped') {
+                failShareLink('CONFLICT', 'cannot finalize a stopped share');
+            }
+
+            if (!isLeaseActive(reservation.leaseExpiresAt, input.now ?? new Date())) {
+                failShareLink('LEASE_EXPIRED', 'the reservation lease has expired');
+            }
+
+            if (share.generation !== reservation.generation) {
+                failShareLink('STALE_GENERATION', 'a newer reservation superseded this revision');
+            }
+
+            if (share.version !== reservation.baseVersion) {
+                failShareLink('CONFLICT', 'share version changed since the reservation');
+            }
+
+            if (reservation.contentVersion !== null) {
+                if (reservation.opKind === 'create') {
+                    // The first revision is contentVersion 1 and is not a "+1" replacement.
+                    if (reservation.contentVersion !== 1) {
+                        failShareLink(
+                            'PRECONDITION_FAILED',
+                            'a create reservation must target version 1'
+                        );
+                    }
+                } else {
+                    if (share.contentVersion !== reservation.baseContentVersion) {
+                        failShareLink(
+                            'CONFLICT',
+                            'visible content version changed since the reservation'
+                        );
+                    }
+
+                    if (reservation.contentVersion !== share.contentVersion + 1) {
+                        failShareLink(
+                            'PRECONDITION_FAILED',
+                            'the reserved content version is not current + 1'
+                        );
+                    }
+                }
+            }
+
+            if (
+                input.verifiedContentHash !== undefined &&
+                reservation.contentHash !== null &&
+                input.verifiedContentHash !== reservation.contentHash
+            ) {
+                failShareLink(
+                    'PRECONDITION_FAILED',
+                    'verified content hash does not match the reservation'
+                );
+            }
+
+            const previousObjectRef = share.activeObjectRef;
+            if (
+                reservation.contentVersion !== null &&
+                reservation.attachmentId &&
+                reservation.attachmentChunkCount
+            ) {
+                if (input.verifiedAttachmentId !== reservation.attachmentId) {
+                    failShareLink('PRECONDITION_FAILED', 'attachment was not verified');
+                }
+                await verifyPinnedShareAttachment(
+                    tx,
+                    {
+                        namespace: reservation.namespace,
+                        ownerProfileId: reservation.ownerProfileId,
+                        shareId: reservation.shareId,
+                        contentVersion: reservation.contentVersion,
+                        attachmentId: reservation.attachmentId,
+                        chunkCount: reservation.attachmentChunkCount,
+                    },
+                    reservation.requestHash
+                );
+            }
+            const nextObjectRef = reservation.objectRef ?? share.activeObjectRef;
+            const nextContentVersion = reservation.contentVersion ?? share.contentVersion;
+
+            // Unknown snapshots and old service restrictions may be refreshed on
+            // explicit edits, but only after a fresh graph-local check. The
+            // reservation still caps eligibility for stale replays and recovery.
+            const currentPolicy: ShareLinkPolicySnapshot = {
+                isMinor: share.minorPolicyIsMinor,
+                policyResolved: share.minorPolicyResolved,
+                defaultExpiryDays: share.minorPolicyDefaultExpiryDays === 365 ? 365 : 30,
+                viewCountingEnabled: share.minorPolicyViewCountingEnabled,
+            };
+            const checkedPolicy = input.resolveCurrentPolicy
+                ? await input
+                      .resolveCurrentPolicy(tx, share.ownerProfileId, now)
+                      .catch(() => ({ ...DEFAULT_SHARE_LINK_POLICY, isServiceProfile: false }))
+                : null;
+            const reservationPolicy = checkedPolicy
+                ? mergeShareLinkPolicyConservatively(reservation.policy, checkedPolicy)
+                : mergeShareLinkPolicyConservatively(reservation.policy, currentPolicy);
+            const mayRefreshExplicitService =
+                checkedPolicy?.isServiceProfile === true &&
+                checkedPolicy.isMinor === false &&
+                reservation.opKind === 'update';
+            const mayReplaceUnknown =
+                checkedPolicy !== null &&
+                !currentPolicy.policyResolved &&
+                (reservation.opKind === 'create' || reservation.opKind === 'update');
+            const effectivePolicy =
+                mayRefreshExplicitService || mayReplaceUnknown
+                    ? reservationPolicy
+                    : mergeShareLinkPolicyConservatively(currentPolicy, reservationPolicy);
+
+            await tx.run(
+                `MATCH (s:ShareLink {id: $shareId})
+             SET s += $props`,
+                {
+                    shareId: input.shareId,
+                    props: {
+                        version: share.version + 1,
+                        contentVersion: nextContentVersion,
+                        attachmentId: reservation.objectRef
+                            ? (reservation.attachmentId ?? null)
+                            : (share.attachmentId ?? null),
+                        attachmentChunkCount: reservation.objectRef
+                            ? (reservation.attachmentChunkCount ?? null)
+                            : (share.attachmentChunkCount ?? null),
+                        status: 'active',
+                        contentState: 'finalized',
+                        activeObjectRef: nextObjectRef,
+                        activeObjectOperationId: reservation.objectRef
+                            ? reservation.operationId
+                            : share.activeObjectOperationId,
+                        activeContentHash: reservation.contentHash ?? share.activeContentHash,
+                        activeContentBytes: reservation.contentBytes ?? share.activeContentBytes,
+                        activeRecoveryHash: reservation.recoveryHash ?? share.activeRecoveryHash,
+                        lastOperationId: reservation.operationId,
+                        title: reservation.title,
+                        note: reservation.note,
+                        expiresAt: reservation.expiresAt,
+                        selectedCount: reservation.selectedCount,
+                        passcodeHash: reservation.passcodeHash,
+                        notifyOnView:
+                            reservation.notifyOnView && effectivePolicy.viewCountingEnabled,
+                        minorPolicyIsMinor: effectivePolicy.isMinor,
+                        minorPolicyResolved: effectivePolicy.policyResolved,
+                        minorPolicyDefaultExpiryDays: effectivePolicy.defaultExpiryDays,
+                        minorPolicyViewCountingEnabled: effectivePolicy.viewCountingEnabled,
+                        updatedAt: nowIso,
+                    },
+                }
+            );
+
+            const updatedProps = await readShareById(tx, input.shareId);
+
+            if (!updatedProps) {
+                failShareLink('CONFLICT', 'share disappeared during finalize');
+            }
+
+            const updatedShare = toShareLinkRecord(updatedProps);
+
+            await markOperationCommitted(tx, {
+                namespace: reservation.namespace,
+                ownerProfileId: reservation.ownerProfileId,
+                opKind: reservation.opKind,
+                clientRequestId: reservation.clientRequestId,
+                operationId: reservation.operationId,
+                resultJson: JSON.stringify(updatedShare),
+                resultVersion: updatedShare.version,
+                now: nowIso,
+                pruneAfter: pruneAfterFrom(now),
+            });
+
+            await deleteReservation(tx, input.shareId);
+
+            let cleanupQueuedFor: string | null = null;
+
+            if (previousObjectRef && previousObjectRef !== nextObjectRef) {
+                if (share.attachmentId && share.attachmentChunkCount) {
+                    await queueShareAttachmentCleanup(
+                        tx,
+                        {
+                            namespace: share.namespace,
+                            ownerProfileId: share.ownerProfileId,
+                            shareId: share.id,
+                            contentVersion: share.contentVersion,
+                            attachmentId: share.attachmentId,
+                            chunkCount: share.attachmentChunkCount,
+                        },
+                        'superseded',
+                        nowIso
+                    );
+                }
+                await enqueueCleanupJob(tx, {
+                    objectRef: previousObjectRef,
+                    operationId: share.activeObjectOperationId!,
+                    namespace: reservation.namespace,
+                    ownerProfileId: reservation.ownerProfileId,
+                    shareId: input.shareId,
+                    contentVersion: share.contentVersion,
+                    reason: 'superseded',
+                    now: nowIso,
+                });
+
+                cleanupQueuedFor = previousObjectRef;
+            }
+
+            return { outcome: 'finalized', share: updatedShare, cleanupQueuedFor };
+        },
+        { timeoutMs: input.transactionTimeoutMs, noInlineRetry: input.noInlineRetry }
+    );
+};