@vereda/http 1.0.0

package/dist/queue/executor.js

@@ -0,0 +1,273 @@
+import { ConfigurationError, DeadlineExceededError, HttpError, NetworkError, NO_TIMEOUT_CONFIGURED, RetryableStatusError, TimeoutError, ValidationError, } from "../core/errors.js";
+import { DEFAULT_RETRY_ON_STATUS, isBoundedMs } from "../core/types.js";
+import { isReadableStream } from "../core/validate.js";
+/**
+ * Executes a single HTTP request attempt.
+ * Returns a discriminated union describing what happened,
+ * so the caller (retry loop) can decide whether to retry or resolve.
+ */
+export async function executeRequest(req, middleware) {
+    const { url, options, timeoutConfig, retryConfig, signal } = req;
+    const attemptStart = Date.now();
+    if (signal.aborted || options.signal?.aborted) {
+        return { kind: "cancelled" };
+    }
+    // Set once this attempt hands the caller a live, unread Response body (the
+    // success-without-parse and HttpError returns below). An unconsumed body
+    // handed off this way gets bounded in `finally` instead of having its
+    // timer cleared, so `raw.json()`/`error.response.text()` read later can't
+    // hang forever (the parse path already reads the body inside the attempt,
+    // and the RetryableStatusError path already cancels it).
+    let handedOff = false;
+    // Resolve a replayable body factory fresh for this attempt so every attempt
+    // gets its own materialized body. Do not mutate the caller's options.
+    let resolvedBody;
+    if (typeof options.body === "function") {
+        try {
+            resolvedBody = options.body();
+        }
+        catch (err) {
+            return {
+                kind: "error",
+                error: new ConfigurationError(`body factory threw: ${err instanceof Error ? err.message : String(err)}`),
+            };
+        }
+    }
+    else {
+        resolvedBody = options.body;
+    }
+    const timeoutMs = timeoutConfig.attemptMs;
+    const retryOnStatus = retryConfig.retryOnStatus ?? DEFAULT_RETRY_ON_STATUS;
+    // Build the fetch call wrapped in middleware
+    const fetchCall = buildFetchCall(req.fetch);
+    const composed = composeMiddleware(middleware, fetchCall);
+    // Merge the per-attempt signals with AbortSignal.any. It wires its sources
+    // internally (no "abort" listeners attached to them), so neither the ticket
+    // signal nor the caller's signal accumulates one listener per attempt (#7).
+    // Wrapping even a lone ticket signal shields it from fetch's own abort
+    // listener, which undici only removes asynchronously after completion.
+    const sources = [signal];
+    if (options.signal)
+        sources.push(options.signal);
+    // `Infinity` is a legal, explicit "no cap" value (see isBoundedMs) — it must
+    // be treated the same as "not set" here. Node clamps any setTimeout delay
+    // over ~24.8 days to 1ms, so passing Infinity straight to setTimeout would
+    // fire the timer almost immediately instead of never.
+    const hasAttemptTimeout = isBoundedMs(timeoutMs);
+    // Always created (not just when attemptMs is bounded): a handed-off
+    // Response's body read may still need bounding by `deadlineAt` alone in
+    // `finally` below, even when this attempt itself has no attemptMs cap.
+    const timeoutController = new AbortController();
+    sources.push(timeoutController.signal);
+    const attemptSignal = AbortSignal.any(sources);
+    const timeoutId = hasAttemptTimeout ? setTimeout(() => timeoutController.abort(), timeoutMs) : undefined;
+    // A fresh Headers instance per attempt: middleware (e.g. defaultHeaders)
+    // mutates ctx.headers in place, and that must never leak into the next
+    // retry's "starting" headers.
+    const ctx = {
+        url,
+        method: options.method ?? "GET",
+        headers: new Headers(options.headers),
+        body: resolvedBody,
+        signal: attemptSignal,
+        attempt: req.attempt,
+        ticketId: req.ticketId,
+        partition: req.partition,
+    };
+    let response;
+    try {
+        response = await composed(ctx);
+        // The timeout may fire after fetch resolves but before this check runs;
+        // the timed-out attempt is not trustworthy, so it still surfaces as a
+        // timeout (cancellation is checked first in the catch path below).
+        if (timeoutController.signal.aborted) {
+            return { kind: "timeout" };
+        }
+        // Check if status code is retryable (was "queued_status", now typed error)
+        if (retryOnStatus.includes(response.status)) {
+            // Cancel the response body since caller won't read it.
+            // Fire-and-forget: cancel() may hang on stuck connections.
+            // The body will be GC'd when the response is collected.
+            response.body?.cancel().catch(() => { });
+            return {
+                kind: "error",
+                error: new RetryableStatusError(`HTTP ${response.status} ${response.statusText}`, response.status, response, parseRetryAfter(response.headers.get("retry-after"))),
+            };
+        }
+        // Non-2xx responses are non-retryable errors. The body is handed back
+        // unread on `error.response` — bound its read window in `finally`.
+        if (!response.ok) {
+            handedOff = true;
+            return {
+                kind: "error",
+                error: new HttpError(`HTTP ${response.status} ${response.statusText}`, response.status, response),
+            };
+        }
+        // Parse body — the timeout is still active so a slow body read is
+        // covered by the per-attempt deadline (#9).
+        if (options.parse) {
+            let raw;
+            try {
+                raw = await response.json();
+            }
+            catch (err) {
+                // Check timeout first — if our timer fired during response.json(),
+                // that is the cause regardless of whether the external signal also
+                // aborted (cancellation vs timeout precedence).
+                if (timeoutController.signal.aborted) {
+                    return { kind: "timeout" };
+                }
+                if (signal.aborted || options.signal?.aborted) {
+                    return { kind: "cancelled" };
+                }
+                // The body arrived but isn't JSON: the server answered, and asking
+                // again will get the same answer — a parse failure, never retried
+                // (B6). Anything else here is the body stream dying mid-read
+                // (undici's "terminated" TypeError), which is a real network error.
+                if (err instanceof SyntaxError) {
+                    return {
+                        kind: "error",
+                        error: new ValidationError("Response body is not valid JSON", [err], err),
+                    };
+                }
+                return {
+                    kind: "error",
+                    error: new NetworkError("Failed to parse response body as JSON", {
+                        cause: err,
+                    }),
+                };
+            }
+            try {
+                const data = options.parse(raw);
+                return {
+                    kind: "success",
+                    result: { success: true, data, raw: response },
+                };
+            }
+            catch (err) {
+                const issues = extractIssues(err);
+                return {
+                    kind: "error",
+                    error: new ValidationError("Response validation failed", issues, err),
+                };
+            }
+        }
+        // No parse fn — return raw response, unread. Bound its read window in
+        // `finally` instead of clearing the attempt timer.
+        handedOff = true;
+        return {
+            kind: "success",
+            result: { success: true, data: undefined, raw: response },
+        };
+    }
+    catch (err) {
+        // Precedence: cancellation wins over timeout. If the ticket or the
+        // external signal is aborted, report cancelled even if the timeout
+        // also fired — the ticket is already marked cancelled, and
+        // cancellation is the caller's terminal intent. A timeout that fires
+        // first still surfaces as "timeout": the external signal is not yet
+        // aborted when this check runs.
+        if (signal.aborted || options.signal?.aborted) {
+            return { kind: "cancelled" };
+        }
+        if (isAbortError(err)) {
+            // Could be our timeout abort
+            return { kind: "timeout" };
+        }
+        return {
+            kind: "error",
+            error: new NetworkError(err instanceof Error ? err.message : "Network error", { cause: err }),
+        };
+    }
+    finally {
+        // Clear the in-attempt timer either way — it did its job (bounding the
+        // attempt) or the attempt failed on its own. Body has been read (or the
+        // attempt failed), so the abort controller can be released.
+        if (timeoutId !== undefined)
+            clearTimeout(timeoutId);
+        // A handed-off Response (unread body on a success-without-parse or
+        // HttpError result) gets the same bound its body would have had under
+        // `parse`: arm a fresh timer capped at whichever is sooner, this
+        // attempt's remaining attemptMs or the ticket's totalMs deadline. It
+        // fires only if the caller actually reads the body later — aborting
+        // `attemptSignal` (already wired into fetch) makes that read reject,
+        // same as any other abort observed after fetch() has resolved. No
+        // ticket state changes here: the ticket already resolved.
+        if (handedOff) {
+            const attemptTimeoutMs = isBoundedMs(timeoutMs) ? timeoutMs : undefined;
+            const attemptDeadline = attemptTimeoutMs !== undefined ? attemptStart + attemptTimeoutMs : Number.POSITIVE_INFINITY;
+            const totalDeadline = req.deadlineAt ?? Number.POSITIVE_INFINITY;
+            const boundAt = Math.min(attemptDeadline, totalDeadline);
+            if (Number.isFinite(boundAt)) {
+                const delay = Math.max(0, boundAt - Date.now());
+                // Name the abort reason after whichever bound fired — ties go to the
+                // attempt bound, since it's also the only bound when totalMs isn't
+                // configured — using Vereda's own error classes instead of a bare
+                // DOMException. That way a caller's `raw.json()`/`error.response.text()`
+                // rejects with something `instanceof TimeoutError`/`DeadlineExceededError`,
+                // `.kind`-narrowable, and redacted the same as every other error the
+                // client builds. The final branch is defensive only: `boundAt` being
+                // finite guarantees one of the two bounds above is actually configured.
+                const reason = attemptTimeoutMs !== undefined && attemptDeadline <= totalDeadline
+                    ? new TimeoutError(req.displayUrl, attemptTimeoutMs)
+                    : isBoundedMs(req.timeoutConfig.totalMs)
+                        ? new DeadlineExceededError(req.displayUrl, req.timeoutConfig.totalMs)
+                        : new TimeoutError(req.displayUrl, attemptTimeoutMs ?? NO_TIMEOUT_CONFIGURED);
+                const bodyReadTimer = setTimeout(() => {
+                    timeoutController.abort(reason);
+                }, delay);
+                bodyReadTimer.unref();
+            }
+        }
+    }
+}
+function buildFetchCall(customFetch) {
+    const fetchFn = customFetch ?? globalThis.fetch.bind(globalThis);
+    return async (ctx) => {
+        const init = {
+            method: ctx.method,
+            headers: ctx.headers,
+            body: ctx.body,
+            signal: ctx.signal,
+        };
+        if (isReadableStream(ctx.body)) {
+            // Node's fetch requires duplex: "half" for stream bodies.
+            init.duplex = "half";
+        }
+        return fetchFn(ctx.url, init);
+    };
+}
+export function composeMiddleware(middlewares, core) {
+    return middlewares.reduceRight((next, middleware) => (ctx) => middleware(ctx, next), core);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Parse a `Retry-After` header value into a delay in ms, or undefined when
+ *  absent/unparseable. Integer seconds → ms; HTTP-date → ms from now, clamped
+ *  to ≥ 0; anything else (garbage, negative) → undefined. */
+export function parseRetryAfter(header) {
+    if (!header)
+        return undefined;
+    const trimmed = header.trim();
+    if (/^\d+$/.test(trimmed)) {
+        return Number(trimmed) * 1000;
+    }
+    const parsed = Date.parse(trimmed);
+    if (Number.isNaN(parsed))
+        return undefined;
+    return Math.max(0, parsed - Date.now());
+}
+function isAbortError(err) {
+    return err instanceof Error && err.name === "AbortError";
+}
+function extractIssues(err) {
+    if (err && typeof err === "object" && "errors" in err) {
+        return err.errors;
+    }
+    if (err && typeof err === "object" && "issues" in err) {
+        return err.issues;
+    }
+    return [err];
+}
+//# sourceMappingURL=executor.js.map

package/dist/queue/executor.js.map

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

package/dist/queue/policy.d.ts

@@ -0,0 +1,26 @@
+import type { AppError } from "../core/errors.ts";
+export interface RetryPolicyContext {
+    method: string;
+    headers?: HeadersInit;
+    /** value of merged retry.idempotent for this request */
+    idempotent?: boolean;
+}
+export type RetryPolicy = (error: AppError, attempt: number, ctx: RetryPolicyContext) => boolean;
+export declare const RETRIABLE_KINDS: ReadonlySet<AppError["kind"]>;
+/**
+ * The default retry policy (decision D3). An attempt is retried iff all hold:
+ * 1. attempts so far < maxRetries + 1 (enforced by the retry loop bounds)
+ * 2. error `kind` ∈ {network, timeout, retryable_status}
+ * 3. method is idempotent (GET HEAD OPTIONS PUT DELETE TRACE) OR
+ *    `ctx.idempotent === true` OR the request has an `Idempotency-Key` header
+ * 4. user `retryWhen` (consulted separately via `shouldRetry`) returns true
+ * 5. the request is not cancelled / past its deadline (handled elsewhere)
+ */
+export declare function defaultRetryPolicy(error: AppError, _attempt: number, ctx: RetryPolicyContext): boolean;
+/**
+ * Combined retry gate used by both call sites so rule ordering lives in one
+ * place: the default policy runs first, then the user's `retryWhen` is
+ * consulted. `retryWhen` can only veto a retry, never force one.
+ */
+export declare function shouldRetry(error: AppError, attempt: number, ctx: RetryPolicyContext, retryWhen?: (error: AppError, attempt: number) => boolean): boolean;
+//# sourceMappingURL=policy.d.ts.map

package/dist/queue/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/queue/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,wDAAwD;IACxD,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,KAAK,OAAO,CAAC;AAEjG,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAuD,CAAC;AAIlH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAQtG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,kBAAkB,EACvB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,GACvD,OAAO,CAIT"}

package/dist/queue/policy.js

@@ -0,0 +1,37 @@
+export const RETRIABLE_KINDS = new Set(["network", "timeout", "retryable_status"]);
+const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE"]);
+/**
+ * The default retry policy (decision D3). An attempt is retried iff all hold:
+ * 1. attempts so far < maxRetries + 1 (enforced by the retry loop bounds)
+ * 2. error `kind` ∈ {network, timeout, retryable_status}
+ * 3. method is idempotent (GET HEAD OPTIONS PUT DELETE TRACE) OR
+ *    `ctx.idempotent === true` OR the request has an `Idempotency-Key` header
+ * 4. user `retryWhen` (consulted separately via `shouldRetry`) returns true
+ * 5. the request is not cancelled / past its deadline (handled elsewhere)
+ */
+export function defaultRetryPolicy(error, _attempt, ctx) {
+    // Rule 2 — the error kind must be transient.
+    if (!RETRIABLE_KINDS.has(error.kind))
+        return false;
+    // Rule 3 — the request must be safe to repeat (idempotent by method or opt-in).
+    if (IDEMPOTENT_METHODS.has(ctx.method.toUpperCase()))
+        return true;
+    if (ctx.idempotent)
+        return true;
+    if (ctx.headers && new Headers(ctx.headers).has("idempotency-key"))
+        return true;
+    return false;
+}
+/**
+ * Combined retry gate used by both call sites so rule ordering lives in one
+ * place: the default policy runs first, then the user's `retryWhen` is
+ * consulted. `retryWhen` can only veto a retry, never force one.
+ */
+export function shouldRetry(error, attempt, ctx, retryWhen) {
+    if (!defaultRetryPolicy(error, attempt, ctx))
+        return false;
+    if (retryWhen && !retryWhen(error, attempt))
+        return false;
+    return true;
+}
+//# sourceMappingURL=policy.js.map

package/dist/queue/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/queue/policy.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,eAAe,GAAkC,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAElH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAEzF;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAe,EAAE,QAAgB,EAAE,GAAuB;IAC5F,6CAA6C;IAC7C,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACnD,gFAAgF;IAChF,IAAI,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAClE,IAAI,GAAG,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,GAAG,CAAC,OAAO,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAAE,OAAO,IAAI,CAAC;IAChF,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAC1B,KAAe,EACf,OAAe,EACf,GAAuB,EACvB,SAAyD;IAEzD,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3D,IAAI,SAAS,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1D,OAAO,IAAI,CAAC;AACb,CAAC"}

package/dist/queue/retry.d.ts

@@ -0,0 +1,58 @@
+import type { AppError } from "../core/errors.ts";
+import { type RequestOptions, type RetryConfig, type TimeoutConfig } from "../core/types.ts";
+import type { Ticket, TicketController } from "../ticket/ticket.ts";
+import type { Bulkhead } from "./bulkhead.ts";
+import type { CircuitBreaker } from "./circuit-breaker.ts";
+import { type MiddlewareFn } from "./executor.ts";
+import type { Semaphore } from "./semaphore.ts";
+export interface RetryJobOptions {
+    /** Fully resolved request URL (baseUrl applied) — what each retry fetches. */
+    url: string;
+    /** `url` as it may appear in errors/logs (query-redacted unless disabled). */
+    displayUrl: string;
+    requestOptions: RequestOptions<unknown>;
+    timeoutConfig: TimeoutConfig;
+    retryConfig: RetryConfig;
+    /** Absolute `Date.now()` timestamp of the ticket's whole-ticket deadline
+     *  (`startTime + timeoutConfig.totalMs`), or undefined when `totalMs`
+     *  isn't bounded. Forwarded to `executeRequest` so a handed-off Response
+     *  body (unread success or `HttpError`) is bounded by it — see
+     *  `ExecuteRequest.deadlineAt`. */
+    deadlineAt?: number;
+    ticket: Ticket<unknown>;
+    controller: TicketController<unknown>;
+    middleware: MiddlewareFn[];
+    /** Per-attempt bulkhead for retry scheduling. */
+    bulkhead: Bulkhead;
+    /** Global concurrency semaphore acquired after the partition slot (D4). */
+    semaphore?: Semaphore;
+    /** Per-partition circuit breaker. Inert unless configured/enabled. */
+    circuitBreaker: CircuitBreaker;
+    /** Partition name, used to construct CircuitOpenError when the breaker is open. */
+    partition: string;
+    /** The error from the first attempt (fired client-side before queuing). */
+    firstError: AppError;
+    /** Ms the first attempt spent waiting for a bulkhead/semaphore permit,
+     *  carried over so the final queuedMs reported to the client covers the
+     *  whole ticket lifetime, not just the retries run inside this loop. */
+    initialQueuedMs: number;
+    onRetry?: (attempt: number, delayMs: number, error: AppError) => void;
+    /** Called on success so the client can emit the success event with the
+     *  response status code, the total attempt count, and the cumulative ms
+     *  spent waiting for a bulkhead/semaphore permit across all attempts. */
+    onSuccess?: (statusCode: number, attempts: number, queuedMs: number) => void;
+    /** Called on failure (exhausted retries or policy veto inside the loop)
+     *  so the client can emit the failure event. `queuedMs` is cumulative
+     *  across all attempts made so far. */
+    onFailure?: (error: AppError, attempts: number, queuedMs: number) => void;
+    /** Called on cancellation (user cancel, deadline, or external signal)
+     *  so the client can emit the cancelled event. `queuedMs` is cumulative
+     *  across all attempts made so far. */
+    onCancelled?: (attempts: number, queuedMs: number) => void;
+    /** Called before markDone to clean up external resources (e.g. signal listeners). */
+    onCleanup?: () => void;
+    /** Custom fetch function. Falls back to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+}
+export declare function runRetryLoop(job: RetryJobOptions): Promise<void>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/queue/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/queue/retry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAWlD,OAAO,EAIN,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC/B,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IACxC,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,WAAW,CAAC;IACzB;;;;uCAImC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB,UAAU,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACtC,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,EAAE,QAAQ,CAAC;IACnB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,sEAAsE;IACtE,cAAc,EAAE,cAAc,CAAC;IAC/B,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,UAAU,EAAE,QAAQ,CAAC;IACrB;;4EAEwE;IACxE,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;IACtE;;6EAEyE;IACzE,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7E;;2CAEuC;IACvC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1E;;2CAEuC;IACvC,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAChC;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA6QtE"}