@kensio/yulin 1.21.0 → 1.21.1

package/dist/service/logs/metric/emf/sim-logs-embedded-metric-document.js

@@ -0,0 +1,85 @@
+import { embeddedMetricList, embeddedMetricNumber, embeddedMetricRecord, embeddedMetricString, } from "./sim-logs-embedded-metric-json.js";
+/**
+ * The property an Embedded Metric Format document carries its metadata under.
+ *
+ * A log event without it is an ordinary line, and the great majority of lines
+ * in a log group are. Looking for this before parsing anything is what keeps
+ * the check on the write path cheap.
+ */
+export const embeddedMetricMetadataKey = "_aws";
+/**
+ * Read a log event's message as an EMF document, or answer undefined.
+ *
+ * Anything that is not JSON, is not an object, or carries no usable `_aws`
+ * metadata is an ordinary log line. It is stored and left alone rather than
+ * refused, because a log group is full of lines that were never metrics.
+ */
+export function simLogsEmbeddedMetricDocument(message) {
+    if (!message.includes(embeddedMetricMetadataKey)) {
+        return undefined;
+    }
+    const parsed = parseObject(message);
+    const metadata = embeddedMetricRecord(parsed?.get(embeddedMetricMetadataKey));
+    if (parsed === undefined || metadata === undefined) {
+        return undefined;
+    }
+    const directives = embeddedMetricList(metadata.get("CloudWatchMetrics"), directiveOf);
+    return directives.length === 0
+        ? undefined
+        : {
+            timestamp: embeddedMetricNumber(metadata.get("Timestamp")),
+            directives,
+            values: parsed,
+        };
+}
+function parseObject(message) {
+    try {
+        return embeddedMetricRecord(JSON.parse(message));
+    }
+    catch {
+        return undefined;
+    }
+}
+function directiveOf(value) {
+    const entry = embeddedMetricRecord(value);
+    const namespace = embeddedMetricString(entry?.get("Namespace"));
+    if (entry === undefined || namespace === undefined) {
+        return undefined;
+    }
+    const dimensions = entry.get("Dimensions");
+    if (dimensions !== undefined && !Array.isArray(dimensions)) {
+        return undefined;
+    }
+    return {
+        namespace,
+        declaresDimensions: Array.isArray(dimensions) && dimensions.length > 0,
+        dimensionSets: embeddedMetricList(dimensions, dimensionSetOf),
+        metrics: embeddedMetricList(entry.get("Metrics"), metricOf),
+    };
+}
+/**
+ * One dimension set, or undefined where it is not a list of names.
+ *
+ * A member that is not a string takes the whole set with it. Keeping the ones
+ * that were strings would publish under a narrower identity than the document
+ * asked for, which is the same trouble as dropping a single dimension.
+ */
+function dimensionSetOf(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const names = value.map((name) => embeddedMetricString(name));
+    return names.every((name) => name !== undefined) ? names : undefined;
+}
+function metricOf(value) {
+    const entry = embeddedMetricRecord(value);
+    const name = embeddedMetricString(entry?.get("Name"));
+    if (entry === undefined || name === undefined) {
+        return undefined;
+    }
+    return {
+        name,
+        unit: embeddedMetricString(entry.get("Unit")),
+        storageResolution: embeddedMetricNumber(entry.get("StorageResolution")),
+    };
+}

package/dist/service/logs/metric/emf/sim-logs-embedded-metric-json.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The JSON readers an Embedded Metric Format document is taken apart with.
+ *
+ * A document is written by whatever produced the log line, so nothing about
+ * its shape can be assumed. Each of these answers undefined for a value that
+ * is not what the format calls for, and the caller decides whether that makes
+ * the document unreadable or just that one metric unpublishable.
+ */
+/**
+ * An object's own properties as a map, or undefined for anything else.
+ */
+export declare function embeddedMetricRecord(value: unknown): Map<string, unknown> | undefined;
+/**
+ * A string, or undefined for anything else.
+ */
+export declare function embeddedMetricString(value: unknown): string | undefined;
+/**
+ * A finite number, or undefined for anything else.
+ */
+export declare function embeddedMetricNumber(value: unknown): number | undefined;
+/**
+ * Read every entry of a list through a reader, dropping the unreadable ones.
+ */
+export declare function embeddedMetricList<T>(value: unknown, read: (entry: unknown) => T | undefined): readonly T[];

