@learncard/network-brain-service 3.19.0 → 4.0.0

package/src/helpers/share-link-maintenance/runner.ts

@@ -0,0 +1,251 @@
+import type {
+    CleanupRunnerDependencies,
+    RecoveryRunnerDependencies,
+} from '../share-link-coordinator';
+import { runShareContentCleanupOnce } from '../share-link-coordinator/cleanup-runner';
+import { budgetAllows } from '../share-link-coordinator/budget-helpers';
+import { runShareLinkRecoveryOnce } from '../share-link-coordinator/recovery-runner';
+import type { ShareContentClient } from '../share-content-client/types';
+import type { PruneShareViewReceiptsInput } from '../../accesslayer/share-link/types';
+import {
+    createMaintenancePassBudget,
+    resolveMaintenanceBudgetMs,
+    type MaintenancePassBudget,
+} from './budget';
+import { safeLogMaintenance } from './telemetry';
+import type {
+    ShareLinkMaintenanceConfig,
+    ShareLinkMaintenanceFailureCategory,
+    ShareLinkMaintenanceLogger,
+    ShareLinkMaintenanceRunSummary,
+} from './types';
+
+export type ShareLinkMaintenanceRunnerDependencies = {
+    config: ShareLinkMaintenanceConfig;
+    recoveryRepository: RecoveryRunnerDependencies['repository'];
+    cleanupRepository: CleanupRunnerDependencies['repository'];
+    /**
+     * Namespace-scoped, bounded receipt prune. Injected so DB-free unit tests
+     * never load the Neo4j `@instance`; production passes the real repository.
+     */
+    pruneReceipts: (input: PruneShareViewReceiptsInput) => Promise<number>;
+    expireAttachmentStages?: typeof import('../../accesslayer/share-link/attachment').expireShareAttachmentStages;
+    client: Pick<ShareContentClient, 'stat' | 'delete'>;
+    logger: ShareLinkMaintenanceLogger;
+    /** Monotonic clock for the cooperative budget; injectable for tests. */
+    monotonicNow?: () => number;
+    /** Wall clock passed through to the repositories; production omits it. */
+    now?: () => Date;
+    /**
+     * Optional Lambda remaining-time source, in milliseconds. Ignored when a
+     * pre-started `budget` is supplied.
+     */
+    remainingTimeMs?: () => number;
+    /**
+     * Optional budget already started by the runtime BEFORE dependency
+     * initialization. Reused so a slow cold start consumes the invocation
+     * deadline rather than receiving a fresh post-setup budget.
+     */
+    budget?: MaintenancePassBudget;
+};
+
+/**
+ * Bounded graph cost of the very first recovery stage (discovery read). If this
+ * does not fit, neither recovery nor cleanup can start.
+ */
+const recoveryDiscoveryCostMs = (config: ShareLinkMaintenanceConfig): number =>
+    config.graphTimeoutMs;
+
+/**
+ * Worst-case bounded cost of one whole cleanup unit:
+ *   claim (graph) + delete (HTTP) + complete (graph).
+ */
+const cleanupUnitCostMs = (config: ShareLinkMaintenanceConfig): number =>
+    config.requestTimeoutMs + 2 * config.graphTimeoutMs;
+
+/**
+ * Bounded cost of one namespace-scoped receipt-prune read transaction.
+ */
+const receiptPruneCostMs = (config: ShareLinkMaintenanceConfig): number => config.graphTimeoutMs;
+
+/**
+ * One bounded maintenance invocation: namespace-scoped recovery followed by
+ * namespace-scoped cleanup, each with its own count limit and a shared elapsed
+ * deadline.
+ *
+ * The deadline is cooperative (see `createMaintenancePassBudget`): it is checked
+ * before every claim, never enforced with `Promise.race`, so a remote delete or
+ * graph mutation that has already started is always awaited to a tracked result.
+ * Admission requires the remaining time to cover the whole next unit — the
+ * claim, the bounded HTTP call and the finalizing graph write — plus the
+ * finalization/telemetry reserve. The HTTP allowance is fixed when the transport
+ * client is built, so it cannot be shrunk per call; graph transaction timeouts
+ * are dynamically capped to the time actually left.
+ *
+ * Every failure is folded into a fixed category; the summary exposes aggregate
+ * counts and durations only.
+ */
+export const runShareLinkMaintenancePass = async (
+    dependencies: ShareLinkMaintenanceRunnerDependencies
+): Promise<ShareLinkMaintenanceRunSummary> => {
+    const { config, logger } = dependencies;
+
+    const budget =
+        dependencies.budget ??
+        createMaintenancePassBudget({
+            budgetMs: resolveMaintenanceBudgetMs(config.budgetMs, dependencies.remainingTimeMs?.()),
+            finalizeReserveMs: config.finalizeReserveMs,
+            monotonicNow: dependencies.monotonicNow,
+        });
+
+    const categories: Partial<Record<ShareLinkMaintenanceFailureCategory, number>> = {};
+
+    if (budget.exhausted()) {
+        const summary: ShareLinkMaintenanceRunSummary = {
+            status: 'deadline_exhausted',
+            durationMs: budget.elapsedMs(),
+            budgetMs: budget.configuredMs,
+            recovery: null,
+            cleanup: null,
+            receiptPrune: null,
+            categories,
+        };
+
+        safeLogMaintenance(logger, summary);
+
+        return summary;
+    }
+
+    let recovery: ShareLinkMaintenanceRunSummary['recovery'] = null;
+    let cleanup: ShareLinkMaintenanceRunSummary['cleanup'] = null;
+    let receiptPrune: ShareLinkMaintenanceRunSummary['receiptPrune'] = null;
+    let recoveryAttempted = false;
+    let cleanupAttempted = false;
+    let receiptPruneAttempted = false;
+    let budgetStoppedRecovery = false;
+    let budgetStoppedCleanup = false;
+    let budgetStoppedReceiptPrune = false;
+    let attachmentStages: ShareLinkMaintenanceRunSummary['attachmentStages'];
+    let stageFailed = false;
+
+    if (budgetAllows(budget, recoveryDiscoveryCostMs(config))) {
+        recoveryAttempted = true;
+
+        try {
+            recovery = await runShareLinkRecoveryOnce({
+                repository: dependencies.recoveryRepository,
+                client: dependencies.client,
+                claimant: config.claimant,
+                namespace: config.namespace,
+                limit: config.recoveryLimit,
+                leaseMs: config.leaseMs,
+                budget,
+                transactionTimeoutMs: config.graphTimeoutMs,
+                requestTimeoutMs: config.requestTimeoutMs,
+                noInlineRetry: true,
+                now: dependencies.now,
+            });
+        } catch {
+            categories.share_link_maintenance_recovery_failed = 1;
+        }
+    } else {
+        budgetStoppedRecovery = true;
+    }
+
+    if (dependencies.expireAttachmentStages) {
+        if (budgetAllows(budget, config.graphTimeoutMs)) {
+            try {
+                attachmentStages = {
+                    queued: await dependencies.expireAttachmentStages({
+                        namespace: config.namespace,
+                        limit: 10,
+                        now: dependencies.now?.(),
+                        transaction: { timeoutMs: config.graphTimeoutMs, noInlineRetry: true },
+                    }),
+                };
+            } catch {
+                attachmentStages = null;
+                stageFailed = true;
+                categories.share_link_maintenance_attachment_stage_failed = 1;
+            }
+        } else {
+            budgetStoppedCleanup = true;
+        }
+    }
+
+    if (budgetAllows(budget, cleanupUnitCostMs(config))) {
+        cleanupAttempted = true;
+
+        try {
+            cleanup = await runShareContentCleanupOnce({
+                repository: dependencies.cleanupRepository,
+                client: dependencies.client,
+                claimant: config.claimant,
+                namespace: config.namespace,
+                limit: config.cleanupLimit,
+                claimMs: config.claimMs,
+                // One job per claim so a lapsed deadline can never strand a batch.
+                claimBatchSize: 1,
+                transactionTimeoutMs: config.graphTimeoutMs,
+                requestTimeoutMs: config.requestTimeoutMs,
+                noInlineRetry: true,
+                budget,
+                now: dependencies.now,
+            });
+        } catch {
+            categories.share_link_maintenance_cleanup_failed = 1;
+        }
+    } else {
+        budgetStoppedCleanup = true;
+    }
+
+    if (budgetAllows(budget, receiptPruneCostMs(config))) {
+        receiptPruneAttempted = true;
+
+        try {
+            const pruned = await dependencies.pruneReceipts({
+                namespace: config.namespace,
+                limit: config.receiptPruneLimit,
+                now: dependencies.now?.(),
+                // One bounded explicit read transaction, no inline retry: the
+                // scheduler cadence owns retry.
+                transaction: { timeoutMs: config.graphTimeoutMs, noInlineRetry: true },
+            });
+            receiptPrune = { pruned };
+        } catch {
+            categories.share_link_maintenance_receipt_prune_failed = 1;
+        }
+    } else {
+        budgetStoppedReceiptPrune = true;
+    }
+
+    const failed =
+        stageFailed ||
+        (recoveryAttempted && recovery === null) ||
+        (cleanupAttempted && cleanup === null) ||
+        (receiptPruneAttempted && receiptPrune === null);
+    const deadlineStopped =
+        budgetStoppedRecovery || budgetStoppedCleanup || budgetStoppedReceiptPrune;
+    const status = failed
+        ? 'failed'
+        : budget.exhausted() || deadlineStopped
+          ? 'deadline_exhausted'
+          : 'completed';
+
+    const summary: ShareLinkMaintenanceRunSummary = {
+        status,
+        durationMs: budget.elapsedMs(),
+        budgetMs: budget.configuredMs,
+        recovery,
+        cleanup,
+        receiptPrune,
+        ...(dependencies.expireAttachmentStages
+            ? { attachmentStages: attachmentStages ?? null }
+            : {}),
+        categories,
+    };
+
+    safeLogMaintenance(logger, summary);
+
+    return summary;
+};

