@spinajs/log 2.0.481 → 2.0.482

package/lib/cjs/targets/wrappers/RetryingTarget.d.ts

@@ -0,0 +1,44 @@
+import { ICommonTargetOptions, ILogEntry, ITargetsOption, LogTarget } from "@spinajs/log-common";
+import { ResiliencePipeline } from "@spinajs/util";
+/**
+ * Options for {@link RetryingTarget}.
+ */
+export interface IRetryingTargetOptions extends ICommonTargetOptions {
+    options: {
+        /**
+         * Inline child target this wrapper decorates. Resolved through DI exactly
+         * like a top-level target.
+         */
+        target: ITargetsOption;
+        /**
+         * Total number of write attempts ( the first try plus retries ). Default 3.
+         */
+        maxAttempts?: number;
+        /**
+         * Base delay in milliseconds between retries ( exponential backoff + jitter
+         * is applied on top ). Default 100.
+         */
+        delayMs?: number;
+    };
+}
+/**
+ * Wraps ONE inner target and RETRIES its `write` when it REJECTS, using the
+ * `@spinajs/util` resilience pipeline ( exponential backoff + jitter ). Only
+ * useful for targets that surface failure by rejecting ( console / custom /
+ * strict ) — self-healing targets ( File / Loki / OTLP ) own their reliability
+ * and resolve, so wrapping them is a no-op. See the write() rejection contract
+ * on {@link LogTarget.write}.
+ *
+ * The inner target is declared inline and owned by this wrapper ( resolve /
+ * flush / dispose ). Pure / browser-safe - just delegates to its child.
+ */
+export declare class RetryingTarget extends LogTarget<IRetryingTargetOptions> {
+    protected Inner: LogTarget<ICommonTargetOptions>;
+    /** Reusable retry pipeline guarding the inner write. */
+    protected RetryPipeline: ResiliencePipeline<void>;
+    resolve(): void;
+    write(entry: ILogEntry): Promise<void>;
+    forceFlush(): Promise<void>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=RetryingTarget.d.ts.map

package/lib/cjs/targets/wrappers/RetryingTarget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetryingTarget.d.ts","sourceRoot":"","sources":["../../../../src/targets/wrappers/RetryingTarget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEjG,OAAO,EAAe,kBAAkB,EAAuC,MAAM,eAAe,CAAC;AAErG;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IAClE,OAAO,EAAE;QACP;;;WAGG;QACH,MAAM,EAAE,cAAc,CAAC;QAEvB;;WAEG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;QAErB;;;WAGG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;;;;;;;;;GAUG;AACH,qBAEa,cAAe,SAAQ,SAAS,CAAC,sBAAsB,CAAC;IACnE,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,oBAAoB,CAAC,CAAC;IAEjD,wDAAwD;IACxD,SAAS,CAAC,aAAa,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAE3C,OAAO,IAAI,IAAI;IAoBf,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAGtC"}

package/lib/cjs/targets/wrappers/RetryingTarget.js

@@ -0,0 +1,61 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryingTarget = void 0;
+const log_common_1 = require("@spinajs/log-common");
+const di_1 = require("@spinajs/di");
+const util_1 = require("@spinajs/util");
+/**
+ * Wraps ONE inner target and RETRIES its `write` when it REJECTS, using the
+ * `@spinajs/util` resilience pipeline ( exponential backoff + jitter ). Only
+ * useful for targets that surface failure by rejecting ( console / custom /
+ * strict ) — self-healing targets ( File / Loki / OTLP ) own their reliability
+ * and resolve, so wrapping them is a no-op. See the write() rejection contract
+ * on {@link LogTarget.write}.
+ *
+ * The inner target is declared inline and owned by this wrapper ( resolve /
+ * flush / dispose ). Pure / browser-safe - just delegates to its child.
+ */
+let RetryingTarget = class RetryingTarget extends log_common_1.LogTarget {
+    resolve() {
+        this.Inner = di_1.DI.resolve(this.Options.options.target.type, [this.Options.options.target]);
+        const maxAttempts = this.Options.options.maxAttempts ?? 3;
+        const delayMs = this.Options.options.delayMs ?? 100;
+        // MaxRetryAttempts counts RETRIES ( on top of the first attempt ), so
+        // subtract one from the total attempt budget.
+        this.RetryPipeline = new util_1.ResiliencePipelineBuilder()
+            .addRetry({
+            MaxRetryAttempts: Math.max(0, maxAttempts - 1),
+            Delay: util_1.TimeSpan.fromMilliseconds(delayMs),
+            BackoffType: util_1.BackoffType.Exponential,
+            UseJitter: true,
+        })
+            .build();
+        super.resolve();
+    }
+    write(entry) {
+        if (!this.Options.enabled) {
+            return Promise.resolve();
+        }
+        // wrap in Promise.resolve because some targets' write is sync / void. The
+        // pipeline retries whenever the inner write REJECTS.
+        return this.RetryPipeline.execute(() => Promise.resolve(this.Inner.write(entry)).then(() => undefined));
+    }
+    forceFlush() {
+        return this.Inner.forceFlush();
+    }
+    async dispose() {
+        await this.Inner.dispose?.();
+    }
+};
+exports.RetryingTarget = RetryingTarget;
+exports.RetryingTarget = RetryingTarget = __decorate([
+    (0, di_1.Singleton)(),
+    (0, di_1.Injectable)("RetryingTarget")
+], RetryingTarget);
+//# sourceMappingURL=RetryingTarget.js.map

package/lib/cjs/targets/wrappers/RetryingTarget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetryingTarget.js","sourceRoot":"","sources":["../../../../src/targets/wrappers/RetryingTarget.ts"],"names":[],"mappings":";;;;;;;;;AAAA,oDAAiG;AACjG,oCAAwD;AACxD,wCAAqG;AA0BrG;;;;;;;;;;GAUG;AAGI,IAAM,cAAc,GAApB,MAAM,cAAe,SAAQ,sBAAiC;IAM5D,OAAO;QACZ,IAAI,CAAC,KAAK,GAAG,OAAE,CAAC,OAAO,CAAkC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAE1H,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC;QAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,GAAG,CAAC;QAEpD,sEAAsE;QACtE,8CAA8C;QAC9C,IAAI,CAAC,aAAa,GAAG,IAAI,gCAAyB,EAAQ;aACvD,QAAQ,CAAC;YACR,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,CAAC;YAC9C,KAAK,EAAE,eAAQ,CAAC,gBAAgB,CAAC,OAAO,CAAC;YACzC,WAAW,EAAE,kBAAW,CAAC,WAAW;YACpC,SAAS,EAAE,IAAI;SAChB,CAAC;aACD,KAAK,EAAE,CAAC;QAEX,KAAK,CAAC,OAAO,EAAE,CAAC;IAClB,CAAC;IAEM,KAAK,CAAC,KAAgB;QAC3B,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAC1B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QAED,0EAA0E;QAC1E,qDAAqD;QACrD,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAC1G,CAAC;IAEM,UAAU;QACf,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;IACjC,CAAC;IAEM,KAAK,CAAC,OAAO;QAClB,MAAO,IAAI,CAAC,KAAa,CAAC,OAAO,EAAE,EAAE,CAAC;IACxC,CAAC;CACF,CAAA;AA3CY,wCAAc;yBAAd,cAAc;IAF1B,IAAA,cAAS,GAAE;IACX,IAAA,eAAU,EAAC,gBAAgB,CAAC;GAChB,cAAc,CA2C1B"}

package/lib/cjs/targets/wrappers/SplitGroupTarget.d.ts

@@ -0,0 +1,30 @@
+import { ICommonTargetOptions, ILogEntry, ITargetsOption, LogTarget } from "@spinajs/log-common";
+/**
+ * Options for {@link SplitGroupTarget}.
+ */
+export interface ISplitGroupTargetOptions extends ICommonTargetOptions {
+    options: {
+        /**
+         * Inline child target definitions this group fans out to. Each is resolved
+         * through DI exactly like a top-level target, so any registered target type
+         * ( File, Json, Loki, another wrapper ... ) can be nested here.
+         */
+        targets: ITargetsOption[];
+    };
+}
+/**
+ * Fan-out wrapper: one configured target name that writes every entry to MANY
+ * inner targets. The inner targets are declared inline under `options.targets`
+ * and are owned by this wrapper ( they are NOT part of the logger's Targets
+ * list ), so the wrapper resolves, flushes and disposes them.
+ *
+ * Pure / browser-safe - just delegates to its children.
+ */
+export declare class SplitGroupTarget extends LogTarget<ISplitGroupTargetOptions> {
+    protected Inner: LogTarget<ICommonTargetOptions>[];
+    resolve(): void;
+    write(entry: ILogEntry): Promise<void>;
+    forceFlush(): Promise<void>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=SplitGroupTarget.d.ts.map

package/lib/cjs/targets/wrappers/SplitGroupTarget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SplitGroupTarget.d.ts","sourceRoot":"","sources":["../../../../src/targets/wrappers/SplitGroupTarget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGjG;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,oBAAoB;IACpE,OAAO,EAAE;QACP;;;;WAIG;QACH,OAAO,EAAE,cAAc,EAAE,CAAC;KAC3B,CAAC;CACH;AAED;;;;;;;GAOG;AACH,qBAEa,gBAAiB,SAAQ,SAAS,CAAC,wBAAwB,CAAC;IACvE,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,oBAAoB,CAAC,EAAE,CAAM;IAEjD,OAAO,IAAI,IAAI;IAQf,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAStC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAKtC"}

package/lib/cjs/targets/wrappers/SplitGroupTarget.js

@@ -0,0 +1,52 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SplitGroupTarget = void 0;
+const log_common_1 = require("@spinajs/log-common");
+const di_1 = require("@spinajs/di");
+/**
+ * Fan-out wrapper: one configured target name that writes every entry to MANY
+ * inner targets. The inner targets are declared inline under `options.targets`
+ * and are owned by this wrapper ( they are NOT part of the logger's Targets
+ * list ), so the wrapper resolves, flushes and disposes them.
+ *
+ * Pure / browser-safe - just delegates to its children.
+ */
+let SplitGroupTarget = class SplitGroupTarget extends log_common_1.LogTarget {
+    constructor() {
+        super(...arguments);
+        this.Inner = [];
+    }
+    resolve() {
+        // resolve each child via DI exactly like FrameworkLogger.resolveLogTargets
+        // does - the child's ITargetsOption is passed as the single ctor arg.
+        this.Inner = this.Options.options.targets.map((t) => di_1.DI.resolve(t.type, [t]));
+        super.resolve();
+    }
+    write(entry) {
+        if (!this.Options.enabled) {
+            return Promise.resolve();
+        }
+        // wrap in Promise.resolve because some targets' write is sync / void.
+        return Promise.allSettled(this.Inner.map((t) => Promise.resolve(t.write(entry)))).then(() => undefined);
+    }
+    forceFlush() {
+        return Promise.allSettled(this.Inner.map((t) => t.forceFlush())).then(() => undefined);
+    }
+    async dispose() {
+        // the wrapper owns its children ( they are not in the logger's Targets list )
+        // so it drives their teardown.
+        await Promise.allSettled(this.Inner.map((t) => t.dispose?.()));
+    }
+};
+exports.SplitGroupTarget = SplitGroupTarget;
+exports.SplitGroupTarget = SplitGroupTarget = __decorate([
+    (0, di_1.Singleton)(),
+    (0, di_1.Injectable)("SplitGroupTarget")
+], SplitGroupTarget);
+//# sourceMappingURL=SplitGroupTarget.js.map

package/lib/cjs/targets/wrappers/SplitGroupTarget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SplitGroupTarget.js","sourceRoot":"","sources":["../../../../src/targets/wrappers/SplitGroupTarget.ts"],"names":[],"mappings":";;;;;;;;;AAAA,oDAAiG;AACjG,oCAAwD;AAgBxD;;;;;;;GAOG;AAGI,IAAM,gBAAgB,GAAtB,MAAM,gBAAiB,SAAQ,sBAAmC;IAAlE;;QACK,UAAK,GAAsC,EAAE,CAAC;IA4B1D,CAAC;IA1BQ,OAAO;QACZ,2EAA2E;QAC3E,sEAAsE;QACtE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAE,CAAC,OAAO,CAAkC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAE/G,KAAK,CAAC,OAAO,EAAE,CAAC;IAClB,CAAC;IAEM,KAAK,CAAC,KAAgB;QAC3B,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAC1B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QAED,sEAAsE;QACtE,OAAO,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC1G,CAAC;IAEM,UAAU;QACf,OAAO,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACzF,CAAC;IAEM,KAAK,CAAC,OAAO;QAClB,8EAA8E;QAC9E,+BAA+B;QAC/B,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAS,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC;CACF,CAAA;AA7BY,4CAAgB;2BAAhB,gBAAgB;IAF5B,IAAA,cAAS,GAAE;IACX,IAAA,eAAU,EAAC,kBAAkB,CAAC;GAClB,gBAAgB,CA6B5B"}

package/lib/cjs/traceparent.d.ts

@@ -0,0 +1,63 @@
+/**
+ * W3C Trace Context ( traceparent ) utilities.
+ *
+ * Pure, dependency-free and cross-platform ( Node 20+ and browsers ) — randomness
+ * is sourced from the WHATWG `crypto.getRandomValues`, available on `globalThis`
+ * in both environments, so this module deliberately does NOT import
+ * `node:crypto` and stays safe to bundle for the browser.
+ *
+ * A W3C `traceparent` header has the shape:
+ *
+ *   version "-" trace-id "-" parent-id "-" trace-flags
+ *   00      -   32 hex    -   16 hex     -   2 hex
+ *
+ * See https://www.w3.org/TR/trace-context/#traceparent-header.
+ */
+/**
+ * Minimal trace context this service carries on the ambient store and emits on
+ * the outbound `traceparent` header.
+ */
+export interface ITraceContext {
+    /** 32-hex-char trace id, shared by every span across services in one trace. */
+    traceId: string;
+    /** 16-hex-char span id identifying this service's span within the trace. */
+    spanId: string;
+    /** Whether the trace is sampled ( low bit of the trace-flags ). */
+    sampled: boolean;
+}
+/**
+ * Parse & validate an inbound `traceparent` header value.
+ *
+ * @returns the decomposed parts ( plus the derived `sampled` flag ), or `null`
+ *          when the value is missing / malformed / forbidden by the spec
+ *          ( all-zero trace-id, all-zero parent-id, or version `ff` ).
+ */
+export declare function parseTraceparent(value: string | undefined | null): {
+    version: string;
+    traceId: string;
+    parentId: string;
+    flags: string;
+    sampled: boolean;
+} | null;
+/**
+ * A fresh random trace id ( 16 bytes -> 32 lowercase hex chars ).
+ */
+export declare function randomTraceId(): string;
+/**
+ * A fresh random span id ( 8 bytes -> 16 lowercase hex chars ).
+ */
+export declare function randomSpanId(): string;
+/**
+ * Render a {@link ITraceContext} as a W3C `traceparent` header value.
+ */
+export declare function formatTraceparent(ctx: ITraceContext): string;
+/**
+ * Derive this service's trace context for a request.
+ *
+ * When `inboundTraceparent` is a valid header we CONTINUE the trace: the trace
+ * id and sampled decision are inherited, and a fresh span id is minted for this
+ * service's own span ( its parent being the inbound `parent-id` ). Otherwise a
+ * brand-new, sampled trace is STARTED.
+ */
+export declare function newTraceContext(inboundTraceparent?: string | null): ITraceContext;
+//# sourceMappingURL=traceparent.d.ts.map

package/lib/cjs/traceparent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceparent.d.ts","sourceRoot":"","sources":["../../src/traceparent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAwBjK;AAgBD;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa,CAejF"}

package/lib/cjs/traceparent.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * W3C Trace Context ( traceparent ) utilities.
+ *
+ * Pure, dependency-free and cross-platform ( Node 20+ and browsers ) — randomness
+ * is sourced from the WHATWG `crypto.getRandomValues`, available on `globalThis`
+ * in both environments, so this module deliberately does NOT import
+ * `node:crypto` and stays safe to bundle for the browser.
+ *
+ * A W3C `traceparent` header has the shape:
+ *
+ *   version "-" trace-id "-" parent-id "-" trace-flags
+ *   00      -   32 hex    -   16 hex     -   2 hex
+ *
+ * See https://www.w3.org/TR/trace-context/#traceparent-header.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTraceparent = parseTraceparent;
+exports.randomTraceId = randomTraceId;
+exports.randomSpanId = randomSpanId;
+exports.formatTraceparent = formatTraceparent;
+exports.newTraceContext = newTraceContext;
+const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+const ZERO_TRACE_ID = "00000000000000000000000000000000";
+const ZERO_SPAN_ID = "0000000000000000";
+/**
+ * Parse & validate an inbound `traceparent` header value.
+ *
+ * @returns the decomposed parts ( plus the derived `sampled` flag ), or `null`
+ *          when the value is missing / malformed / forbidden by the spec
+ *          ( all-zero trace-id, all-zero parent-id, or version `ff` ).
+ */
+function parseTraceparent(value) {
+    if (!value) {
+        return null;
+    }
+    const match = TRACEPARENT_RE.exec(value.toLowerCase());
+    if (!match) {
+        return null;
+    }
+    const [, version, traceId, parentId, flags] = match;
+    // Spec-forbidden values: version ff is reserved, and all-zero ids are invalid.
+    if (version === "ff" || traceId === ZERO_TRACE_ID || parentId === ZERO_SPAN_ID) {
+        return null;
+    }
+    return {
+        version,
+        traceId,
+        parentId,
+        flags,
+        sampled: (parseInt(flags, 16) & 0x01) === 1,
+    };
+}
+/**
+ * Cross-platform `n` random bytes rendered as lowercase hex.
+ */
+function randomHex(bytes) {
+    const buffer = new Uint8Array(bytes);
+    globalThis.crypto.getRandomValues(buffer);
+    let out = "";
+    for (const b of buffer) {
+        out += b.toString(16).padStart(2, "0");
+    }
+    return out;
+}
+/**
+ * A fresh random trace id ( 16 bytes -> 32 lowercase hex chars ).
+ */
+function randomTraceId() {
+    return randomHex(16);
+}
+/**
+ * A fresh random span id ( 8 bytes -> 16 lowercase hex chars ).
+ */
+function randomSpanId() {
+    return randomHex(8);
+}
+/**
+ * Render a {@link ITraceContext} as a W3C `traceparent` header value.
+ */
+function formatTraceparent(ctx) {
+    return `00-${ctx.traceId}-${ctx.spanId}-${ctx.sampled ? "01" : "00"}`;
+}
+/**
+ * Derive this service's trace context for a request.
+ *
+ * When `inboundTraceparent` is a valid header we CONTINUE the trace: the trace
+ * id and sampled decision are inherited, and a fresh span id is minted for this
+ * service's own span ( its parent being the inbound `parent-id` ). Otherwise a
+ * brand-new, sampled trace is STARTED.
+ */
+function newTraceContext(inboundTraceparent) {
+    const parsed = parseTraceparent(inboundTraceparent);
+    if (parsed) {
+        return {
+            traceId: parsed.traceId,
+            spanId: randomSpanId(),
+            sampled: parsed.sampled,
+        };
+    }
+    return {
+        traceId: randomTraceId(),
+        spanId: randomSpanId(),
+        sampled: true,
+    };
+}
+//# sourceMappingURL=traceparent.js.map

package/lib/cjs/traceparent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceparent.js","sourceRoot":"","sources":["../../src/traceparent.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AA0BH,4CAwBC;AAmBD,sCAEC;AAKD,oCAEC;AAKD,8CAEC;AAUD,0CAeC;AA/FD,MAAM,cAAc,GAAG,6DAA6D,CAAC;AACrF,MAAM,aAAa,GAAG,kCAAkC,CAAC;AACzD,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAExC;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,KAAgC;IAC/D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;IACvD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;IAEpD,+EAA+E;IAC/E,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,aAAa,IAAI,QAAQ,KAAK,YAAY,EAAE,CAAC;QAC/E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,OAAO;QACP,OAAO;QACP,QAAQ;QACR,KAAK;QACL,OAAO,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;KAC5C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,KAAa;IAC9B,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IACrC,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAE1C,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa;IAC3B,OAAO,SAAS,CAAC,EAAE,CAAC,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY;IAC1B,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,GAAkB;IAClD,OAAO,MAAM,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACxE,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,eAAe,CAAC,kBAAkC;IAChE,MAAM,MAAM,GAAG,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;IACpD,IAAI,MAAM,EAAE,CAAC;QACX,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,MAAM,EAAE,YAAY,EAAE;YACtB,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAE,aAAa,EAAE;QACxB,MAAM,EAAE,YAAY,EAAE;QACtB,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/lib/mjs/archive/LogArchiveService.d.ts

@@ -0,0 +1,75 @@
+import { AsyncService, Class } from "@spinajs/di";
+import { Log } from "@spinajs/log-common";
+import { LogArchiveStrategy } from "./archive-strategy.js";
+import { LogRetentionStrategy } from "./retention-strategy.js";
+import { ILogArchiveContext } from "./context.js";
+/**
+ * Orchestrates rotation + retention for a single file log target.
+ *
+ * It owns nothing schedule-wise itself: it resolves ONE rotation strategy
+ * ( `archiveStrategy` ) and a LIST of retention strategies
+ * ( `retentionStrategies` ) by class name from DI, delegates start / stop to the
+ * rotation strategy, and provides the shared `rotate()` routine every rotation
+ * ( interval, cron or manual ) funnels through.
+ *
+ * `@NewInstance()` - each file target gets its own service ( per-target
+ * scheduling and strategy state ).
+ */
+export declare class LogArchiveService extends AsyncService {
+    protected Logger: Log;
+    protected ArchiveStrategy: LogArchiveStrategy;
+    protected RetentionStrategies: LogRetentionStrategy[];
+    /**
+     * Resolves the configured rotation + retention strategies by class name.
+     * Follows the fs temp-provider mechanism: look the class up in the DI
+     * registry by name, then resolve an instance.
+     */
+    resolve(): Promise<void>;
+    /**
+     * Wires strategies for the given context and starts the rotation schedule.
+     */
+    start(ctx: ILogArchiveContext): Promise<void>;
+    /**
+     * Stops the rotation schedule. Safe to call multiple times.
+     */
+    stop(): void;
+    /**
+     * Single rotation routine, shared by every scheduling strategy:
+     *
+     *  1. acquire the target write-lock so no append runs while we rename,
+     *  2. rename the active file to a sequenced archive name in the archive dir,
+     *  3. compress ( zip into archiveFs, drop the raw file ) OR move cross-fs,
+     *  4. run every retention strategy in order,
+     *  5. release the lock ( always, even on failure ).
+     *
+     * The whole routine is guarded so a failed rotation neither crashes the
+     * scheduler nor leaves the lock held.
+     */
+    rotate(ctx: ILogArchiveContext): Promise<void>;
+    /**
+     * Renames the active log file into the archive dir under a unique
+     * `archived_<name>_<seq><ext>` name. When `archiveFs` differs from `fs` the
+     * file is first renamed within `fs` then moved across.
+     *
+     * Returns the archive path relative to `archiveFs`.
+     */
+    protected moveToArchive(ctx: ILogArchiveContext): Promise<string>;
+    /**
+     * Zips `archived` into `archiveFs` and removes the raw archived file, so the
+     * archive dir only ever holds the compressed copy.
+     */
+    protected compress(ctx: ILogArchiveContext, archived: string): Promise<void>;
+    /**
+     * Next archive sequence number for a given base name. Uses existing archive
+     * file names first, falling back to a timestamp so two rotations in the same
+     * tick never collide.
+     */
+    protected nextSequence(ctx: ILogArchiveContext, name: string, ext: string): Promise<number>;
+    /**
+     * Resolves a strategy instance by class name, mirroring the fs temp-provider
+     * mechanism: look the class up in the DI registry by name, then resolve an
+     * instance ( `@NewInstance()` gives a fresh per-target instance ).
+     */
+    protected resolveStrategy<T>(base: Class<T>, className: string): T;
+}
+//# sourceMappingURL=LogArchiveService.d.ts.map

package/lib/mjs/archive/LogArchiveService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LogArchiveService.d.ts","sourceRoot":"","sources":["../../../src/archive/LogArchiveService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,EAAiD,MAAM,aAAa,CAAC;AACjG,OAAO,EAAU,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAGlD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlD;;;;;;;;;;;GAWG;AACH,qBAEa,iBAAkB,SAAQ,YAAY;IAEjD,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC;IAEtB,SAAS,CAAC,eAAe,EAAE,kBAAkB,CAAC;IAC9C,SAAS,CAAC,mBAAmB,EAAE,oBAAoB,EAAE,CAAM;IAE3D;;;;OAIG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrC;;OAEG;IACU,KAAK,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1D;;OAEG;IACI,IAAI,IAAI,IAAI;IAInB;;;;;;;;;;;OAWG;IACU,MAAM,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB3D;;;;;;OAMG;cACa,aAAa,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBvE;;;OAGG;cACa,QAAQ,CAAC,GAAG,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlF;;;;OAIG;cACa,YAAY,CAAC,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoCjG;;;;OAIG;IACH,SAAS,CAAC,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,CAAC;CAcnE"}

package/lib/mjs/archive/LogArchiveService.js

@@ -0,0 +1,186 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { AsyncService, DI, Injectable, NewInstance, ResolveException } from "@spinajs/di";
+import { Logger, Log } from "@spinajs/log-common";
+import { DateTime } from "luxon";
+import { parse, posix } from "path";
+import { LogArchiveStrategy } from "./archive-strategy.js";
+import { LogRetentionStrategy } from "./retention-strategy.js";
+import { ARCHIVE_PREFIX, archivePath } from "./strategies/util.js";
+/**
+ * Orchestrates rotation + retention for a single file log target.
+ *
+ * It owns nothing schedule-wise itself: it resolves ONE rotation strategy
+ * ( `archiveStrategy` ) and a LIST of retention strategies
+ * ( `retentionStrategies` ) by class name from DI, delegates start / stop to the
+ * rotation strategy, and provides the shared `rotate()` routine every rotation
+ * ( interval, cron or manual ) funnels through.
+ *
+ * `@NewInstance()` - each file target gets its own service ( per-target
+ * scheduling and strategy state ).
+ */
+let LogArchiveService = class LogArchiveService extends AsyncService {
+    constructor() {
+        super(...arguments);
+        this.RetentionStrategies = [];
+    }
+    /**
+     * Resolves the configured rotation + retention strategies by class name.
+     * Follows the fs temp-provider mechanism: look the class up in the DI
+     * registry by name, then resolve an instance.
+     */
+    async resolve() {
+        await super.resolve();
+    }
+    /**
+     * Wires strategies for the given context and starts the rotation schedule.
+     */
+    async start(ctx) {
+        // archiveStrategy / retentionStrategies are populated from the logger.file
+        // config defaults ( see FileTarget.resolve ), so no inline fallback here -
+        // the config is the single source of truth for what runs.
+        this.ArchiveStrategy = this.resolveStrategy(LogArchiveStrategy, ctx.options.archiveStrategy);
+        const retentionNames = ctx.options.retentionStrategies ?? [];
+        this.RetentionStrategies = retentionNames.map((n) => this.resolveStrategy(LogRetentionStrategy, n));
+        this.ArchiveStrategy.start(ctx);
+    }
+    /**
+     * Stops the rotation schedule. Safe to call multiple times.
+     */
+    stop() {
+        this.ArchiveStrategy?.stop();
+    }
+    /**
+     * Single rotation routine, shared by every scheduling strategy:
+     *
+     *  1. acquire the target write-lock so no append runs while we rename,
+     *  2. rename the active file to a sequenced archive name in the archive dir,
+     *  3. compress ( zip into archiveFs, drop the raw file ) OR move cross-fs,
+     *  4. run every retention strategy in order,
+     *  5. release the lock ( always, even on failure ).
+     *
+     * The whole routine is guarded so a failed rotation neither crashes the
+     * scheduler nor leaves the lock held.
+     */
+    async rotate(ctx) {
+        await ctx.withWriteLock(async () => {
+            // nothing written yet - nothing to rotate
+            if (!(await ctx.fs.exists(ctx.activePath))) {
+                return;
+            }
+            const archived = await this.moveToArchive(ctx);
+            if (ctx.options.compress) {
+                await this.compress(ctx, archived);
+            }
+        });
+        // retention runs OUTSIDE the write-lock - it only touches archive files,
+        // never the active log, so it must not block appends.
+        for (const strategy of this.RetentionStrategies) {
+            await strategy.safePrune(ctx);
+        }
+    }
+    /**
+     * Renames the active log file into the archive dir under a unique
+     * `archived_<name>_<seq><ext>` name. When `archiveFs` differs from `fs` the
+     * file is first renamed within `fs` then moved across.
+     *
+     * Returns the archive path relative to `archiveFs`.
+     */
+    async moveToArchive(ctx) {
+        const { name, ext } = parse(posix.basename(ctx.activePath.replace(/\\/g, "/")));
+        const seq = await this.nextSequence(ctx, name, ext);
+        const archiveName = `${ARCHIVE_PREFIX}${name}_${seq}${ext}`;
+        const archiveRel = archivePath(ctx, archiveName);
+        if (ctx.archiveFs === ctx.fs) {
+            await ctx.fs.rename(ctx.activePath, archiveRel);
+            return archiveRel;
+        }
+        // cross-fs: rename to a temp name inside `fs`, then move into archiveFs
+        const stagingRel = `${ARCHIVE_PREFIX}${name}_${seq}${ext}`;
+        await ctx.fs.rename(ctx.activePath, stagingRel);
+        await ctx.fs.move(stagingRel, archiveRel, ctx.archiveFs);
+        return archiveRel;
+    }
+    /**
+     * Zips `archived` into `archiveFs` and removes the raw archived file, so the
+     * archive dir only ever holds the compressed copy.
+     */
+    async compress(ctx, archived) {
+        const zipRel = `${archived}.zip`;
+        // zip() honors a non-temp dstFs / dstFile - output lands directly in archiveFs
+        await ctx.archiveFs.zip(archived, ctx.archiveFs, zipRel);
+        await ctx.archiveFs.rm(archived);
+        this.Logger.trace(`Compressed archive ${archived} -> ${zipRel}`);
+    }
+    /**
+     * Next archive sequence number for a given base name. Uses existing archive
+     * file names first, falling back to a timestamp so two rotations in the same
+     * tick never collide.
+     */
+    async nextSequence(ctx, name, ext) {
+        let existing = [];
+        try {
+            existing = await ctx.archiveFs.list(ctx.archiveDir || "/");
+        }
+        catch {
+            existing = [];
+        }
+        const prefix = `${ARCHIVE_PREFIX}${name}_`;
+        // prefix is escaped via escapeRegExp before interpolation
+        // eslint-disable-next-line security/detect-non-literal-regexp
+        const seqReg = new RegExp(`^${escapeRegExp(prefix)}(\\d+)`);
+        let max = 0;
+        for (const f of existing) {
+            const m = seqReg.exec(f);
+            if (m) {
+                const n = parseInt(m[1], 10);
+                if (n > max) {
+                    max = n;
+                }
+            }
+        }
+        const next = max + 1;
+        // guard against a name clash ( eg. same-second cron + size rotation ) by
+        // appending a millisecond timestamp only when the computed name already exists
+        const candidate = archivePath(ctx, `${ARCHIVE_PREFIX}${name}_${next}${ext}`);
+        if (await ctx.archiveFs.exists(candidate)) {
+            return DateTime.now().toMillis();
+        }
+        return next;
+    }
+    /**
+     * Resolves a strategy instance by class name, mirroring the fs temp-provider
+     * mechanism: look the class up in the DI registry by name, then resolve an
+     * instance ( `@NewInstance()` gives a fresh per-target instance ).
+     */
+    resolveStrategy(base, className) {
+        const types = DI.RootContainer.Registry.getTypes(base);
+        const type = types.find((x) => x.name === className);
+        if (!type) {
+            const baseName = base.name;
+            throw new ResolveException(`Log archive strategy ${className} ( ${baseName} ) not registered, make sure it is imported and registered in DI container`);
+        }
+        // strategies are plain ( non-async ) services, so resolve is synchronous
+        return DI.resolve(type);
+    }
+};
+__decorate([
+    Logger("LogFileTarget"),
+    __metadata("design:type", Log)
+], LogArchiveService.prototype, "Logger", void 0);
+LogArchiveService = __decorate([
+    Injectable(),
+    NewInstance()
+], LogArchiveService);
+export { LogArchiveService };
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=LogArchiveService.js.map