feat: add diagnostics and telemetry runtime

src/contracts/telemetry.js

@@ -81,7 +81,7 @@ export const TELEMETRY_REGISTRY = Object.freeze({
     "http_status_group",
     "attempt_count_bucket",
     "route_id",
-  ]),
+  ], ["operation_id", "duration_bucket"]),
   "ui.render.failed": event("ui.render.failed", "React boundary catch", [
     "route_id",
     "build_id",
@@ -101,11 +101,44 @@ export const TELEMETRY_REGISTRY = Object.freeze({
   ),
 });
 
+const SAFE_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,63}$/;
+const ATTRIBUTE_VALUE_POLICIES =
+  /** @type {Readonly<Record<string, (value: string) => boolean>>} */ (
+    Object.freeze({
+      route_id: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
+      operation_id: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
+      error_kind: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
+      http_status_group: (value) => /^(?:[1-5]xx|none)$/.test(value),
+      attempt_count_bucket: (value) => /^(?:1|2|3|3-4|5\+)$/.test(value),
+      duration_bucket: (value) =>
+        /^(?:lt100ms|100-499ms|500-1999ms|gte2000ms|unknown)$/.test(
+          value,
+        ),
+      component_boundary: (value) =>
+        /^(?:route|feature|boot)$/.test(value),
+      mismatch_kind: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
+      reason: (value) =>
+        /^(?:queue-full|sink-failure|invalid-event|invalid-context|serialization-failure)$/.test(
+          value,
+        ),
+      queue_size_bucket: (value) =>
+        /^(?:0|1-10|11-50|51\+)$/.test(value),
+    })
+  );
+
+/** @param {string} key @param {unknown} value */
+function validAttributeValue(key, value) {
+  if (typeof value !== "string") return false;
+  const policy = ATTRIBUTE_VALUE_POLICIES[key];
+  return policy ? policy(value) : SAFE_IDENTIFIER.test(value);
+}
+
 /**
  * @param {string} eventName
  * @param {Record<string, unknown>} attributes
+ * @param {() => number} [now]
  */
-export function projectTelemetryEvent(eventName, attributes) {
+function projectTelemetryEventUnsafe(eventName, attributes, now = Date.now) {
   const registry =
     /** @type {Record<string, (typeof TELEMETRY_REGISTRY)[keyof typeof TELEMETRY_REGISTRY]>} */ (
       TELEMETRY_REGISTRY
@@ -118,13 +151,47 @@ export function projectTelemetryEvent(eventName, attributes) {
     };
   }
 
+  const attributeKeys = Object.keys(attributes);
+  if (
+    attributeKeys.length >
+    TELEMETRY_ATTRIBUTE_ALLOWLIST.length +
+      TELEMETRY_FORBIDDEN_ATTRIBUTES.length
+  ) {
+    return {
+      success: /** @type {false} */ (false),
+      reason: "invalid-attribute-value",
+    };
+  }
+  const unknown = attributeKeys.filter(
+    (key) =>
+      !TELEMETRY_ATTRIBUTE_ALLOWLIST.includes(key) &&
+      !TELEMETRY_FORBIDDEN_ATTRIBUTES.includes(key),
+  );
+  if (unknown.length > 0) {
+    return {
+      success: /** @type {false} */ (false),
+      reason: "unknown-attributes",
+    };
+  }
   const projected = Object.fromEntries(
     Object.entries(attributes).filter(
-      ([key]) =>
+      ([key, value]) =>
         TELEMETRY_ATTRIBUTE_ALLOWLIST.includes(key) &&
-        !TELEMETRY_FORBIDDEN_ATTRIBUTES.includes(key),
+        !TELEMETRY_FORBIDDEN_ATTRIBUTES.includes(key) &&
+        validAttributeValue(key, value),
     ),
   );
+  const invalid = Object.entries(attributes).filter(
+    ([key, value]) =>
+      TELEMETRY_ATTRIBUTE_ALLOWLIST.includes(key) &&
+      !validAttributeValue(key, value),
+  );
+  if (invalid.length > 0) {
+    return {
+      success: /** @type {false} */ (false),
+      reason: "invalid-attribute-value",
+    };
+  }
   const missing = definition.requiredAttributes.filter(
     (key) => projected[key] === undefined,
   );
@@ -135,11 +202,34 @@ export function projectTelemetryEvent(eventName, attributes) {
     };
   }
 
+  let timestamp;
+  try {
+    timestamp = new Date(now()).toISOString();
+  } catch {
+    timestamp = new Date(0).toISOString();
+  }
   return {
     success: /** @type {true} */ (true),
     event: Object.freeze({
       eventName,
+      timestamp,
       attributes: Object.freeze(projected),
     }),
   };
 }
+
+/**
+ * @param {string} eventName
+ * @param {Record<string, unknown>} attributes
+ * @param {() => number} [now]
+ */
+export function projectTelemetryEvent(eventName, attributes, now = Date.now) {
+  try {
+    return projectTelemetryEventUnsafe(eventName, attributes, now);
+  } catch {
+    return {
+      success: /** @type {false} */ (false),
+      reason: "serialization-failure",
+    };
+  }
+}