@logbrew/sdk 0.1.37 → 0.1.39

package/retry-delay.cjs

@@ -0,0 +1,32 @@
+const MAX_DELIVERY_INTERVAL_MS = 60_000;
+const MIN_RATE_LIMIT_WAIT_MS = 1000;
+const MAX_RATE_LIMIT_WAIT_MS = 3_600_000;
+const MAX_BACKOFF_EXPONENT = 30;
+const FIRST_FAILURE = 1;
+const BACKOFF_BASE = 2;
+const HALF = 2;
+const INCLUSIVE = 1;
+const JITTER_DIVISOR = 10;
+
+/**
+ * @param {number} deliveryIntervalMs
+ * @param {number} consecutiveFailures
+ * @returns {number}
+ */
+function automaticRetryDelayMs(deliveryIntervalMs, consecutiveFailures) {
+  const exponent = Math.min(consecutiveFailures - FIRST_FAILURE, MAX_BACKOFF_EXPONENT);
+  const maximumDelay = Math.min(MAX_DELIVERY_INTERVAL_MS, deliveryIntervalMs * (BACKOFF_BASE ** exponent));
+  const minimumDelay = Math.ceil(maximumDelay / HALF);
+  return minimumDelay + Math.floor(Math.random() * (maximumDelay - minimumDelay + INCLUSIVE));
+}
+
+/**
+ * @param {number} delayMs
+ * @returns {number}
+ */
+function rateLimitWaitMs(delayMs) {
+  const bounded = Math.min(MAX_RATE_LIMIT_WAIT_MS, Math.max(MIN_RATE_LIMIT_WAIT_MS, delayMs));
+  return Math.min(MAX_RATE_LIMIT_WAIT_MS, bounded + Math.floor(Math.random() * (Math.floor(bounded / JITTER_DIVISOR) + INCLUSIVE)));
+}
+
+module.exports = { MAX_DELIVERY_INTERVAL_MS, automaticRetryDelayMs, rateLimitWaitMs };

package/sdk-error.cjs

@@ -0,0 +1,36 @@
+const MIN_RETRY_AFTER_MS = 0;
+
+/**
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function retryAfterMsOrUndefined(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= MIN_RETRY_AFTER_MS ? value : undefined;
+}
+
+class SdkError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   * @param {Readonly<{ retryAfterMs?: unknown, retryable?: unknown }> | null} [details]
+   */
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "SdkError";
+    this.code = code;
+    const retryAfterMs = retryAfterMsOrUndefined(details?.retryAfterMs);
+    if (retryAfterMs !== undefined) {
+      /** @type {number | undefined} */
+      this.retryAfterMs = retryAfterMs;
+    }
+    if (details?.retryable === true) {
+      /** @type {boolean | undefined} */
+      this.retryable = true;
+    }
+  }
+}
+
+module.exports = { SdkError, retryAfterMsOrUndefined };

package/span-validation.cjs

