Skip to content

The Open Standard for Generative UI

7.4 KB
Raw Blame
import type { OpenUIError, ParseResult } from "@openuidev/lang-core";
import { observability } from "@openuidev/observability";
import { useEffect, useRef } from "react";
import {
  STREAM_EVENT_KIND,
  STREAM_PHASE_SETTLED,
  STREAM_PHASE_STREAMING,
  STREAM_PHASE_UNMOUNTED,
  type SettledStreamEventDetail,
  type StreamPhase,
} from "./streamEvent";

type CurrentRef<T> = { current: T };

export interface UseStreamingObservabilityOptions {
  response: string | null;
  isStreaming: boolean;
  result: ParseResult | null;
  errorsRef: CurrentRef<OpenUIError[]>;
  errorRevision: number;
  publish?: boolean;
  /** `createLibrary()` instance id, echoed on stream events for Debug matching. */
  __libraryId?: string;
}

export interface StreamingObservabilityState {
  id: string | null;
  updateIndex: number;
  lastResponse: string | null;
  hasPublishedStreamingSnapshot: boolean;
  settled: boolean;
  lastSettledErrorKey: string | null;
  /** Epoch ms when this stream first published. Frozen across later snapshots. */
  startedAt: number | null;
  /** Frozen once the stream first settles, so later error republishes don't grow it. */
  durationMs: number | null;
}

export interface StreamingObservabilityUpdate {
  id: string;
  phase: StreamPhase;
  updateIndex: number;
}

let fallbackId = 0;

function createStreamId(): string {
  if (typeof globalThis.crypto?.randomUUID === "function") {
    return globalThis.crypto.randomUUID();
  }
  fallbackId += 1;
  return `openui-lang-${Date.now().toString(36)}-${fallbackId.toString(36)}`;
}

export function createStreamingObservabilityState(): StreamingObservabilityState {
  return {
    id: null,
    updateIndex: 0,
    lastResponse: null,
    hasPublishedStreamingSnapshot: false,
    settled: false,
    lastSettledErrorKey: null,
    startedAt: null,
    durationMs: null,
  };
}

function captureStreamTiming(state: StreamingObservabilityState, now = Date.now()) {
  state.startedAt ??= now;
  if (state.settled) {
    state.durationMs ??= Math.max(0, now - state.startedAt);
  }
  const elapsedMs = state.durationMs ?? Math.max(0, now - state.startedAt);
  return {
    startedAt: state.startedAt,
    elapsedMs,
    ...(state.durationMs != null ? { durationMs: state.durationMs } : {}),
  };
}

/** Advances a Renderer through successive stream lifecycles. */
export function advanceStreamingObservability(
  state: StreamingObservabilityState,
  isStreaming: boolean,
  response: string | null,
  settledErrorKey: string | null = null,
  idFactory: () => string = createStreamId,
): StreamingObservabilityUpdate | null {
  if (isStreaming) {
    // A mounted Renderer can be reused for another message. Once the previous
    // stream has settled, the next streaming transition starts a new identity.
    if (state.settled) Object.assign(state, createStreamingObservabilityState());

    state.id ??= idFactory();
    if (state.hasPublishedStreamingSnapshot && state.lastResponse === response) return null;

    state.hasPublishedStreamingSnapshot = true;
    state.lastResponse = response;
    state.updateIndex += 1;
    return { id: state.id, phase: STREAM_PHASE_STREAMING, updateIndex: state.updateIndex };
  }

  // A Renderer mounted only for static or historical content never starts a stream.
  if (!state.id) return null;
  if (
    state.settled &&
    (settledErrorKey === null || state.lastSettledErrorKey === settledErrorKey)
  ) {
    return null;
  }

  state.updateIndex += 1;
  state.settled = true;
  state.lastSettledErrorKey = settledErrorKey;
  return { id: state.id, phase: STREAM_PHASE_SETTLED, updateIndex: state.updateIndex };
}

