@logbrew/sdk 0.1.37 → 0.1.39

package/log-context.cjs

@@ -1,95 +1,115 @@
-const ZERO_TRACE_ID = "00000000000000000000000000000000";
-const ZERO_SPAN_ID = "0000000000000000";
+const { SdkError } = require("./sdk-error.cjs");
+const { ZERO_SPAN_ID, ZERO_TRACE_ID, isRecord } = require("./validation.cjs");
 
-function buildLogContextHelpers({ SdkError }) {
-  function compactMetadata(metadata) {
-    if (metadata === undefined) {
-      return {};
-    }
-    if (!metadata || Array.isArray(metadata) || typeof metadata !== "object") {
-      throw new SdkError("validation_error", "metadata must be an object");
-    }
-    const safeMetadata = {};
-    for (const [key, value] of Object.entries(metadata)) {
-      if (isMetadataValue(value)) {
-        safeMetadata[key] = value;
-      }
-    }
-    return safeMetadata;
-  }
+/**
+ * @import { LogCorrelationTraceContext, Metadata, MetadataValue } from "./index.cjs"
+ */
 
-  function traceFromProvider(provider, onError) {
-    if (!provider) {
-      return undefined;
-    }
-    try {
-      return provider();
-    } catch (error) {
-      onError(error);
-      return undefined;
-    }
-  }
-
-  return {
-    compactMetadata,
-    isMetadataValue,
-    normalizeLogTraceContext,
-    traceFromProvider,
-    traceMetadataFromLogContext
-  };
-}
+const TRACE_ID_PATTERN = /^[0-9a-fA-F]{32}$/u;
+const SPAN_ID_PATTERN = /^[0-9a-fA-F]{16}$/u;
 
+/**
+ * @param {unknown} value
+ * @returns {value is MetadataValue}
+ */
 function isMetadataValue(value) {
   return (
     value === null
     || typeof value === "string"
-    || typeof value === "number" && Number.isFinite(value)
+    || (typeof value === "number" && Number.isFinite(value))
     || typeof value === "boolean"
   );
 }
 
