@superblocksteam/telemetry 2.0.0-SNAPSHOT.329be19cb7ca892b

package/dist/node/log-processor.js

@@ -0,0 +1,397 @@
+"use strict";
+/**
+ * Policy-Aware Log Processor
+ *
+ * Wraps a delegate LogRecordProcessor to provide:
+ * 1. Export mode filtering (LOCAL_ONLY, ERRORS_ONLY, INFO_AND_ABOVE)
+ * 2. Severity level filtering
+ * 3. Log body and attribute sanitization
+ *
+ * @see https://github.com/superblocksteam/engineering/blob/main/projects/o11y-refactor/epics/epic-c4-logging-strategy.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyAwareLogProcessor = exports.LogExportMode = void 0;
+exports.parseLogExportMode = parseLogExportMode;
+exports.getLoggingPolicy = getLoggingPolicy;
+exports.getMinimumPinoLevelFromLoggingPolicy = getMinimumPinoLevelFromLoggingPolicy;
+exports.getMinimumPinoLevelForDeployment = getMinimumPinoLevelForDeployment;
+const shared_1 = require("@superblocksteam/shared");
+const log_sanitizer_js_1 = require("../common/log-sanitizer.js");
+const policy_evaluator_js_1 = require("../common/policy-evaluator.js");
+const policy_js_1 = require("../types/policy.js");
+const local_obs_mode_js_1 = require("./local-obs-mode.js");
+// ============================================================================
+// Log Export Mode
+// ============================================================================
+/**
+ * Controls what logs are exported via OTEL.
+ */
+var LogExportMode;
+(function (LogExportMode) {
+    /** No log export - local stdout/stderr only */
+    LogExportMode["LOCAL_ONLY"] = "local_only";
+    /** Export WARN/ERROR/FATAL only (default for cloud-prem) */
+    LogExportMode["ERRORS_ONLY"] = "errors_only";
+    /** Export INFO and above (not recommended for cloud-prem) */
+    LogExportMode["INFO_AND_ABOVE"] = "info_and_above";
+})(LogExportMode || (exports.LogExportMode = LogExportMode = {}));
+/**
+ * Parse a string value into a LogExportMode, returning undefined if unrecognized.
+ * Used to validate SUPERBLOCKS_LOG_EXPORT_MODE env var values.
+ */
+function parseLogExportMode(value) {
+    if (!value)
+        return undefined;
+    const normalized = value.toLowerCase();
+    if (normalized === LogExportMode.INFO_AND_ABOVE)
+        return LogExportMode.INFO_AND_ABOVE;
+    if (normalized === LogExportMode.ERRORS_ONLY)
+        return LogExportMode.ERRORS_ONLY;
+    if (normalized === LogExportMode.LOCAL_ONLY)
+        return LogExportMode.LOCAL_ONLY;
+    return undefined;
+}
+/**
+ * Get logging policy based on telemetry policy.
+ *
+ * @param policy - Telemetry policy
+ * @param exportModeOverride - Optional override for the export mode. When set, overrides the
+ *   deployment-type default (e.g. allows INFO_AND_ABOVE on a cloud-prem trial environment).
+ *   Cloud-prem sanitization (redaction, forbidden fields) is still applied regardless of override.
+ * @returns Logging policy configuration
+ */
+function getLoggingPolicy(policy, exportModeOverride) {
+    const evaluator = new policy_evaluator_js_1.TelemetryPolicyEvaluator(policy);
+    // Check if Tier 2 export is allowed.
+    // ORDERING IS SECURITY-CRITICAL: this gate MUST come before the cloud-prem branch.
+    // exportModeOverride must never escalate a LOCAL_ONLY (Tier 2 disabled) deployment to
+    // INFO_AND_ABOVE. Do not move the cloud-prem branch above this check.
+    const canExportTier2 = evaluator.isExportEnabled(policy_js_1.TelemetryTier.TIER_2_OPERATIONAL);
+    if (!canExportTier2) {
+        return {
+            exportMode: LogExportMode.LOCAL_ONLY,
+            localMaxLevel: "debug",
+            messageSecretPatterns: log_sanitizer_js_1.DEFAULT_SECRET_PATTERNS,
+            secretFieldNames: log_sanitizer_js_1.SECRET_FIELDS,
+            secretFieldPatterns: log_sanitizer_js_1.SECRET_FIELD_PATTERNS,
+            redactStackTraces: true,
+            redactPatterns: [],
+            sensitivePatterns: log_sanitizer_js_1.DEFAULT_SENSITIVE_PATTERNS,
+            forbiddenFields: log_sanitizer_js_1.TIER1_FORBIDDEN_LOG_FIELDS,
+        };
+    }
+    // Cloud-prem: export errors only by default, with full sanitization (secrets + sensitive patterns).
+    // exportModeOverride allows specific deployments (e.g. trial environments) to opt into INFO_AND_ABOVE
+    // for debugging. Sanitization is always applied on cloud-prem regardless of the override.
+    if (policy.deploymentType === shared_1.DeploymentTypeEnum.CLOUD_PREM) {
+        return {
+            exportMode: exportModeOverride ?? LogExportMode.ERRORS_ONLY,
+            localMaxLevel: "debug",
+            messageSecretPatterns: log_sanitizer_js_1.DEFAULT_SECRET_PATTERNS,
+            secretFieldNames: log_sanitizer_js_1.SECRET_FIELDS,
+            secretFieldPatterns: log_sanitizer_js_1.SECRET_FIELD_PATTERNS,
+            redactStackTraces: true,
+            redactPatterns: log_sanitizer_js_1.CLOUD_PREM_REDACT_PATTERNS,
+            sensitivePatterns: log_sanitizer_js_1.DEFAULT_SENSITIVE_PATTERNS,
+            forbiddenFields: new Set([
+                ...log_sanitizer_js_1.TIER1_FORBIDDEN_LOG_FIELDS,
+                ...log_sanitizer_js_1.EXPORT_FORBIDDEN_FIELDS_CLOUD_PREM,
+            ]),
+        };
+    }
+    // Cloud: all sanitization off (logs sent as-is)
+    return {
+        exportMode: LogExportMode.INFO_AND_ABOVE,
+        localMaxLevel: "debug",
+        messageSecretPatterns: [],
+        secretFieldNames: new Set(),
+        secretFieldPatterns: [],
+        redactStackTraces: false,
+        redactPatterns: [],
+        sensitivePatterns: [],
+        forbiddenFields: new Set(),
+    };
+}
+/**
+ * Pino levels below WARN; when exportMode is ERRORS_ONLY we never write these to stdout.
+ */
+const LEVELS_BELOW_WARN = new Set(["trace", "debug", "info"]);
+/**
+ * Ordered from most verbose (index 0) to least verbose (index 5).
+ * Used to compare levels: "more restrictive" = higher index = fewer logs retained.
+ */
+const PINO_LEVEL_ORDER = ["trace", "debug", "info", "warn", "error", "fatal"];
+function levelOrderIndex(level) {
+    const normalized = level.toLowerCase();
+    const idx = PINO_LEVEL_ORDER.indexOf(normalized);
+    return idx >= 0 ? idx : PINO_LEVEL_ORDER.indexOf("info");
+}
+/**
+ * Returns the more restrictive of two levels (the one that retains fewer logs).
+ * E.g. moreRestrictiveLevel("trace", "debug") === "debug".
+ */
+function moreRestrictiveLevel(a, b) {
+    const idxA = levelOrderIndex(a);
+    const idxB = levelOrderIndex(b);
+    return PINO_LEVEL_ORDER[Math.max(idxA, idxB)] ?? "info";
+}
+/**
+ * Returns the effective Pino log level from the current logging policy and env level.
+ * 1. Applies exportMode: when ERRORS_ONLY, never below warn so export paths never see INFO/DEBUG.
+ * 2. Applies localMaxLevel: caps local retention so we never set the logger more verbose than
+ *    policy.localMaxLevel (e.g. localMaxLevel "debug" prevents trace from being written locally).
+ *
+ * Use when policy is available (e.g. after initNodeTelemetry) to sync logger level from policy.
+ *
+ * @param loggingPolicy - Logging policy (e.g. from getLoggingPolicy(telemetryPolicy))
+ * @param envLevel - Level from env (e.g. SUPERBLOCKS_SERVER_LOG_LEVEL)
+ * @returns Level to pass to Pino
+ */
+function getMinimumPinoLevelFromLoggingPolicy(loggingPolicy, envLevel) {
+    let level;
+    const envLevelNormalized = envLevel.toLowerCase();
+    // Under local-obs the OTLP log processor exports INFO+ (see the override in
+    // init.ts), so the Pino floor must also allow INFO. Without this, a cloud-prem
+    // deployment type keeps the ERRORS_ONLY 'warn' floor and INFO lines are dropped
+    // by Pino before they can reach the pino->OTel tee. See isLocalObsMode.
+    if (loggingPolicy.exportMode === LogExportMode.ERRORS_ONLY &&
+        !(0, local_obs_mode_js_1.isLocalObsMode)() &&
+        LEVELS_BELOW_WARN.has(envLevelNormalized)) {
+        level = "warn";
+    }
+    else {
+        level = envLevel;
+    }
+    return moreRestrictiveLevel(level, loggingPolicy.localMaxLevel);
+}
+/**
+ * Returns the effective Pino log level for a deployment given the env-configured level.
+ * Used at logger bootstrap when policy is not yet initialized (e.g. server logger module load).
+ * Delegates to getMinimumPinoLevelFromLoggingPolicy with a synthetic policy from deployment type
+ * so the exportMode → level rule lives in one place.
+ *
+ * @param envLevel - Level from env (e.g. SUPERBLOCKS_SERVER_LOG_LEVEL)
+ * @param deploymentType - Deployment type from env (e.g. SUPERBLOCKS_DEPLOYMENT_TYPE)
+ * @param exportModeOverride - Optional override from env (e.g. SUPERBLOCKS_LOG_EXPORT_MODE).
+ *   When set to a valid LogExportMode, overrides the deployment-type default.
+ *   NOTE: This function runs at bootstrap before the policy evaluator is initialized,
+ *   so it cannot verify the Tier 2 export gate. The override only lowers the Pino
+ *   stdout level; actual telemetry export is gated by getLoggingPolicy() after init,
+ *   which always enforces !canExportTier2 before applying the override.
+ * @returns Level to pass to Pino (envLevel or 'warn' for cloud-prem when envLevel is below warn)
+ */
+function getMinimumPinoLevelForDeployment(envLevel, deploymentType, exportModeOverride) {
+    const isCloudPrem = deploymentType === shared_1.DeploymentTypeEnum.CLOUD_PREM;
+    const deploymentDefault = isCloudPrem
+        ? LogExportMode.ERRORS_ONLY
+        : LogExportMode.INFO_AND_ABOVE;
+    // Only apply the override for cloud-prem; cloud always uses INFO_AND_ABOVE (mirrors getLoggingPolicy).
+    const exportMode = (isCloudPrem ? exportModeOverride : undefined) ?? deploymentDefault;
+    return getMinimumPinoLevelFromLoggingPolicy({
+        exportMode,
+        localMaxLevel: "debug",
+        messageSecretPatterns: [],
+        secretFieldNames: new Set(),
+        secretFieldPatterns: [],
+        redactStackTraces: false,
+        redactPatterns: [],
+        sensitivePatterns: [],
+        forbiddenFields: new Set(),
+    }, envLevel);
+}
+// ============================================================================
+// Severity Level Utilities
+// ============================================================================
+/**
+ * OTEL severity numbers:
+ * 1-4: TRACE
+ * 5-8: DEBUG
+ * 9-12: INFO
+ * 13-16: WARN
+ * 17-20: ERROR
+ * 21-24: FATAL
+ */
+function getSeverityName(severityNumber) {
+    if (!severityNumber)
+        return "info";
+    if (severityNumber <= 4)
+        return "trace";
+    if (severityNumber <= 8)
+        return "debug";
+    if (severityNumber <= 12)
+        return "info";
+    if (severityNumber <= 16)
+        return "warn";
+    if (severityNumber <= 20)
+        return "error";
+    return "fatal";
+}
+/**
+ * Check if a severity level should be exported based on export mode.
+ */
+function shouldExportSeverity(severityNumber, mode) {
+    if (mode === LogExportMode.LOCAL_ONLY) {
+        return false;
+    }
+    const severity = getSeverityName(severityNumber);
+    if (mode === LogExportMode.ERRORS_ONLY) {
+        return severity === "warn" || severity === "error" || severity === "fatal";
+    }
+    // INFO_AND_ABOVE
+    return (severity === "info" ||
+        severity === "warn" ||
+        severity === "error" ||
+        severity === "fatal");
+}
+// ============================================================================
+// Policy-Aware Log Processor
+// ============================================================================
+/**
+ * Log processor that filters and sanitizes logs based on policy.
+ *
+ * This processor:
+ * 1. Blocks all logs if exportMode is LOCAL_ONLY
+ * 2. Filters by severity level based on exportMode
+ * 3. Sanitizes log body and attributes before forwarding
+ */
+class PolicyAwareLogProcessor {
+    policy;
+    delegate;
+    constructor(policy, delegate) {
+        this.policy = policy;
+        this.delegate = delegate;
+    }
+    /**
+     * Called when a log record is emitted.
+     */
+    onEmit(logRecord, context) {
+        // Check if export mode allows this log
+        if (this.policy.exportMode === LogExportMode.LOCAL_ONLY) {
+            return; // Don't export anything
+        }
+        // Check if severity level should be exported
+        if (!shouldExportSeverity(logRecord.severityNumber, this.policy.exportMode)) {
+            return;
+        }
+        // Sanitize the log record in place before forwarding (policy-driven; empty config = passthrough)
+        this.sanitizeLogRecord(logRecord);
+        // Forward to delegate - cast is safe because logRecord is SdkLogRecord at runtime
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.delegate.onEmit(logRecord, context);
+    }
+    /** True when policy has no sanitization (cloud passthrough). */
+    isPassthroughPolicy() {
+        const p = this.policy;
+        return (p.messageSecretPatterns.length === 0 &&
+            p.secretFieldNames.size === 0 &&
+            p.secretFieldPatterns.length === 0 &&
+            !p.redactStackTraces &&
+            p.forbiddenFields.size === 0 &&
+            p.sensitivePatterns.length === 0 &&
+            p.redactPatterns.length === 0);
+    }
+    /**
+     * Sanitize a log record for export.
+     * Mutates the log record in place to preserve OTEL SDK internal state.
+     * All redaction is policy-driven; when config is empty/off, content is left as-is.
+     */
+    sanitizeLogRecord(logRecord) {
+        const p = this.policy;
+        // Sanitize body - mutate in place
+        if (typeof logRecord.body === "string") {
+            let body = p.messageSecretPatterns.length > 0
+                ? (0, log_sanitizer_js_1.redactSensitivePatterns)(logRecord.body, p.messageSecretPatterns)
+                : logRecord.body;
+            body = (0, log_sanitizer_js_1.redactSensitivePatterns)(body, p.sensitivePatterns);
+            body = (0, log_sanitizer_js_1.applyRedactPatterns)(body, p.redactPatterns);
+            if (p.redactStackTraces && (0, log_sanitizer_js_1.containsStackTrace)(body)) {
+                body = (0, log_sanitizer_js_1.redactStackTraceForExport)(body, p.sensitivePatterns, p.messageSecretPatterns);
+            }
+            logRecord.body = body;
+        }
+        else if (logRecord.body && typeof logRecord.body === "object") {
+            if (!this.isPassthroughPolicy()) {
+                logRecord.body =
+                    (0, log_sanitizer_js_1.sanitizeLogObjectForExport)(logRecord.body, p.forbiddenFields, 0, p.sensitivePatterns);
+            }
+        }
+        // Sanitize attributes - mutate in place
+        const attrs = logRecord.attributes;
+        if (attrs) {
+            const sanitizedAttributes = this.sanitizeAttributes(attrs);
+            // Clear and repopulate attributes
+            for (const key of Object.keys(attrs)) {
+                delete attrs[key];
+            }
+            for (const [key, value] of Object.entries(sanitizedAttributes)) {
+                attrs[key] = value;
+            }
+        }
+    }
+    /**
+     * Sanitize log attributes.
+     */
+    sanitizeAttributes(attributes) {
+        if (!attributes) {
+            return {};
+        }
+        const p = this.policy;
+        const sanitized = {};
+        for (const [key, value] of Object.entries(attributes)) {
+            const lowerKey = key.toLowerCase();
+            if ((0, log_sanitizer_js_1.isSecretFieldFromPolicy)(key, p.secretFieldNames, p.secretFieldPatterns)) {
+                sanitized[key] = log_sanitizer_js_1.REDACTED_PLACEHOLDER;
+                continue;
+            }
+            if (p.forbiddenFields.has(lowerKey)) {
+                continue;
+            }
+            if (typeof value === "string") {
+                let str = p.messageSecretPatterns.length > 0
+                    ? (0, log_sanitizer_js_1.redactSensitivePatterns)(value, p.messageSecretPatterns)
+                    : value;
+                str = (0, log_sanitizer_js_1.redactSensitivePatterns)(str, p.sensitivePatterns);
+                str = (0, log_sanitizer_js_1.applyRedactPatterns)(str, p.redactPatterns);
+                if (p.redactStackTraces) {
+                    if ((0, log_sanitizer_js_1.isStackAttributeKey)(key)) {
+                        sanitized[key] = (0, log_sanitizer_js_1.containsStackTrace)(str)
+                            ? (0, log_sanitizer_js_1.redactStackTraceForExport)(str, p.sensitivePatterns, p.messageSecretPatterns)
+                            : log_sanitizer_js_1.STACK_TRACE_REDACTED_PLACEHOLDER;
+                    }
+                    else if ((0, log_sanitizer_js_1.containsStackTrace)(str)) {
+                        sanitized[key] = (0, log_sanitizer_js_1.redactStackTraceForExport)(str, p.sensitivePatterns, p.messageSecretPatterns);
+                    }
+                    else {
+                        sanitized[key] = str;
+                    }
+                }
+                else {
+                    sanitized[key] = str;
+                }
+            }
+            else if (value &&
+                typeof value === "object" &&
+                !this.isPassthroughPolicy()) {
+                sanitized[key] = (0, log_sanitizer_js_1.sanitizeLogObjectForExport)(value, p.forbiddenFields, 0, p.sensitivePatterns);
+            }
+            else {
+                sanitized[key] = value;
+            }
+        }
+        return sanitized;
+    }
+    /**
+     * Shutdown the processor.
+     */
+    async shutdown() {
+        return this.delegate.shutdown();
+    }
+    /**
+     * Force flush pending logs.
+     */
+    async forceFlush() {
+        return this.delegate.forceFlush();
+    }
+}
+exports.PolicyAwareLogProcessor = PolicyAwareLogProcessor;
+//# sourceMappingURL=log-processor.js.map

