@learncard/network-brain-service 3.19.0 → 4.0.0

package/src/helpers/share-link-attachment.ts

@@ -0,0 +1,115 @@
+import {
+    PutShareLinkAttachmentChunkInputValidator,
+    DeleteShareLinkAttachmentChunksInputValidator,
+} from '@learncard/types';
+import type {
+    PutShareLinkAttachmentChunkInput,
+    DeleteShareLinkAttachmentChunksInput,
+} from '@learncard/types';
+import type { ShareContentClient } from './share-content-client';
+import {
+    beginShareAttachmentChunk,
+    completeShareAttachmentChunk,
+    deleteUnreferencedShareAttachment,
+    shareAttachmentTuple,
+    type ShareAttachmentBinding,
+} from '../accesslayer/share-link/attachment';
+import { ShareLinkCoordinatorError } from './share-link-coordinator/types';
+import type { ShareOwnerContext } from './share-link-coordinator/types';
+import { isShareLinkRepositoryError } from '../accesslayer/share-link/errors';
+
+export type ShareLinkAttachmentOwnerApi = {
+    put: (
+        input: PutShareLinkAttachmentChunkInput,
+        owner: ShareOwnerContext
+    ) => Promise<{ ok: true }>;
+    delete: (
+        input: DeleteShareLinkAttachmentChunksInput,
+        owner: ShareOwnerContext
+    ) => Promise<{ ok: boolean }>;
+};
+
+export const createShareLinkAttachmentOwnerApi = (
+    client: Pick<ShareContentClient, 'put' | 'delete'>,
+    repository = {
+        begin: beginShareAttachmentChunk,
+        complete: completeShareAttachmentChunk,
+        deleteUnreferenced: deleteUnreferencedShareAttachment,
+    }
+): ShareLinkAttachmentOwnerApi => {
+    const bindingFor = (
+        input: DeleteShareLinkAttachmentChunksInput,
+        owner: ShareOwnerContext
+    ): ShareAttachmentBinding => ({
+        namespace: owner.namespace,
+        ownerProfileId: owner.ownerProfileId,
+        shareId: input.id,
+        contentVersion: input.contentVersion,
+        attachmentId: input.attachmentId,
+        chunkCount: input.chunkCount,
+    });
+    return {
+        put: async (input, owner) => {
+            const parsed = PutShareLinkAttachmentChunkInputValidator.safeParse(input);
+            if (!parsed.success)
+                throw new ShareLinkCoordinatorError('INVALID_INPUT', 'invalid attachment');
+            const value = parsed.data;
+            const binding = bindingFor(value, owner);
+            try {
+                await repository.begin(binding, value.chunkIndex);
+                const result = await client.put({
+                    ...shareAttachmentTuple(binding, value.chunkIndex),
+                    envelope: value.envelope,
+                    ownerEncryptedRecovery: value.ownerEncryptedRecovery,
+                });
+                if (!result.ok)
+                    throw new ShareLinkCoordinatorError(
+                        result.error === 'CONFLICT' ? 'CONFLICT' : 'UNAVAILABLE',
+                        'attachment upload unavailable'
+                    );
+                await repository.complete(binding, value.chunkIndex);
+                return { ok: true };
+            } catch (error) {
+                if (error instanceof ShareLinkCoordinatorError) throw error;
+                const code = isShareLinkRepositoryError(error) ? error.code : undefined;
+                throw new ShareLinkCoordinatorError(
+                    code === 'CONFLICT'
+                        ? 'CONFLICT'
+                        : code === 'NOT_FOUND'
+                          ? 'NOT_FOUND'
+                          : code === 'PRECONDITION_FAILED' || code === 'INVALID_INPUT'
+                            ? code
+                            : 'UNAVAILABLE',
+                    'attachment upload unavailable'
+                );
+            }
+        },
+        delete: async (input, owner) => {
+            const parsed = DeleteShareLinkAttachmentChunksInputValidator.safeParse(input);
+            if (!parsed.success)
+                throw new ShareLinkCoordinatorError('INVALID_INPUT', 'invalid attachment');
+            const binding = bindingFor(parsed.data, owner);
+            let allowed: boolean;
+            try {
+                allowed = await repository.deleteUnreferenced(binding);
+            } catch {
+                throw new ShareLinkCoordinatorError(
+                    'UNAVAILABLE',
+                    'attachment cleanup unavailable'
+                );
+            }
+            if (!allowed) return { ok: false };
+            // Durable jobs were queued before I/O; interrupted/failed deletes are retried by maintenance.
+            let ok = true;
+            for (let index = 0; index < binding.chunkCount; index++) {
+                try {
+                    const result = await client.delete(shareAttachmentTuple(binding, index));
+                    if (!result.ok) ok = false;
+                } catch {
+                    ok = false;
+                }
+            }
+            return { ok };
+        },
+    };
+};

