@logbrew/sdk 0.1.38 → 0.1.39

package/delivery-health.cjs

@@ -0,0 +1,133 @@
+/**
+ * @import { PauseReason } from "./automatic-delivery.cjs"
+ * @import { StatusClass } from "./batch-sender.cjs"
+ * @import { DropReason } from "./client-report.cjs"
+ * @import { DeliveryOutcome } from "./event-pipeline.cjs"
+ * @typedef {Readonly<{
+ *   automaticDelivery: boolean,
+ *   lifecycle: "active" | "shutting_down" | "closed",
+ *   storage: "persistent" | "memory",
+ *   queueEvents: number,
+ *   queueBytes: number,
+ *   hydratedEvents: number,
+ *   hydratedBytes: number,
+ *   droppedEvents: number,
+ *   droppedByReason: Readonly<Record<DropReason, number>>,
+ *   lastDropReason: DropReason | "none",
+ *   scheduled: boolean,
+ *   inFlight: boolean,
+ *   coalesced: boolean,
+ *   pendingOperations: number,
+ *   lastOutcome: DeliveryOutcome,
+ *   lastStatusClass: StatusClass,
+ *   pausedReason: PauseReason,
+ *   consecutiveFailures: number,
+ *   retryDelayMs: number,
+ *   flushes: number,
+ *   failures: number,
+ *   attempts: number,
+ *   batches: number,
+ *   acceptedEvents: number,
+ *   lastAttemptAtUnixMs: number,
+ *   lastAcceptedAtUnixMs: number,
+ *   lastDroppedAtUnixMs: number
+ * }>} HealthState
+ */
+
+const DELIVERY_HEALTH_SCHEMA_VERSION = 1;
+const NONE = 0;
+const HEALTH_KEYS = Object.freeze([
+  "schemaVersion",
+  "automaticDelivery",
+  "lifecycle",
+  "deliveryState",
+  "storage",
+  "queueEvents",
+  "queueBytes",
+  "hydratedEvents",
+  "hydratedBytes",
+  "droppedEvents",
+  "droppedByReason",
+  "lastDropReason",
+  "scheduled",
+  "inFlight",
+  "coalesced",
+  "pendingOperations",
+  "lastOutcome",
+  "lastStatusClass",
+  "pausedReason",
+  "consecutiveFailures",
+  "retryDelayMs",
+  "flushes",
+  "failures",
+  "attempts",
+  "batches",
+  "acceptedEvents",
+  "lastAttemptAtUnixMs",
+  "lastAcceptedAtUnixMs",
+  "lastDroppedAtUnixMs"
+]);
+
+/**
+ * @param {boolean} closed
+ * @param {boolean} closing
+ * @returns {HealthState["lifecycle"]}
+ */
+function lifecycleOf(closed, closing) {
+  if (closed) {
+    return "closed";
+  }
+  return closing ? "shutting_down" : "active";
+}
+
+/**
+ * @param {HealthState} state
+ * @returns {string | undefined}
+ */
+function activeState(state) {
+  if (state.inFlight) {
+    return "in_flight";
+  }
+  if (state.retryDelayMs > NONE) {
+    return "retrying";
+  }
+  if (state.pausedReason !== "none") {
+    return "paused";
+  }
+  if (state.queueEvents > NONE) {
+    return state.scheduled ? "scheduled" : "queued";
+  }
+  return undefined;
+}
+
+/**
+ * @param {HealthState} state
+ * @returns {string}
+ */
+function deliveryState(state) {
+  const active = activeState(state);
+  if (active !== undefined) {
+    return active;
+  }
+  if (state.lastOutcome === "accepted" || state.lastOutcome === "failed") {
+    return state.lastOutcome;
+  }
+  return state.droppedEvents > NONE ? "dropped" : "idle";
+}
+
+/**
+ * @param {HealthState} state
+ * @returns {Readonly<Record<string, unknown>>}
+ */
+function deliveryHealthSnapshot(state) {
+  /** @type {Readonly<Record<string, unknown>>} */
+  const values = {
+    ...state,
+    deliveryState: deliveryState(state),
+    droppedByReason: Object.freeze({ ...state.droppedByReason }),
+    schemaVersion: DELIVERY_HEALTH_SCHEMA_VERSION
+  };
+  return Object.freeze(Object.fromEntries(HEALTH_KEYS.map((key) => [key, values[key]])));
+}
+
+module.exports = { deliveryHealthSnapshot, lifecycleOf };

