@prisma/streams-server 0.1.2 → 0.1.3

package/src/profiles/metrics.ts

@@ -0,0 +1,85 @@
+import { Result } from "better-result";
+import type {
+  StreamProfileDefinition,
+  StreamProfilePersistResult,
+  StreamProfileReadResult,
+} from "./profile";
+import { cloneStreamProfileSpec, expectPlainObjectResult, rejectUnknownKeysResult, normalizeProfileContentType } from "./profile";
+import { buildInternalMetricsRegistry, buildMetricsDefaultRegistry } from "./metrics/schema";
+import { normalizeMetricsRecordResult } from "./metrics/normalize";
+
+const INTERNAL_METRICS_STREAM = "__stream_metrics__";
+
+export type MetricsStreamProfile = {
+  kind: "metrics";
+};
+
+function cloneMetricsProfile(): MetricsStreamProfile {
+  return { kind: "metrics" };
+}
+
+function validateMetricsProfileResult(raw: unknown, path: string): Result<MetricsStreamProfile, { message: string }> {
+  const objRes = expectPlainObjectResult(raw, path);
+  if (Result.isError(objRes)) return objRes;
+  if (objRes.value.kind !== "metrics") return Result.err({ message: `${path}.kind must be metrics` });
+  const keyCheck = rejectUnknownKeysResult(objRes.value, ["kind"], path);
+  if (Result.isError(keyCheck)) return keyCheck;
+  return Result.ok(cloneMetricsProfile());
+}
+
+export const METRICS_STREAM_PROFILE_DEFINITION: StreamProfileDefinition = {
+  kind: "metrics",
+  usesStoredProfileRow: false,
+
+  defaultProfile(): MetricsStreamProfile {
+    return cloneMetricsProfile();
+  },
+
+  validateResult(raw, path) {
+    return validateMetricsProfileResult(raw, path);
+  },
+
+  readProfileResult(): Result<StreamProfileReadResult, { message: string }> {
+    return Result.ok({ profile: cloneMetricsProfile(), cache: null });
+  },
+
+  persistProfileResult({ db, registry, stream, streamRow, profile }): Result<StreamProfilePersistResult, { kind: "bad_request"; message: string }> {
+    if (profile.kind !== "metrics") return Result.err({ kind: "bad_request", message: "invalid metrics profile" });
+    const contentType = normalizeProfileContentType(streamRow.content_type);
+    if (contentType !== "application/json") {
+      return Result.err({
+        kind: "bad_request",
+        message: "metrics profile requires application/json stream content-type",
+      });
+    }
+    const desiredRegistry =
+      stream === INTERNAL_METRICS_STREAM ? buildInternalMetricsRegistry(stream) : buildMetricsDefaultRegistry(stream);
+    const registryRes = registry.replaceRegistryResult(stream, desiredRegistry);
+    if (Result.isError(registryRes)) return Result.err({ kind: "bad_request", message: registryRes.error.message });
+    db.updateStreamProfile(stream, "metrics");
+    db.deleteStreamProfile(stream);
+    db.deleteStreamTouchState(stream);
+    return Result.ok({
+      profile: cloneStreamProfileSpec(cloneMetricsProfile()),
+      cache: null,
+      schemaRegistry: registryRes.value,
+    });
+  },
+
+  jsonIngest: {
+    prepareRecordResult({ value }) {
+      const normalizedRes = normalizeMetricsRecordResult(value);
+      if (Result.isError(normalizedRes)) return normalizedRes;
+      return Result.ok({
+        value: normalizedRes.value.value,
+        routingKey: normalizedRes.value.routingKey,
+      });
+    },
+  },
+
+  metrics: {
+    normalizeRecordResult({ value }) {
+      return normalizeMetricsRecordResult(value);
+    },
+  },
+};

package/src/profiles/profile.ts