package/src/helpers/share-link-coordinator/attachment-stat.ts

@@ -0,0 +1,41 @@
+import { shareAttachmentTuple } from '../../accesslayer/share-link/attachment';
+import type { ShareLinkReservationRecord } from '../../accesslayer/share-link/types';
+import type { ShareContentClient } from '../share-content-client';
+import type { MaintenanceBudget } from './types';
+import { budgetAllows } from './budget-helpers';
+
+/** Verify the complete immutable set before releasing the atomic commit fence. */
+export const verifyShareAttachmentStats = async (
+    client: Pick<ShareContentClient, 'stat'>,
+    reservation: ShareLinkReservationRecord,
+    budget?: MaintenanceBudget,
+    remoteAndFinalizeCostMs = 0
+): Promise<boolean> => {
+    if (reservation.contentVersion === null || !reservation.attachmentId) return true;
+    const count = reservation.attachmentChunkCount;
+    if (!count || count < 1 || count > 16) return false;
+    const binding = {
+        namespace: reservation.namespace,
+        ownerProfileId: reservation.ownerProfileId,
+        shareId: reservation.shareId,
+        contentVersion: reservation.contentVersion,
+        attachmentId: reservation.attachmentId,
+        chunkCount: count,
+    };
+    for (let index = 0; index < count; index++) {
+        // Each bounded HTTP call must leave enough time for finalization and the
+        // pass reserve. A many-chunk asset cannot overrun the maintenance budget.
+        if (!budgetAllows(budget, remoteAndFinalizeCostMs)) return false;
+        const tuple = shareAttachmentTuple(binding, index);
+        const result = await client.stat(tuple);
+        if (!result.ok || result.value.kind !== 'active') return false;
+        const active = result.value;
+        if (
+            Object.entries(tuple).some(
+                ([key, value]) => active[key as keyof typeof active] !== value
+            )
+        )
+            return false;
+    }
+    return true;
+};

package/src/helpers/share-link-coordinator/budget-helpers.ts

@@ -0,0 +1,53 @@
+import type { MaintenanceBudget } from './types';
+
+/**
+ * True only for the maintenance budget that opted into whole-unit admission.
+ * Legacy/direct callers that pass a bare budget keep the reviewed `exhausted`
+ * gate and are never subjected to the extra mid-unit rechecks.
+ */
+export const budgetHasUnitReserve = (budget: MaintenanceBudget | undefined): boolean =>
+    budget !== undefined && typeof budget.reserveMs === 'function';
+
+/**
+ * Cooperative budget helpers shared by the recovery and cleanup runners.
+ *
+ * `budgetAllows` is deliberately conservative only when the caller opted into the
+ * maintenance reserve (`reserveMs`). Direct/legacy callers that pass a bare budget
+ * keep the reviewed `exhausted()` behaviour, so this cannot silently disable a
+ * one-shot runner that predates the maintenance scheduler.
+ */
+export const budgetAllows = (budget: MaintenanceBudget | undefined, costMs: number): boolean => {
+    if (!budget) return true;
+
+    if (typeof budget.reserveMs !== 'function' || !Number.isFinite(costMs)) {
+        return !budget.exhausted();
+    }
+
+    const remaining = budget.remainingMs();
+    if (!Number.isFinite(remaining)) return false;
+
+    return remaining - budget.reserveMs() >= Math.max(0, costMs);
+};
+
+/**
+ * Bound a per-call managed-transaction timeout by the time actually left before
+ * the pass reserve. The result is always >= 1 so an explicit maintenance
+ * transaction still has a positive server-side bound; it can never extend the
+ * configured timeout.
+ */
+export const boundTransactionTimeout = (
+    configuredTimeoutMs: number | undefined,
+    budget: MaintenanceBudget | undefined
+): number | undefined => {
+    if (configuredTimeoutMs === undefined) return undefined;
+    if (!budget) return configuredTimeoutMs;
+
+    const remaining = budget.remainingMs();
+    if (!Number.isFinite(remaining)) return configuredTimeoutMs;
+
+    const reserved = typeof budget.reserveMs === 'function' ? budget.reserveMs() : 0;
+    const available = remaining - reserved;
+    if (!Number.isFinite(available)) return configuredTimeoutMs;
+
+    return Math.max(1, Math.trunc(Math.min(configuredTimeoutMs, available)));
+};

