@researchdatabox/redbox-core 5.1.0-beta.12573 → 5.1.0-beta.13939

package/dist/utilities/HarvestRunIndexes.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HARVEST_EVENT_INDEXES = exports.HARVEST_CHUNK_INDEXES = exports.HARVEST_RUN_INDEXES = void 0;
+exports.preflightHarvestRunIndexes = preflightHarvestRunIndexes;
+exports.ensureHarvestRunIndexes = ensureHarvestRunIndexes;
+// Shared by model metadata and explicit Mongo provisioning: Waterline does not
+// create compound indexes from the model's indexes metadata in safe mode.
+exports.HARVEST_RUN_INDEXES = [
+    { key: { status: 1, completedAt: 1, _id: 1 } },
+    { key: { brandId: 1, recordType: 1, sourceName: 1, sourceRunId: 1 }, unique: true },
+    { key: { brandId: 1, startedAt: -1, _id: -1 } },
+    { key: { status: 1 } },
+    { key: { recordType: 1 } },
+];
+exports.HARVEST_CHUNK_INDEXES = [
+    { key: { runId: 1, contentHash: 1, attempt: 1 }, unique: true },
+    { key: { runId: 1, contentHash: 1, status: 1 } },
+    { key: { runId: 1, chunkIndex: 1 } },
+    { key: { runId: 1, brandId: 1, submittedAt: 1, _id: 1 } },
+];
+exports.HARVEST_EVENT_INDEXES = [
+    { key: { runId: 1, brandId: 1, createdAt: -1, _id: -1 } },
+    { key: { runId: 1, brandId: 1, outcome: 1, createdAt: -1, _id: -1 } },
+    { key: { runId: 1, brandId: 1, operation: 1, createdAt: -1, _id: -1 } },
+    { key: { runId: 1, brandId: 1, chunkId: 1, createdAt: 1, _id: 1 } },
+    { key: { runId: 1, brandId: 1, harvestId: 1, createdAt: -1, _id: -1 } },
+    { key: { harvestId: 1, recordType: 1, brandId: 1 } },
+    { key: { oid: 1 } },
+];
+/** Read-only deployment check. Never repairs data or changes indexes. */
+async function preflightHarvestRunIndexes(db) {
+    const issues = [];
+    for (const [name, definitions] of [
+        ['harvestrun', exports.HARVEST_RUN_INDEXES],
+        ['harvestrunchunk', exports.HARVEST_CHUNK_INDEXES],
+        ['harvestrecordevent', exports.HARVEST_EVENT_INDEXES],
+    ]) {
+        // A fresh installation may not have these collections yet.
+        if (!(await db.listCollections({ name }, { nameOnly: true }).hasNext()))
+            continue;
+        const collection = db.collection(name);
+        const existing = await collection.indexes();
+        for (const definition of definitions) {
+            const key = Object.fromEntries(Object.entries(definition.key));
+            const keyEntries = JSON.stringify(Object.entries(key));
+            const indexName = Object.entries(key)
+                .map(([field, direction]) => `${field}_${direction}`)
+                .join('_');
+            const conflicts = existing.filter(index => {
+                const sameKey = JSON.stringify(Object.entries(index.key)) === keyEntries;
+                return ((index.name === indexName && !sameKey) ||
+                    (sameKey &&
+                        (index.name !== indexName ||
+                            Boolean(index.unique) !== Boolean(definition.unique) ||
+                            Boolean(index.sparse) ||
+                            Boolean(index.partialFilterExpression) ||
+                            Boolean(index.collation))));
+            });
+            if (conflicts.length)
+                issues.push(`${name}: conflicting index options for ${indexName}`);
+            if (!definition.unique)
+                continue;
+            const groupKey = Object.fromEntries(Object.keys(key).map(field => [field, { $ifNull: [`$${field}`, null] }]));
+            const duplicates = await collection
+                .aggregate([{ $group: { _id: groupKey, count: { $sum: 1 } } }, { $match: { count: { $gt: 1 } } }, { $count: 'groups' }], { allowDiskUse: true })
+                .toArray();
+            if (duplicates.length)
+                issues.push(`${name}: ${duplicates[0].groups} duplicate groups for ${indexName}`);
+        }
+    }
+    return issues;
+}
+/**
+ * Create the required harvest indexes without replacing existing definitions.
+ * Repeated calls are safe; duplicates and conflicting options reject startup.
+ */
+async function ensureHarvestRunIndexes(db) {
+    // Mongo createIndexes is idempotent. Conflicting options or duplicate unique
+    // keys reject initialization; existing indexes and records are never dropped.
+    await db.collection('harvestrun').createIndexes(exports.HARVEST_RUN_INDEXES);
+    await db.collection('harvestrunchunk').createIndexes(exports.HARVEST_CHUNK_INDEXES);
+    await db.collection('harvestrecordevent').createIndexes(exports.HARVEST_EVENT_INDEXES);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiSGFydmVzdFJ1bkluZGV4ZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdXRpbGl0aWVzL0hhcnZlc3RSdW5JbmRleGVzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQThCQSxnRUE0Q0M7QUFNRCwwREFNQztBQXBGRCwrRUFBK0U7QUFDL0UsMEVBQTBFO0FBQzdELFFBQUEsbUJBQW1CLEdBQXVCO0lBQ3JELEVBQUUsR0FBRyxFQUFFLEVBQUUsTUFBTSxFQUFFLENBQUMsRUFBRSxXQUFXLEVBQUUsQ0FBQyxFQUFFLEdBQUcsRUFBRSxDQUFDLEVBQUUsRUFBRTtJQUM5QyxFQUFFLEdBQUcsRUFBRSxFQUFFLE9BQU8sRUFBRSxDQUFDLEVBQUUsVUFBVSxFQUFFLENBQUMsRUFBRSxVQUFVLEVBQUUsQ0FBQyxFQUFFLFdBQVcsRUFBRSxDQUFDLEVBQUUsRUFBRSxNQUFNLEVBQUUsSUFBSSxFQUFFO0lBQ25GLEVBQUUsR0FBRyxFQUFFLEVBQUUsT0FBTyxFQUFFLENBQUMsRUFBRSxTQUFTLEVBQUUsQ0FBQyxDQUFDLEVBQUUsR0FBRyxFQUFFLENBQUMsQ0FBQyxFQUFFLEVBQUU7SUFDL0MsRUFBRSxHQUFHLEVBQUUsRUFBRSxNQUFNLEVBQUUsQ0FBQyxFQUFFLEVBQUU7SUFDdEIsRUFBRSxHQUFHLEVBQUUsRUFBRSxVQUFVLEVBQUUsQ0FBQyxFQUFFLEVBQUU7Q0FDM0IsQ0FBQztBQUVXLFFBQUEscUJBQXFCLEdBQXVCO0lBQ3ZELEVBQUUsR0FBRyxFQUFFLEVBQUUsS0FBSyxFQUFFLENBQUMsRUFBRSxXQUFXLEVBQUUsQ0FBQyxFQUFFLE9BQU8sRUFBRSxDQUFDLEVBQUUsRUFBRSxNQUFNLEVBQUUsSUFBSSxFQUFFO0lBQy9ELEVBQUUsR0FBRyxFQUFFLEVBQUUsS0FBSyxFQUFFLENBQUMsRUFBRSxXQUFXLEVBQUUsQ0FBQyxFQUFFLE1BQU0sRUFBRSxDQUFDLEVBQUUsRUFBRTtJQUNoRCxFQUFFLEdBQUcsRUFBRSxFQUFFLEtBQUssRUFBRSxDQUFDLEVBQUUsVUFBVSxFQUFFLENBQUMsRUFBRSxFQUFFO0lBQ3BDLEVBQUUsR0FBRyxFQUFFLEVBQUUsS0FBSyxFQUFFLENBQUMsRUFBRSxPQUFPLEVBQUUsQ0FBQyxFQUFFLFdBQVcsRUFBRSxDQUFDLEVBQUUsR0FBRyxFQUFFLENBQUMsRUFBRSxFQUFFO0NBQzFELENBQUM7QUFFVyxRQUFBLHFCQUFxQixHQUF1QjtJQUN2RCxFQUFFLEdBQUcsRUFBRSxFQUFFLEtBQUssRUFBRSxDQUFDLEVBQUUsT0FBTyxFQUFFLENBQUMsRUFBRSxTQUFTLEVBQUUsQ0FBQyxDQUFDLEVBQUUsR0FBRyxFQUFFLENBQUMsQ0FBQyxFQUFFLEVBQUU7SUFDekQsRUFBRSxHQUFHLEVBQUUsRUFBRSxLQUFLLEVBQUUsQ0FBQyxFQUFFLE9BQU8sRUFBRSxDQUFDLEVBQUUsT0FBTyxFQUFFLENBQUMsRUFBRSxTQUFTLEVBQUUsQ0FBQyxDQUFDLEVBQUUsR0FBRyxFQUFFLENBQUMsQ0FBQyxFQUFFLEVBQUU7SUFDckUsRUFBRSxHQUFHLEVBQUUsRUFBRSxLQUFLLEVBQUUsQ0FBQyxFQUFFLE9BQU8sRUFBRSxDQUFDLEVBQUUsU0FBUyxFQUFFLENBQUMsRUFBRSxTQUFTLEVBQUUsQ0FBQyxDQUFDLEVBQUUsR0FBRyxFQUFFLENBQUMsQ0FBQyxFQUFFLEVBQUU7SUFDdkUsRUFBRSxHQUFHLEVBQUUsRUFBRSxLQUFLLEVBQUUsQ0FBQyxFQUFFLE9BQU8sRUFBRSxDQUFDLEVBQUUsT0FBTyxFQUFFLENBQUMsRUFBRSxTQUFTLEVBQUUsQ0FBQyxFQUFFLEdBQUcsRUFBRSxDQUFDLEVBQUUsRUFBRTtJQUNuRSxFQUFFLEdBQUcsRUFBRSxFQUFFLEtBQUssRUFBRSxDQUFDLEVBQUUsT0FBTyxFQUFFLENBQUMsRUFBRSxTQUFTLEVBQUUsQ0FBQyxFQUFFLFNBQVMsRUFBRSxDQUFDLENBQUMsRUFBRSxHQUFHLEVBQUUsQ0FBQyxDQUFDLEVBQUUsRUFBRTtJQUN2RSxFQUFFLEdBQUcsRUFBRSxFQUFFLFNBQVMsRUFB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

package/dist/utilities/PinoLoggerUtils.d.ts

@@ -0,0 +1,9 @@
+import type { Logger } from 'pino';
+/**
+ * Check that a value can be used as a parent pino logger for namespace loggers.
+ *
+ * This module has no side effects, so it can be imported without creating a logger.
+ * @param value The value to check.
+ */
+export declare function isPinoLogger(value: unknown): value is Logger;
+//# sourceMappingURL=PinoLoggerUtils.d.ts.map

package/dist/utilities/PinoLoggerUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PinoLoggerUtils.d.ts","sourceRoot":"","sources":["../../src/utilities/PinoLoggerUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAM5D"}

package/dist/utilities/PinoLoggerUtils.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPinoLogger = isPinoLogger;
+/**
+ * Check that a value can be used as a parent pino logger for namespace loggers.
+ *
+ * This module has no side effects, so it can be imported without creating a logger.
+ * @param value The value to check.
+ */
+function isPinoLogger(value) {
+    if (value === undefined || value === null || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    return typeof record.level === 'string' && typeof record.child === 'function' && typeof record.info === 'function';
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUGlub0xvZ2dlclV0aWxzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3V0aWxpdGllcy9QaW5vTG9nZ2VyVXRpbHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7QUFRQSxvQ0FNQztBQVpEOzs7OztHQUtHO0FBQ0gsU0FBZ0IsWUFBWSxDQUFDLEtBQWM7SUFDekMsSUFBSSxLQUFLLEtBQUssU0FBUyxJQUFJLEtBQUssS0FBSyxJQUFJLElBQUksT0FBTyxLQUFLLEtBQUssUUFBUSxFQUFFLENBQUM7UUFDdkUsT0FBTyxLQUFLLENBQUM7SUFDZixDQUFDO0lBQ0QsTUFBTSxNQUFNLEdBQUcsS0FBZ0MsQ0FBQztJQUNoRCxPQUFPLE9BQU8sTUFBTSxDQUFDLEtBQUssS0FBSyxRQUFRLElBQUksT0FBTyxNQUFNLENBQUMsS0FBSyxLQUFLLFVBQVUsSUFBSSxPQUFPLE1BQU0sQ0FBQyxJQUFJLEtBQUssVUFBVSxDQUFDO0FBQ3JILENBQUMifQ==

package/dist/utilities/RequestChronicle.d.ts

@@ -0,0 +1,221 @@
+import { Request } from 'express';
+import { ILogger } from '@researchdatabox/sails-ng-common';
+import { RequestChronicleSettings } from './RequestChronicleSettings';
+export { defaultRequestChronicleSettings, type RequestChronicleSettings } from './RequestChronicleSettings';
+/**
+ * What happened to the request.
+ * - success: the response was sent with a status below 400, and no errors were recorded.
+ * - failure: the response was sent with a 4xx or 5xx status, or errors were recorded.
+ * - aborted: the connection closed before the response was completely sent.
+ */
+export declare const RequestChronicleOutcomes: readonly ["success", "failure", "aborted"];
+export type RequestChronicleOutcomeType = (typeof RequestChronicleOutcomes)[number];
+/**
+ * Why the request chronicle was retained (or discarded), which also determines the log level.
+ */
+export declare const RequestChronicleClassifications: readonly ["error", "client-error", "aborted", "slow", "warning", "sample", "discard"];
+export type RequestChronicleClassificationsType = (typeof RequestChronicleClassifications)[number];
+export type RequestChronicleError = {
+    name?: string;
+    message?: string;
+    code?: string;
+    /** The first lines of the stack trace, only for unexpected errors (not validation errors). */
+    stack?: string;
+    details?: RequestChronicleError[];
+};
+/**
+ * A holder for attributes of one request and response,
+ * which chronicles what happened over the whole request.
+ *
+ * See the 'Request Chronicle Logging' wiki page for the fields and how they are captured.
+ */
+export interface RequestChronicle {
+    /** A unique identifier generated for this request. Use it to relate other logs to this request. */
+    requestId?: string;
+    /** The OpenTelemetry trace id, when there is an active trace. */
+    traceId?: string;
+    /**
+     * Details of the result of the request chronicle.
+     */
+    result?: {
+        /** When the request started. */
+        timestamp?: string;
+        outcome?: RequestChronicleOutcomeType;
+        durationMs?: number;
+        classification?: RequestChronicleClassificationsType;
+        /** The log level used for this event. */
+        severity?: string;
+    };
+    /**
+     * Details of the original request.
+     */
+    req?: {
+        method?: string;
+        path?: string;
+        hostname?: string;
+        /** A valid 'X-Request-Id' header supplied by a proxy or client. */
+        upstreamRequestId?: string;
+    };
+    /**
+     * Details of the response generated from the request.
+     */
+    res?: {
+        statusCode?: number;
+        /** Whether the response was completely sent before the connection closed. */
+        completed?: boolean;
+    };
+    /**
+     * Any errors encountered during the request processing.
+     */
+    errors?: RequestChronicleError[];
+    /** The number of errors not included in 'errors' due to the limit. */
+    errorsOmitted?: number;
+    /**
+     * Arbitrary data added during the request processing.
+     */
+    [key: string]: unknown;
+}
+export interface RequestChronicleOptions {
+    /** Retention settings. Defaults to `sails.config.log.requestChronicle`. */
+    settings?: Partial<Record<keyof RequestChronicleSettings, unknown>>;
+    /** Random number source between 0 and 1, used for sampling. */
+    random?: () => number;
+    /** Monotonic clock in milliseconds, used for the duration. */
+    now?: () => number;
+    /** Generates the request id. */
+    generateRequestId?: () => string;
+}
+/** The response properties used to conclude the request chronicle. */
+export type RequestChronicleResponse = {
+    statusCode?: number;
+    headersSent?: boolean;
+    writableFinished?: boolean;
+};
+/**
+ * Limits on the size of the captured data.
+ */
+export declare const RequestChronicleLimits: Readonly<{
+    maxDepth: 4;
+    maxStringLength: 500;
+    maxArrayItems: 20;
+    maxObjectKeys: 30;
+    maxValueJsonLength: 4096;
+    maxInfoKeys: 100;
+    maxErrors: 20;
+    maxErrorDepth: 3;
+    maxErrorDetails: 10;
+    maxErrorMessageLength: 1000;
+    maxErrorJsonLength: 8192;
+    maxStackLength: 4000;
+    maxStackLines: 12;
+    maxKeyLength: 100;
+}>;
+/**
+ * Remove tokens from request paths and URLs.
+ * @param value The path or URL.
+ */
+export declare function sanitizeChroniclePath(value: string): string;
+/**
+ * Convert a value to a string that is safe to log: secrets and token-bearing paths are redacted,
+ * and the length is bounded. Only the start of a very long string is processed.
+ * @param value The value.
+ * @param maxLength The maximum length, excluding the truncation marker.
+ */
+export declare function safeChronicleText(value: unknown, maxLength: number): string;
+/**
+ * Convert a value to a plain, size-bounded representation that is safe to log.
+ * Redacts sensitive keys and token-bearing paths, and limits depth, items, keys, and string length.
+ * @param value The value to sanitise.
+ */
+export declare function sanitizeChronicleValue(value: unknown): unknown;
+/**
+ * Describe the shape of a value without including its content.
+ * Use this for results that may be large or contain personal or sensitive data.
+ * @param value The value to describe.
+ */
+export declare function summarizeChronicleValue(value: unknown): {
+    type: string;
+    length?: number;
+    keyCount?: number;
+};
+/**
+ * Convert a possible error to a consistent, size-bounded plain object representation.
+ * Handles causes, aggregate and suppressed errors, and cycles, without throwing.
+ * Names, messages, codes, and stacks are redacted and bounded, as is the whole result.
+ * @param item This might be an error, or a string, or something else.
+ */
+export declare function toChronicleError(item: unknown): RequestChronicleError;
+/**
+ * Convert arrays to objects keyed by index, so that the structure survives
+ * log formats that flatten nested objects but not arrays (e.g. pino-logfmt: `errors_0_message`).
+ * @param value The value to convert.
+ */
+export declare function toChronicleLogRecord(value: unknown): unknown;
+declare const helperBrand: unique symbol;
+export declare class RequestChronicleHelper {
+    #private;
+    private logger;
+    private readonly [helperBrand];
+    private constructor();
+    /**
+     * Get the request chronicle helper for a request, creating it if needed.
+     * The logger and options are only used when the helper is created.
+     */
+    static fromReq(logger: ILogger, req: Sails.Req | Request, options?: RequestChronicleOptions): RequestChronicleHelper;
+    /**
+     * Get the request chronicle helper for a request, without creating it.
+     * Requests that did not pass through the HTTP middleware (e.g. socket and virtual requests) have no helper.
+     */
+    static existing(req: Sails.Req | Request | undefined | null): RequestChronicleHelper | undefined;
+    /**
+     * Get the current request chronicle data.
+     * Do not use this for logging - use the `log` method.
+     */
+    get data(): RequestChronicle;
+    /** The request id, generated when the chronicle starts. */
+    get requestId(): string | undefined;
+    get settings(): RequestChronicleSettings;
+    get isRunning(): boolean;
+    get isFinished(): boolean;
+    start(): void;
+    updateReq(req: Sails.Req | Request): void;
+    /**
+     * Conclude the request chronicle.
+     * Only the first call has an effect.
+     * @param res The response. A response that has not finished writing is recorded as aborted.
+     * @return True if this call concluded the chronicle, otherwise false.
+     */
+    finish(res?: RequestChronicleResponse): boolean;
+    /**
+     * Log the finished request chronicle once, at the level for its classification.
+     * @param logger The logger to use.
+     */
+    log(logger?: ILogger): void;
+    get hasErrors(): boolean;
+    /**
+     * Record an error.
+     * Errors recorded when the chronicle is not running are logged immediately, with the request id.
+     * @param error The error.
+     * @param info Safe operation details to include when the error is logged outside a running chronicle.
+     */
+    addError(error?: unknown, info?: Record<string, unknown>): void;
+    /**
+     * Add arbitrary details to the request chronicle.
+     * Values are sanitised and size-bounded.
+     * Warnings retain the request and raise its severity to at least warn.
+     * Details added after the chronicle finished are logged at the supplied level, with the request id.
+     * Details added when there is no running chronicle (e.g. socket requests) are ignored.
+     * @param info The details to add.
+     * @param level The severity of these details; defaults to debug for late details.
+     */
+    addInfo(info: Record<string, unknown>, level?: 'debug' | 'info' | 'warn'): void;
+    /**
+     * Record the result of work that may continue after the response is sent, such as an audit event.
+     * While the request is running, the result is added to the request chronicle.
+     * After the request finishes, the result is logged separately, with the request id.
+     * @param operation A short name for the operation.
+     * @param error The error if the operation failed, otherwise undefined.
+     */
+    addOperationResult(operation: string, error?: unknown): void;
+}
+//# sourceMappingURL=RequestChronicle.d.ts.map

package/dist/utilities/RequestChronicle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestChronicle.d.ts","sourceRoot":"","sources":["../../src/utilities/RequestChronicle.ts"],"names":[],"mappings":"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"}