@geonosis/observability 1.0.0

package/dist/chunk-2ZTQU3OO.js

@@ -0,0 +1,161 @@
+// src/attributes.ts
+import { Result, TaggedError as tagged } from "better-result";
+var ATTRIBUTE_KEYS = [
+  "actor",
+  "envelopeId",
+  "release",
+  "runtime",
+  "service",
+  "tenant"
+];
+var SPAN_NAME_CONVENTION = "A span name is `<area>.<action>`, lowercase, at least two dot-separated segments, letters and digits with dashes inside a segment: `queue.handle-batch`, `db.cell.query`. A name is a dimension in every trace query, so `queue.handle-batch` and `Queue Handle Batch` in one tree are two dimensions where the author meant one.";
+var InvalidAttributes = class extends tagged("InvalidAttributes") {
+};
+var TENANT_IS_A_PERSON = "the tenant is a group id, never a person: it is the join key every dashboard fans out on, and the one field an erasure request cannot reach once an address is in it";
+var optionalStrings = [
+  "actor",
+  "envelopeId",
+  "release",
+  "runtime",
+  "tenant"
+];
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isAttributeValue = (value) => value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string";
+var tenantIsAPerson = (tenant) => tenant.includes("@");
+var problemsOf = (value) => {
+  if (!isRecord(value)) return ["attributes must be an object"];
+  const problems = [];
+  const service = value.service;
+  if (typeof service !== "string" || service.trim() === "") {
+    problems.push(
+      "attributes.service is required and must be a non-empty string: a report nobody can route to a service is a report nobody reads"
+    );
+  }
+  for (const key of optionalStrings) {
+    const one = value[key];
+    if (one !== void 0 && (typeof one !== "string" || one.trim() === "")) {
+      problems.push(`attributes.${key} must be a non-empty string when it is present`);
+    }
+  }
+  if (typeof value.tenant === "string" && tenantIsAPerson(value.tenant)) {
+    problems.push(`attributes.tenant "${value.tenant}" looks like a person \u2014 ${TENANT_IS_A_PERSON}`);
+  }
+  const extra = value.extra;
+  if (extra !== void 0) {
+    if (!isRecord(extra)) {
+      problems.push("attributes.extra must be an object");
+    } else {
+      for (const key of Object.keys(extra)) {
+        if (ATTRIBUTE_KEYS.includes(key)) {
+          problems.push(
+            `attributes.extra.${key} shadows the vocabulary's own "${key}" \u2014 a report with two answers for one question has none`
+          );
+        }
+        if (!isAttributeValue(extra[key])) {
+          problems.push(
+            `attributes.extra.${key} must be a string, number, boolean or null \u2014 a vendor puts these on a wire without a serializer of its own`
+          );
+        }
+      }
+    }
+  }
+  return problems;
+};
+var attributesOf = (value) => {
+  const taken = { service: value.service };
+  for (const key of optionalStrings) {
+    if (value[key] !== void 0) taken[key] = value[key];
+  }
+  if (value.extra !== void 0) taken.extra = value.extra;
+  return taken;
+};
+var parseAttributes = (value) => {
+  const problems = problemsOf(value);
+  if (problems.length > 0) {
+    return Result.err(new InvalidAttributes({ message: problems.join("; ") }));
+  }
+  return Result.ok(attributesOf(value));
+};
+var attributesSchema = (z) => {
+  const zod = z;
+  const text = () => zod.string().min(1);
+  const extraValue = zod.union([zod.string(), zod.number(), zod.boolean(), zod.null()]);
+  return zod.object({
+    actor: text().optional(),
+    envelopeId: text().optional(),
+    extra: zod.record(zod.string().min(0), extraValue).optional(),
+    release: text().optional(),
+    runtime: text().optional(),
+    service: zod.string().min(1),
+    tenant: text().optional()
+  }).check((context) => {
+    for (const problem of problemsOf(context.value)) {
+      context.issues.push({ code: "custom", input: context.value, message: problem, path: [] });
+    }
+  });
+};
+
+// src/ports.ts
+import { TaggedError as tagged2 } from "better-result";
+var SinkFailure = class extends tagged2("SinkFailure") {
+};
+
+// src/uuid.ts
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var isUuid = (value) => UUID.test(value);
+var NAMESPACE = "a3c2b1f0-6d84-4b9e-9f27-1c5e0d3a7b48";
+var bytesOfUuid = (uuid) => {
+  const hex2 = uuid.replaceAll("-", "");
+  const bytes = new Uint8Array(16);
+  for (let index = 0; index < 16; index += 1) {
+    bytes[index] = Number.parseInt(hex2.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+};
+var hex = (bytes) => [...bytes].map((one) => one.toString(16).padStart(2, "0")).join("");
+var webCrypto = () => globalThis.crypto ?? {};
+var sha1 = async (data) => {
+  const subtle = webCrypto().subtle;
+  if (subtle === void 0 || typeof subtle.digest !== "function") {
+    throw new TypeError(
+      "crypto.subtle is not available in this runtime, so an envelope id that is not already a UUID cannot be derived into a stable one. Node 19+, workerd and every browser have it."
+    );
+  }
+  return new Uint8Array(await subtle.digest("SHA-1", data));
+};
+var uuidFrom = async (value, inNamespace = NAMESPACE) => {
+  const namespace = bytesOfUuid(inNamespace);
+  const name = new TextEncoder().encode(value);
+  const input = new Uint8Array(namespace.length + name.length);
+  input.set(namespace, 0);
+  input.set(name, namespace.length);
+  const digest = (await sha1(input)).slice(0, 16);
+  digest[6] = (digest[6] ?? 0) & 15 | 80;
+  digest[8] = (digest[8] ?? 0) & 63 | 128;
+  const text = hex(digest);
+  return `${text.slice(0, 8)}-${text.slice(8, 12)}-${text.slice(12, 16)}-${text.slice(16, 20)}-${text.slice(20)}`;
+};
+var randomUuid = () => {
+  const crypto = webCrypto();
+  if (typeof crypto.randomUUID !== "function") {
+    throw new TypeError("crypto.randomUUID is not available in this runtime");
+  }
+  return crypto.randomUUID();
+};
+var uuidForEnvelope = async (envelopeId) => {
+  if (envelopeId === void 0) return randomUuid();
+  return isUuid(envelopeId) ? envelopeId : uuidFrom(envelopeId);
+};
+
+export {
+  ATTRIBUTE_KEYS,
+  SPAN_NAME_CONVENTION,
+  InvalidAttributes,
+  parseAttributes,
+  attributesSchema,
+  SinkFailure,
+  isUuid,
+  uuidFrom,
+  randomUuid,
+  uuidForEnvelope
+};

package/dist/chunk-EJS3A3ZV.js

@@ -0,0 +1,82 @@
+import {
+  SinkFailure,
+  parseAttributes,
+  uuidForEnvelope
+} from "./chunk-2ZTQU3OO.js";
+
+// src/posthog/index.ts
+import { Result } from "better-result";
+var defaultIdentity = (attributes) => attributes.actor ?? attributes.tenant ?? attributes.service;
+var propertiesOf = (attributes, groupName) => ({
+  ...attributes.extra,
+  ...attributes.envelopeId === void 0 ? {} : { envelopeId: attributes.envelopeId },
+  ...attributes.release === void 0 ? {} : { release: attributes.release },
+  ...attributes.runtime === void 0 ? {} : { runtime: attributes.runtime },
+  service: attributes.service,
+  ...attributes.tenant === void 0 ? {} : (
+    // `captureException` takes no groups of its own, and `$groups` is the wire property `groups`
+    // becomes — so an exception is filed under its organisation like everything else rather than
+    // floating free of one. during.day spells it by hand for the same reason.
+    { $groups: { [groupName]: attributes.tenant }, tenant: attributes.tenant }
+  )
+});
+var failureOf = (cause) => new SinkFailure({
+  cause,
+  message: cause instanceof Error ? cause.message : String(cause),
+  sink: "posthog"
+});
+var createPostHogSink = ({
+  groupName = "organization",
+  identityOf = defaultIdentity,
+  newClient
+}) => {
+  let buffered = [];
+  const send = async (taken) => {
+    const refusals = [];
+    try {
+      const client = newClient(taken.length);
+      client.on("error", (one) => refusals.push(one));
+      for (const one of taken) {
+        client.captureException(
+          one.error,
+          identityOf(one.attributes),
+          propertiesOf(one.attributes, groupName),
+          one.uuid
+        );
+      }
+      await client.shutdown();
+      return refusals.length === 0 ? Result.ok(void 0) : Result.err(failureOf(refusals[0]));
+    } catch (cause) {
+      return Result.err(failureOf(cause));
+    }
+  };
+  const flushable = () => {
+    const taken = buffered;
+    buffered = [];
+    return {
+      pending: taken.length,
+      promise: taken.length === 0 ? Promise.resolve(Result.ok(void 0)) : send(taken)
+    };
+  };
+  return {
+    capture: async (error, attributes) => {
+      const parsed = parseAttributes(attributes);
+      if (parsed.isErr()) return Result.err(failureOf(parsed.error));
+      const taken = parsed.unwrap();
+      try {
+        const uuid = await uuidForEnvelope(taken.envelopeId);
+        buffered.push({ attributes: taken, error, uuid });
+        return Result.ok({ deduplicated: false, id: uuid });
+      } catch (cause) {
+        return Result.err(failureOf(cause));
+      }
+    },
+    flush: () => flushable().promise,
+    flushable,
+    kind: "posthog"
+  };
+};
+
+export {
+  createPostHogSink
+};

package/dist/chunk-UFR2R2VM.js

@@ -0,0 +1,141 @@
+import {
+  SinkFailure,
+  parseAttributes,
+  randomUuid
+} from "./chunk-2ZTQU3OO.js";
+
+// src/memory.ts
+import { Result } from "better-result";
+var idFor = (attributes) => attributes.envelopeId ?? randomUuid();
+var createMemorySink = (options = {}) => {
+  const now = options.now ?? Date.now;
+  const captured = [];
+  let flushes = 0;
+  return {
+    capture: (error, attributes) => {
+      const parsed = parseAttributes(attributes);
+      if (parsed.isErr()) {
+        return Promise.resolve(
+          Result.err(
+            new SinkFailure({
+              cause: parsed.error,
+              message: parsed.error.message,
+              sink: "memory"
+            })
+          )
+        );
+      }
+      const taken = parsed.unwrap();
+      const id = idFor(taken);
+      captured.push({ at: now(), attributes: taken, error, id });
+      return Promise.resolve(Result.ok({ deduplicated: false, id }));
+    },
+    get captured() {
+      return captured;
+    },
+    clear: () => {
+      captured.length = 0;
+    },
+    flush: () => {
+      flushes += 1;
+      return Promise.resolve(Result.ok(void 0));
+    },
+    get flushes() {
+      return flushes;
+    },
+    kind: "memory"
+  };
+};
+var createSwallowingSink = () => ({
+  capture: (_error, attributes) => Promise.resolve(Result.ok({ deduplicated: false, id: idFor(attributes) })),
+  flush: () => Promise.resolve(Result.ok(void 0)),
+  kind: "swallowing"
+});
+
+// src/prove.ts
+var PROBE_SERVICE = "geonosis-observability-probe";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var POLL_MS = 50;
+var sleep = (ms) => new Promise((resolve) => {
+  setTimeout(resolve, ms);
+});
+var memoryProbe = () => {
+  const sink = createMemorySink();
+  return {
+    kind: sink.kind,
+    seen: () => Promise.resolve(sink.captured.map((one) => one.id)),
+    sink
+  };
+};
+var lookFor = async ({
+  deadline,
+  probe,
+  traceId
+}) => {
+  for (; ; ) {
+    const found = await probe.seen(traceId);
+    if (found.includes(traceId)) return found;
+    if (Date.now() >= deadline) return found;
+    await sleep(POLL_MS);
+  }
+};
+var proveObservability = async ({
+  attributes,
+  probe,
+  timeoutMs = DEFAULT_TIMEOUT_MS
+}) => {
+  if (probe === void 0) {
+    return { kind: "none", reason: "no sink configured", verdict: "cannot-measure" };
+  }
+  const traceId = randomUuid();
+  try {
+    const planted = await probe.sink.capture(
+      new Error(`geonosis observability probe ${traceId} \u2014 planted, not a real incident`),
+      { service: PROBE_SERVICE, ...attributes, envelopeId: traceId }
+    );
+    if (planted.isErr()) {
+      return {
+        kind: probe.kind,
+        reason: `the sink refused the plant: ${planted.error.message}`,
+        traceId,
+        verdict: "cannot-measure"
+      };
+    }
+    const flushed = await probe.sink.flush();
+    if (flushed.isErr()) {
+      return {
+        kind: probe.kind,
+        reason: `the sink took the plant and could not flush it: ${flushed.error.message}`,
+        traceId,
+        verdict: "cannot-measure"
+      };
+    }
+    const found = await lookFor({ deadline: Date.now() + timeoutMs, probe, traceId });
+    if (found.includes(traceId)) return { found, kind: probe.kind, traceId, verdict: "proven" };
+    return found.length === 0 ? { found, kind: probe.kind, traceId, verdict: "cannot-fail" } : { found, kind: probe.kind, traceId, verdict: "misread" };
+  } finally {
+    await probe.close?.();
+  }
+};
+var formatProof = (proof) => {
+  if (proof.verdict === "proven") {
+    return `PROVEN observability: the planted error reached ${proof.kind} as ${proof.traceId}`;
+  }
+  if (proof.verdict === "cannot-fail") return "CANNOT FAIL: the sink swallowed it";
+  if (proof.verdict === "misread") {
+    return `MISREAD: ${proof.kind} kept ${proof.found?.length ?? 0} report(s) but not the planted ${proof.traceId} \u2014 it holds ${(proof.found ?? []).join(", ")}, so every lookup with the id the caller was handed comes back empty`;
+  }
+  return `CANNOT MEASURE: ${proof.reason ?? "the probe could not be run"}`;
+};
+var exitCodeOf = (proof) => proof.verdict === "proven" ? 0 : 2;
+
+export {
+  idFor,
+  createMemorySink,
+  createSwallowingSink,
+  PROBE_SERVICE,
+  memoryProbe,
+  proveObservability,
+  formatProof,
+  exitCodeOf
+};

package/dist/health/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The tiered dependency registry.
+ *
+ * during.day's `healthStatus` runs every probe on every call, in parallel, with no tier, no TTL and
+ * no timeout, and answers 503 if ANY of them failed. Its own comment records why the probes exist
+ * at all: "a check that answers for itself answers `ok` while the database behind it is gone;
+ * production returned 200 to every probe while its pages threw."
+ *
+ * Three things are missing from that, and each of them is why a real check does not get added:
+ *
+ *  - **No timeout.** A probe that hangs hangs the endpoint. A check that never answers is not a
+ *    check that failed, and a load balancer reads the difference as its own timeout.
+ *  - **No tier.** Wire a probe for a mail provider and its outage takes production down to report a
+ *    degradation. So nobody wires it, and you are back to a `/health` that checks nothing.
+ *  - **No TTL.** A load balancer at 1 Hz is a query per second per instance of pure liveness
+ *    traffic, which is what makes a real probe feel expensive.
+ *
+ * Midday's `packages/health/src/registry.ts` has all three, and the split this takes from it:
+ * `ready()` answers ONLY for tier 1 — is it safe to send traffic here — and `dependencies()`
+ * reports every tier. No framework is imported; the Hono and `node:http` fixtures are in the README
+ * because a health registry that depended on a server could not be used by the other one.
+ */
+type HealthTier = 1 | 2 | 3 | 4;
+type HealthDependency = {
+    /** Whatever proves the thing is really there. It throws, or it does not. */
+    check: () => Promise<unknown>;
+    name: string;
+    /** 1 core (traffic must not be sent without it) … 4 optional. */
+    tier: HealthTier;
+    /** How long a good answer may be reused. Absent means every call runs the check. */
+    ttlMs?: number;
+    /** How long to wait before calling it dead. 5s by default; a hang is a failure, not a wait. */
+    timeoutMs?: number;
+};
+type DependencyStatus = {
+    /** True when this answer came from inside its TTL rather than from a check that just ran. */
+    cached: boolean;
+    detail?: string;
+    durationMs: number;
+    name: string;
+    ok: boolean;
+    tier: HealthTier;
+};
+type HealthReport = {
+    /** Any dependency in this report failed — including one whose tier does not take traffic out. */
+    degraded: boolean;
+    dependencies: readonly DependencyStatus[];
+    /** Every TIER-1 dependency answered. This is the one a load balancer reads. */
+    ok: boolean;
+    status: 200 | 503;
+};
+type HealthRegistry = {
+    /** Every tier, for a human and for a dashboard. Its `status` still follows tier 1 alone. */
+    dependencies: () => Promise<HealthReport>;
+    /** Tier 1 only. 503 when any of them failed or timed out. */
+    ready: () => Promise<HealthReport>;
+};
+declare const createHealthRegistry: ({ dependencies, now, }: {
+    dependencies: readonly HealthDependency[];
+    now?: () => number;
+}) => HealthRegistry;
+
+export { type DependencyStatus, type HealthDependency, type HealthRegistry, type HealthReport, type HealthTier, createHealthRegistry };

package/dist/health/index.js

@@ -0,0 +1,89 @@
+// src/health/index.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+var TIERS = [1, 2, 3, 4];
+var detailOf = (thrown) => thrown instanceof Error ? thrown.message : String(thrown);
+var TimedOut = class extends Error {
+};
+var ran = async (dependency, now) => {
+  const timeoutMs = dependency.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const started = now();
+  let timer;
+  try {
+    await Promise.race([
+      dependency.check(),
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new TimedOut(`timed out after ${timeoutMs}ms`)), timeoutMs);
+      })
+    ]);
+    return { durationMs: now() - started, ok: true };
+  } catch (thrown) {
+    return { detail: detailOf(thrown), durationMs: now() - started, ok: false };
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+};
+var declared = (dependencies) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const one of dependencies) {
+    if (typeof one.name !== "string" || one.name.trim() === "") {
+      throw new TypeError(
+        "a health dependency must have a name: it is what a 503 names, and a dependency nobody can name is one nobody can go and look at"
+      );
+    }
+    if (!TIERS.includes(one.tier)) {
+      throw new TypeError(
+        `health dependency "${one.name}" has tier ${String(one.tier)} \u2014 the tiers are 1 (core) to 4 (optional), and a dependency outside them cannot be told from one that takes traffic out`
+      );
+    }
+    if (seen.has(one.name)) {
+      throw new TypeError(
+        `two health dependencies are called "${one.name}" \u2014 a report with two answers under one name has none`
+      );
+    }
+    seen.add(one.name);
+  }
+  return [...dependencies].toSorted((a, b) => a.tier - b.tier || a.name.localeCompare(b.name));
+};
+var createHealthRegistry = ({
+  dependencies,
+  now = Date.now
+}) => {
+  const ordered = declared(dependencies);
+  const cache = /* @__PURE__ */ new Map();
+  const statusOf = async (dependency) => {
+    const ttlMs = dependency.ttlMs;
+    const held = cache.get(dependency.name);
+    if (ttlMs !== void 0 && held !== void 0 && now() - held.at <= ttlMs) {
+      return { ...held.status, cached: true };
+    }
+    const outcome = await ran(dependency, now);
+    const status = {
+      cached: false,
+      ...outcome.detail === void 0 ? {} : { detail: outcome.detail },
+      durationMs: outcome.durationMs,
+      name: dependency.name,
+      ok: outcome.ok,
+      tier: dependency.tier
+    };
+    if (ttlMs !== void 0 && status.ok) cache.set(dependency.name, { at: now(), status });
+    return status;
+  };
+  const reportOver = async (chosen) => {
+    const statuses = await Promise.all(chosen.map((one) => statusOf(one)));
+    const core = statuses.filter((one) => one.tier === 1);
+    const ok = core.length > 0 && core.every((one) => one.ok);
+    return {
+      degraded: statuses.some((one) => !one.ok),
+      dependencies: statuses,
+      ok,
+      status: ok ? 200 : 503
+    };
+  };
+  return {
+    dependencies: () => reportOver(ordered),
+    ready: () => reportOver(ordered.filter((one) => one.tier === 1))
+  };
+};
+export {
+  createHealthRegistry
+};