-function traceMetadataFromLogContext(trace) {
-  const normalized = normalizeLogTraceContext(trace);
-  if (!normalized) {
+/**
+ * @param {unknown} metadata
+ * @returns {Metadata}
+ */
+function compactMetadata(metadata) {
+  if (metadata === undefined) {
     return {};
   }
-  return {
-    traceId: normalized.traceId,
-    spanId: normalized.spanId,
-    ...(normalized.parentSpanId !== undefined ? { parentSpanId: normalized.parentSpanId } : {}),
-    ...(normalized.sampled !== undefined ? { sampled: normalized.sampled } : {})
-  };
+  if (!isRecord(metadata)) {
+    throw new SdkError("validation_error", "metadata must be an object");
+  }
+  /** @type {Metadata} */
+  const safeMetadata = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (isMetadataValue(value)) {
+      safeMetadata[key] = value;
+    }
+  }
+  return safeMetadata;
 }
 
+/**
+ * @template Trace
+ * @param {(() => Trace) | null | undefined} provider
+ * @param {(error: unknown) => void} onError
+ * @returns {Trace | undefined}
+ */
+function traceFromProvider(provider, onError) {
+  if (!provider) {
+    return undefined;
+  }
+  try {
+    return provider();
+  } catch (error) {
+    onError(error);
+    return undefined;
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {Readonly<RegExp>} pattern
+ * @param {string} zeroValue
+ * @returns {string | undefined}
+ */
+function normalizeHexId(value, pattern, zeroValue) {
+  if (typeof value !== "string" || !pattern.test(value) || value.toLowerCase() === zeroValue) {
+    return undefined;
+  }
+  return value.toLowerCase();
+}
+
+/**
+ * @param {unknown} trace
+ * @returns {LogCorrelationTraceContext | undefined}
+ */
 function normalizeLogTraceContext(trace) {
-  if (!trace || Array.isArray(trace) || typeof trace !== "object") {
+  if (!isRecord(trace)) {
     return undefined;
   }
-  const traceId = normalizeHexId(trace.traceId, 32, ZERO_TRACE_ID);
-  const spanId = normalizeHexId(trace.spanId, 16, ZERO_SPAN_ID);
-  if (!traceId || !spanId) {
+  const traceId = normalizeHexId(trace["traceId"], TRACE_ID_PATTERN, ZERO_TRACE_ID);
+  const spanId = normalizeHexId(trace["spanId"], SPAN_ID_PATTERN, ZERO_SPAN_ID);
+  if (traceId === undefined || spanId === undefined) {
     return undefined;
   }
-  const parentSpanId = normalizeHexId(trace.parentSpanId, 16, ZERO_SPAN_ID);
+  const parentSpanId = normalizeHexId(trace["parentSpanId"], SPAN_ID_PATTERN, ZERO_SPAN_ID);
+  const { sampled } = trace;
   return {
     traceId,
+
     spanId,
-    ...(parentSpanId !== undefined ? { parentSpanId } : {}),
-    ...(typeof trace.sampled === "boolean" ? { sampled: trace.sampled } : {})
+    ...(parentSpanId === undefined ? {} : { parentSpanId }),
+    ...(typeof sampled === "boolean" ? { sampled } : {})
   };
 }
 
-function normalizeHexId(value, length, zeroValue) {
-  if (typeof value !== "string") {
-    return undefined;
-  }
-  const pattern = length === 32
-    ? /^[0-9a-fA-F]{32}$/u
-    : /^[0-9a-fA-F]{16}$/u;
-  if (!pattern.test(value) || value.toLowerCase() === zeroValue) {
-    return undefined;
-  }
-  return value.toLowerCase();
+/**
+ * @param {unknown} trace
+ * @returns {Metadata}
+ */
+function traceMetadataFromLogContext(trace) {
+  const normalized = normalizeLogTraceContext(trace);
+  return normalized === undefined ? {} : { ...normalized };
 }
 
-module.exports = { buildLogContextHelpers };
+module.exports = {
+  compactMetadata,
+  isMetadataValue,
+  normalizeLogTraceContext,
+  traceFromProvider,
+  traceMetadataFromLogContext
+};

package/metric-validation.cjs

@@ -0,0 +1,95 @@
+const { withMetadata } = require("./event-metadata.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { hasUnicodeControlCharacter, optionalEntry, requireAllowedValue, requireFiniteNumber, requireNonEmpty } = require("./validation.cjs");
+
+/**
+ * @import { EventAttributes } from "./event-validation.cjs"
+ * @typedef {"counter" | "gauge" | "histogram"} MetricKind
+ */
+
+const MAX_METRIC_DESCRIPTION_LENGTH = 1024;
+const MIN_METRIC_VALUE = 0;
+const FIRST_CODE_POINT = 0;
+const FIRST_SURROGATE = 0xD8_00;
+const LAST_SURROGATE = 0xDF_FF;
+const LINE_SEPARATOR = 0x20_28;
+const PARAGRAPH_SEPARATOR = 0x20_29;
+/** @type {ReadonlySet<MetricKind>} */
+const METRIC_KINDS = new Set(["counter", "gauge", "histogram"]);
+/** @type {ReadonlySet<MetricKind>} */
+const NON_NEGATIVE_METRIC_KINDS = new Set(["counter", "histogram"]);
+/** @type {ReadonlySet<string>} */
+const CUMULATIVE_TEMPORALITIES = new Set(["delta", "cumulative"]);
+/** @type {ReadonlyMap<MetricKind, ReadonlySet<string>>} */
+const METRIC_TEMPORALITIES_BY_KIND = new Map([
+  ["counter", CUMULATIVE_TEMPORALITIES],
+  ["gauge", new Set(["instant"])],
+  ["histogram", CUMULATIVE_TEMPORALITIES]
+]);
+
+/**
+ * @param {string} character
+ * @returns {boolean}
+ */
+function isSeparatorOrSurrogate(character) {
+  const code = character.codePointAt(FIRST_CODE_POINT);
+  return code !== undefined && (
+    (code >= FIRST_SURROGATE && code <= LAST_SURROGATE)
+    || code === LINE_SEPARATOR
+    || code === PARAGRAPH_SEPARATOR
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function metricDescriptionOrUndefined(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  const characters = typeof value === "string" ? [...value] : [];
+  if (
+    typeof value !== "string"
+    || value.trim() === ""
+    || characters.length > MAX_METRIC_DESCRIPTION_LENGTH
+    || hasUnicodeControlCharacter(value)
+    || characters.some((character) => isSeparatorOrSurrogate(character))
+  ) {
+    throw new SdkError(
+      "validation_error",
+      `metric description must be a non-blank string of at most ${MAX_METRIC_DESCRIPTION_LENGTH} non-control characters`
+    );
+  }
+  return value.trim();
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} attributes
+ * @returns {EventAttributes}
+ */
+function validateMetric(attributes) {
+  const name = requireNonEmpty("metric name", attributes["name"]);
+  const kind = requireAllowedValue("metric kind", attributes["kind"], METRIC_KINDS);
+  const value = requireFiniteNumber("metric value", attributes["value"]);
+  const unit = requireNonEmpty("metric unit", attributes["unit"]);
+  const allowedTemporalities = METRIC_TEMPORALITIES_BY_KIND.get(kind) ?? CUMULATIVE_TEMPORALITIES;
+  const temporality = requireAllowedValue(`metric temporality for ${kind}`, attributes["temporality"], allowedTemporalities);
+  if (NON_NEGATIVE_METRIC_KINDS.has(kind) && value < MIN_METRIC_VALUE) {
+    throw new SdkError("validation_error", `metric ${kind} value must be non-negative`);
+  }
+  const description = metricDescriptionOrUndefined(attributes["description"]);
+  return withMetadata({
+    name,
+    ...optionalEntry("description", description),
+    kind,
+
+    value,
+
+    unit,
+
+    temporality
+  }, attributes["metadata"], attributes["context"]);
+}
+
+module.exports = { validateMetric };

package/network-milestone.cjs

@@ -0,0 +1,155 @@
+const { ACTION_STATUSES } = require("./event-validation.cjs");
+const { compactMetadata } = require("./log-context.cjs");
+const { sanitizeRouteTemplate } = require("./product-action.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { isRecord, requireAllowedValue, requireNonEmpty, stringOrUndefined } = require("./validation.cjs");
+
+/**
+ * @import { ActionStatus, TimelineAttributes, TimelineOptions } from "./product-action.cjs"
+ * @typedef {{
+ *   durationMs: number | undefined,
+ *   metadata: unknown,
+ *   method: string,
+ *   name: string,
+ *   routeTemplate: string,
+ *   sessionId: unknown,
+ *   status: ActionStatus,
+ *   statusCode: number | undefined,
+ *   traceId: unknown
+ * }} NetworkMilestoneDetails
+ */
+
+const MIN_STATUS_CODE = 100;
+const MAX_STATUS_CODE = 599;
+const FAILURE_STATUS_CODE = 400;
+const MIN_DURATION_MS = 0;
+const HTTP_METHOD_PATTERN = /^[A-Z][A-Z0-9_-]*$/u;
+
+/**
+ * @param {unknown} method
+ * @returns {string}
+ */
+function normalizeHttpMethod(method) {
+  const value = method === undefined ? "GET" : method;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new SdkError("validation_error", "network milestone method must be a non-empty string");
+  }
+  const normalized = value.trim().toUpperCase();
+  if (!HTTP_METHOD_PATTERN.test(normalized)) {
+    throw new SdkError("validation_error", "network milestone method must be a valid HTTP method");
+  }
+  return normalized;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function statusCodeOrUndefined(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "number" || !Number.isInteger(value) || value < MIN_STATUS_CODE || value > MAX_STATUS_CODE) {
+    throw new SdkError("validation_error", "network milestone statusCode must be an integer from 100 to 599");
+  }
+  return value;
+}
+
+/**
+ * @param {string} label
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function nonNegativeNumberOrUndefined(label, value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value < MIN_DURATION_MS) {
+    throw new SdkError("validation_error", `${label} must be a non-negative number`);
+  }
+  return value;
+}
+
+/**
+ * @param {number | undefined} statusCode
+ * @returns {"failure" | "success"}
+ */
+function statusFromStatusCode(statusCode) {
+  return statusCode !== undefined && statusCode >= FAILURE_STATUS_CODE ? "failure" : "success";
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} request
+ * @returns {NetworkMilestoneDetails}
+ */
+function networkMilestoneFields(request) {
+  const routeTemplate = requireNonEmpty("network milestone routeTemplate", sanitizeRouteTemplate(request["routeTemplate"]));
+  const method = normalizeHttpMethod(request["method"]);
+  const statusCode = statusCodeOrUndefined(request["statusCode"]);
+  const requestedStatus = request["status"];
+  const status = requireAllowedValue(
+    "network milestone status",
+    requestedStatus === undefined ? statusFromStatusCode(statusCode) : requestedStatus,
+    ACTION_STATUSES
+  );
+  const durationMs = nonNegativeNumberOrUndefined("network milestone durationMs", request["durationMs"]);
+  const name = stringOrUndefined(request["name"]) ?? `network.${method.toLowerCase()} ${routeTemplate}`;
+  return {
+    durationMs,
+    metadata: request["metadata"],
+    method,
+    name,
+    routeTemplate,
+    sessionId: request["sessionId"],
+    status,
+    statusCode,
+    traceId: request["traceId"]
+  };
+}
+
+/**
+ * @param {unknown} request
+ * @returns {NetworkMilestoneDetails}
+ */
+function networkMilestoneDetails(request) {
+  if (typeof request === "string") {
+    return networkMilestoneFields({ routeTemplate: request });
+  }
+  if (!isRecord(request)) {
+    throw new SdkError("validation_error", "network milestone must be a string or object");
+  }
+  return networkMilestoneFields(request);
+}
+
+/**
+ * @param {unknown} request
+ * @param {TimelineOptions} [options]
+ * @returns {TimelineAttributes}
+ */
+function createNetworkMilestoneAttributes(request, options = {}) {
+  const details = networkMilestoneDetails(request);
+  return {
+    name: details.name,
+
+    status: details.status,
+
+    metadata: compactMetadata({
+      source: "network.milestone",
+      ...compactMetadata(options.metadata),
+      ...compactMetadata(details.metadata),
+      routeTemplate: details.routeTemplate,
+
+      method: details.method,
+
+      statusCode: details.statusCode,
+
+      durationMs: details.durationMs,
+
+      sessionId: stringOrUndefined(details.sessionId),
+
+      traceId: stringOrUndefined(details.traceId)
+    })
+  };
+}
+
+module.exports = { createNetworkMilestoneAttributes };

package/null-value.cjs

@@ -0,0 +1,4 @@
+/** @type {null} */
+const NULL_VALUE = null;
+
+module.exports = { NULL_VALUE };