Merge pull request #171 from Benalex8797/feat/Add

Backend: Add structured logging + request correlation IDs

Author: Junirezz

frontend/package-lock.json

@@ -0,0 +1,19 @@
+import { useEffect } from "react";
+import { useCorrelationId } from "../context/CorrelationIdContext";
+import { setCorrelationIdGetter } from "../lib/apiClient";
+
+/**
+ * Invisible component that keeps the shared API client's correlation ID
+ * getter in sync with the current `CorrelationIdContext` value.
+ *
+ * Must be rendered inside `CorrelationIdProvider`.
+ */
+export function CorrelationIdSync() {
+  const { correlationId } = useCorrelationId();
+
+  useEffect(() => {
+    setCorrelationIdGetter(() => correlationId);
+  }, [correlationId]);
+
+  return null;
+}

frontend/src/components/CorrelationIdSync.tsx

@@ -49,8 +49,7 @@ export const Pagination: React.FC<PaginationProps> = ({
   return (
     <div className="pagination-container" aria-label="Pagination">
       <div className="pagination-summary" aria-live="polite">
-        Showing <strong>{startItem}–{endItem}</strong> of{" "}
-        <strong>{totalItems}</strong> results
+        {`Page ${page} of ${totalPages}`} &mdash; Showing {startItem}–{endItem} of {totalItems} results
       </div>
 
       <div className="pagination-controls-wrapper">

frontend/src/components/Pagination.tsx

@@ -28,31 +28,28 @@ interface TabsProps {
   className?: string;
 }
 
-export function Tabs({
+/** Inner component that uses useSearchParams — only rendered when syncWithUrl=true */
+function TabsWithUrl({
   defaultValue,
   value: controlledValue,
   onValueChange,
-  syncWithUrl = false,
   urlParam = "tab",
   children,
   className = "",
-}: TabsProps) {
+}: Omit<TabsProps, "syncWithUrl">) {
   const [searchParams, setSearchParams] = useSearchParams();
   const [internalValue, setInternalValue] = useState(defaultValue || "");
 
-  const urlValue = syncWithUrl ? searchParams.get(urlParam) : null;
+  const urlValue = searchParams.get(urlParam);
   const activeValue =
     controlledValue !== undefined
       ? controlledValue
-      : syncWithUrl && urlValue
+      : urlValue
       ? urlValue
       : internalValue;
 
   useEffect(() => {
-    // If we're syncing with URL but the param isn't there, and we have a defaultValue,
-    // let's set the default value in the URL implicitly, or just let activeValue handle it.
-    // Setting it explicitly ensures deep links are predictable.
-    if (syncWithUrl && !urlValue && defaultValue) {
+    if (!urlValue && defaultValue) {
       setSearchParams(
         (prev) => {
           const newParams = new URLSearchParams(prev);
@@ -62,24 +59,53 @@ export function Tabs({
         { replace: true }
       );
     }
-  }, [syncWithUrl, urlValue, defaultValue, urlParam, setSearchParams]);
+  }, [urlValue, defaultValue, urlParam, setSearchParams]);
 
   const handleValueChange = (newValue: string) => {
     if (controlledValue === undefined) {
       setInternalValue(newValue);
     }
 
-    if (syncWithUrl) {
-      setSearchParams(
-        (prev) => {
-          const newParams = new URLSearchParams(prev);
-          newParams.set(urlParam, newValue);
-          return newParams;
-        },
-        { replace: true }
-      );
+    setSearchParams(
+      (prev) => {
+        const newParams = new URLSearchParams(prev);
+        newParams.set(urlParam, newValue);
+        return newParams;
+      },
+      { replace: true }
+    );
+
+    if (onValueChange) {
+      onValueChange(newValue);
     }
+  };
+
+  return (
+    <TabsContext.Provider value={{ value: activeValue, onValueChange: handleValueChange }}>
+      <div className={`tabs-root ${className}`} data-state={activeValue}>
+        {children}
+      </div>
+    </TabsContext.Provider>
+  );
+}
+
+/** Inner component for tabs without URL sync */
+function TabsWithoutUrl({
+  defaultValue,
+  value: controlledValue,
+  onValueChange,
+  children,
+  className = "",
+}: Omit<TabsProps, "syncWithUrl" | "urlParam">) {
+  const [internalValue, setInternalValue] = useState(defaultValue || "");
+
+  const activeValue =
+    controlledValue !== undefined ? controlledValue : internalValue;
 
+  const handleValueChange = (newValue: string) => {
+    if (controlledValue === undefined) {
+      setInternalValue(newValue);
+    }
     if (onValueChange) {
       onValueChange(newValue);
     }
@@ -94,6 +120,16 @@ export function Tabs({
   );
 }
 
+export function Tabs({
+  syncWithUrl = false,
+  ...props
+}: TabsProps) {
+  if (syncWithUrl) {
+    return <TabsWithUrl {...props} />;
+  }
+  return <TabsWithoutUrl {...props} />;
+}
+
 export function TabsList({ children, className = "", style }: { children: ReactNode; className?: string; style?: React.CSSProperties }) {
   return (
     <div

frontend/src/components/Tabs.tsx

@@ -1,4 +1,4 @@
-import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
 import type { ComponentProps } from 'react';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import WalletConnect from './WalletConnect';
@@ -101,7 +101,10 @@ describe('WalletConnect', () => {
     });
 
     it('handles wallet disconnects gracefully during polling', async () => {
-        vi.useFakeTimers();
+        // Helper to flush all pending promises
+        const flushPromises = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+        vi.useFakeTimers({ shouldAdvanceTime: false });
         mockedFreighter.isAllowed
             .mockResolvedValueOnce({ isAllowed: true })
             .mockResolvedValueOnce({ isAllowed: false });
@@ -115,14 +118,16 @@ describe('WalletConnect', () => {
             />
         );
 
-        await waitFor(() => {
-            expect(mockOnConnect).toHaveBeenCalledWith('GABC123');
-        });
+        // Advance timers by 0 to flush the initial synchronous setup,
+        // then flush microtasks from the async calls
+        vi.advanceTimersByTime(0);
+        await vi.advanceTimersByTimeAsync(0);
 
-        await vi.advanceTimersByTimeAsync(10000);
+        expect(mockOnConnect).toHaveBeenCalledWith('GABC123');
 
-        await waitFor(() => {
-            expect(mockOnDisconnect).toHaveBeenCalled();
-        });
-    });
+        // Advance past the 10s polling interval
+        await vi.advanceTimersByTimeAsync(10001);
+
+        expect(mockOnDisconnect).toHaveBeenCalled();
+    }, 20000);
 });

frontend/src/components/WalletConnect.test.tsx

@@ -0,0 +1,32 @@
+import React, { createContext, useCallback, useContext, useState } from 'react';
+
+export interface CorrelationIdContextValue {
+  correlationId: string;
+  /** Replace the active ID (e.g. when starting a new user action). */
+  refreshCorrelationId: () => void;
+}
+
+const CorrelationIdContext = createContext<CorrelationIdContextValue | undefined>(undefined);
+
+export const CorrelationIdProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [correlationId, setCorrelationId] = useState<string>(() => crypto.randomUUID());
+
+  const refreshCorrelationId = useCallback(() => {
+    setCorrelationId(crypto.randomUUID());
+  }, []);
+
+  return (
+    <CorrelationIdContext.Provider value={{ correlationId, refreshCorrelationId }}>
+      {children}
+    </CorrelationIdContext.Provider>
+  );
+};
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function useCorrelationId(): CorrelationIdContextValue {
+  const context = useContext(CorrelationIdContext);
+  if (!context) {
+    throw new Error('useCorrelationId must be used within a CorrelationIdProvider');
+  }
+  return context;
+}

frontend/src/context/CorrelationIdContext.tsx

@@ -19,7 +19,8 @@ export function useUrlState<TFilters extends Record<string, string>>(
   const state = useMemo(() => {
     const pageRaw = searchParams.get("page");
     const pageSizeRaw = searchParams.get("pageSize");
-    const sortDirectionRaw = searchParams.get("sortDirection");
+    // Support both "direction" and "sortDirection" as URL param names
+    const sortDirectionRaw = searchParams.get("direction") ?? searchParams.get("sortDirection");
 
     const pageNum = Number(pageRaw);
     const page =
@@ -74,7 +75,7 @@ export function useUrlState<TFilters extends Record<string, string>>(
             next.set("sortBy", updates.sortBy);
           }
           if (updates.sortDirection !== undefined) {
-            next.set("sortDirection", updates.sortDirection);
+            next.set("direction", updates.sortDirection);
           }
 
           if (updates.filters !== undefined) {

frontend/src/hooks/useUrlState.ts

@@ -94,4 +94,57 @@ describe("ApiClient", () => {
         "We could not complete that request. Please review your input and try again.",
     });
   });
+
+  it("sets X-Correlation-ID header on outgoing requests via the request interceptor", async () => {
+    const correlationId = "test-correlation-id-abc123";
+    let capturedHeaders: Headers | undefined;
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation((url: string, init: RequestInit) => {
+        capturedHeaders = init.headers as Headers;
+        return Promise.resolve(
+          new Response(JSON.stringify({ ok: true }), {
+            status: 200,
+            headers: { "content-type": "application/json" },
+          }),
+        );
+      }),
+    );
+
+    const client = createApiClient({
+      baseUrl: "http://localhost",
+      getCorrelationId: () => correlationId,
+    });
+
+    await client.get("/health");
+
+    expect(capturedHeaders).toBeDefined();
+    expect(capturedHeaders!.get("X-Correlation-ID")).toBe(correlationId);
+  });
+
+  it("attaches correlationId to ApiError on HTTP failure", async () => {
+    const correlationId = "error-correlation-id-xyz789";
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(JSON.stringify({ error: "not found" }), {
+          status: 404,
+          statusText: "Not Found",
+          headers: { "content-type": "application/json" },
+        }),
+      ),
+    );
+
+    const client = createApiClient({
+      baseUrl: "http://localhost",
+      getCorrelationId: () => correlationId,
+    });
+
+    const error = await client.get("/missing").catch((e) => e);
+
+    expect(error).toBeInstanceOf(ApiError);
+    expect(error.correlationId).toBe(correlationId);
+  });
 });

frontend/src/lib/api/client.test.ts

@@ -1,5 +1,10 @@
 import { ApiError, normalizeApiError, type NormalizeApiErrorOptions } from "./error";
 import { emitApiTelemetry } from "./telemetry";
+import {
+  createCorrelationRequestInterceptor,
+  createCorrelationResponseInterceptor,
+  generateCorrelationId,
+} from "./correlationInterceptors";
 
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 
@@ -33,6 +38,7 @@ export interface ApiResponseContext<T> {
 interface ApiClientConfig {
   baseUrl?: string;
   headers?: HeadersInit;
+  getCorrelationId?: () => string;
 }
 
 type RequestInterceptor = (
@@ -164,6 +170,7 @@ async function buildApiError(
     ...options,
     method: request.method,
     url: request.url,
+    correlationId: (request.headers as Headers).get("X-Correlation-ID") ?? undefined,
   });
 }
 
@@ -175,6 +182,9 @@ export class ApiClient {
 
   constructor(config: ApiClientConfig = {}) {
     this.baseConfig = config;
+    const getCorrelationId = config.getCorrelationId ?? generateCorrelationId;
+    this.useRequest(createCorrelationRequestInterceptor(getCorrelationId));
+    this.useResponse(createCorrelationResponseInterceptor());
   }
 
   useRequest(interceptor: RequestInterceptor) {
@@ -219,6 +229,7 @@ export class ApiClient {
         method: request.method,
         url: request.url,
         attempt,
+        correlationId: (request.headers as Headers).get("X-Correlation-ID") ?? undefined,
       });
 
       try {
@@ -252,6 +263,7 @@ export class ApiClient {
           attempt,
           durationMs,
           status: response.status,
+          correlationId: (request.headers as Headers).get("X-Correlation-ID") ?? undefined,
         });
 
         return context.data;
@@ -273,6 +285,7 @@ export class ApiClient {
             attempt,
             delayMs,
             reason: apiError.code,
+            correlationId: (request.headers as Headers).get("X-Correlation-ID") ?? undefined,
           });
           await sleep(delayMs);
           continue;
@@ -285,6 +298,7 @@ export class ApiClient {
           attempt,
           durationMs,
           error: apiError,
+          correlationId: (request.headers as Headers).get("X-Correlation-ID") ?? undefined,
         });
 
         throw apiError;