@logbrew/sdk 0.1.37 → 0.1.39

package/client-options.cjs

@@ -0,0 +1,292 @@
+const { isClientReportStore, validateEventStore } = require("./event-store.cjs");
+const { MAX_DELIVERY_INTERVAL_MS } = require("./retry-delay.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { cloneTelemetryContext, validateTelemetryContext } = require("./telemetry-context.cjs");
+const { isCallable, isRecord, requireNonEmpty, requireNonNegativeInteger, requirePositiveInteger } = require("./validation.cjs");
+
+/**
+ * @import { Callable, DeepReadonly } from "./validation.cjs"
+ * @import { BatchTransport } from "./batch-sender.cjs"
+ * @import { ClientReportStore, EventStore } from "./event-store.cjs"
+ * @import { TelemetryContext } from "./index.cjs"
+ * @typedef {Readonly<Record<PropertyKey, unknown>>} ClientOptions
+ * @typedef {Readonly<{
+ *   apiKey: string,
+ *   automaticDelivery: boolean,
+ *   deliveryIntervalMs: number,
+ *   deliveryQueueThreshold: number,
+ *   eventStore: EventStore | undefined,
+ *   eventQueueFactory: Callable | undefined,
+ *   clientReportStore: ClientReportStore | undefined,
+ *   eventFilter: Callable | undefined,
+ *   maxBatchBytes: number,
+ *   maxBatchEvents: number,
+ *   maxQueueBytes: number,
+ *   maxQueueSize: number,
+ *   onEventDropped: Callable | undefined,
+ *   context: DeepReadonly<TelemetryContext> | undefined,
+ *   contextProvider: Callable | undefined,
+ *   breadcrumbProvider: Callable | undefined,
+ *   sdk: Readonly<{ name: string, language: string, version: string }>,
+ *   maxRetries: number,
+ *   transport: BatchTransport | undefined
+ * }>} ClientConfig
+ * @typedef {Omit<ClientConfig, "clientReportStore" | "context" | "eventQueueFactory" | "eventStore"> & {
+ *   context: TelemetryContext | undefined
+ * }} ClientSettings
+ */
+
+const EVENT_QUEUE_FACTORY = Symbol.for("@logbrew/sdk.eventQueueFactory");
+const CLIENT_REPORT_STORE = Symbol.for("@logbrew/sdk.clientReportStore");
+const CONTEXT_PROVIDER = Symbol.for("@logbrew/sdk.contextProvider");
+const BREADCRUMB_PROVIDER = Symbol.for("@logbrew/sdk.breadcrumbProvider");
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_MAX_QUEUE_SIZE = 1000;
+const DEFAULT_MAX_QUEUE_BYTES = 4_194_304;
+const DEFAULT_MAX_BATCH_EVENTS = 100;
+const DEFAULT_MAX_BATCH_BYTES = 262_144;
+const DEFAULT_DELIVERY_INTERVAL_MS = 1000;
+const DEFAULT_DELIVERY_QUEUE_THRESHOLD = 50;
+
+/**
+ * @param {unknown} value
+ * @param {string} message
+ * @returns {Callable | undefined}
+ */
+function optionalFunction(value, message) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!isCallable(value)) {
+    throw new SdkError("validation_error", message);
+  }
+  return value;
+}
+
+/**
+ * @param {unknown} maxQueueSize
+ * @returns {number}
+ */
+function defaultDeliveryQueueThreshold(maxQueueSize) {
+  if (typeof maxQueueSize === "bigint") {
+    throw new TypeError("Cannot convert a BigInt value to a number");
+  }
+  return Math.min(DEFAULT_DELIVERY_QUEUE_THRESHOLD, Number(maxQueueSize));
+}
+
+/**
+ * @param {unknown} transport
+ * @returns {transport is BatchTransport}
+ */
+function isTransport(transport) {
+  return isRecord(transport) && typeof transport["send"] === "function";
+}
+
+/**
+ * @param {unknown} transport
+ * @returns {BatchTransport | undefined}
+ */
+function validateTransport(transport) {
+  if (transport === undefined) {
+    return undefined;
+  }
+  if (!isTransport(transport)) {
+    throw new SdkError("validation_error", "transport.send must be a function");
+  }
+  return transport;
+}
+
+/**
+ * @param {ClientOptions} options
+ * @returns {Pick<ClientConfig, "apiKey" | "context" | "contextProvider" | "breadcrumbProvider" | "sdk">}
+ */
+function validateIdentity(options) {
+  const apiKey = requireNonEmpty("apiKey", options["apiKey"]);
+  const name = requireNonEmpty("sdkName", options["sdkName"]);
+  const version = requireNonEmpty("sdkVersion", options["sdkVersion"]);
+  const context = validateTelemetryContext(options["context"], "client telemetry context");
+  const contextProvider = optionalFunction(options["contextProvider"], "context provider must be a function");
+  const breadcrumbProvider = optionalFunction(options["breadcrumbProvider"], "breadcrumb provider must be a function");
+  return {
+    apiKey,
+    breadcrumbProvider,
+    context,
+    contextProvider,
+    sdk: {
+      name,
+
+      language: "javascript",
+
+      version
+    }
+  };
+}
+
+/**
+ * @param {ClientOptions} options
+ * @returns {Pick<ClientConfig, "maxRetries" | "eventFilter" | "maxQueueSize" | "maxQueueBytes" | "maxBatchEvents" | "maxBatchBytes" | "onEventDropped">}
+ */
+function validateLimits(options) {
+  const maxRetries = requireNonNegativeInteger("maxRetries", options["maxRetries"]);
+  const eventFilter = optionalFunction(options["eventFilter"], "eventFilter must be a function");
+  const maxQueueSize = requirePositiveInteger("maxQueueSize", options["maxQueueSize"]);
+  const maxQueueBytes = requirePositiveInteger("maxQueueBytes", options["maxQueueBytes"]);
+  const maxBatchEvents = requirePositiveInteger("maxBatchEvents", options["maxBatchEvents"]);
+  const maxBatchBytes = requirePositiveInteger("maxBatchBytes", options["maxBatchBytes"]);
+  const onEventDropped = optionalFunction(options["onEventDropped"], "onEventDropped must be a function");
+  return { eventFilter, maxBatchBytes, maxBatchEvents, maxQueueBytes, maxQueueSize, maxRetries, onEventDropped };
+}
+
+/**
+ * @param {ClientOptions} options
+ * @returns {Pick<ClientConfig, "eventStore" | "eventQueueFactory" | "clientReportStore">}
+ */
+function validateStorage(options) {
+  const eventStore = validateEventStore(options["eventStore"]);
+  const eventQueueFactory = optionalFunction(options["eventQueueFactory"], "event queue factory must be a function");
+  if (eventStore !== undefined && eventQueueFactory !== undefined) {
+    throw new SdkError("validation_error", "eventStore and event queue factory are mutually exclusive");
+  }
+  const { clientReportStore } = options;
+  if (clientReportStore !== undefined && !isClientReportStore(clientReportStore)) {
+    throw new SdkError("validation_error", "client report store must provide loadClientReport and saveClientReport");
+  }
+  return { clientReportStore, eventQueueFactory, eventStore };
+}
+
+/**
+ * @param {ClientOptions} options
+ * @returns {Pick<ClientConfig, "transport" | "automaticDelivery">}
+ */
+function validateAutomaticDelivery(options) {
+  const transport = validateTransport(options["transport"]);
+  const { automaticDelivery } = options;
+  if (typeof automaticDelivery !== "boolean") {
+    throw new SdkError("validation_error", "automaticDelivery must be a boolean");
+  }
+  if (automaticDelivery && transport === undefined) {
+    throw new SdkError("validation_error", "automaticDelivery requires transport");
+  }
+  return { automaticDelivery, transport };
+}
+
+/**
+ * @param {ClientOptions} options
+ * @param {number} maxQueueSize
+ * @returns {Pick<ClientConfig, "transport" | "automaticDelivery" | "deliveryIntervalMs" | "deliveryQueueThreshold">}
+ */
+function validateDelivery(options, maxQueueSize) {
+  const automatic = validateAutomaticDelivery(options);
+  const deliveryIntervalMs = requirePositiveInteger("deliveryIntervalMs", options["deliveryIntervalMs"]);
+  if (deliveryIntervalMs > MAX_DELIVERY_INTERVAL_MS) {
+    throw new SdkError("validation_error", `deliveryIntervalMs must be at most ${MAX_DELIVERY_INTERVAL_MS}`);
+  }
+  const deliveryQueueThreshold = requirePositiveInteger("deliveryQueueThreshold", options["deliveryQueueThreshold"]);
+  if (deliveryQueueThreshold > maxQueueSize) {
+    throw new SdkError("validation_error", "deliveryQueueThreshold must not exceed maxQueueSize");
+  }
+  return { ...automatic, deliveryIntervalMs, deliveryQueueThreshold };
+}
+
+/**
+ * @param {ClientOptions} options
+ * @returns {ClientConfig}
+ */
+function clientConfig({
+  apiKey,
+  sdkName,
+  sdkVersion,
+  context,
+  [CONTEXT_PROVIDER]: contextProvider,
+  [BREADCRUMB_PROVIDER]: breadcrumbProvider,
+  maxRetries = DEFAULT_MAX_RETRIES,
+  eventFilter,
+  maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
+  maxQueueBytes = DEFAULT_MAX_QUEUE_BYTES,
+  maxBatchEvents = DEFAULT_MAX_BATCH_EVENTS,
+  maxBatchBytes = DEFAULT_MAX_BATCH_BYTES,
+  onEventDropped,
+  eventStore,
+  [EVENT_QUEUE_FACTORY]: eventQueueFactory,
+  [CLIENT_REPORT_STORE]: clientReportStore,
+  transport,
+  automaticDelivery = transport !== undefined,
+  deliveryIntervalMs = DEFAULT_DELIVERY_INTERVAL_MS,
+  deliveryQueueThreshold = defaultDeliveryQueueThreshold(maxQueueSize)
+}) {
+  const options = {
+    apiKey,
+    automaticDelivery,
+    breadcrumbProvider,
+    clientReportStore,
+    context,
+    contextProvider,
+    deliveryIntervalMs,
+    deliveryQueueThreshold,
+    eventFilter,
+    eventQueueFactory,
+    eventStore,
+    maxBatchBytes,
+    maxBatchEvents,
+    maxQueueBytes,
+    maxQueueSize,
+    maxRetries,
+    onEventDropped,
+    sdkName,
+    sdkVersion,
+    transport
+  };
+  const identity = validateIdentity(options);
+  const limits = validateLimits(options);
+  return { ...identity, ...limits, ...validateStorage(options), ...validateDelivery(options, limits.maxQueueSize) };
+}
+
+/**
+ * @param {ClientConfig} config
+ * @returns {ClientSettings}
+ */
+function publicSettings(config) {
+  return {
+    apiKey: config.apiKey,
+
+    automaticDelivery: config.automaticDelivery,
+
+    deliveryIntervalMs: config.deliveryIntervalMs,
+
+    deliveryQueueThreshold: config.deliveryQueueThreshold,
+
+    eventFilter: config.eventFilter,
+
+    maxBatchBytes: config.maxBatchBytes,
+
+    maxBatchEvents: config.maxBatchEvents,
+
+    maxQueueBytes: config.maxQueueBytes,
+
+    maxQueueSize: config.maxQueueSize,
+
+    onEventDropped: config.onEventDropped,
+
+    context: cloneTelemetryContext(config.context),
+
+    contextProvider: config.contextProvider,
+
+    breadcrumbProvider: config.breadcrumbProvider,
+
+    transport: config.transport,
+
+    sdk: config.sdk,
+
+    maxRetries: config.maxRetries
+  };
+}
+
+module.exports = {
+  BREADCRUMB_PROVIDER,
+  CLIENT_REPORT_STORE,
+  CONTEXT_PROVIDER,
+  EVENT_QUEUE_FACTORY,
+  clientConfig,
+  publicSettings,
+  validateTransport
+};