@@ -0,0 +1,225 @@
+import { Result } from "better-result";
+import type { SqliteDurableStore, StreamRow } from "../db/db";
+import type { SchemaRegistry, SchemaRegistryStore } from "../schema/registry";
+import type { TouchProcessorManager } from "../touch/manager";
+import type { CanonicalChange } from "../touch/canonical_change";
+import type { TouchConfig } from "../touch/spec";
+import type { AggSummaryState } from "../search/agg_format";
+
+export const STREAM_PROFILE_API_VERSION = "durable.streams/profile/v1" as const;
+export const DEFAULT_STREAM_PROFILE = "generic" as const;
+
+export type StreamProfileKind = string;
+
+export type StreamProfileSpec = {
+  kind: StreamProfileKind;
+  [key: string]: unknown;
+};
+
+export type StreamProfileResource = {
+  apiVersion: typeof STREAM_PROFILE_API_VERSION;
+  profile: StreamProfileSpec;
+};
+
+export type StreamProfileMutationError = {
+  kind: "bad_request";
+  message: string;
+  code?: string;
+};
+
+export type StreamProfileReadError = {
+  kind: "invalid_profile";
+  message: string;
+  code?: string;
+};
+
+export type StreamProfileValidationError = {
+  message: string;
+};
+
+export type StoredProfileRow = {
+  stream: string;
+  profile_json: string;
+  updated_at_ms: bigint;
+};
+
+export type CachedStreamProfile = {
+  profile: StreamProfileSpec;
+  updatedAtMs: bigint;
+};
+
+export type StreamProfileReadResult = {
+  profile: StreamProfileSpec;
+  cache: CachedStreamProfile | null;
+};
+
+export type StreamProfilePersistResult = {
+  profile: StreamProfileSpec;
+  cache: CachedStreamProfile | null;
+  schemaRegistry?: SchemaRegistry | null;
+};
+
+export type PersistProfileArgs = {
+  db: SqliteDurableStore;
+  registry: SchemaRegistryStore;
+  stream: string;
+  streamRow: StreamRow;
+  profile: StreamProfileSpec;
+};
+
+export type PreparedJsonRecord = {
+  value: unknown;
+  routingKey: string | null;
+};
+
+export type MetricsCompanionRecord = {
+  metric: string;
+  unit: string;
+  metricKind: string;
+  temporality: string;
+  windowStartMs: number;
+  windowEndMs: number;
+  intervalMs: number;
+  stream: string | null;
+  instance: string | null;
+  attributes: Record<string, string>;
+  dimensionPairs: string[];
+  dimensionKey: string | null;
+  seriesKey: string;
+  summary: AggSummaryState;
+};
+
+export type NormalizedMetricsRecord = PreparedJsonRecord & {
+  value: Record<string, unknown>;
+  companion: MetricsCompanionRecord;
+};
+
+export type StreamTouchRoute =
+  | { kind: "meta" }
+  | { kind: "wait" }
+  | { kind: "templates_activate" };
+
+export type StreamProfileTouchResponder = {
+  json(status: number, body: any, headers?: HeadersInit): Response;
+  badRequest(message: string): Response;
+  internalError(message?: string): Response;
+  notFound(message?: string): Response;
+};
+
+export type StreamTouchRouteArgs = {
+  route: StreamTouchRoute;
+  req: Request;
+  stream: string;
+  streamRow: StreamRow;
+  profile: StreamProfileSpec;
+  db: SqliteDurableStore;
+  touchManager: TouchProcessorManager;
+  respond: StreamProfileTouchResponder;
+};
+
+export interface StreamTouchCapability {
+  getTouchConfig(profile: StreamProfileSpec): TouchConfig | null;
+  syncState(args: { db: SqliteDurableStore; stream: string; profile: StreamProfileSpec }): void;
+  deriveCanonicalChanges(record: unknown, profile: StreamProfileSpec): CanonicalChange[];
+  handleRoute?(args: StreamTouchRouteArgs): Promise<Response>;
+}
+
+export interface StreamProfileJsonIngestCapability {
+  prepareRecordResult(args: { stream: string; profile: StreamProfileSpec; value: unknown }): Result<PreparedJsonRecord, StreamProfileValidationError>;
+}
+
+export interface StreamProfileMetricsCapability {
+  normalizeRecordResult(args: {
+    stream: string;
+    profile: StreamProfileSpec;
+    value: unknown;
+  }): Result<NormalizedMetricsRecord, StreamProfileValidationError>;
+}
+
+export interface StreamProfileDefinition {
+  kind: StreamProfileKind;
+  usesStoredProfileRow: boolean;
+  defaultProfile(): StreamProfileSpec;
+  validateResult(raw: unknown, path: string): Result<StreamProfileSpec, StreamProfileValidationError>;
+  readProfileResult(args: { row: StoredProfileRow | null; cached: CachedStreamProfile | null }): Result<StreamProfileReadResult, StreamProfileValidationError>;
+  persistProfileResult(args: PersistProfileArgs): Result<StreamProfilePersistResult, StreamProfileMutationError>;
+  touch?: StreamTouchCapability;
+  jsonIngest?: StreamProfileJsonIngestCapability;
+  metrics?: StreamProfileMetricsCapability;
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function expectPlainObjectResult(
+  value: unknown,
+  path: string
+): Result<Record<string, unknown>, StreamProfileValidationError> {
+  if (!isPlainObject(value)) return Result.err({ message: `${path} must be an object` });
+  return Result.ok(value);
+}
+
+export function rejectUnknownKeysResult(
+  obj: Record<string, unknown>,
+  allowed: readonly string[],
+  path: string
+): Result<void, StreamProfileValidationError> {
+  const allowedSet = new Set(allowed);
+  for (const key of Object.keys(obj)) {
+    if (!allowedSet.has(key)) return Result.err({ message: `${path}.${key} is not supported` });
+  }
+  return Result.ok(undefined);
+}
+
+export function normalizeProfileContentType(value: string | null): string | null {
+  if (!value) return null;
+  const base = value.split(";")[0]?.trim().toLowerCase();
+  return base ? base : null;
+}
+
+export function parseStoredProfileJsonResult(raw: string): Result<unknown, StreamProfileValidationError> {
+  try {
+    return Result.ok(JSON.parse(raw));
+  } catch (e: any) {
+    return Result.err({ message: String(e?.message ?? e) });
+  }
+}
+
+export function readProfileKindResult(
+  raw: unknown,
+  path = "profile"
+): Result<StreamProfileKind, StreamProfileValidationError> {
+  const objRes = expectPlainObjectResult(raw, path);
+  if (Result.isError(objRes)) return objRes;
+  const kind = typeof objRes.value.kind === "string" ? objRes.value.kind.trim() : "";
+  if (kind !== "") return Result.ok(kind);
+  return Result.err({ message: `${path}.kind must be a non-empty string` });
+}
+
+export function parseProfileUpdateEnvelopeResult(body: unknown): Result<unknown, StreamProfileValidationError> {
+  const bodyRes = expectPlainObjectResult(body, "profile update");
+  if (Result.isError(bodyRes)) {
+    return Result.err({ message: "profile update must be a JSON object" });
+  }
+  const keyCheck = rejectUnknownKeysResult(bodyRes.value, ["apiVersion", "profile"], "profileUpdate");
+  if (Result.isError(keyCheck)) return keyCheck;
+  if (bodyRes.value.apiVersion !== undefined && bodyRes.value.apiVersion !== STREAM_PROFILE_API_VERSION) {
+    return Result.err({ message: "invalid profile apiVersion" });
+  }
+  if (!Object.prototype.hasOwnProperty.call(bodyRes.value, "profile")) {
+    return Result.err({ message: "missing profile" });
+  }
+  return Result.ok(bodyRes.value.profile);
+}
+
+export function cloneStreamProfileSpec(profile: StreamProfileSpec): StreamProfileSpec {
+  return structuredClone(profile);
+}
+
+export function buildStreamProfileResource(profile: StreamProfileSpec): StreamProfileResource {
+  return {
+    apiVersion: STREAM_PROFILE_API_VERSION,
+    profile: cloneStreamProfileSpec(profile),
+  };
+}

package/src/{touch/engine.ts → profiles/stateProtocol/changes.ts}

@@ -1,23 +1,10 @@
-import type { StreamInterpreterConfig } from "./spec.ts";
+import type { CanonicalChange } from "../../touch/canonical_change";
 
-export type CanonicalChange = {
-  entity: string;
-  key?: string;
-  op: "insert" | "update" | "delete";
-  before?: unknown;
-  after?: unknown;
-};
-
-export function interpretRecordToChanges(record: any, _cfg: StreamInterpreterConfig): CanonicalChange[] {
-  return interpretStateProtocolRecord(record);
-}
-
-function interpretStateProtocolRecord(record: any): CanonicalChange[] {
+export function deriveStateProtocolChanges(record: unknown): CanonicalChange[] {
   if (!record || typeof record !== "object" || Array.isArray(record)) return [];
   const headers = (record as any).headers;
   if (!headers || typeof headers !== "object" || Array.isArray(headers)) return [];
 
-  // Control messages are ignored by touch derivation.
   if (typeof (headers as any).control === "string") return [];
 
   const opRaw = (headers as any).operation;
@@ -30,11 +17,7 @@ function interpretStateProtocolRecord(record: any): CanonicalChange[] {
   if (typeof type !== "string" || type.trim() === "") return [];
   if (typeof key !== "string" || key.trim() === "") return [];
 
-  const before = Object.prototype.hasOwnProperty.call(record, "oldValue")
-    ? (record as any).oldValue
-    : Object.prototype.hasOwnProperty.call(record, "old_value")
-      ? (record as any).old_value
-      : undefined;
+  const before = Object.prototype.hasOwnProperty.call(record, "oldValue") ? (record as any).oldValue : undefined;
   const after = Object.prototype.hasOwnProperty.call(record, "value") ? (record as any).value : undefined;
 
   return [{ entity: type, key, op, before, after }];