package/error-causes.cjs

@@ -0,0 +1,130 @@
+const { errorCauseType, isObjectLike, safeProperty } = require("./error-details.cjs");
+
+/**
+ * @typedef {{
+ *   errorCauseCount?: number,
+ *   errorCauseTypes?: string,
+ *   errorCauseSources?: string,
+ *   errorExceptionGroup?: true,
+ *   errorCauseTruncated?: true
+ * }} ErrorCauseMetadata
+ */
+
+const MAX_ERROR_CAUSES = 5;
+const NO_CAUSES = 0;
+
+class ErrorCauseCollector {
+  constructor() {
+    /** @type {Readonly<{ source: string, type: string }>[]} */
+    this.items = [];
+    /** @type {Set<object>} */
+    this.seen = new Set();
+    this.sawExceptionGroup = false;
+    this.truncated = false;
+  }
+
+  /**
+   * @param {unknown} value
+   * @param {string} source
+   * @returns {void}
+   */
+  collect(value, source) {
+    if (value === undefined || value === null) {
+      return;
+    }
+    if (this.items.length >= MAX_ERROR_CAUSES) {
+      this.truncated = true;
+      return;
+    }
+    if (!this.markSeen(value)) {
+      return;
+    }
+    this.items.push({ source, type: errorCauseType(value) });
+    this.collectNested(value);
+  }
+
+  /**
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  markSeen(value) {
+    if (!isObjectLike(value)) {
+      return true;
+    }
+    if (this.seen.has(value)) {
+      this.truncated = true;
+      return false;
+    }
+    this.seen.add(value);
+    return true;
+  }
+
+  /**
+   * @param {unknown} parent
+   * @returns {void}
+   */
+  collectNested(parent) {
+    if (!isObjectLike(parent)) {
+      return;
+    }
+    this.collectCause(parent);
+    this.collectErrors(parent);
+  }
+
+  /**
+   * @param {object} parent
+   * @returns {void}
+   */
+  collectCause(parent) {
+    const cause = safeProperty(parent, "cause");
+    if (!cause.available) {
+      this.truncated = true;
+    } else if (cause.value !== undefined && cause.value !== null) {
+      this.collect(cause.value, "cause");
+    }
+  }
+
+  /**
+   * @param {object} parent
+   * @returns {void}
+   */
+  collectErrors(parent) {
+    const errors = safeProperty(parent, "errors");
+    if (!errors.available) {
+      this.truncated = true;
+    } else if (Array.isArray(errors.value)) {
+      this.sawExceptionGroup = true;
+      /** @type {readonly unknown[]} */
+      const children = errors.value;
+      for (const [index, child] of children.entries()) {
+        this.collect(child, `errors[${index}]`);
+      }
+    }
+  }
+}
+
+/**
+ * @param {unknown} error
+ * @returns {ErrorCauseMetadata}
+ */
+function errorCauseMetadata(error) {
+  const collector = new ErrorCauseCollector();
+  if (isObjectLike(error)) {
+    collector.seen.add(error);
+    collector.collectNested(error);
+  }
+  if (collector.items.length === NO_CAUSES) {
+    return {};
+  }
+  return {
+    errorCauseCount: collector.items.length,
+
+    errorCauseTypes: collector.items.map((item) => item.type).join(","),
+
+    errorCauseSources: collector.items.map((item) => item.source).join(","),
+    ...(collector.sawExceptionGroup ? { errorExceptionGroup: true } : {}),
+    ...(collector.truncated ? { errorCauseTruncated: true } : {})
+  };
+}
+
+module.exports = { errorCauseMetadata };

package/error-details.cjs