package/src/helpers/share-link-coordinator/cleanup-runner.ts

@@ -0,0 +1,286 @@
+import {
+    SHARE_LINK_CLEANUP_DEFAULT_BATCH,
+    SHARE_LINK_CLEANUP_MAX_BATCH,
+} from '../share-link-lifecycle';
+import {
+    isTransientShareContentError,
+    type ShareContentClientErrorCode,
+} from '../share-content-client/types';
+import {
+    ShareLinkCoordinatorError,
+    type CleanupRunnerDependencies,
+    type CleanupRunSummary,
+    type ShareCleanupCategory,
+} from './types';
+import { budgetAllows, budgetHasUnitReserve, boundTransactionTimeout } from './budget-helpers';
+
+const OPAQUE_IDENTIFIER_RE = /^[A-Za-z0-9._~-]+$/;
+
+const isOpaqueIdentifier = (value: unknown, maxLength = 128): value is string =>
+    typeof value === 'string' &&
+    value.length >= 1 &&
+    value.length <= maxLength &&
+    OPAQUE_IDENTIFIER_RE.test(value);
+
+/**
+ * Validate the operator-configured scope before any graph or remote I/O. A
+ * missing or malformed namespace means the pass does nothing at all.
+ */
+const assertRunnerScope = (dependencies: CleanupRunnerDependencies): void => {
+    if (!isOpaqueIdentifier(dependencies.claimant)) {
+        throw new ShareLinkCoordinatorError(
+            'INVALID_INPUT',
+            'claimant must be an opaque configured identifier'
+        );
+    }
+    if (!isOpaqueIdentifier(dependencies.namespace)) {
+        throw new ShareLinkCoordinatorError(
+            'INVALID_INPUT',
+            'namespace must be an opaque configured identifier'
+        );
+    }
+};
+
+const clampTotal = (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 clampBatchSize = (batchSize: number | undefined, total: number): number => {
+    if (!Number.isSafeInteger(batchSize) || (batchSize as number) < 1) return total;
+
+    return Math.min(batchSize as number, total);
+};
+
+const recordCategory = (
+    categories: Partial<Record<ShareCleanupCategory, number>>,
+    category: ShareCleanupCategory
+): void => {
+    categories[category] = (categories[category] ?? 0) + 1;
+};
+
+/**
+ * Cap the managed-transaction timeout by the time left in the pass so a graph
+ * unit cannot outlive a cooperative deadline. No budget means the configured
+ * repository default is used unchanged.
+ */
+const boundTransactionTimeoutMs = (
+    configuredTimeoutMs: number | undefined,
+    budget: CleanupRunnerDependencies['budget']
+): number | undefined => boundTransactionTimeout(configuredTimeoutMs, budget);
+
+/**
+ * Worst-case bounded cost of one whole cleanup unit:
+ *   claim (graph) + delete (HTTP) + complete (graph).
+ * The HTTP allowance is fixed when the transport client is constructed, so it
+ * cannot be reduced per call; the graph calls are bounded per call below.
+ */
+const cleanupUnitCostMs = (dependencies: CleanupRunnerDependencies): number =>
+    (dependencies.requestTimeoutMs ?? 0) + 2 * (dependencies.transactionTimeoutMs ?? 0);
+
+/** Cost of the remote/complete tail once a job has already been claimed. */
+const cleanupRemoteCostMs = (dependencies: CleanupRunnerDependencies): number =>
+    (dependencies.requestTimeoutMs ?? 0) + (dependencies.transactionTimeoutMs ?? 0);
+
+type DeleteOutcome =
+    | { ok: true }
+    | { ok: false; transient: true; error: ShareContentClientErrorCode }
+    | { ok: false; category: ShareCleanupCategory };
+
+type ClaimedCleanupJob = Awaited<
+    ReturnType<CleanupRunnerDependencies['repository']['claimCleanupJobs']>
+>['jobs'][number];
+
+/**
+ * Bounded, one-shot cleanup runner for durable C3 cleanup jobs.
+ *
+ * It is deliberately NOT a scheduler: nothing registers it, no interval is
+ * created, and no ShareLink routes or workers are enabled by importing it. The
+ * maintenance scheduler owns cadence.
+ *
+ * For every claimed job it sends the exact immutable binding —
+ * `{ namespace, ownerProfileId, shareId, contentVersion, objectId: objectRef,
+ * operationId }` — to LearnCloud `delete`. `operationId` is the ORIGINAL object
+ * operation id recorded by C3, never the latest metadata operation.
+ *
+ * A job is completed only on a proven LearnCloud deletion/tombstone response.
+ * Transient/unavailable responses are returned to the queue with C3's capped
+ * exponential backoff. Any other response leaves the job claimed (never
+ * completed) so the fenced claim expires and another worker can retry; this
+ * never pretends a deletion happened. The returned summary contains aggregate
+ * counts and fixed categories only — never an object ref or exception text.
+ */
+export const runShareContentCleanupOnce = async (
+    dependencies: CleanupRunnerDependencies
+): Promise<CleanupRunSummary> => {
+    assertRunnerScope(dependencies);
+
+    const { repository, client } = dependencies;
+    const total = clampTotal(dependencies.limit);
+    const batchSize = clampBatchSize(dependencies.claimBatchSize, total);
+
+    const summary: CleanupRunSummary = {
+        claimed: 0,
+        completed: 0,
+        retried: 0,
+        claimLost: 0,
+        skipped: 0,
+        categories: {},
+    };
+
+    // Claim just-in-time so a deadline can never strand a whole claimed batch.
+    // The default (batch size >= total) keeps the reviewed single-claim
+    // behaviour; maintenance sets a small batch size and re-checks the budget
+    // before every claim.
+    const singleShot = batchSize >= total;
+
+    while (summary.claimed < total) {
+        // Whole-unit admission: a claim is only started when the remaining budget
+        // can also cover the delete and the completion (or the retry write).
+        if (!budgetAllows(dependencies.budget, cleanupUnitCostMs(dependencies))) break;
+
+        const remaining = total - summary.claimed;
+        const claimLimit = singleShot ? total : Math.min(batchSize, remaining);
+
+        let claim: Awaited<ReturnType<CleanupRunnerDependencies['repository']['claimCleanupJobs']>>;
+        try {
+            claim = await repository.claimCleanupJobs({
+                namespace: dependencies.namespace,
+                claimant: dependencies.claimant,
+                limit: claimLimit,
+                claimMs: dependencies.claimMs,
+                transactionTimeoutMs: boundTransactionTimeoutMs(
+                    dependencies.transactionTimeoutMs,
+                    dependencies.budget
+                ),
+                noInlineRetry: dependencies.noInlineRetry,
+                // Omit production time so the repository samples it after the lock.
+                now: dependencies.now?.(),
+            });
+        } catch {
+            // Could not confirm a claim; a later pass retries after the lease.
+            summary.claimLost += 1;
+            recordCategory(summary.categories, 'claim_error');
+            break;
+        }
+
+        if (claim.jobs.length === 0) break;
+
+        let stoppedBeforeRemote = false;
+
+        for (const job of claim.jobs) {
+            summary.claimed += 1;
+
+            // Recheck after the awaited claim, before the network call: the claim
+            // may have waited on a lock. If the tail no longer fits, leave the job
+            // fenced (its lease will lapse) and start no further call. Only the
+            // maintenance budget opts into this mid-unit reserve.
+            if (
+                budgetHasUnitReserve(dependencies.budget) &&
+                !budgetAllows(dependencies.budget, cleanupRemoteCostMs(dependencies))
+            ) {
+                recordCategory(summary.categories, 'budget_exhausted');
+                stoppedBeforeRemote = true;
+                break;
+            }
+
+            const deletion = await safeDelete(client, job);
+
+            if (deletion.ok) {
+                const completion = await safeComplete(repository, {
+                    objectRef: job.objectRef,
+                    claimToken: claim.claimToken,
+                    outcome: 'completed',
+                    transactionTimeoutMs: boundTransactionTimeoutMs(
+                        dependencies.transactionTimeoutMs,
+                        dependencies.budget
+                    ),
+                    noInlineRetry: dependencies.noInlineRetry,
+                    now: dependencies.now?.(),
+                });
+
+                if (completion?.outcome === 'completed') summary.completed += 1;
+                else {
+                    summary.claimLost += 1;
+                    recordCategory(summary.categories, 'claim_lost');
+                }
+
+                continue;
+            }
+
+            if ('transient' in deletion) {
+                const completion = await safeComplete(repository, {
+                    objectRef: job.objectRef,
+                    claimToken: claim.claimToken,
+                    outcome: 'retry',
+                    errorMessage: deletion.error,
+                    transactionTimeoutMs: boundTransactionTimeoutMs(
+                        dependencies.transactionTimeoutMs,
+                        dependencies.budget
+                    ),
+                    noInlineRetry: dependencies.noInlineRetry,
+                    now: dependencies.now?.(),
+                });
+
+                if (completion?.outcome === 'retry') summary.retried += 1;
+                else {
+                    summary.claimLost += 1;
+                    recordCategory(summary.categories, 'claim_lost');
+                }
+
+                continue;
+            }
+
+            // Deterministic/authorization failure: never complete. Leave the claim to
+            // expire so the bounded fence lets another worker retry later.
+            summary.skipped += 1;
+            recordCategory(summary.categories, deletion.category);
+        }
+
+        if (singleShot || stoppedBeforeRemote) break;
+    }
+
+    return summary;
+};
+
+const safeDelete = async (
+    client: CleanupRunnerDependencies['client'],
+    job: ClaimedCleanupJob
+): Promise<DeleteOutcome> => {
+    let result: Awaited<ReturnType<CleanupRunnerDependencies['client']['delete']>>;
+
+    try {
+        result = await client.delete({
+            namespace: job.namespace,
+            ownerProfileId: job.ownerProfileId,
+            shareId: job.shareId,
+            contentVersion: job.contentVersion,
+            objectId: job.objectRef,
+            operationId: job.operationId,
+        });
+    } catch {
+        return { ok: false, category: 'client_error' };
+    }
+
+    if (result.ok) return { ok: true };
+    if (isTransientShareContentError(result.error)) {
+        return { ok: false, transient: true, error: result.error };
+    }
+
+    return { ok: false, category: result.error };
+};
+
+const safeComplete = async (
+    repository: CleanupRunnerDependencies['repository'],
+    input: Parameters<CleanupRunnerDependencies['repository']['completeCleanupJob']>[0]
+): Promise<Awaited<
+    ReturnType<CleanupRunnerDependencies['repository']['completeCleanupJob']>
+> | null> => {
+    try {
+        return await repository.completeCleanupJob(input);
+    } catch {
+        return null;
+    }
+};