package/dist/service/logs/metric/emf/sim-logs-embedded-metric-json.js

@@ -0,0 +1,41 @@
+/**
+ * The JSON readers an Embedded Metric Format document is taken apart with.
+ *
+ * A document is written by whatever produced the log line, so nothing about
+ * its shape can be assumed. Each of these answers undefined for a value that
+ * is not what the format calls for, and the caller decides whether that makes
+ * the document unreadable or just that one metric unpublishable.
+ */
+/**
+ * An object's own properties as a map, or undefined for anything else.
+ */
+export function embeddedMetricRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? new Map(Object.entries(value))
+        : undefined;
+}
+/**
+ * A string, or undefined for anything else.
+ */
+export function embeddedMetricString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * A finite number, or undefined for anything else.
+ */
+export function embeddedMetricNumber(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : undefined;
+}
+/**
+ * Read every entry of a list through a reader, dropping the unreadable ones.
+ */
+export function embeddedMetricList(value, read) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((entry) => read(entry))
+        .filter((entry) => entry !== undefined);
+}

package/dist/service/logs/metric/emf/sim-logs-embedded-metric-values.d.ts

@@ -0,0 +1,20 @@
+import type { SimLogsMetricDimension } from "../sim-logs-metric-datapoint.js";
+import type { SimLogsEmbeddedMetricDeclaration, SimLogsEmbeddedMetricDocument } from "./sim-logs-embedded-metric-document.js";
+/**
+ * Why a metric an EMF document declared could not be published.
+ */
+export type SimLogsEmbeddedMetricRefusal = string;
+/**
+ * The values a metric declaration names, or the reason there are none.
+ *
+ * EMF carries a metric's value as a top-level property of the same document,
+ * either as one number or as a list of them.
+ */
+export declare function embeddedMetricValues(document: SimLogsEmbeddedMetricDocument, metric: SimLogsEmbeddedMetricDeclaration): readonly number[] | SimLogsEmbeddedMetricRefusal;
+/**
+ * One dimension set, or undefined where the document names a key it lacks.
+ *
+ * A dimension quietly dropped would put the datapoint under an identity no
+ * alarm is watching, so the whole set goes rather than part of it.
+ */
+export declare function embeddedMetricDimensions(document: SimLogsEmbeddedMetricDocument, keys: readonly string[]): readonly SimLogsMetricDimension[] | undefined;

package/dist/service/logs/metric/emf/sim-logs-embedded-metric-values.js

@@ -0,0 +1,39 @@
+/**
+ * The resolution real CloudWatch reads as a high resolution metric.
+ */
+const highStorageResolution = 1;
+/**
+ * The values a metric declaration names, or the reason there are none.
+ *
+ * EMF carries a metric's value as a top-level property of the same document,
+ * either as one number or as a list of them.
+ */
+export function embeddedMetricValues(document, metric) {
+    if (metric.storageResolution === highStorageResolution) {
+        return ("StorageResolution 1 asks for a high resolution metric, and every " +
+            "period in this simulated CloudWatch is a whole number of minutes.");
+    }
+    const raw = document.values.get(metric.name);
+    const values = (Array.isArray(raw) ? raw : [raw]).filter((value) => typeof value === "number" && Number.isFinite(value));
+    return values.length === 0
+        ? `The document declares ${metric.name} and carries no number under that ` +
+            `name, so there is no value to publish.`
+        : values;
+}
+/**
+ * One dimension set, or undefined where the document names a key it lacks.
+ *
+ * A dimension quietly dropped would put the datapoint under an identity no
+ * alarm is watching, so the whole set goes rather than part of it.
+ */
+export function embeddedMetricDimensions(document, keys) {
+    const dimensions = [];
+    for (const name of keys) {
+        const value = document.values.get(name);
+        if (typeof value !== "string") {
+            return undefined;
+        }
+        dimensions.push({ name, value });
+    }
+    return dimensions;
+}

