@smthrs/observability 0.35.0 → 1.0.0-rc.3

package/dist/esm/Otlp.js

@@ -0,0 +1,350 @@
+/**
+ * Default OTLP export wiring for flows telemetry.
+ *
+ * The store packages already open spans through Effect's tracer and update
+ * `Metric` counters on their hot paths; what they deliberately do not do is
+ * ship an exporter. This module is that exporter: one layer that installs
+ * Effect's own OTLP logger, metrics exporter, and tracer
+ * (`effect/unstable/observability/Otlp`) against a collector endpoint, with
+ * the flows service identity filled in. Nothing beyond `effect` is involved;
+ * no OpenTelemetry SDK dependency.
+ *
+ * Browser support is met by construction rather than by a no-op variant:
+ * export happens over Effect's `HttpClient`, and {@link layerFetch} binds the
+ * `fetch` implementation the host already has, so no entry point here ever
+ * resolves a `node:` built-in. See the
+ * {@link https://smithers.sh/docs/reference/api/observability | observability API contract}.
+ *
+ * @since 0.1.0
+ */
+import * as Redaction from "@smthrs/journal/Redaction";
+import * as Cause from "effect/Cause";
+import { Clock } from "effect/Clock";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as Metric from "effect/Metric";
+import * as Option from "effect/Option";
+import * as References from "effect/References";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import * as Tracer from "effect/Tracer";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import * as Headers from "effect/unstable/http/Headers";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import * as Otlp from "effect/unstable/observability/Otlp";
+import * as Endpoint from "./Endpoint.js";
+import * as Resource from "./Resource.js";
+/**
+ * The `service.name` resource attribute installed when the caller supplies
+ * none: the flows distribution itself. Override it per application with
+ * {@link Options.serviceName}.
+ *
+ * @category resource
+ * @since 0.1.0
+ */
+export const defaultServiceName = "flows";
+/**
+ * The `service.version` resource attribute installed when the caller supplies
+ * none. Mirrors the release version in this package's `package.json`.
+ *
+ * A published package cannot read its own manifest on every runtime it
+ * supports, so the version lives here as a literal.
+ * `scripts/set-release-version.mjs` rewrites this declaration with the
+ * manifests, and its `--check` mode reports drift, so a release bump cannot
+ * leave it behind.
+ *
+ * @category resource
+ * @since 0.1.0
+ */
+export const defaultServiceVersion = "1.0.0-rc.3";
+// The upstream logger and tracer each buffer at most one 1,000-record batch.
+// Do not queue at the transport: upstream forks every full batch independently.
+const maxBatchSize = 1000;
+const maxInFlight = 4;
+/**
+ * Maximum encoded export request size, in bytes.
+ * @category transport
+ * @since 1.0.0-rc.0
+ */
+export const maxRequestBytes = 1024 * 1024;
+const requestTimeout = "10 seconds";
+const diagnosticIntervalMillis = 60_000;
+// The envelope around the resource in every request repeats `service.name` as
+// the instrumentation scope name: at most 1,024 code units, at most six bytes
+// each once JSON-escaped, so under 8 KiB together with the envelope's own keys.
+/**
+ * Reserved bytes for request wrappers and the escaped instrumentation scope.
+ * @category transport
+ * @since 1.0.0-rc.0
+ */
+export const maximumEnvelopeBytes = 8 * 1024;
+/**
+ * Bytes of every export request kept free for the signal batch itself.
+ *
+ * The transport discards a request over 1 MiB, and the resource rides in every
+ * request, so the largest resource `Resource.decode` admits
+ * (`Resource.maximumResourceBytes`, 128 KiB) and the envelope that repeats the
+ * service name (under 8 KiB) come off the top. The 888 KiB left gives each
+ * record of a full 1,000-record logger or tracer batch about 900 bytes, three
+ * to four times a bare log record or span, and gives the metrics snapshot room
+ * for several thousand series. Every resource the decoder accepts therefore
+ * leaves an ordinary batch of any signal exportable; what this reserve does
+ * not bound is a single application record or a registry large enough to
+ * exceed it on its own.
+ *
+ * @category transport
+ * @since 1.0.0-rc.0
+ */
+export const reservedBatchBytes = maxRequestBytes - Resource.maximumResourceBytes - maximumEnvelopeBytes;
+const boundedClient = Layer.effect(HttpClient.HttpClient, Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const clock = yield* Clock;
+    // The loggers installed when this transport is acquired. The OTLP logger
+    // the same acquisition installs does not exist yet, so a diagnostic pinned
+    // to this set cannot enter the exporter it describes, whichever fiber runs
+    // the export: the interval and shutdown fibers inherit this set anyway,
+    // but a flush requested from application code runs with the application's
+    // loggers, which by then include this exporter.
+    const ambientLoggers = yield* Effect.withFiber((fiber) => Effect.succeed(fiber.getRef(Logger.CurrentLoggers)));
+    const permits = Semaphore.makeUnsafe(maxInFlight);
+    // The counter lives with the transport it describes.
+    const droppedExports = Metric.counter("flows_observability_otlp_dropped");
+    let nextDiagnosticAt = -Infinity;
+    // A local discard is terminal, so the upstream retry loop must not retain
+    // or retry its payload, and the counter records batches, not records. The
+    // warning is the diagnostic the counter cannot be: the counter is exported
+    // through this same transport and shares every outage with it. One
+    // warning per minute keeps a sustained outage from flooding the ambient
+    // loggers; the running total in its annotations carries the volume.
+    // Replace ambient annotations and log spans to bound the diagnostic itself.
+    const discard = (reason, request, bytes) => Metric.update(droppedExports, 1).pipe(Effect.andThen(Effect.suspend(() => {
+        const now = clock.currentTimeMillisUnsafe();
+        if (now < nextDiagnosticAt)
+            return Effect.void;
+        nextDiagnosticAt = now + diagnosticIntervalMillis;
+        return Metric.value(droppedExports).pipe(Effect.flatMap((dropped) => Effect.logWarning("An OTLP export batch was discarded").pipe(Effect.provideService(References.CurrentLogSpans, []), Effect.provideService(References.CurrentLogAnnotations, {
+            code: "otlp_export_discarded",
+            reason,
+            bytes,
+            limit: maxRequestBytes,
+            dropped: dropped.count
+        }))), Effect.provideService(Logger.CurrentLoggers, ambientLoggers));
+    })), Effect.as(HttpClientResponse.fromWeb(request, new Response(null, { status: 204 }))));
+    return HttpClient.transform(client, (requestEffect, request) => Effect.suspend(() => {
+        // layerJson always supplies a Uint8Array body with a byte length.
+        const bytes = request.body.contentLength;
+        if (bytes > maxRequestBytes)
+            return discard("oversized", request, bytes);
+        // Fetch must expose redirects before any credential or signal body
+        // leaves the configured endpoint, even when the caller enables follow.
+        const confinedRequest = Effect.flatMap(Effect.serviceOption(FetchHttpClient.RequestInit), (init) => requestEffect.pipe(Effect.provideService(FetchHttpClient.RequestInit, {
+            ...Option.getOrUndefined(init),
+            redirect: "manual"
+        })));
+        return confinedRequest.pipe(Effect.timeoutOrElse({
+            duration: requestTimeout,
+            orElse: () => discard("stalled", request, bytes)
+        }), permits.withPermitsIfAvailable(1), Effect.flatMap(Option.match({
+            onNone: () => discard("saturated", request, bytes),
+            onSome: Effect.succeed
+        })));
+    }));
+}));
+const loopbackIpv4 = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+/** Whether a decoded endpoint's host never leaves this machine. */
+const isLoopback = (endpoint) => {
+    const hostname = new URL(endpoint).hostname;
+    return hostname === "localhost" || hostname === "[::1]" || loopbackIpv4.test(hostname);
+};
+/**
+ * Refuses a credential header bound for a plaintext collector off this
+ * machine. Anyone on the network path could read the token from every export
+ * request, and the exporter would never report it. Loopback `http://` stays
+ * allowed for a local collector or sidecar; non-credential headers such as a
+ * tenant id stay allowed on any endpoint.
+ */
+/**
+ * Vendor credential headers whose names `Redaction.isSensitiveKey` does not
+ * recognize. Honeycomb sends its ingest key as `x-honeycomb-team`.
+ */
+const vendorCredentialHeaders = new Set(["x-honeycomb-team"]);
+const isCredentialHeader = (name) => Redaction.isSensitiveKey(name) || vendorCredentialHeaders.has(name.toLowerCase());
+const refusePlaintextCredentials = (baseUrl, headers) => {
+    if (!baseUrl.toLowerCase().startsWith("http:") || isLoopback(baseUrl))
+        return Effect.void;
+    const credential = Object.keys(Headers.fromInput(headers)).some(isCredentialHeader);
+    return credential
+        ? Effect.fail(new Endpoint.InvalidExporterEndpoint({
+            code: "invalid_exporter_endpoint",
+            path: "baseUrl",
+            message: "OTLP collector baseUrl must use https:// when headers carry credentials, unless it is a loopback address"
+        }))
+        : Effect.void;
+};
+const redactText = (text) => String(Redaction.redact(text));
+/**
+ * A failed span's error rebuilt with its text redacted. It keeps the original
+ * error's `name` and `stack` (redacted) so the collector's exception type and
+ * trace stay readable; it is exported to the collector and never thrown.
+ */
+class RedactedSpanError extends Schema.TaggedError()("@smthrs/observability/RedactedSpanError", {
+    message: Schema.String
+}) {
+}
+/**
+ * A span failure rendered with credentials removed. The exporter serializes a
+ * failed span's cause into its status message and `exception` events, which
+ * would otherwise carry any token an error message quoted to the collector.
+ */
+const redactedExit = (exit) => {
+    if (exit._tag === "Success" || Cause.hasInterruptsOnly(exit.cause))
+        return exit;
+    const errors = Cause.prettyErrors(exit.cause, { includeCauseInStack: true }).map((error) => {
+        const redacted = new RedactedSpanError({ message: redactText(error.message) });
+        Object.defineProperty(redacted, "name", { value: redactText(error.name), configurable: true, writable: true });
+        // `prettyErrors` always renders a stack.
+        redacted.stack = redactText(String(error.stack));
+        return redacted;
+    });
+    return Exit.failCause(errors.map(Cause.fail).reduce(Cause.combine, Cause.empty));
+};
+/**
+ * Wraps the installed tracer so every exported span's failure and string
+ * attributes pass through the journal redaction rules first.
+ */
+const redactedSpans = Layer.effect(Tracer.Tracer)(Effect.map(Effect.tracer, (tracer) => Tracer.make({
+    ...tracer,
+    span(options) {
+        const span = tracer.span(options);
+        const end = span.end.bind(span);
+        const attribute = span.attribute.bind(span);
+        span.end = (endTime, exit) => end(endTime, redactedExit(exit));
+        span.attribute = (key, value) => attribute(key, typeof value === "string" ? redactText(value) : value);
+        return span;
+    }
+})));
+/**
+ * Creates the OTLP logs, metrics, and traces layer with flows resource
+ * defaults, JSON-serialized. Exports share a four-request limit with no waiting
+ * queue. Requests larger than 1 MiB or stalled for ten seconds are discarded;
+ * `flows_observability_otlp_dropped` counts discarded batches, and at most
+ * once a minute a `Warn` record with code `otlp_export_discarded` names the
+ * reason, the request size, and the running total through the loggers that
+ * were installed when the layer was acquired, never through this exporter.
+ *
+ * **Details**
+ *
+ * The layer still requires an `HttpClient`, which is how it stays
+ * platform-neutral: a Node host may hand it `@effect/platform-node`'s Undici
+ * client (re-exported by `@smthrs/platform-node`), a browser or test
+ * hands it something else. Use {@link layerFetch} when the host's global
+ * `fetch` is good enough. On Node 26 and every browser it is.
+ * Fetch redirects are refused. Supply `FetchHttpClient.RequestInit` around
+ * the whole exporting effect to retain other fetch options; options scoped
+ * only to the supplied client's layer are replaced by the redirect policy.
+ * Other HTTP transports must independently refuse automatic redirects.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (options) => Layer.unwrap(Effect.map(Effect.all([
+    Resource.decode({
+        serviceName: options.serviceName ?? defaultServiceName,
+        serviceVersion: options.serviceVersion ?? defaultServiceVersion,
+        ...(options.attributes === undefined ? {} : { attributes: options.attributes })
+    }),
+    Endpoint.decode(options.baseUrl, "baseUrl").pipe(Effect.tap((baseUrl) => refusePlaintextCredentials(baseUrl, options.headers)))
+]), ([decoded, baseUrl]) => {
+    const resource = Resource.toOpenTelemetryConfiguration(decoded);
+    return (Otlp.layerJson({
+        baseUrl,
+        resource: {
+            serviceName: resource.serviceName,
+            // `serviceVersion` is supplied above before Resource decoding.
+            serviceVersion: resource.serviceVersion,
+            ...(resource.attributes === undefined ? {} : { attributes: resource.attributes })
+        },
+        headers: options.headers,
+        maxBatchSize,
+        loggerExportInterval: options.exportInterval,
+        metricsExportInterval: options.exportInterval,
+        tracerExportInterval: options.exportInterval,
+        shutdownTimeout: options.shutdownTimeout
+    }).pipe(Layer.provide(boundedClient), 
+    // Upstream merges OTEL_RESOURCE_ATTRIBUTES even with explicit
+    // options. Keep unvalidated ambient metadata out of every request.
+    Layer.provide(ConfigProvider.layer(ConfigProvider.fromUnknown({}))), (exporter) => Layer.provideMerge(redactedSpans, exporter)));
+}));
+/**
+ * Provides {@link layer} over the host's global `fetch`, the default wiring
+ * for a Node host, and browser-safe by construction because it never touches
+ * a `node:` built-in.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import * as Otlp from "@smthrs/observability/Otlp"
+ *
+ * const Telemetry = Otlp.layerFetch({ baseUrl: "http://localhost:4318" })
+ * ```
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerFetch = (options) => layer(options).pipe(Layer.provide(FetchHttpClient.layer));
+/**
+ * Parses `OTEL_EXPORTER_OTLP_HEADERS`: comma-separated `key=value` pairs whose
+ * values are percent-decoded, as the OpenTelemetry exporter specification
+ * defines. A pair without `=` or with an empty key is skipped.
+ *
+ * @category environment
+ * @since 1.0.0
+ */
+export const parseHeaders = (value) => {
+    const headers = {};
+    for (const pair of (value ?? "").split(",")) {
+        const separator = pair.indexOf("=");
+        const key = pair.slice(0, separator).trim();
+        if (separator < 0 || key === "")
+            continue;
+        const raw = pair.slice(separator + 1).trim();
+        let decoded = raw;
+        try {
+            decoded = decodeURIComponent(raw);
+        }
+        catch { /* A malformed escape is kept verbatim. */ }
+        headers[key] = decoded;
+    }
+    return headers;
+};
+/**
+ * {@link layerFetch} when the environment names a collector, otherwise
+ * {@link layerNoop}.
+ *
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` is the collector base URL and
+ * `OTEL_EXPORTER_OTLP_HEADERS` the headers sent with every export. An unset or
+ * empty endpoint installs no exporter at all.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerEnvironment = (environment, options = {}) => {
+    const endpoint = environment["OTEL_EXPORTER_OTLP_ENDPOINT"]?.trim();
+    if (endpoint === undefined || endpoint === "")
+        return layerNoop;
+    return layerFetch({ ...options, baseUrl: endpoint, headers: parseHeaders(environment["OTEL_EXPORTER_OTLP_HEADERS"]) });
+};
+/**
+ * Exports nothing. The explicit stand-in for hosts with no collector, such as
+ * a development shell, a test, or a browser deployment that has not opted in, so
+ * wiring code can switch layers rather than branch.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = Layer.empty;
+//# sourceMappingURL=Otlp.js.map

package/dist/esm/Otlp.js.map

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

package/dist/esm/Resource.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Explicit, validated OpenTelemetry resource metadata for Smithers.
+ *
+ * @since 0.1.0
+ */
+import * as OtelResource from "@effect/opentelemetry/Resource";
+import type { Attributes as OtelAttributes } from "@opentelemetry/api";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+/**
+ * Largest service-name or service-version field accepted by a resource.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumIdentityLength = 1024;
+/**
+ * Largest attribute key accepted by a resource.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumAttributeKeyLength = 1024;
+/**
+ * Largest string value accepted by one resource attribute.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumAttributeStringLength = 65536;
+/**
+ * Largest number of elements accepted in one array attribute value.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumAttributeArrayLength = 256;
+/**
+ * Largest number of attributes accepted by one resource.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumAttributes = 256;
+/**
+ * Largest OTLP/JSON encoding accepted for one whole resource, in UTF-8 bytes.
+ *
+ * The measure is the OTLP `Resource` message the exporters place in every
+ * request, `{"attributes":[{"key":…,"value":{…}}],"droppedAttributesCount":0}`
+ * with service identity and SDK-added `telemetry.sdk.name` and
+ * `telemetry.sdk.language` included, after JSON escaping and UTF-8 encoding.
+ * These SDK fields are conservatively reserved even for the default Effect
+ * exporter. Caller attributes overwritten by SDK identity or metadata are
+ * still counted. It is the bound the per-field limits cannot express: 256
+ * attributes at the string ceiling would encode to 16 MiB, and the resource
+ * rides in every export request, so the default transport, which discards a
+ * request over 1 MiB, would deliver nothing at all. 128 KiB admits one
+ * ASCII attribute at the string ceiling and leaves that transport 888 KiB of every
+ * request for the signal batch; see `Otlp.reservedBatchBytes`.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumResourceBytes = 131072;
+/**
+ * Runtime schema for one OpenTelemetry resource attribute value.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const AttributeValue: Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.$Array<Schema.String>, Schema.$Array<Schema.Number>, Schema.$Array<Schema.Boolean>]>;
+/**
+ * Runtime schema for OpenTelemetry resource attributes.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const Attributes: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.$Array<Schema.String>, Schema.$Array<Schema.Number>, Schema.$Array<Schema.Boolean>]>>;
+/**
+ * Runtime schema for the service identity attached to exported telemetry.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const Configuration: Schema.Struct<{
+    readonly serviceName: Schema.NonEmptyString;
+    readonly serviceVersion: Schema.optional<Schema.NonEmptyString>;
+    readonly attributes: Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.$Array<Schema.String>, Schema.$Array<Schema.Number>, Schema.$Array<Schema.Boolean>]>>>;
+}>;
+/**
+ * Configuration used to identify the service emitting telemetry.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Configuration = typeof Configuration.Type;
+declare const InvalidResourceConfiguration_base: Schema.Class<InvalidResourceConfiguration, Schema.TaggedStruct<"@smthrs/observability/InvalidResourceConfiguration", {
+    readonly code: Schema.Literal<"invalid_resource_configuration">;
+    readonly path: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Stable resource-configuration refusal shared by every OTEL layer.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ */
+export declare class InvalidResourceConfiguration extends InvalidResourceConfiguration_base {
+}
+/**
+ * Decodes one resource configuration without retaining rejected values.
+ *
+ * @category decoding
+ * @since 1.0.0-rc.0
+ */
+export declare const decode: (configuration: unknown) => Effect.Effect<Configuration, InvalidResourceConfiguration>;
+/**
+ * Decodes one resource configuration for the package's pure projection API.
+ *
+ * @category decoding
+ * @since 1.0.0-rc.0
+ */
+export declare const decodeSync: (configuration: unknown) => Configuration;
+/**
+ * Projects a decoded resource into the exact optional-property shape expected
+ * by the OpenTelemetry SDK.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export declare const toOpenTelemetryConfiguration: (configuration: Configuration) => {
+    readonly serviceName: string;
+    readonly serviceVersion?: string;
+    readonly attributes?: OtelAttributes;
+};
+/**
+ * Converts explicit service metadata into OpenTelemetry resource attributes.
+ *
+ * No environment variables are read. Invalid metadata throws the same typed
+ * {@link InvalidResourceConfiguration} every layer returns during acquisition.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export declare const configToAttributes: (configuration: Configuration) => OtelAttributes;
+/**
+ * Provides an explicitly validated OpenTelemetry resource.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layer: (configuration: Configuration) => Layer.Layer<OtelResource.Resource, InvalidResourceConfiguration>;
+/**
+ * The OpenTelemetry resource service.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export declare const Resource: typeof OtelResource.Resource;
+export {};
+//# sourceMappingURL=Resource.d.ts.map

package/dist/esm/Resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Resource.d.ts","sourceRoot":"","sources":["../../src/Resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,YAAY,MAAM,gCAAgC,CAAA;AAC9D,OAAO,KAAK,EAAE,UAAU,IAAI,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACtE,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAA;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,OAAQ,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,QAAS,CAAA;AAElD;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAEpC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,SAAU,CAAA;AAqB3C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,kKAgB1B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,iMAYtB,CAAA;AA0CD;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;EAqBzB,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;;;;;;AAErD;;;;;GAKG;AACH,qBAAa,4BAA6B,SAAQ,iCAOjD;CAAG;AAWJ;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GACjB,eAAe,OAAO,KACrB,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,4BAA4B,CAC6B,CAAA;AAEzF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,eAAe,OAAO,KAAG,aAMnD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GACvC,eAAe,aAAa,KAC3B;IACD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAA;CAcpC,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,eAAe,aAAa,KAAG,cACwB,CAAA;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAChB,eAAe,aAAa,KAC3B,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,4BAA4B,CAG/D,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,8BAAwB,CAAA"}