/** Ends a stream whose Renderer unmounted before it settled. */
export function unmountStreamingObservability(
  state: StreamingObservabilityState,
): StreamingObservabilityUpdate | null {
  if (!state.id || state.settled) return null;
  state.updateIndex += 1;
  // A StrictMode remount reuses this state; let it republish the stream it resumes.
  state.hasPublishedStreamingSnapshot = false;
  return { id: state.id, phase: STREAM_PHASE_UNMOUNTED, updateIndex: state.updateIndex };
}

function parserMetadata(result: ParseResult | null) {
  if (!result) return undefined;
  return {
    incomplete: result.meta.incomplete,
    unresolved: result.meta.unresolved,
    orphaned: result.meta.orphaned,
    statementCount: result.meta.statementCount,
  };
}

/**
 * Publishes the incremental OpenUI Lang stream lifecycle. The stable id is
 * created only after this Renderer instance has actually entered streaming.
 */
export function useStreamingObservability({
  response,
  isStreaming,
  result,
  errorsRef,
  errorRevision,
  publish = true,
  __libraryId,
}: UseStreamingObservabilityOptions): void {
  const streamRef = useRef<StreamingObservabilityState>(createStreamingObservabilityState());
  const lastStreamingRef = useRef<{ result: ParseResult | null; __libraryId?: string }>({
    result: null,
  });

  useEffect(() => {
    const stream = streamRef.current;
    return () => {
      const update = unmountStreamingObservability(stream);
      if (!update) return;
      const { result: lastResult, __libraryId: lastLibraryId } = lastStreamingRef.current;
      const startedAt = stream.startedAt ?? Date.now();
      const durationMs = Math.max(0, Date.now() - startedAt);
      observability.warn({
        id: update.id,
        kind: STREAM_EVENT_KIND,
        phase: update.phase,
        updateIndex: update.updateIndex,
        response: stream.lastResponse,
        responseLength: stream.lastResponse?.length ?? 0,
        parser: parserMetadata(lastResult),
        startedAt,
        elapsedMs: durationMs,
        durationMs,
        ...(lastLibraryId !== undefined ? { __libraryId: lastLibraryId } : {}),
        message: "Stream interrupted",
      });
    };
  }, []);

  useEffect(() => {
    if (!publish) return;
    const errors = errorsRef.current;
    const settledErrorKey = isStreaming ? null : JSON.stringify(errors);
    const update = advanceStreamingObservability(
      streamRef.current,
      isStreaming,
      response,
      settledErrorKey,
    );
    const libraryIdFields = __libraryId !== undefined ? { __libraryId } : {};

    if (isStreaming) {
      if (update) {
        lastStreamingRef.current = { result, __libraryId };
        observability.info({
          id: update.id,
          kind: STREAM_EVENT_KIND,
          phase: update.phase,
          updateIndex: update.updateIndex,
          response,
          responseLength: response?.length ?? 0,
          parser: parserMetadata(result),
          ...captureStreamTiming(streamRef.current),
          ...libraryIdFields,
          message: "OpenUI Lang is streaming",
        });
      }
      return;
    }

    if (update?.phase === STREAM_PHASE_SETTLED) {
      observability(errors.length > 0 ? "error" : "info", {
        id: update.id,
        kind: STREAM_EVENT_KIND,
        phase: STREAM_PHASE_SETTLED,
        updateIndex: update.updateIndex,
        response,
        responseLength: response?.length ?? 0,
        parser: parserMetadata(result),
        errors,
        errorCount: errors.length,
        ...captureStreamTiming(streamRef.current),
        ...libraryIdFields,
        message:
          errors.length > 0
            ? `OpenUI Lang settled with ${errors.length} error${errors.length === 1 ? "" : "s"}`
            : "OpenUI Lang settled",
      } satisfies SettledStreamEventDetail);
    }
  }, [publish, isStreaming, response, result, errorsRef, errorRevision, __libraryId]);
}