package/dist/service/logs/metric/sim-logs-metric-datapoint.d.ts

@@ -0,0 +1,25 @@
+/**
+ * One dimension on a metric a metric filter publishes.
+ */
+export interface SimLogsMetricDimension {
+    readonly name: string;
+    readonly value: string;
+}
+/**
+ * One metric datapoint a metric filter's transformation produced from a log
+ * event.
+ *
+ * This is what simulated CloudWatch Logs hands to simulated CloudWatch. The
+ * timestamp is the instant CloudWatch Logs took the event, rather than the
+ * instant the datapoint reaches the metric store. Publication happens on the
+ * background scheduler, so a clock that moved in between would otherwise put
+ * the datapoint in a later period than the log line it counts.
+ */
+export interface SimLogsMetricDatapoint {
+    readonly namespace: string;
+    readonly metricName: string;
+    readonly value: number;
+    readonly timestamp: number;
+    readonly unit: string | undefined;
+    readonly dimensions: readonly SimLogsMetricDimension[];
+}

package/dist/service/logs/metric/sim-logs-metric-datapoint.js

@@ -0,0 +1 @@
+export {};

package/dist/service/logs/metric/sim-logs-metric-fan-out.d.ts

@@ -0,0 +1,62 @@
+import type { BackgroundScheduler } from "../../../util/background/background.js";
+import type { SimLogsStoredEvent } from "../event/sim-logs-event.js";
+import type { SimLogsLogGroup } from "../group/sim-logs-log-group.js";
+import { type SimLogsMetricPublicationFailure } from "./sim-logs-metric-publication-failure.js";
+import type { SimLogsMetricPublications } from "./sim-logs-metric-publications.js";
+interface SimLogsMetricFanOutProperties {
+    readonly publications: SimLogsMetricPublications | undefined;
+    readonly background: BackgroundScheduler;
+}
+/**
+ * Turns events written to a log group into metric datapoints.
+ *
+ * Two things ask for them. A metric filter on the group counts the events it
+ * matches, and an event that is itself an Embedded Metric Format document
+ * carries its own. Real CloudWatch reads both without being asked.
+ *
+ * Publication happens on the background scheduler, for the reason subscription
+ * delivery does. Real CloudWatch Logs answers `PutLogEvents` whether or not
+ * the metric took the datapoint, and a metric that cannot be written must not
+ * fail the write that produced it. `simAws.backgroundTasksComplete()` is what
+ * waits for it.
+ */
+export declare class SimLogsMetricFanOut {
+    #private;
+    constructor(properties: SimLogsMetricFanOutProperties);
+    /**
+     * Every publication this scope could not make.
+     *
+     * A failed publication is invisible in an account, where it becomes a metric
+     * nobody is watching. Keeping it is what lets a test find out that the
+     * metrics it set up never wrote anything.
+     */
+    get failures(): readonly SimLogsMetricPublicationFailure[];
+    /**
+     * Check a metric filter could publish at all, before one is put.
+     *
+     * A simulated CloudWatch Logs built on its own has no CloudWatch to write
+     * into, and a filter that accepts its configuration and publishes nothing is
+     * the hardest kind of thing to find.
+     */
+    checkPublishable(): void;
+    /**
+     * Schedule the datapoints a batch of events produced.
+     *
+     * A whole batch goes to each metric filter at once, because a filter
+     * aggregates its default value over a period rather than over one event. An
+     * embedded document is read one event at a time, because each carries its
+     * own metrics and its own timestamp.
+     *
+     * A CloudWatch Logs with nowhere to publish reads nothing. It can hold no
+     * metric filter, and a Powertools log line written to one is an ordinary log
+     * line rather than a failure worth recording.
+     */
+    written(group: SimLogsLogGroup, events: readonly SimLogsStoredEvent[]): void;
+    /**
+     * Schedule the datapoints the events carried as EMF documents.
+     */
+    private writtenEmbedded;
+    private schedule;
+    private recordFailure;
+}
+export {};

