@shipfox/client-logs 0.2.0

package/src/hooks/api/step-logs-query.test.tsx

@@ -0,0 +1,283 @@
+import {configureApiClient} from '@shipfox/client-api';
+import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
+import {cleanup, renderHook, waitFor} from '@testing-library/react';
+import type {ReactNode} from 'react';
+import {STEP_LOG_DRAIN_REFETCH_MS, STEP_LOG_LIVE_REFETCH_MS} from '#core/log-read.js';
+import {type UseStepAttemptLogsQueryOptions, useStepAttemptLogsQuery} from './step-logs.js';
+
+const STEP_ID = '11111111-1111-4111-8111-111111111111';
+
+function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(body), {
+    headers: {'content-type': 'application/json'},
+    status: 200,
+    ...init,
+  });
+}
+
+const outputLine = (data: string, ts = 1): string =>
+  `${JSON.stringify({v: 1, ts, type: 'output', stream: 'stdout', data})}\n`;
+const inlineBody = ({
+  ndjson,
+  nextCursor,
+  hasMore = false,
+  state = 'open',
+}: {
+  ndjson: string;
+  nextCursor: number;
+  hasMore?: boolean;
+  state?: 'open' | 'closed';
+}) => ({
+  mode: 'inline',
+  ndjson,
+  next_cursor: nextCursor,
+  has_more: hasMore,
+  state,
+  truncated: false,
+});
+
+const presignedBody = () => ({
+  mode: 'presigned',
+  url: 'https://storage.example.test/logs/object?sig=1',
+  state: 'closed',
+  expires_at: '2026-06-23T10:00:00.000Z',
+  total_bytes: 128,
+  truncated: false,
+});
+
+function renderStepLogsHook(
+  params: {stepId: string | undefined; attempt: number | undefined} = {
+    stepId: STEP_ID,
+    attempt: 1,
+  },
+  options: UseStepAttemptLogsQueryOptions = {},
+) {
+  const queryClient = new QueryClient({
+    defaultOptions: {queries: {retry: false}},
+  });
+  const wrapper = ({children}: {children: ReactNode}) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  return renderHook(() => useStepAttemptLogsQuery(params.stepId, params.attempt, options), {
+    wrapper,
+  });
+}
+
+function requestsFrom(fetchImpl: ReturnType<typeof vi.fn>): Request[] {
+  return fetchImpl.mock.calls.map((call) => call[0] as Request);
+}
+
+describe('useStepAttemptLogsQuery', () => {
+  afterEach(() => {
+    cleanup();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    configureApiClient({baseUrl: '', fetchImpl: undefined});
+  });
+
+  test('does not fetch until step id and attempt are available', () => {
+    const fetchImpl = vi.fn(async () => jsonResponse(inlineBody({ndjson: '', nextCursor: 0})));
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    renderStepLogsHook({stepId: undefined, attempt: undefined});
+
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  test('uses the cached cursor on the next fetch and appends live records', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse(inlineBody({ndjson: outputLine('alpha\n', 1), nextCursor: 5})),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(inlineBody({ndjson: outputLine('beta\n', 2), nextCursor: 6})),
+      );
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    const {result} = renderStepLogsHook();
+    await waitFor(() => expect(result.current.data?.records).toHaveLength(1));
+    await result.current.refetch();
+
+    await waitFor(() => expect(result.current.data?.records).toHaveLength(2));
+    const urls = requestsFrom(fetchImpl).map((request) => new URL(request.url));
+    expect(urls.map((url) => url.searchParams.get('cursor'))).toEqual(['0', '5']);
+    expect(result.current.data?.records.map((record) => record.type)).toEqual(['output', 'output']);
+  });
+
+  test('fetches and parses compacted presigned logs into the same record state', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse(presignedBody()));
+    const objectFetch = vi.fn(async () => new Response(outputLine('cold\n', 3), {status: 200}));
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+    vi.stubGlobal('fetch', objectFetch);
+
+    const {result} = renderStepLogsHook();
+
+    await waitFor(() => expect(result.current.data?.source).toBe('presigned'));
+    expect(objectFetch).toHaveBeenCalledWith('https://storage.example.test/logs/object?sig=1', {
+      signal: expect.any(AbortSignal),
+    });
+    expect(result.current.data?.records).toMatchObject([{type: 'output', data: 'cold\n'}]);
+    expect(result.current.data?.state).toBe('compacted');
+    expect(result.current.data?.complete).toBe(true);
+    expect(result.current.data?.totalBytes).toBe(128);
+  });
+
+  test('keeps prior records visible when a refetch fails', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse(inlineBody({ndjson: outputLine('alpha\n', 1), nextCursor: 5})),
+      )
+      .mockResolvedValueOnce(jsonResponse({code: 'server-error'}, {status: 500}));
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    const {result} = renderStepLogsHook();
+    await waitFor(() => expect(result.current.data?.records).toHaveLength(1));
+    const refetch = await result.current.refetch();
+
+    expect(refetch.error).toBeTruthy();
+    expect(result.current.data?.records).toMatchObject([{type: 'output', data: 'alpha\n'}]);
+  });
+
+  test('retries transient initial errors before surfacing a failure', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(jsonResponse({code: 'server-error'}, {status: 500}))
+      .mockResolvedValueOnce(jsonResponse({code: 'server-error'}, {status: 500}))
+      .mockResolvedValueOnce(
+        jsonResponse(inlineBody({ndjson: outputLine('eventual logs\n', 1), nextCursor: 5})),
+      );
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    const {result} = renderStepLogsHook(
+      {stepId: STEP_ID, attempt: 1},
+      {initialErrorRetryCount: 2, initialErrorRetryDelayMs: 10},
+    );
+
+    await waitFor(() => expect(result.current.data?.records).toHaveLength(1));
+    expect(result.current.data?.records).toMatchObject([{type: 'output', data: 'eventual logs\n'}]);
+    expect(fetchImpl).toHaveBeenCalledTimes(3);
+  });
+
+  test('stops polling after a persistent error instead of re-polling the dead cursor', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse(inlineBody({ndjson: outputLine('alpha\n', 1), nextCursor: 5, hasMore: true})),
+      )
+      .mockResolvedValue(jsonResponse({code: 'server-error'}, {status: 500}));
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    const {result} = renderStepLogsHook();
+    await waitFor(() => expect(result.current.data?.records).toHaveLength(1));
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    const callsWhenErrored = fetchImpl.mock.calls.length;
+    await new Promise((resolve) => setTimeout(resolve, 350));
+
+    expect(fetchImpl.mock.calls.length).toBe(callsWhenErrored);
+  });
+
+  test('keeps polling a missing stream when requested and merges the later response', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(jsonResponse({code: 'not-found'}, {status: 404}))
+      .mockResolvedValueOnce(
+        jsonResponse(
+          inlineBody({ndjson: outputLine('stream created\n', 1), nextCursor: 5, hasMore: true}),
+        ),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(inlineBody({ndjson: outputLine('next line\n', 2), nextCursor: 6})),
+      );
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    const {result} = renderStepLogsHook({stepId: STEP_ID, attempt: 1}, {retryMissingStream: true});
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    await waitFor(() => expect(result.current.data?.records).toHaveLength(2), {
+      timeout: STEP_LOG_LIVE_REFETCH_MS + STEP_LOG_DRAIN_REFETCH_MS + 1_500,
+    });
+    expect(result.current.data?.records.map((record) => record.type)).toEqual(['output', 'output']);
+    const urls = requestsFrom(fetchImpl).map((request) => new URL(request.url));
+    expect(urls.map((url) => url.searchParams.get('cursor'))).toEqual(['0', '0', '5']);
+  });
+
+  test('settles a bounded missing stream retry window as complete empty logs', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({code: 'not-found'}, {status: 404}));
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    const {result} = renderStepLogsHook(
+      {stepId: STEP_ID, attempt: 1},
+      {retryMissingStream: true, missingStreamRetryCount: 2, missingStreamRetryDelayMs: 10},
+    );
+
+    await waitFor(() => expect(result.current.data?.complete).toBe(true));
+    expect(result.current.data?.records).toEqual([]);
+    expect(result.current.data?.state).toBe('closed');
+    expect(fetchImpl).toHaveBeenCalledTimes(3);
+  });
+
+  test('starts a fresh bounded window after unbounded missing-stream polling', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({code: 'not-found'}, {status: 404}));
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+    const queryClient = new QueryClient({
+      defaultOptions: {queries: {retry: false}},
+    });
+    const wrapper = ({children}: {children: ReactNode}) => (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+    const initialProps: {options: UseStepAttemptLogsQueryOptions} = {
+      options: {retryMissingStream: true},
+    };
+
+    const {result, rerender} = renderHook(
+      ({options}: {options: UseStepAttemptLogsQueryOptions}) =>
+        useStepAttemptLogsQuery(STEP_ID, 1, options),
+      {wrapper, initialProps},
+    );
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    await result.current.refetch();
+    await result.current.refetch();
+
+    rerender({
+      options: {
+        retryMissingStream: true,
+        missingStreamRetryCount: 1,
+        missingStreamRetryDelayMs: 10,
+      },
+    });
+    const firstBoundedRefetch = await result.current.refetch();
+    const secondBoundedRefetch = await result.current.refetch();
+
+    expect(firstBoundedRefetch.data).toBeUndefined();
+    expect(firstBoundedRefetch.error).toBeTruthy();
+    expect(secondBoundedRefetch.data?.complete).toBe(true);
+    expect(secondBoundedRefetch.data?.records).toEqual([]);
+    expect(fetchImpl).toHaveBeenCalledTimes(5);
+  });
+
+  test('does not keep polling server errors when missing-stream retry is requested', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({code: 'server-error'}, {status: 500}));
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    const {result} = renderStepLogsHook({stepId: STEP_ID, attempt: 1}, {retryMissingStream: true});
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    await new Promise((resolve) => setTimeout(resolve, STEP_LOG_LIVE_REFETCH_MS + 100));
+
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+
+  test('does not poll after a closed drained inline stream loads', async () => {
+    const fetchImpl = vi.fn(async () =>
+      jsonResponse(inlineBody({ndjson: outputLine('done\n', 1), nextCursor: 1, state: 'closed'})),
+    );
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    const {result} = renderStepLogsHook();
+    await waitFor(() => expect(result.current.data?.complete).toBe(true));
+    await new Promise((resolve) => setTimeout(resolve, 350));
+
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/api/step-logs.test.ts

@@ -0,0 +1,66 @@
+import {configureApiClient} from '@shipfox/client-api';
+import {readStepAttemptLogsPage, stepLogsQueryKeys} from './step-logs.js';
+
+function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(body), {
+    headers: {'content-type': 'application/json'},
+    status: 200,
+    ...init,
+  });
+}
+
+function requestFrom(fetchImpl: ReturnType<typeof vi.fn>): Request {
+  return fetchImpl.mock.calls[0]?.[0] as Request;
+}
+
+describe('stepLogsQueryKeys', () => {
+  test('keys a log detail by step id and attempt', () => {
+    const key = stepLogsQueryKeys.detail('11111111-1111-4111-8111-111111111111', 2);
+
+    expect(key).toEqual(['step-logs', 'detail', '11111111-1111-4111-8111-111111111111', 2]);
+  });
+});
+
+describe('readStepAttemptLogsPage', () => {
+  beforeEach(() => {
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl: undefined});
+  });
+
+  test('requests a step attempt log page with the cursor', async () => {
+    const body = {
+      mode: 'inline',
+      ndjson: '',
+      next_cursor: 8,
+      has_more: false,
+      state: 'open',
+      truncated: false,
+    };
+    const fetchImpl = vi.fn(async () => jsonResponse(body));
+    configureApiClient({fetchImpl});
+
+    const result = await readStepAttemptLogsPage({
+      stepId: '11111111-1111-4111-8111-111111111111',
+      attempt: 2,
+      cursor: 7,
+    });
+
+    const url = new URL(requestFrom(fetchImpl).url);
+    expect(result).toEqual(body);
+    expect(url.pathname).toBe('/steps/11111111-1111-4111-8111-111111111111/attempts/2/logs');
+    expect(url.searchParams.get('cursor')).toBe('7');
+    expect(requestFrom(fetchImpl).method).toBe('GET');
+  });
+
+  test('bubbles API errors from the read endpoint', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({code: 'not-found'}, {status: 404}));
+    configureApiClient({fetchImpl});
+
+    const result = readStepAttemptLogsPage({
+      stepId: '11111111-1111-4111-8111-111111111111',
+      attempt: 1,
+      cursor: 0,
+    });
+
+    await expect(result).rejects.toMatchObject({code: 'not-found', status: 404});
+  });
+});