@@ -0,0 +1,191 @@
+const { withMetadata } = require("./event-metadata.cjs");
+const { compactMetadata } = require("./log-context.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { parseTraceparent } = require("./trace-context.cjs");
+const {
+  isRecord,
+  optionalEntry,
+  requireAllowedValue,
+  requireNonEmpty,
+  requireSpanId,
+  requireTimestamp,
+  requireTraceId
+} = require("./validation.cjs");
+
+/**
+ * @import { Metadata, SpanAttributes, SpanEventSummary, SpanLinkSummary } from "./index.cjs"
+ * @import { EventAttributes } from "./event-validation.cjs"
+ */
+
+const MAX_SPAN_EVENTS = 8;
+const MAX_SPAN_LINKS = 8;
+const NO_ENTRIES = 0;
+const MIN_DURATION_MS = 0;
+/** @type {ReadonlySet<SpanAttributes["status"]>} */
+const SPAN_STATUSES = new Set(["ok", "error"]);
+
+/**
+ * @param {unknown} metadata
+ * @returns {Metadata | undefined}
+ */
+function nonEmptyMetadata(metadata) {
+  if (metadata === undefined) {
+    return undefined;
+  }
+  const compacted = compactMetadata(metadata);
+  return Object.keys(compacted).length > NO_ENTRIES ? compacted : undefined;
+}
+
+/**
+ * @param {unknown} durationMs
+ * @returns {number | undefined}
+ */
+function optionalSpanDuration(durationMs) {
+  if (durationMs === undefined) {
+    return undefined;
+  }
+  if (typeof durationMs !== "number" || Number.isNaN(durationMs) || durationMs < MIN_DURATION_MS) {
+    throw new SdkError("validation_error", "span durationMs must be non-negative");
+  }
+  return durationMs;
+}
+
+/**
+ * @param {unknown} list
+ * @param {string} label
+ * @param {number} maxEntries
+ * @returns {readonly unknown[] | undefined}
+ */
+function optionalBoundedList(list, label, maxEntries) {
+  if (list === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(list)) {
+    throw new SdkError("validation_error", `${label} must be an array`);
+  }
+  if (list.length > maxEntries) {
+    throw new SdkError("validation_error", `${label} must contain at most ${maxEntries} entries`);
+  }
+  return list.length === NO_ENTRIES ? undefined : list;
+}
+
+/**
+ * @param {unknown} event
+ * @returns {SpanEventSummary}
+ */
+function validateSpanEvent(event) {
+  if (!isRecord(event)) {
+    throw new SdkError("validation_error", "span event must be an object");
+  }
+  const name = requireNonEmpty("span event name", event["name"]);
+  const timestamp = event["timestamp"] === undefined ? undefined : requireTimestamp(event["timestamp"]);
+  return {
+    name,
+    ...optionalEntry("timestamp", timestamp),
+    ...optionalEntry("metadata", nonEmptyMetadata(event["metadata"]))
+  };
+}
+
+/**
+ * @param {unknown} events
+ * @returns {SpanEventSummary[] | undefined}
+ */
+function validateSpanEvents(events) {
+  return optionalBoundedList(events, "span events", MAX_SPAN_EVENTS)?.map((event) => validateSpanEvent(event));
+}
+
+/**
+ * @param {unknown} link
+ * @returns {SpanLinkSummary}
+ */
+function validateSpanLink(link) {
+  if (!isRecord(link)) {
+    throw new SdkError("validation_error", "span link must be an object");
+  }
+  const traceId = requireTraceId(link["traceId"]);
+  const spanId = requireSpanId("span link spanId", link["spanId"]);
+  const { sampled } = link;
+  if (sampled !== undefined && typeof sampled !== "boolean") {
+    throw new SdkError("validation_error", "span link sampled must be a boolean");
+  }
+  return {
+    traceId: traceId.toLowerCase(),
+
+    spanId: spanId.toLowerCase(),
+    ...optionalEntry("sampled", sampled),
+    ...optionalEntry("metadata", nonEmptyMetadata(link["metadata"]))
+  };
+}
+
+/**
+ * @param {unknown} links
+ * @returns {SpanLinkSummary[] | undefined}
+ */
+function validateSpanLinks(links) {
+  return optionalBoundedList(links, "span links", MAX_SPAN_LINKS)?.map((link) => validateSpanLink(link));
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} attributes
+ * @returns {EventAttributes}
+ */
+function validateSpan(attributes) {
+  const name = requireNonEmpty("span name", attributes["name"]);
+  const traceId = requireNonEmpty("span traceId", attributes["traceId"]);
+  const spanId = requireNonEmpty("span spanId", attributes["spanId"]);
+  const status = requireAllowedValue("span status", attributes["status"], SPAN_STATUSES);
+  const parentSpanId = attributes["parentSpanId"] === undefined
+    ? undefined
+    : requireNonEmpty("span parentSpanId", attributes["parentSpanId"]);
+  const durationMs = optionalSpanDuration(attributes["durationMs"]);
+  const events = validateSpanEvents(attributes["events"]);
+  const links = validateSpanLinks(attributes["links"]);
+  return withMetadata({
+    name,
+
+    traceId,
+
+    spanId,
+
+    status,
+    ...optionalEntry("parentSpanId", parentSpanId),
+    ...optionalEntry("durationMs", durationMs),
+    ...optionalEntry("events", events),
+    ...optionalEntry("links", links)
+  }, attributes["metadata"], attributes["context"]);
+}
+
+/**
+ * @param {unknown} traceparent
+ * @param {unknown} attributes
+ * @returns {SpanAttributes}
+ */
+function spanAttributesFromTraceparent(traceparent, attributes) {
+  if (!isRecord(attributes)) {
+    throw new SdkError("validation_error", "span attributes must be an object");
+  }
+  const context = parseTraceparent(traceparent);
+  const name = requireNonEmpty("span name", attributes["name"]);
+  const spanId = requireSpanId("spanId", attributes["spanId"]);
+  const status = requireAllowedValue("span status", attributes["status"], SPAN_STATUSES);
+  const durationMs = optionalSpanDuration(attributes["durationMs"]);
+  const events = validateSpanEvents(attributes["events"]);
+  const links = validateSpanLinks(attributes["links"]);
+  return {
+    name,
+
+    traceId: context.traceId,
+
+    spanId: spanId.toLowerCase(),
+
+    parentSpanId: context.parentSpanId,
+
+    status,
+    ...optionalEntry("durationMs", durationMs),
+    ...optionalEntry("events", events),
+    ...optionalEntry("links", links),
+    ...optionalEntry("metadata", attributes["metadata"] === undefined ? undefined : compactMetadata(attributes["metadata"]))
+  };
+}
+
+module.exports = { spanAttributesFromTraceparent, validateSpan };

package/stored-events.cjs

@@ -0,0 +1,243 @@
+const { isObjectLike } = require("./error-details.cjs");
+const { cloneEvent } = require("./event-clone.cjs");
+const { EVENT_VALIDATORS, isEventType } = require("./event-validation.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { utf8ByteLength } = require("./utf8.cjs");
+const { isRecord, requireNonEmpty, requireTimestamp } = require("./validation.cjs");
+
+/**
+ * @import { EventType, EventValidator, SdkEvent } from "./event-validation.cjs"
+ * @import { DeepReadonly } from "./validation.cjs"
+ * @typedef {{ event: DeepReadonly<SdkEvent>, eventBytes: number, serializedEvent: string }} StoredRecord
+ * @typedef {Readonly<Record<string, unknown>>} UnknownRecord
+ * @typedef {{
+ *   attributes: UnknownRecord,
+ *   event: UnknownRecord,
+ *   eventBytes: number,
+ *   header: { type: EventType, id: string, timestamp: string },
+ *   serializedEvent: string,
+ *   validator: EventValidator
+ * }} RecordParts
+ */
+
+const MIN_EVENT_BYTES = 0;
+const CONTEXT_SCHEMA_VERSION = 1;
+const KEY_INDEX = 0;
+const STEP = 1;
+
+/**
+ * @returns {InstanceType<typeof SdkError>}
+ */
+function invalidStoredRecord() {
+  return new SdkError("persistence_error", "event store returned an invalid record");
+}
+
+/**
+ * @param {string} operation
+ * @param {unknown} result
+ * @returns {unknown}
+ */
+function requireSynchronousStoreResult(operation, result) {
+  if (isObjectLike(result) && typeof Reflect.get(result, "then") === "function") {
+    throw new SdkError("persistence_error", `eventStore.${operation} must complete synchronously`);
+  }
+  return result;
+}
+
+/**
+ * @param {readonly [string, unknown]} left
+ * @param {readonly [string, unknown]} right
+ * @returns {number}
+ */
+function byKey(left, right) {
+  return left[KEY_INDEX].localeCompare(right[KEY_INDEX]);
+}
+
+/**
+ * @param {string} _key
+ * @param {unknown} entry
+ * @returns {unknown}
+ */
+function sortedEntries(_key, entry) {
+  if (!isRecord(entry)) {
+    return entry;
+  }
+  const entries = Object.entries(entry);
+  entries.sort(byKey);
+  return Object.fromEntries(entries);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function structuralJson(value) {
+  return JSON.stringify(value, sortedEntries);
+}
+
+/**
+ * @param {UnknownRecord} event
+ * @param {UnknownRecord} attributes
+ * @returns {{ event: UnknownRecord, attributes: UnknownRecord }}
+ */
+function recoveredEvent(event, attributes) {
+  const fatalAttributes = event["type"] === "issue" && attributes["level"] === "fatal"
+    ? { ...attributes, level: "critical" }
+    : attributes;
+  const { context } = fatalAttributes;
+  const recoveredAttributes = isRecord(context) && context["schemaVersion"] === undefined
+    ? { ...fatalAttributes, context: { schemaVersion: CONTEXT_SCHEMA_VERSION, ...context } }
+    : fatalAttributes;
+  return { attributes: recoveredAttributes, event: { ...event, attributes: recoveredAttributes } };
+}
+
+/**
+ * @param {unknown} eventBytes
+ * @param {unknown} serializedEvent
+ * @returns {Readonly<{ eventBytes: number, serializedEvent: string }>}
+ */
+function storedPayload(eventBytes, serializedEvent) {
+  if (typeof eventBytes !== "number" || !Number.isSafeInteger(eventBytes) || eventBytes <= MIN_EVENT_BYTES || typeof serializedEvent !== "string") {
+    throw invalidStoredRecord();
+  }
+  return { eventBytes, serializedEvent };
+}
+
+/**
+ * @param {UnknownRecord} event
+ * @param {Readonly<{ eventBytes: number, serializedEvent: string }>} payload
+ * @returns {RecordParts}
+ */
+function storedEventParts(event, payload) {
+  const { type } = event;
+  const validator = isEventType(type) ? EVENT_VALIDATORS.get(type) : undefined;
+  if (!isEventType(type) || validator === undefined) {
+    throw invalidStoredRecord();
+  }
+  const header = {
+    type,
+
+    id: requireNonEmpty("event id", event["id"]),
+
+    timestamp: requireTimestamp(event["timestamp"])
+  };
+  const { attributes } = event;
+  if (!isRecord(attributes)) {
+    throw invalidStoredRecord();
+  }
+  return { ...payload, attributes, event, header, validator };
+}
+
+/**
+ * @param {UnknownRecord} record
+ * @returns {RecordParts}
+ */
+function storedRecordParts(record) {
+  const { event, eventBytes, serializedEvent } = record;
+  if (!isRecord(event)) {
+    throw invalidStoredRecord();
+  }
+  return storedEventParts(event, storedPayload(eventBytes, serializedEvent));
+}
+
+/**
+ * @param {Readonly<RecordParts["header"]>} header
+ * @param {Readonly<{ event: UnknownRecord, attributes: UnknownRecord }>} recovered
+ * @param {EventValidator} validator
+ * @returns {StoredRecord}
+ */
+function normalizedRecord(header, recovered, validator) {
+  /** @type {SdkEvent} */
+  const normalizedEvent = { ...header, attributes: validator(recovered.attributes) };
+  const normalizedSerializedEvent = JSON.stringify(normalizedEvent);
+  if (structuralJson(normalizedEvent) !== structuralJson(recovered.event)) {
+    throw invalidStoredRecord();
+  }
+  return {
+    event: cloneEvent(normalizedEvent),
+    eventBytes: utf8ByteLength(normalizedSerializedEvent),
+    serializedEvent: normalizedSerializedEvent
+  };
+}
+
+/**
+ * @param {unknown} record
+ * @returns {StoredRecord}
+ */
+function normalizeRecord(record) {
+  if (!isRecord(record)) {
+    throw invalidStoredRecord();
+  }
+  const { attributes, event, eventBytes, header, serializedEvent, validator } = storedRecordParts(record);
+  if (JSON.stringify(event) !== serializedEvent || utf8ByteLength(serializedEvent) !== eventBytes) {
+    throw invalidStoredRecord();
+  }
+  return normalizedRecord(header, recoveredEvent(event, attributes), validator);
+}
+
+/**
+ * @param {unknown} record
+ * @returns {StoredRecord}
+ */
+function normalizeStoredRecord(record) {
+  try {
+    return normalizeRecord(record);
+  } catch (error) {
+    if (error instanceof SdkError && error.code === "persistence_error") {
+      throw error;
+    }
+    throw invalidStoredRecord();
+  }
+}
+
+/**
+ * @param {string} serializedEvent
+ * @returns {unknown}
+ */
+function parseStoredEvent(serializedEvent) {
+  try {
+    /** @type {unknown} */
+    const event = JSON.parse(serializedEvent);
+    return event;
+  } catch {
+    throw invalidStoredRecord();
+  }
+}
+
+/**
+ * @param {unknown} serializedEvent
+ * @returns {DeepReadonly<SdkEvent>}
+ */
+function restoreStoredEvent(serializedEvent) {
+  if (typeof serializedEvent !== "string" || serializedEvent === "") {
+    throw invalidStoredRecord();
+  }
+  return normalizeStoredRecord({
+    event: parseStoredEvent(serializedEvent),
+    eventBytes: utf8ByteLength(serializedEvent),
+    serializedEvent
+  }).event;
+}
+
+/**
+ * @param {readonly string[]} expected
+ * @param {readonly string[]} actual
+ * @returns {boolean}
+ */
+function isOrderedSubsequence(expected, actual) {
+  let index = 0;
+  for (const value of actual) {
+    if (value === expected[index]) {
+      index += STEP;
+    }
+  }
+  return index === expected.length;
+}
+
+module.exports = {
+  invalidStoredRecord,
+  isOrderedSubsequence,
+  normalizeStoredRecord,
+  requireSynchronousStoreResult,
+  restoreStoredEvent
+};