package/dist/service/logs/metric/sim-logs-metric-fan-out.js

@@ -0,0 +1,116 @@
+import { SimLogsUnsupportedOperationException } from "../error/sim-logs.error.js";
+import { simLogsEmbeddedMetricReading } from "./emf/sim-logs-embedded-metric-datapoints.js";
+import { metricFilterSource, simLogsEmbeddedMetricSource, } from "./sim-logs-metric-publication-failure.js";
+/**
+ * Turns events written to a log group into metric datapoints.
+ *
+ * Two things ask for them. A metric filter on the group counts the events it
+ * matches, and an event that is itself an Embedded Metric Format document
+ * carries its own. Real CloudWatch reads both without being asked.
+ *
+ * Publication happens on the background scheduler, for the reason subscription
+ * delivery does. Real CloudWatch Logs answers `PutLogEvents` whether or not
+ * the metric took the datapoint, and a metric that cannot be written must not
+ * fail the write that produced it. `simAws.backgroundTasksComplete()` is what
+ * waits for it.
+ */
+export class SimLogsMetricFanOut {
+    #publications;
+    #background;
+    #failures = [];
+    constructor(properties) {
+        this.#publications = properties.publications;
+        this.#background = properties.background;
+    }
+    /**
+     * Every publication this scope could not make.
+     *
+     * A failed publication is invisible in an account, where it becomes a metric
+     * nobody is watching. Keeping it is what lets a test find out that the
+     * metrics it set up never wrote anything.
+     */
+    get failures() {
+        return this.#failures;
+    }
+    /**
+     * Check a metric filter could publish at all, before one is put.
+     *
+     * A simulated CloudWatch Logs built on its own has no CloudWatch to write
+     * into, and a filter that accepts its configuration and publishes nothing is
+     * the hardest kind of thing to find.
+     */
+    checkPublishable() {
+        if (this.#publications === undefined) {
+            throw new SimLogsUnsupportedOperationException("This simulated CloudWatch Logs has no simulated CloudWatch to " +
+                "publish a metric filter's datapoints into. Reach CloudWatch Logs " +
+                "through a SimAws Account Region scope for a metric filter to " +
+                "publish.");
+        }
+    }
+    /**
+     * Schedule the datapoints a batch of events produced.
+     *
+     * A whole batch goes to each metric filter at once, because a filter
+     * aggregates its default value over a period rather than over one event. An
+     * embedded document is read one event at a time, because each carries its
+     * own metrics and its own timestamp.
+     *
+     * A CloudWatch Logs with nowhere to publish reads nothing. It can hold no
+     * metric filter, and a Powertools log line written to one is an ordinary log
+     * line rather than a failure worth recording.
+     */
+    written(group, events) {
+        if (this.#publications === undefined) {
+            return;
+        }
+        for (const filter of group.metricFilters.all) {
+            const datapoints = filter.datapoints(events);
+            if (datapoints.length > 0) {
+                this.schedule(group.logGroupName, metricFilterSource(filter.filterName), datapoints);
+            }
+        }
+        this.writtenEmbedded(group.logGroupName, events);
+    }
+    /**
+     * Schedule the datapoints the events carried as EMF documents.
+     */
+    writtenEmbedded(logGroupName, events) {
+        const datapoints = [];
+        for (const event of events) {
+            const reading = simLogsEmbeddedMetricReading(event.message, event.ingestionTime);
+            datapoints.push(...reading.datapoints);
+            for (const skip of reading.skipped) {
+                this.#failures.push({
+                    logGroupName,
+                    source: simLogsEmbeddedMetricSource,
+                    ...skip,
+                });
+            }
+        }
+        if (datapoints.length > 0) {
+            this.schedule(logGroupName, simLogsEmbeddedMetricSource, datapoints);
+        }
+    }
+    schedule(logGroupName, source, datapoints) {
+        this.#background.schedule(async () => {
+            try {
+                await this.#publications?.publish(datapoints);
+            }
+            catch (error) {
+                this.recordFailure(logGroupName, source, datapoints, error);
+            }
+        });
+    }
+    recordFailure(logGroupName, source, datapoints, error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        for (const datapoint of datapoints) {
+            this.#failures.push({
+                logGroupName,
+                source,
+                metricNamespace: datapoint.namespace,
+                metricName: datapoint.metricName,
+                reason,
+            });
+        }
+    }
+}