package/src/helpers/share-link-maintenance/runtime.ts

@@ -0,0 +1,340 @@
+import type {
+    CleanupRunnerDependencies,
+    RecoveryRunnerDependencies,
+} from '../share-link-coordinator';
+import type { PruneShareViewReceiptsInput } from '../../accesslayer/share-link/types';
+import type { ShareContentClient } from '../share-content-client/types';
+import { createMaintenancePassBudget, resolveMaintenanceBudgetMs } from './budget';
+import { resolveShareLinkMaintenanceConfig } from './config';
+import { runShareLinkMaintenancePass } from './runner';
+import { safeLogMaintenance } from './telemetry';
+import type {
+    ShareLinkMaintenanceConfigResolution,
+    ShareLinkMaintenanceLogger,
+    ShareLinkMaintenanceRunSummary,
+} from './types';
+
+type MaintenanceClient = Pick<ShareContentClient, 'stat' | 'delete'>;
+
+type ResolvedRunnerDependencies = {
+    expireAttachmentStages?: typeof import('../../accesslayer/share-link/attachment').expireShareAttachmentStages;
+    recoveryRepository: RecoveryRunnerDependencies['repository'];
+    cleanupRepository: CleanupRunnerDependencies['repository'];
+    pruneReceipts: (input: PruneShareViewReceiptsInput) => Promise<number>;
+    client: MaintenanceClient;
+};
+
+type DependencySetup =
+    | { status: 'ready'; dependencies: ResolvedRunnerDependencies }
+    | { status: 'failed' }
+    | { status: 'expired' };
+
+export type ShareLinkMaintenanceRuntime = {
+    /** Config outcome fixed at construction; never contains raw values. */
+    readonly resolution: ShareLinkMaintenanceConfigResolution;
+    runOnce: (options?: {
+        /**
+         * Live Lambda remaining-time source. A numeric value is accepted as a
+         * backward-compatible test seam; production passes the live
+         * `getRemainingTimeInMillis` callback.
+         */
+        remainingTimeMs?: number | (() => number);
+    }) => Promise<ShareLinkMaintenanceRunSummary>;
+};
+
+export type CreateShareLinkMaintenanceRuntimeOptions = {
+    rawEnvironment?: Record<string, unknown>;
+    logger?: ShareLinkMaintenanceLogger;
+    now?: () => Date;
+    monotonicNow?: () => number;
+    /** Test seam: resolve the transport client without dynamic imports. */
+    createClient?: (
+        config: Extract<ShareLinkMaintenanceConfigResolution, { status: 'enabled' }>['config']
+    ) => Promise<MaintenanceClient>;
+    /** Test seam: resolve the production repositories without loading Neo4j. */
+    createRepositories?: (
+        client: MaintenanceClient,
+        config: Extract<ShareLinkMaintenanceConfigResolution, { status: 'enabled' }>['config']
+    ) => Promise<{
+        recoveryRepository: RecoveryRunnerDependencies['repository'];
+        cleanupRepository: CleanupRunnerDependencies['repository'];
+        pruneReceipts: ResolvedRunnerDependencies['pruneReceipts'];
+        expireAttachmentStages?: ResolvedRunnerDependencies['expireAttachmentStages'];
+    }>;
+};
+
+const inertSummary = (
+    status: 'disabled' | 'invalid_configuration',
+    categories: ShareLinkMaintenanceRunSummary['categories']
+): ShareLinkMaintenanceRunSummary => ({
+    status,
+    durationMs: 0,
+    budgetMs: 0,
+    recovery: null,
+    cleanup: null,
+    receiptPrune: null,
+    categories,
+});
+
+const deadlineSummary = (
+    budget: ReturnType<typeof createMaintenancePassBudget>
+): ShareLinkMaintenanceRunSummary => ({
+    status: 'deadline_exhausted',
+    durationMs: budget.elapsedMs(),
+    budgetMs: budget.configuredMs,
+    recovery: null,
+    cleanup: null,
+    receiptPrune: null,
+    categories: {},
+});
+
+const initializationFailedSummary = (): ShareLinkMaintenanceRunSummary => ({
+    status: 'initialization_failed',
+    durationMs: 0,
+    budgetMs: 0,
+    recovery: null,
+    cleanup: null,
+    receiptPrune: null,
+    categories: { share_link_maintenance_initialization_failed: 1 },
+});
+
+/** Sample a live remaining-time source once; fail closed on a bad value. */
+const sampleRemainingMs = (source: number | (() => number) | undefined): number | undefined => {
+    if (source === undefined) return undefined;
+
+    let value: unknown;
+
+    try {
+        value = typeof source === 'function' ? source() : source;
+    } catch {
+        // A throwing Lambda context must not start work; fail closed.
+        return 0;
+    }
+
+    if (typeof value !== 'number' || !Number.isFinite(value)) return 0;
+
+    return value;
+};
+
+/**
+ * Production composition for the share-link maintenance pass.
+ *
+ * Disabled or malformed configuration resolves to an inert runtime: `runOnce`
+ * returns a fixed summary and never constructs the client, signer, repositories
+ * or any graph/remote dependency. When enabled, composition is lazy on the first
+ * invocation and reuses the existing did:web signing adapter with an explicitly
+ * configured trusted origin/audience/opaque namespace. There is no unsigned or
+ * fresh-key path.
+ *
+ * The invocation budget starts BEFORE dependency initialization: a cold start
+ * consumes the same deadline as the work, and an already-exhausted invocation
+ * performs no dependency/signer/graph setup at all. A successful setup is cached;
+ * a failed or budget-aborted setup is cleared so the next cadence retries.
+ */
+export const createShareLinkMaintenanceRuntime = (
+    options: CreateShareLinkMaintenanceRuntimeOptions = {}
+): ShareLinkMaintenanceRuntime => {
+    const resolution = resolveShareLinkMaintenanceConfig(
+        options.rawEnvironment ?? (process.env as Record<string, unknown>)
+    );
+    const logger = options.logger ?? consoleLogger;
+
+    if (resolution.status === 'disabled') {
+        const summary = inertSummary('disabled', {});
+        return {
+            resolution,
+            runOnce: async () => {
+                safeLogMaintenance(logger, summary);
+
+                return summary;
+            },
+        };
+    }
+
+    if (resolution.status === 'invalid') {
+        const summary = inertSummary('invalid_configuration', {
+            share_link_maintenance_configuration_invalid: 1,
+        });
+        return {
+            resolution,
+            runOnce: async () => {
+                safeLogMaintenance(logger, summary);
+
+                return summary;
+            },
+        };
+    }
+
+    const { config } = resolution;
+    let cached: Promise<DependencySetup> | null = null;
+
+    const buildDependencies = async (
+        budget: ReturnType<typeof createMaintenancePassBudget>
+    ): Promise<DependencySetup> => {
+        try {
+            const client = options.createClient
+                ? await options.createClient(config)
+                : await buildRuntimeClient(config);
+
+            if (budget.exhausted()) return { status: 'expired' };
+
+            const repositories = options.createRepositories
+                ? await options.createRepositories(client, config)
+                : await buildRuntimeRepositories(client, config);
+
+            if (budget.exhausted()) return { status: 'expired' };
+
+            return { status: 'ready', dependencies: { client, ...repositories } };
+        } catch {
+            return { status: 'failed' };
+        }
+    };
+
+    const resolveDependencies = async (
+        budget: ReturnType<typeof createMaintenancePassBudget>
+    ): Promise<DependencySetup> => {
+        if (!cached) {
+            const pending = buildDependencies(budget);
+            cached = pending;
+
+            const result = await pending;
+
+            // Keep a successful/in-flight setup cached; clear a failed or
+            // budget-aborted one so the next cadence can retry.
+            if (result.status !== 'ready' && cached === pending) cached = null;
+
+            return result;
+        }
+
+        return cached;
+    };
+
+    return {
+        resolution,
+        runOnce: async runOptions => {
+            const requestedRemaining = sampleRemainingMs(runOptions?.remainingTimeMs);
+            const budget = createMaintenancePassBudget({
+                budgetMs: resolveMaintenanceBudgetMs(config.budgetMs, requestedRemaining),
+                finalizeReserveMs: config.finalizeReserveMs,
+                monotonicNow: options.monotonicNow,
+            });
+
+            if (budget.exhausted()) {
+                const summary = deadlineSummary(budget);
+                safeLogMaintenance(logger, summary);
+
+                return summary;
+            }
+
+            const setup = await resolveDependencies(budget);
+
+            if (setup.status === 'failed') {
+                const summary = initializationFailedSummary();
+                safeLogMaintenance(logger, summary);
+
+                return summary;
+            }
+
+            if (setup.status === 'expired' || budget.exhausted()) {
+                const summary = deadlineSummary(budget);
+                safeLogMaintenance(logger, summary);
+
+                return summary;
+            }
+
+            return runShareLinkMaintenancePass({
+                config,
+                recoveryRepository: setup.dependencies.recoveryRepository,
+                cleanupRepository: setup.dependencies.cleanupRepository,
+                pruneReceipts: setup.dependencies.pruneReceipts,
+                expireAttachmentStages: setup.dependencies.expireAttachmentStages,
+                client: setup.dependencies.client,
+                logger,
+                monotonicNow: options.monotonicNow,
+                now: options.now,
+                budget,
+            });
+        },
+    };
+};
+
+/** Lazy production transport: loads the did:web signer only when enabled. */
+const buildRuntimeClient = async (
+    config: Extract<ShareLinkMaintenanceConfigResolution, { status: 'enabled' }>['config']
+): Promise<MaintenanceClient> => {
+    const [{ getServerDidWebDID }, { createDidWebLearnCardTokenSigner }, clientModule] =
+        await Promise.all([
+            import('../learnCard.helpers'),
+            import('../share-content-client/adapters'),
+            import('../share-content-client'),
+        ]);
+
+    const signerDid = getServerDidWebDID();
+    const clientConfig = clientModule.resolveShareContentClientConfig({
+        enabled: true,
+        origin: config.origin,
+        namespace: config.namespace,
+        audience: config.audience,
+        signerDid,
+        allowInsecureLoopback: config.allowInsecureLoopback,
+        signer: createDidWebLearnCardTokenSigner(),
+        requestTimeoutMs: config.requestTimeoutMs,
+        // Maintenance is one bounded attempt per unit; the scheduler/cadence owns
+        // retry, so a transient failure is re-queued rather than retried inline.
+        maxAttempts: 1,
+        retryBackoffMs: 0,
+    });
+
+    if (!clientConfig.enabled) {
+        throw new Error('share-link maintenance client configuration was rejected');
+    }
+
+    return clientModule.createShareContentClient(clientConfig);
+};
+
+/** Lazy production repositories: imports the Neo4j-backed wiring only when enabled. */
+const buildRuntimeRepositories = async (
+    client: MaintenanceClient,
+    config: Extract<ShareLinkMaintenanceConfigResolution, { status: 'enabled' }>['config']
+): Promise<{
+    recoveryRepository: RecoveryRunnerDependencies['repository'];
+    cleanupRepository: CleanupRunnerDependencies['repository'];
+    pruneReceipts: ResolvedRunnerDependencies['pruneReceipts'];
+    expireAttachmentStages?: ResolvedRunnerDependencies['expireAttachmentStages'];
+}> => {
+    const runtimeModule = await import('../share-link-coordinator/runtime');
+
+    const recoveryDependencies = runtimeModule.createRuntimeRecoveryRunnerDependencies({
+        client,
+        claimant: config.claimant,
+        namespace: config.namespace,
+    });
+    const cleanupDependencies = runtimeModule.createRuntimeCleanupRunnerDependencies({
+        client,
+        claimant: config.claimant,
+        namespace: config.namespace,
+    });
+
+    // Preinitialize the idempotent share-link constraint/index gate once, outside
+    // the per-unit budget, so a maintenance transaction never pays the one-time
+    // schema setup. It is cached in-process and is not a per-pass cost.
+    const { ensureShareLinkConstraints } = await import('../../models/share-link-constraints');
+    await ensureShareLinkConstraints();
+
+    // Load the receipt-prune repository last: it pulls the Neo4j `@instance`, so
+    // it must only be imported when an enabled runtime actually composes work.
+    const { pruneShareViewReceipts } = await import('../../accesslayer/share-link/receipt');
+
+    return {
+        recoveryRepository: recoveryDependencies.repository,
+        cleanupRepository: cleanupDependencies.repository,
+        pruneReceipts: pruneShareViewReceipts,
+        expireAttachmentStages: (await import('../../accesslayer/share-link/attachment'))
+            .expireShareAttachmentStages,
+    };
+};
+
+const consoleLogger: ShareLinkMaintenanceLogger = {
+    info: event => console.log('[share-link-maintenance]', event),
+    error: event => console.error('[share-link-maintenance]', event),
+};