package/dist/node/log-processor.js.map

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

package/dist/node/metrics-client.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Metrics Client for Node.js Telemetry
+ *
+ * Provides a simple interface for recording metrics via OpenTelemetry.
+ * This is the recommended way to record metrics in services using the telemetry package.
+ */
+import type { Meter } from "@opentelemetry/api";
+/**
+ * Labels for metrics (key-value pairs).
+ */
+export type Labels = Record<string, string | number>;
+/**
+ * Handle for a counter metric.
+ */
+export interface CounterHandle {
+    inc(labels?: Labels, value?: number): void;
+}
+/**
+ * Handle for a gauge metric.
+ */
+export interface GaugeHandle {
+    set(labels: Labels, value: number): void;
+}
+/**
+ * Handle for a histogram metric.
+ */
+export interface HistogramHandle {
+    observe(labels: Labels, value: number): void;
+}
+/**
+ * Options for counter creation. Only applied the first time a counter name is
+ * registered; later calls reuse the existing instrument.
+ */
+export interface CounterOptions {
+    description?: string;
+    unit?: string;
+}
+/**
+ * Options for histogram creation. Only applied the first time a histogram
+ * name is registered; later calls reuse the existing instrument.
+ */
+export interface HistogramOptions extends CounterOptions {
+    /**
+     * Explicit bucket boundaries advice for the OTEL SDK. Without this, the
+     * SDK's default boundaries top out at 10,000 — long-tail observations
+     * (e.g. multi-minute latencies in ms) all collapse into the +Inf bucket.
+     */
+    bucketBoundaries?: number[];
+}
+/**
+ * Metrics client that provides a unified interface for recording OTEL metrics.
+ */
+export declare class MetricsClient {
+    private readonly meter;
+    private counters;
+    private histograms;
+    private gaugeValues;
+    constructor(meter: Meter);
+    /**
+     * Creates or retrieves a counter and returns a handle.
+     */
+    counter(name: string, options?: CounterOptions): CounterHandle;
+    /**
+     * Creates or retrieves a gauge and returns a handle.
+     * Note: OTEL gauges are async/observable, so we store the value and emit via callback.
+     * Values are automatically expired after 5 minutes to prevent unbounded memory growth.
+     */
+    gauge(name: string): GaugeHandle;
+    /**
+     * Creates or retrieves a histogram and returns a handle.
+     */
+    histogram(name: string, options?: HistogramOptions): HistogramHandle;
+    /**
+     * Increments a counter by name (creates if not exists). `options` is only
+     * applied on the instrument's first registration; see `counter`.
+     */
+    incCounter(name: string, labels?: Labels, value?: number, options?: CounterOptions): void;
+    /**
+     * Sets a gauge value by name (creates if not exists).
+     */
+    setGauge(name: string, labels: Labels, value: number): void;
+    /**
+     * Observes a histogram value by name (creates if not exists). `options` is
+     * only applied on the instrument's first registration; see `histogram`.
+     */
+    observeHistogram(name: string, labels: Labels, value: number, options?: HistogramOptions): void;
+}
+//# sourceMappingURL=metrics-client.d.ts.map

package/dist/node/metrics-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-client.d.ts","sourceRoot":"","sources":["../../src/node/metrics-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAkC,MAAM,oBAAoB,CAAC;AAEhF;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAuHrD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,aAAa;IAMZ,OAAO,CAAC,QAAQ,CAAC,KAAK;IALlC,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,UAAU,CAAgC;IAElD,OAAO,CAAC,WAAW,CAAkC;gBAExB,KAAK,EAAE,KAAK;IAEzC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,aAAa;IAa9D;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW;IA2BhC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,eAAe;IAiCpE;;;OAGG;IACH,UAAU,CACR,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,GAAE,MAAU,EACjB,OAAO,CAAC,EAAE,cAAc,GACvB,IAAI;IAIP;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAI3D;;;OAGG;IACH,gBAAgB,CACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,GACzB,IAAI;CAGR"}