package/dist/service/logs/metric/sim-logs-metric-filter-selection.d.ts

@@ -0,0 +1,17 @@
+import type { SimLogsMetricFilter } from "./sim-logs-metric-filter.js";
+/**
+ * What a DescribeMetricFilters request is selecting on, beyond the log group.
+ */
+export interface SimLogsMetricFilterSelection {
+    readonly filterNamePrefix?: string | undefined;
+    readonly metricName?: string | undefined;
+    readonly metricNamespace?: string | undefined;
+}
+/**
+ * The filters a request selects, by name prefix and by the metric they write.
+ *
+ * Selecting on the metric is what makes a request naming no log group useful.
+ * It is how a caller finds every filter writing to a metric it has an alarm
+ * on, wherever in the account those filters were put.
+ */
+export declare function simLogsSelectedMetricFilters(filters: readonly SimLogsMetricFilter[], selection: SimLogsMetricFilterSelection): readonly SimLogsMetricFilter[];

package/dist/service/logs/metric/sim-logs-metric-filter-selection.js

@@ -0,0 +1,17 @@
+/**
+ * The filters a request selects, by name prefix and by the metric they write.
+ *
+ * Selecting on the metric is what makes a request naming no log group useful.
+ * It is how a caller finds every filter writing to a metric it has an alarm
+ * on, wherever in the account those filters were put.
+ */
+export function simLogsSelectedMetricFilters(filters, selection) {
+    return filters.filter((filter) => filter.filterName.startsWith(selection.filterNamePrefix ?? "") &&
+        writesTheMetric(filter, selection));
+}
+function writesTheMetric(filter, selection) {
+    return filter.transformations.some((transformation) => (selection.metricNamespace === undefined ||
+        transformation.metricNamespace === selection.metricNamespace) &&
+        (selection.metricName === undefined ||
+            transformation.metricName === selection.metricName));
+}

package/dist/service/logs/metric/sim-logs-metric-filter-store.d.ts

@@ -0,0 +1,35 @@
+import type { SimLogsMetricFilter } from "./sim-logs-metric-filter.js";
+/**
+ * The metric filters on one log group.
+ *
+ * They belong to the group the way its subscription filters and its streams
+ * do. A metric filter has no identity outside the group it watches, and
+ * deleting the group takes its filters with it.
+ */
+export declare class SimLogsMetricFilterStore {
+    #private;
+    /**
+     * Every filter on this group, in the order they were put.
+     */
+    get all(): readonly SimLogsMetricFilter[];
+    /**
+     * How many filters this group has, which is what `DescribeLogGroups` reports
+     * as `metricFilterCount`.
+     */
+    get count(): number;
+    /**
+     * Find a filter on this group by name.
+     */
+    find(filterName: string): SimLogsMetricFilter | undefined;
+    /**
+     * Put a filter, replacing one of the same name.
+     *
+     * Putting a filter already there by name is an update rather than a second
+     * filter, which is what makes `PutMetricFilter` the way to change a pattern.
+     */
+    put(filter: SimLogsMetricFilter): void;
+    /**
+     * Remove a filter by name, refusing one that was never there.
+     */
+    delete(filterName: string): void;
+}