package/src/hooks/api/step-logs.ts

@@ -0,0 +1,166 @@
+import type {ReadLogsResponseDto} from '@shipfox/api-logs-dto';
+import {ApiError, apiRequest} from '@shipfox/client-api';
+import {useQuery, useQueryClient} from '@tanstack/react-query';
+import {useRef} from 'react';
+import {
+  mergeLogRead,
+  STEP_LOG_LIVE_REFETCH_MS,
+  type StepLogSnapshot,
+  stepLogRefetchInterval,
+} from '#core/log-read.js';
+
+export const stepLogsQueryKeys = {
+  all: ['step-logs'] as const,
+  detail: (stepId: string, attempt: number) =>
+    [...stepLogsQueryKeys.all, 'detail', stepId, attempt] as const,
+};
+
+interface ReadStepAttemptLogsPageParams {
+  stepId: string;
+  attempt: number;
+  cursor: number;
+  signal?: AbortSignal;
+}
+
+export async function readStepAttemptLogsPage({
+  stepId,
+  attempt,
+  cursor,
+  signal,
+}: ReadStepAttemptLogsPageParams): Promise<ReadLogsResponseDto> {
+  const params = new URLSearchParams({cursor: String(cursor)});
+  return await apiRequest<ReadLogsResponseDto>(
+    `/steps/${encodeURIComponent(stepId)}/attempts/${attempt}/logs?${params.toString()}`,
+    {signal},
+  );
+}
+
+class StepLogObjectFetchError extends Error {
+  readonly status: number;
+
+  constructor(status: number) {
+    super(`Could not load compacted logs (${status})`);
+    this.name = 'StepLogObjectFetchError';
+    this.status = status;
+  }
+}
+
+async function readPresignedLogObject(url: string, signal?: AbortSignal): Promise<string> {
+  const response = await fetch(url, signal ? {signal} : undefined);
+  if (!response.ok) throw new StepLogObjectFetchError(response.status);
+  return await response.text();
+}
+
+export function isMissingStepLogStreamError(error: unknown): boolean {
+  return error instanceof ApiError && error.status === 404 && error.code === 'not-found';
+}
+
+export interface UseStepAttemptLogsQueryOptions {
+  retryMissingStream?: boolean;
+  missingStreamRetryCount?: number | undefined;
+  missingStreamRetryDelayMs?: number | undefined;
+  initialErrorRetryCount?: number;
+  initialErrorRetryDelayMs?: number;
+}
+
+export function useStepAttemptLogsQuery(
+  stepId: string | undefined,
+  attempt: number | undefined,
+  options: UseStepAttemptLogsQueryOptions = {},
+) {
+  const queryClient = useQueryClient();
+  const missingStreamFailureCountRef = useRef(0);
+  const missingStreamScopeRef = useRef<string | null>(null);
+  const enabled = Boolean(stepId && attempt && Number.isInteger(attempt) && attempt > 0);
+  const queryKey =
+    enabled && stepId && attempt
+      ? stepLogsQueryKeys.detail(stepId, attempt)
+      : [...stepLogsQueryKeys.all, 'detail'];
+  const missingStreamScope =
+    enabled && stepId && attempt
+      ? `${stepId}:${attempt}:${options.missingStreamRetryCount ?? 'unbounded'}`
+      : null;
+  if (missingStreamScopeRef.current !== missingStreamScope) {
+    missingStreamScopeRef.current = missingStreamScope;
+    missingStreamFailureCountRef.current = 0;
+  }
+  const initialErrorRetryCount = options.initialErrorRetryCount ?? 0;
+  const initialErrorRetryDelayMs = options.initialErrorRetryDelayMs ?? STEP_LOG_LIVE_REFETCH_MS;
+  const missingStreamRetryDelayMs = options.missingStreamRetryDelayMs ?? STEP_LOG_LIVE_REFETCH_MS;
+
+  return useQuery({
+    queryKey,
+    enabled,
+    queryFn: async ({signal}) => {
+      const previous = queryClient.getQueryData<StepLogSnapshot>(queryKey);
+      let response: ReadLogsResponseDto;
+      try {
+        response = await readStepAttemptLogsPage({
+          stepId: stepId ?? '',
+          attempt: attempt ?? 0,
+          cursor: previous?.nextCursor ?? 0,
+          signal,
+        });
+      } catch (error) {
+        if (
+          options.retryMissingStream &&
+          previous === undefined &&
+          isMissingStepLogStreamError(error)
+        ) {
+          const retryCount = options.missingStreamRetryCount;
+          if (retryCount === undefined) throw error;
+          if (missingStreamFailureCountRef.current >= retryCount) {
+            return emptyCompleteLogSnapshot();
+          }
+          missingStreamFailureCountRef.current += 1;
+        }
+        throw error;
+      }
+
+      missingStreamFailureCountRef.current = 0;
+
+      if (response.mode === 'presigned') {
+        const ndjson = await readPresignedLogObject(response.url, signal);
+        return mergeLogRead(previous, {mode: 'presigned', response, ndjson});
+      }
+
+      return mergeLogRead(previous, {mode: 'inline', response});
+    },
+    retry: (failureCount, error) => {
+      if (initialErrorRetryCount <= 0) return false;
+      if (queryClient.getQueryData<StepLogSnapshot>(queryKey) !== undefined) return false;
+      if (options.retryMissingStream && isMissingStepLogStreamError(error)) return false;
+      return failureCount < initialErrorRetryCount;
+    },
+    retryDelay: initialErrorRetryDelayMs,
+    refetchInterval: (query) => {
+      if (
+        options.retryMissingStream &&
+        query.state.data === undefined &&
+        isMissingStepLogStreamError(query.state.error)
+      ) {
+        return missingStreamRetryDelayMs;
+      }
+
+      return stepLogRefetchInterval(query.state.data, query.state.status === 'error');
+    },
+    refetchIntervalInBackground: false,
+    refetchOnMount: (query) => !query.state.data?.complete,
+    refetchOnWindowFocus: (query) => !query.state.data?.complete,
+    refetchOnReconnect: (query) => !query.state.data?.complete,
+  });
+}
+
+function emptyCompleteLogSnapshot(): StepLogSnapshot {
+  return {
+    records: [],
+    nextCursor: 0,
+    source: 'inline',
+    state: 'closed',
+    complete: true,
+    hasMore: false,
+    truncated: false,
+    totalBytes: null,
+    expiresAt: null,
+  };
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export type {StepLogSnapshot} from '#core/log-read.js';
+export {
+  buildLogTree,
+  type GroupLogNode,
+  type LogNode,
+  type LogTree,
+  type MarkerLogNode,
+  type OutputLogNode,
+  type SessionLogNode,
+} from '#core/log-tree.js';
+export * from './components/index.js';
+export {
+  isMissingStepLogStreamError,
+  readStepAttemptLogsPage,
+  stepLogsQueryKeys,
+  type UseStepAttemptLogsQueryOptions,
+  useStepAttemptLogsQuery,
+} from './hooks/api/step-logs.js';

package/test/setup.ts

@@ -0,0 +1,3 @@
+import {installClientDomTestEnv} from '@shipfox/client-test-setup';
+
+installClientDomTestEnv();

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@shipfox/ts-config/react",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["**/*.test.tsx", "**/*.test.ts", "**/*.stories.tsx"]
+}