package/client-report.cjs

@@ -0,0 +1,232 @@
+const { incrementBounded, nextBoundedTimestamp } = require("./bounded-number.cjs");
+const { propertyOf } = require("./error-details.cjs");
+const { NULL_VALUE } = require("./null-value.cjs");
+const { randomHex } = require("./random-hex.cjs");
+const { requireSynchronousStoreResult } = require("./stored-events.cjs");
+const { isRecord } = require("./validation.cjs");
+
+/**
+ * @import { ClientReportStore } from "./event-store.cjs"
+ * @typedef {"event_too_large" | "evicted_for_fatal" | "queue_bytes_overflow" | "queue_overflow"} DropReason
+ * @typedef {Readonly<{ report_id: unknown, dropped_events: Readonly<Record<string, number>> }>} ClientReport
+ * @typedef {{ pending: ClientReport | undefined, unreported: Record<string, number> }} RestoredReport
+ */
+
+const MAX_CLIENT_REPORT_REASONS = 16;
+const MAX_CLIENT_REPORT_COUNT = 1_000_000_000;
+const MIN_CLIENT_REPORT_COUNT = 1;
+const CLIENT_REPORT_SAVE_INTERVAL_MS = 1000;
+const CLIENT_REPORT_ID_PATTERN = /^[A-Za-z0-9_-]{16,64}$/u;
+const CLIENT_REPORT_REASON_PATTERN = /^[a-z][a-z0-9_]{0,63}$/u;
+const REPORT_ID_BYTES = 16;
+const NO_COUNT = 0;
+const STEP = 1;
+
+/**
+ * @param {string} reason
+ * @param {unknown} count
+ * @returns {count is number}
+ */
+function isReportCount(reason, count) {
+  return CLIENT_REPORT_REASON_PATTERN.test(reason) && typeof count === "number" && Number.isSafeInteger(count)
+    && count >= MIN_CLIENT_REPORT_COUNT && count <= MAX_CLIENT_REPORT_COUNT;
+}
+
+/**
+ * @param {unknown} counts
+ * @returns {Record<string, number>}
+ */
+function validClientReportCounts(counts) {
+  /** @type {Record<string, number>} */
+  const valid = {};
+  if (!isRecord(counts)) {
+    return valid;
+  }
+  for (const [reason, count] of Object.entries(counts)) {
+    if (Object.keys(valid).length < MAX_CLIENT_REPORT_REASONS && isReportCount(reason, count)) {
+      valid[reason] = count;
+    }
+  }
+  return valid;
+}
+
+/**
+ * @param {Readonly<Record<string, number>>} counts
+ * @returns {Record<string, number>}
+ */
+function reportableCounts(counts) {
+  /** @type {Record<string, number>} */
+  const reportable = {};
+  for (const [reason, count] of Object.entries(counts)) {
+    if (Object.keys(reportable).length < MAX_CLIENT_REPORT_REASONS && count > NO_COUNT) {
+      reportable[reason] = count;
+    }
+  }
+  return reportable;
+}
+
+/**
+ * @param {Readonly<Record<string, number>>} counts
+ * @param {Readonly<Record<string, number>>} reported
+ * @returns {Record<string, number>}
+ */
+function withoutReported(counts, reported) {
+  const reportedReasons = new Set(Object.keys(reported));
+  /** @type {Record<string, number>} */
+  const remaining = {};
+  for (const [reason, count] of Object.entries(counts)) {
+    if (!reportedReasons.has(reason)) {
+      remaining[reason] = count;
+    }
+  }
+  return remaining;
+}
+
+/**
+ * @param {unknown} reportId
+ * @returns {boolean}
+ */
+function isReportId(reportId) {
+  if (typeof reportId === "number") {
+    return CLIENT_REPORT_ID_PATTERN.test(String(reportId));
+  }
+  return typeof reportId === "string" && CLIENT_REPORT_ID_PATTERN.test(reportId);
+}
+
+/**
+ * @param {ClientReportStore | undefined} store
+ * @returns {unknown}
+ */
+function loadClientReportState(store) {
+  try {
+    return store === undefined ? undefined : requireSynchronousStoreResult("loadClientReport", store.loadClientReport());
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @param {ClientReportStore | undefined} store
+ * @returns {RestoredReport}
+ */
+function loadClientReport(store) {
+  const state = loadClientReportState(store);
+  const pending = propertyOf(state, "pending");
+  const pendingCounts = validClientReportCounts(propertyOf(pending, "dropped_events"));
+  const reportId = propertyOf(pending, "report_id");
+  return {
+    pending: isReportId(reportId) && Object.keys(pendingCounts).length > NO_COUNT
+      ? Object.freeze({
+        report_id: reportId,
+
+        dropped_events: pendingCounts
+      })
+      : undefined,
+    unreported: validClientReportCounts(propertyOf(state, "unreported"))
+  };
+}
+
+/**
+ * @param {ClientReportStore} store
+ * @param {unknown} state
+ * @returns {boolean}
+ */
+function saveClientReportState(store, state) {
+  try {
+    requireSynchronousStoreResult("saveClientReport", store.saveClientReport(state));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+class DropLedger {
+  droppedEventCount = NO_COUNT;
+
+  /** @type {Record<DropReason, number>} */
+  droppedEventsByReason = {
+    event_too_large: NO_COUNT,
+    evicted_for_fatal: NO_COUNT,
+    queue_bytes_overflow: NO_COUNT,
+    queue_overflow: NO_COUNT
+  };
+
+  clientReportSavedAtMs = NO_COUNT;
+
+  /** @type {DropReason | "none"} */
+  lastDropReason = "none";
+
+  lastDroppedAtUnixMs = NO_COUNT;
+
+  /**
+   * @param {ClientReportStore | undefined} store
+   */
+  constructor(store) {
+    this.clientReportStore = store;
+    const restoredReport = loadClientReport(store);
+    this.unreportedDropsByReason = restoredReport.unreported;
+    this.pendingClientReport = restoredReport.pending;
+  }
+
+  /**
+   * @param {DropReason} reason
+   * @returns {void}
+   */
+  record(reason) {
+    this.droppedEventCount = incrementBounded(this.droppedEventCount);
+    this.droppedEventsByReason[reason] = incrementBounded(this.droppedEventsByReason[reason]);
+    const previous = this.unreportedDropsByReason[reason];
+    this.unreportedDropsByReason[reason] = Math.min(MAX_CLIENT_REPORT_COUNT, (previous ?? NO_COUNT) + STEP);
+    this.save(previous === undefined);
+    this.lastDropReason = reason;
+    this.lastDroppedAtUnixMs = nextBoundedTimestamp(this.lastDroppedAtUnixMs);
+  }
+
+  /**
+   * @returns {ClientReport | undefined}
+   */
+  pendingReport() {
+    if (this.pendingClientReport !== undefined) {
+      return this.pendingClientReport;
+    }
+    const droppedEvents = reportableCounts(this.unreportedDropsByReason);
+    if (Object.keys(droppedEvents).length === NO_COUNT) {
+      return undefined;
+    }
+    this.unreportedDropsByReason = withoutReported(this.unreportedDropsByReason, droppedEvents);
+    this.pendingClientReport = Object.freeze({
+      report_id: randomHex(REPORT_ID_BYTES),
+
+      dropped_events: droppedEvents
+    });
+    this.save(true);
+    return this.pendingClientReport;
+  }
+
+  /**
+   * @returns {void}
+   */
+  acknowledgeReport() {
+    this.pendingClientReport = undefined;
+    this.save(true);
+  }
+
+  /**
+   * @param {boolean} immediately
+   * @returns {void}
+   */
+  save(immediately) {
+    const now = Date.now();
+    const store = this.clientReportStore;
+    if (store === undefined || (!immediately && now - this.clientReportSavedAtMs < CLIENT_REPORT_SAVE_INTERVAL_MS)) {
+      return;
+    }
+    this.clientReportSavedAtMs = now;
+    saveClientReportState(store, {
+      pending: this.pendingClientReport ?? NULL_VALUE,
+      unreported: { ...this.unreportedDropsByReason }
+    });
+  }
+}
+
+module.exports = { DropLedger };