package/dist/service/logs/metric/sim-logs-metric-filter-store.js

@@ -0,0 +1,47 @@
+import { SimLogsResourceNotFoundException } from "../error/sim-logs.error.js";
+/**
+ * The metric filters on one log group.
+ *
+ * They belong to the group the way its subscription filters and its streams
+ * do. A metric filter has no identity outside the group it watches, and
+ * deleting the group takes its filters with it.
+ */
+export class SimLogsMetricFilterStore {
+    #filters = new Map();
+    /**
+     * Every filter on this group, in the order they were put.
+     */
+    get all() {
+        return this.#filters.values().toArray();
+    }
+    /**
+     * How many filters this group has, which is what `DescribeLogGroups` reports
+     * as `metricFilterCount`.
+     */
+    get count() {
+        return this.#filters.size;
+    }
+    /**
+     * Find a filter on this group by name.
+     */
+    find(filterName) {
+        return this.#filters.get(filterName);
+    }
+    /**
+     * Put a filter, replacing one of the same name.
+     *
+     * Putting a filter already there by name is an update rather than a second
+     * filter, which is what makes `PutMetricFilter` the way to change a pattern.
+     */
+    put(filter) {
+        this.#filters.set(filter.filterName, filter);
+    }
+    /**
+     * Remove a filter by name, refusing one that was never there.
+     */
+    delete(filterName) {
+        if (!this.#filters.delete(filterName)) {
+            throw new SimLogsResourceNotFoundException("The specified metric filter does not exist.");
+        }
+    }
+}

package/dist/service/logs/metric/sim-logs-metric-filter.d.ts

@@ -0,0 +1,49 @@
+import type { SimLogsStoredEvent } from "../event/sim-logs-event.js";
+import type { SimLogsMetricDatapoint } from "./sim-logs-metric-datapoint.js";
+import type { SimLogsMetricTransformation } from "./sim-logs-metric-transformation.js";
+interface SimLogsMetricFilterProperties {
+    readonly filterName: string;
+    readonly logGroupName: string;
+    readonly filterPattern: string | undefined;
+    readonly transformations: readonly SimLogsMetricTransformation[];
+    readonly creationTime: number;
+}
+/**
+ * One metric filter on a log group.
+ *
+ * The pattern is compiled once, when the filter is put, the way a subscription
+ * filter's is. A pattern this simulator cannot read is refused there rather
+ * than on the first event that happens to arrive.
+ */
+export declare class SimLogsMetricFilter {
+    #private;
+    readonly filterName: string;
+    readonly logGroupName: string;
+    readonly filterPatternText: string;
+    readonly transformations: readonly SimLogsMetricTransformation[];
+    readonly creationTime: number;
+    constructor(properties: SimLogsMetricFilterProperties);
+    /**
+     * Whether this filter matches an event's message.
+     */
+    matches(message: string): boolean;
+    /**
+     * The datapoints a batch of log events publishes through this filter.
+     *
+     * A matching event publishes one datapoint per transformation, stamped with
+     * the instant CloudWatch Logs took it.
+     *
+     * A default value is published once for a period that took events and
+     * matched none of them, rather than once per event that missed. That is what
+     * real CloudWatch Logs reports: a minute with two records and one match
+     * counts one, and a minute with two records and no match reports the default
+     * once. Publishing per event would inflate `SampleCount` and change what an
+     * alarm over the metric decides.
+     */
+    datapoints(events: readonly SimLogsStoredEvent[]): readonly SimLogsMetricDatapoint[];
+    /**
+     * What one period of events publishes.
+     */
+    private periodDatapoints;
+}
+export {};