@@ -0,0 +1,124 @@
+const { stringOrUndefined } = require("./validation.cjs");
+
+/**
+ * @typedef {{ available: true, value: unknown } | { available: false, value: undefined }} PropertyRead
+ * @typedef {{ name: string, message?: string | undefined, stack?: string | undefined }} ErrorDetails
+ */
+
+const TYPE_NAME_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]{0,63}$/u;
+const BUILTIN_ERROR_NAMES = new Set([
+  "AggregateError",
+  "Error",
+  "EvalError",
+  "RangeError",
+  "ReferenceError",
+  "SyntaxError",
+  "TypeError",
+  "URIError"
+]);
+
+/**
+ * @param {unknown} value
+ * @returns {value is object}
+ */
+function isObjectLike(value) {
+  return value !== null && (typeof value === "object" || typeof value === "function");
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} key
+ * @returns {unknown}
+ */
+function propertyOf(value, key) {
+  return isObjectLike(value) ? Reflect.get(value, key) : undefined;
+}
+
+/**
+ * @param {object} value
+ * @param {string} name
+ * @returns {PropertyRead}
+ */
+function safeProperty(value, name) {
+  try {
+    /** @type {unknown} */
+    const property = Reflect.get(value, name);
+    return { available: true, value: property };
+  } catch {
+    return { available: false, value: undefined };
+  }
+}
+
+/**
+ * @param {Readonly<PropertyRead>} property
+ * @returns {string | undefined}
+ */
+function nonBlankText(property) {
+  return property.available ? stringOrUndefined(property.value) : undefined;
+}
+
+/**
+ * @param {unknown} error
+ * @returns {ErrorDetails}
+ */
+function errorDetails(error) {
+  if (error instanceof Error || (typeof error === "object" && error !== null)) {
+    const name = safeProperty(error, "name");
+    const message = safeProperty(error, "message");
+    const stack = safeProperty(error, "stack");
+    return {
+      name: nonBlankText(name) ?? "Error",
+
+      message: nonBlankText(message),
+
+      stack: nonBlankText(stack)
+    };
+  }
+  if (typeof error === "string" && error.trim() !== "") {
+    return { message: error, name: "Error" };
+  }
+  return { name: "Error" };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function safeCauseTypeName(value) {
+  return typeof value === "string" && TYPE_NAME_PATTERN.test(value) ? value : undefined;
+}
+
+/**
+ * @param {object} value
+ * @returns {string | undefined}
+ */
+function constructorTypeName(value) {
+  const constructor = safeProperty(value, "constructor");
+  if (!constructor.available || !isObjectLike(constructor.value)) {
+    return undefined;
+  }
+  const name = safeProperty(constructor.value, "name");
+  return name.available ? safeCauseTypeName(name.value) : undefined;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function errorCauseType(value) {
+  if (!isObjectLike(value)) {
+    return "NonError";
+  }
+  const constructorName = constructorTypeName(value);
+  if (!(value instanceof Error)) {
+    return constructorName ?? "Object";
+  }
+  if (constructorName !== undefined && constructorName !== "Error") {
+    return constructorName;
+  }
+  const name = safeProperty(value, "name");
+  const builtinName = name.available && typeof name.value === "string" && BUILTIN_ERROR_NAMES.has(name.value) ? name.value : undefined;
+  return builtinName ?? constructorName ?? "Error";
+}
+
+module.exports = { errorCauseType, errorDetails, isObjectLike, propertyOf, safeProperty };

package/error-issue.cjs

@@ -0,0 +1,187 @@
+const { errorCauseMetadata } = require("./error-causes.cjs");
+const { errorDetails } = require("./error-details.cjs");
+const { normalizeSeverity } = require("./event-validation.cjs");
+const { createJavaScriptExceptionChain } = require("./exception-chain.cjs");
+const { createIssueException, validateIssueEvidence } = require("./issue-diagnostics.cjs");
+const { javascriptStackEvidence } = require("./issue-stack.cjs");
+const { compactMetadata, traceMetadataFromLogContext } = require("./log-context.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { hasUnicodeControlCharacter, isRecord, optionalEntry, stringOrUndefined } = require("./validation.cjs");
+
+/**
+ * @import { IssueAttributes, IssueStackFrame } from "./index.cjs"
+ * @import { ErrorDetails } from "./error-details.cjs"
+ * @import { DeepReadonly } from "./validation.cjs"
+ * @typedef {Readonly<{ details: Readonly<ErrorDetails>, frame: Readonly<IssueStackFrame> | undefined }>} ParsedError
+ */
+
+const MAX_EXCEPTION_TYPE_LENGTH = 256;
+const NO_FRAMES = 0;
+const LOCATION_TEXT_PATTERN = /[?#]/u;
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function boundedIssueExceptionType(value) {
+  const normalized = value.trim();
+  if (
+    normalized === ""
+    || [...normalized].length > MAX_EXCEPTION_TYPE_LENGTH
+    || LOCATION_TEXT_PATTERN.test(normalized)
+    || hasUnicodeControlCharacter(normalized)
+  ) {
+    return "Error";
+  }
+  return normalized;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function issueFingerprintOrUndefined(value) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new SdkError("validation_error", "issue fingerprint must be a non-empty string");
+  }
+  return value.trim();
+}
+
+/**
+ * @param {string} groupingPrefix
+ * @param {Readonly<IssueStackFrame> | undefined} frame
+ * @param {string | undefined} issueFingerprint
+ * @returns {Record<string, string>}
+ */
+function issueGroupingMetadata(groupingPrefix, frame, issueFingerprint) {
+  /** @type {string} */
+  let issueGroupingSource = "error_type";
+  if (issueFingerprint !== undefined) {
+    issueGroupingSource = "explicit_fingerprint";
+  } else if (frame !== undefined) {
+    issueGroupingSource = "error_type_and_frame";
+  }
+  return {
+    issueGroupingKey: frame === undefined ? groupingPrefix : `${groupingPrefix}:${frame.filename}`,
+
+    issueGroupingSource,
+    ...optionalEntry("issueFingerprint", issueFingerprint)
+  };
+}
+
+/**
+ * @param {Readonly<IssueStackFrame> | undefined} frame
+ * @returns {Record<string, string>}
+ */
+function releaseArtifactMetadata(frame) {
+  if (frame?.debugId === undefined || frame.debugId === "") {
+    return {};
+  }
+  return {
+    releaseArtifactType: "sourcemap",
+
+    releaseArtifactCodeFile: frame.filename,
+
+    releaseArtifactDebugId: frame.debugId
+  };
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} options
+ * @returns {Record<string, unknown>}
+ */
+function labelMetadata(options) {
+  /** @type {Record<string, unknown>} */
+  const labels = {};
+  for (const key of ["release", "environment", "service", "runtime", "platform"]) {
+    if (stringOrUndefined(options[key]) !== undefined) {
+      labels[key] = options[key];
+    }
+  }
+  return labels;
+}
+
+/**
+ * @param {Readonly<IssueStackFrame> | undefined} frame
+ * @returns {Record<string, unknown>}
+ */
+function errorFrameMetadata(frame) {
+  if (frame === undefined) {
+    return {};
+  }
+  return {
+    errorFrameFile: frame.filename,
+
+    errorFrameLine: frame.line,
+
+    errorFrameColumn: frame.column
+  };
+}
+
+/**
+ * @param {unknown} error
+ * @param {Readonly<Record<string, unknown>>} options
+ * @param {ParsedError} parsed
+ * @returns {Record<string, unknown>}
+ */
+function errorIssueMetadata(error, options, parsed) {
+  const { details, frame } = parsed;
+  const source = stringOrUndefined(options["source"]) ?? "javascript.error";
+  return {
+    ...compactMetadata(options["metadata"]),
+
+    source,
+
+    errorName: details.name,
+    ...optionalEntry("errorMessage", details.message),
+    ...errorFrameMetadata(frame),
+    ...issueGroupingMetadata(`${source}:${details.name}`, frame, issueFingerprintOrUndefined(options["fingerprint"])),
+    ...errorCauseMetadata(error),
+    ...labelMetadata(options),
+    ...traceMetadataFromLogContext(options["trace"]),
+    ...releaseArtifactMetadata(frame),
+    ...optionalEntry("errorStack", options["includeErrorStack"] === true ? details.stack : undefined)
+  };
+}
+
+/**
+ * @param {unknown} error
+ * @param {unknown} [options]
+ * @returns {DeepReadonly<IssueAttributes>}
+ */
+function createIssueAttributesFromError(error, options = {}) {
+  if (!isRecord(options)) {
+    throw new SdkError("validation_error", "error issue options must be an object");
+  }
+  const details = errorDetails(error);
+  const stackEvidence = javascriptStackEvidence(details.stack, options["debugIdMap"]);
+  const [frame] = stackEvidence.frames;
+  const metadata = errorIssueMetadata(error, options, { details, frame });
+  const exception = createIssueException(
+    boundedIssueExceptionType(details.name),
+    stringOrUndefined(options["mechanism"]) ?? "javascript.error",
+    options["handled"] === undefined ? true : options["handled"]
+  );
+  const exceptionChain = createJavaScriptExceptionChain(error, {
+    debugIdMap: options["debugIdMap"],
+    details,
+    exception,
+    stackEvidence
+  });
+  return {
+    title: stringOrUndefined(options["title"]) ?? details.name,
+
+    level: normalizeSeverity("issue level", options["level"] ?? "error"),
+    ...optionalEntry("message", stringOrUndefined(options["message"]) ?? details.message),
+    exception,
+    exceptionChain,
+    ...optionalEntry("stackFrames", stackEvidence.frames.length > NO_FRAMES ? stackEvidence.frames : undefined),
+    ...optionalEntry("evidence", validateIssueEvidence(options["evidence"])),
+    metadata: compactMetadata(metadata)
+  };
+}
+
+module.exports = { createIssueAttributesFromError };

package/event-clone.cjs

@@ -0,0 +1,55 @@
+const { cloneIssueDiagnostics } = require("./issue-diagnostics.cjs");
+const { cloneTelemetryContext } = require("./telemetry-context.cjs");
+const { optionalEntry } = require("./validation.cjs");
+
+/**
+ * @import { NativeStackFrame } from "./index.cjs"
+ * @import { EventAttributes, SdkEvent } from "./event-validation.cjs"
+ * @import { DeepReadonly } from "./validation.cjs"
+ */
+
+/**
+ * @template {Readonly<{ metadata?: Readonly<Record<string, unknown>> }>} Entry
+ * @param {Entry} entry
+ * @returns {Entry}
+ */
+function cloneWithMetadata(entry) {
+  return entry.metadata === undefined ? { ...entry } : { ...entry, metadata: { ...entry.metadata } };
+}
+
+/**
+ * @param {Readonly<NativeStackFrame>} frame
+ * @returns {NativeStackFrame}
+ */
+function cloneNativeStackFrame(frame) {
+  return { ...frame };
+}
+
+/**
+ * @param {DeepReadonly<EventAttributes>} source
+ * @returns {Partial<DeepReadonly<EventAttributes>>}
+ */
+function clonedCollections(source) {
+  const { context, events, links, metadata, nativeStackFrames } = source;
+  return {
+    ...optionalEntry("nativeStackFrames", nativeStackFrames?.map((frame) => cloneNativeStackFrame(frame))),
+    ...optionalEntry("metadata", metadata === undefined ? undefined : { ...metadata }),
+    ...optionalEntry("events", events?.map((entry) => cloneWithMetadata(entry))),
+    ...optionalEntry("links", links?.map((entry) => cloneWithMetadata(entry))),
+    ...optionalEntry("context", context === undefined ? undefined : cloneTelemetryContext(context))
+  };
+}
+
+/**
+ * @param {DeepReadonly<SdkEvent>} event
+ * @returns {DeepReadonly<SdkEvent>}
+ */
+function cloneEvent(event) {
+  const source = event.attributes;
+  return {
+    ...event,
+    attributes: { ...source, ...cloneIssueDiagnostics(source), ...clonedCollections(source) }
+  };
+}
+
+module.exports = { cloneEvent };

package/event-metadata.cjs

@@ -0,0 +1,40 @@
+const { SdkError } = require("./sdk-error.cjs");
+const { validateTelemetryContext } = require("./telemetry-context.cjs");
+const { isRecord, optionalEntry } = require("./validation.cjs");
+
+/**
+ * @import { TelemetryContext } from "./index.cjs"
+ */
+
+/**
+ * @param {unknown} metadata
+ * @returns {Record<string, unknown> | undefined}
+ */
+function cloneMetadata(metadata) {
+  if (metadata === undefined) {
+    return undefined;
+  }
+  if (!isRecord(metadata)) {
+    throw new SdkError("validation_error", "metadata must be an object");
+  }
+  return { ...metadata };
+}
+
+/**
+ * @template {object} Attributes
+ * @param {Attributes} attributes
+ * @param {unknown} metadata
+ * @param {unknown} context
+ * @returns {Attributes & { metadata?: Record<string, unknown>, context?: TelemetryContext }}
+ */
+function withMetadata(attributes, metadata, context) {
+  const safeMetadata = cloneMetadata(metadata);
+  const safeContext = validateTelemetryContext(context);
+  return {
+    ...attributes,
+    ...optionalEntry("metadata", safeMetadata),
+    ...optionalEntry("context", safeContext)
+  };
+}
+
+module.exports = { withMetadata };