Messages tab for streams, with messages as the single record (#819)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Gregory SchierandClaude Opus 5.5 authored and GitHub committed 2026-11-06 18:45:52 -07:00
1 parent f63586f9f0
commit cc382b9226
42 files changed
+3403 -453

No files matched your search

@@ -1,312 +1,2 @@
import type { Virtualizer } from "@tanstack/react-virtual";
import { Banner, HStack, SplitLayout } from "@yaakapp-internal/ui";
import classNames from "classnames";
import { format } from "date-fns";
import type { ReactNode } from "react";
import { useCallback, useMemo, useRef, useState } from "react";
import { useEventViewerKeyboard } from "../../hooks/useEventViewerKeyboard";
import { CopyIconButton } from "../CopyIconButton";
import { AutoScroller } from "./AutoScroller";
import { Button } from "./Button";
import { IconButton } from "./IconButton";
import type { SelectProps } from "./Select";
import { Select } from "./Select";
import { Separator } from "./Separator";
interface EventViewerProps<T> {
/** Array of events to display */
events: T[];
/** Get unique key for each event */
getEventKey: (event: T, index: number) => string;
/** Render the event row - receives event, index, isActive, and onClick */
renderRow: (props: {
event: T;
index: number;
isActive: boolean;
onClick: () => void;
}) => ReactNode;
/** Render the detail pane for the selected event */
renderDetail?: (props: { event: T; index: number; onClose: () => void }) => ReactNode;
/** Optional header above the event list (e.g., connection status) */
header?: ReactNode;
/** Error message to display as a banner */
error?: string | null;
/** Key for SplitLayout state persistence */
splitLayoutStorageKey: string;
/** Default ratio for the split (0.0 - 1.0) */
defaultRatio?: number;
/** Enable keyboard navigation (arrow keys) */
enableKeyboardNav?: boolean;
/** Loading state */
isLoading?: boolean;
/** Message to show while loading */
loadingMessage?: string;
/** Message to show when no events */
emptyMessage?: string;
/** Callback when active index changes (for controlled state in parent) */
onActiveIndexChange?: (index: number | null) => void;
}
export function EventViewer<T>({
events,
getEventKey,
renderRow,
renderDetail,
header,
error,
splitLayoutStorageKey,
defaultRatio = 0.4,
enableKeyboardNav = true,
isLoading = false,
loadingMessage = "Loading events...",
emptyMessage = "No events recorded",
onActiveIndexChange,
}: EventViewerProps<T>) {
const [activeIndex, setActiveIndexInternal] = useState<number | null>(null);
const [isPanelOpen, setIsPanelOpen] = useState(false);
// Wrap setActiveIndex to notify parent
const setActiveIndex = useCallback(
(indexOrUpdater: number | null | ((prev: number | null) => number | null)) => {
setActiveIndexInternal((prev) => {
const newIndex =
typeof indexOrUpdater === "function" ? indexOrUpdater(prev) : indexOrUpdater;
onActiveIndexChange?.(newIndex);
return newIndex;
});
},
[onActiveIndexChange],
);
const containerRef = useRef<HTMLDivElement>(null);
const virtualizerRef = useRef<Virtualizer<HTMLDivElement, Element> | null>(null);
const activeEvent = useMemo(
() => (activeIndex != null ? events[activeIndex] : null),
[activeIndex, events],
);
// Check if the event list container is focused
const isContainerFocused = useCallback(() => {
return containerRef.current?.contains(document.activeElement) ?? false;
}, []);
// Keyboard navigation
useEventViewerKeyboard({
totalCount: events.length,
activeIndex,
setActiveIndex,
virtualizer: virtualizerRef.current,
isContainerFocused,
enabled: enableKeyboardNav,
closePanel: () => setIsPanelOpen(false),
openPanel: () => setIsPanelOpen(true),
});
// Handle virtualizer ready callback
const handleVirtualizerReady = useCallback(
(virtualizer: Virtualizer<HTMLDivElement, Element>) => {
virtualizerRef.current = virtualizer;
},
[],
);
// Handle row click - select and open panel, scroll into view
const handleRowClick = useCallback(
(index: number) => {
setActiveIndex(index);
setIsPanelOpen(true);
// Scroll to ensure selected item is visible after panel opens
requestAnimationFrame(() => {
virtualizerRef.current?.scrollToIndex(index, { align: "auto" });
});
},
[setActiveIndex],
);
const handleClose = useCallback(() => {
setIsPanelOpen(false);
}, []);
if (isLoading) {
return <div className="p-3 text-text-subtlest italic">{loadingMessage}</div>;
}
if (events.length === 0 && !error) {
return <div className="p-3 text-text-subtlest italic">{emptyMessage}</div>;
}
return (
<div ref={containerRef} className="h-full">
<SplitLayout
layout="vertical"
storageKey={splitLayoutStorageKey}
defaultRatio={defaultRatio}
minHeightPx={72}
firstSlot={({ style }) => (
<div style={style} className="w-full h-full grid grid-rows-[auto_minmax(0,1fr)]">
{header ?? <span aria-hidden />}
<AutoScroller
data={events}
focusable={enableKeyboardNav}
onVirtualizerReady={handleVirtualizerReady}
header={
error && (
<Banner color="danger" className="m-3">
{error}
</Banner>
)
}
render={(event, index) => (
<div key={getEventKey(event, index)}>
{renderRow({
event,
index,
isActive: index === activeIndex,
onClick: () => handleRowClick(index),
})}
</div>
)}
/>
</div>
)}
secondSlot={
activeEvent != null && renderDetail && isPanelOpen
? ({ style }) => (
<div style={style} className="grid grid-rows-[auto_minmax(0,1fr)] bg-surface">
<div className="pb-3 px-2">
<Separator />
</div>
<div className="mx-2 overflow-y-auto">
{renderDetail({
event: activeEvent,
index: activeIndex ?? 0,
onClose: handleClose,
})}
</div>
</div>
)
: null
}
/>
</div>
);
}
export type EventDetailAction =
| {
type?: "button";
/** Unique key for React */
key: string;
/** Button label */
label: string;
/** Optional icon */
icon?: ReactNode;
/** Click handler */
onClick: () => void;
}
| {
type: "select";
/** Unique key for React */
key: string;
/** Select label */
label: string;
/** Selected value */
value: string;
/** Select options */
options: SelectProps<string>["options"];
/** Change handler */
onChange: (value: string) => void;
};
interface EventDetailHeaderProps {
title: string;
prefix?: ReactNode;
timestamp?: string;
actions?: EventDetailAction[];
copyText?: string | (() => Promise<string | null>);
onClose?: () => void;
}
export function EventDetailHeader({
title,
prefix,
timestamp,
actions,
copyText,
onClose,
}: EventDetailHeaderProps) {
const formattedTime = timestamp ? format(new Date(`${timestamp}Z`), "HH:mm:ss.SSS") : null;
return (
<div className="flex items-center justify-between gap-2 mb-2 h-xs">
<HStack space={2} className="items-center min-w-0">
{prefix}
<h3 className="font-semibold select-auto cursor-auto truncate">{title}</h3>
</HStack>
<HStack space={2} className="items-center">
{actions?.map((action) =>
action.type === "select" ? (
<div key={action.key} className="w-32">
<Select
name={action.key}
label={action.label}
hideLabel
size="xs"
value={action.value}
options={action.options}
onChange={action.onChange}
/>
</div>
) : (
<Button
key={action.key}
type="button"
variant="border"
size="xs"
onClick={action.onClick}
>
{action.icon}
{action.label}
</Button>
),
)}
{copyText != null && (
<CopyIconButton text={copyText} size="xs" title="Copy" variant="border" iconSize="sm" />
)}
{formattedTime && (
<span className="text-text-subtlest font-mono text-editor ml-2">{formattedTime}</span>
)}
{onClose != null && (
<div
className={classNames(
copyText != null ||
formattedTime ||
((actions ?? []).length > 0 && "border-l border-l-surface-highlight ml-2 pl-3"),
)}
>
<IconButton
color="custom"
className="text-text-subtle -mr-3"
size="xs"
icon="x"
title="Close event panel"
onClick={onClose}
/>
</div>
)}
</HStack>
</div>
);
}
export type { EventDetailAction } from "@yaakapp-internal/ui";
export { EventDetailHeader, EventViewer } from "@yaakapp-internal/ui";
@@ -1,38 +1 @@
import classNames from "classnames";
import { format } from "date-fns";
import type { ReactNode } from "react";
interface EventViewerRowProps {
isActive: boolean;
onClick: () => void;
icon: ReactNode;
content: ReactNode;
timestamp?: string;
}
export function EventViewerRow({
isActive,
onClick,
icon,
content,
timestamp,
}: EventViewerRowProps) {
return (
<div className="px-1">
<button
type="button"
onClick={onClick}
className={classNames(
"w-full grid grid-cols-[auto_minmax(0,1fr)_auto] gap-2 items-center text-left",
"px-1.5 h-xs font-mono text-editor cursor-default group focus:outline-hidden focus:text-text rounded-sm",
isActive && "bg-surface-active text-text!",
"text-text-subtle hover:text",
)}
>
{icon}
<div className="w-full truncate">{content}</div>
{timestamp && <div className="opacity-50">{format(`${timestamp}Z`, "HH:mm:ss.SSS")}</div>}
</button>
</div>
);
}
export { EventViewerRow } from "@yaakapp-internal/ui";
@@ -1,6 +1,15 @@
import type { HttpResponse } from "@yaakapp-internal/models";
import { extractSseValueAtPath, type ServerSentEvent } from "@yaakapp-internal/sse";
import { HStack, Icon, InlineCode, SplitLayout, VStack, IconTooltip } from "@yaakapp-internal/ui";
import {
EventStreamViewer as SharedEventStreamViewer,
HStack,
Icon,
InlineCode,
SplitLayout,
type StreamEvent,
VStack,
IconTooltip,
} from "@yaakapp-internal/ui";
import classNames from "classnames";
import type { CSSProperties, ReactNode } from "react";
import { Fragment, useMemo, useState } from "react";
@@ -20,8 +29,7 @@ import type { DropdownItem } from "../core/Dropdown";
import { Dropdown } from "../core/Dropdown";
import type { EditorProps } from "../core/Editor/Editor";
import { Editor } from "../core/Editor/LazyEditor";
import { EventDetailHeader, EventViewer } from "../core/EventViewer";
import { EventViewerRow } from "../core/EventViewerRow";
import { EventDetailHeader } from "../core/EventViewer";
import { IconButton } from "../core/IconButton";
import { Input } from "../core/Input";
import { Select } from "../core/Select";
@@ -62,6 +70,7 @@ function ActualEventStreamViewer({ response }: Props) {
});
const summarySettings = useSseSummaryResultKeyPath({ response });
const events = useResponseBodyEventSource(response);
const streamEvents = useMemo(() => (events.data ?? []).map(toStreamEvent), [events.data]);
const summary = useResponseBodySseSummary(response, summarySettings.resultKeyPath);
const showExtractedText = summarySettings.resultKeyPath != null;
const showResultKeyPathWarning =
@@ -105,10 +114,7 @@ function ActualEventStreamViewer({ response }: Props) {
),
},
],
[
applyToDetailsSetting,
filterEventPreviewsSetting,
],
[applyToDetailsSetting, filterEventPreviewsSetting],
);
return (
@@ -175,30 +181,21 @@ function ActualEventStreamViewer({ response }: Props) {
resizeHandleClassName="hover:bg-surface-highlight active:bg-surface-highlight"
firstSlot={({ style }) => (
<div style={style} className="min-h-0">
<EventViewer
events={events.data ?? []}
getEventKey={(_, index) => String(index)}
<SharedEventStreamViewer
events={streamEvents}
error={events.error ? String(events.error) : null}
splitLayoutStorageKey="sse_events"
defaultRatio={0.4}
renderRow={({ event, index, isActive, onClick }) => (
<EventViewerRow
isActive={isActive}
onClick={onClick}
icon={<Icon color="info" title="Server Message" icon="arrow_big_down_dash" />}
content={
<HStack space={2} className="items-center">
<EventLabels event={event} index={index} isActive={isActive} />
<span className="truncate text-xs">
{getEventPreview(event, summarySettings.resultKeyPath, filterEventPreviews)}
</span>
</HStack>
}
/>
)}
getPreview={(event) =>
getEventPreview(
sseEventOf(events.data, event),
summarySettings.resultKeyPath,
filterEventPreviews,
)
}
renderDetail={({ event, index, onClose }) => (
<EventDetail
event={event}
event={sseEventOf(events.data, event)}
index={index}
applyJsonPath={applyToDetails}
resultKeyPath={summarySettings.resultKeyPath}
@@ -312,6 +309,23 @@ function SseSummaryFooter({
);
}
/** An SSE event as the shared viewer lists it: received, with its id (or place) and type */
function toStreamEvent(event: ServerSentEvent, index: number): StreamEvent {
return {
key: String(index),
direction: "received",
kind: event.eventType || null,
labels: [String(event.id ?? index), ...(event.eventType ? [event.eventType] : [])],
timestamp: null,
size: null,
preview: event.data,
};
}
function sseEventOf(events: ServerSentEvent[] | undefined, event: StreamEvent): ServerSentEvent {
return events?.[Number(event.key)] ?? { data: "", eventType: "", id: null, retry: null };
}
function getEventPreview(
event: ServerSentEvent,
resultKeyPath: string | null,
@@ -1,4 +1,9 @@
import { afterEach, beforeEach, describe, expect, test, vi } from "vite-plus/test";
// Loaded once as the file is collected (the mocks below are hoisted above it), so the first
// transform of its module graph, the shared UI package among it, is not timed against whichever
// test imports it first. Each test still gets the module fresh after `vi.resetModules()`, which
// reuses that transform.
import "./useSendAnyHttpRequest";
const mocks = vi.hoisted(() => ({
platform: { httpProxyUrl: "https://web.yaak.test" as string | null },
@@ -1,6 +1,11 @@
import { renderToStaticMarkup } from "react-dom/server";
import { afterEach, beforeEach, describe, expect, test, vi } from "vite-plus/test";
import type { DialogInstance } from "../components/Dialogs";
// Loaded once as the file is collected (the mocks below are hoisted above it), so the first
// transform of its module graph, the shared UI package among it, is not timed against whichever
// test imports it first. Each test still gets the module fresh after `vi.resetModules()`, which
// reuses that transform.
import "./confirmWebProxy";
const mocks = vi.hoisted(() => ({
platform: { httpProxyUrl: "https://web.yaak.app" },
@@ -23,6 +23,7 @@ import {
bodyImageType,
filterText,
findHeader,
emptyBodyText,
flowBodyQueryOptions,
formatText,
mimeEssence,
@@ -53,9 +54,9 @@ export function FlowBodyViewer({ flow, which, pretty }: Props) {
return <Banner color="danger">{body.error.message}</Banner>;
}
const { bytes, truncated, storedSize, decodeError } = body.data;
const { bytes, truncated, storedSize, decodeError, note } = body.data;
if (bytes.length === 0 && decodeError == null) {
return <EmptyState>{which === "request" ? "No request body" : "Empty"}</EmptyState>;
return <EmptyState>{emptyBodyText(which, note)}</EmptyState>;
}
const headers = which === "request" ? flow.requestHeaders : flow.responseHeaders;
+25
View File
@@ -11,6 +11,7 @@ import {
HttpStatusTagRaw,
Icon,
IconButton,
LoadingIcon,
SizeTag,
type TabButtonRenderProps,
type TabItem,
@@ -25,13 +26,16 @@ import { selectedFlowAtom } from "../lib/atoms";
import { findHeader, mimeEssence } from "../lib/body";
import { saveDialogFlowAtom, useFlowActions } from "../lib/flowActions";
import { statusReason } from "../lib/statusReason";
import { messagesTabLabel, streamIsOpen } from "../lib/messages";
import { EmptyState, FlowBodyViewer, useFlowBody } from "./FlowBodyViewer";
import { FlowHeaders, FlowQuery, queryParams } from "./FlowHeaders";
import { FlowMessages } from "./FlowMessages";
const TAB_RESPONSE = "response";
const TAB_REQUEST = "request";
const TAB_HEADERS = "headers";
const TAB_QUERY = "query";
const TAB_MESSAGES = "messages";
export function FlowDetail({ style, sideBySide }: { style?: CSSProperties; sideBySide: boolean }) {
const flow = useAtomValue(selectedFlowAtom);
@@ -75,9 +79,19 @@ function FlowPane({ flow }: { flow: Flow }) {
const queryCount = useMemo(() => queryParams(flow.url).length, [flow.url]);
const openSave = useSetAtom(saveDialogFlowAtom);
const flowActions = useFlowActions();
const messagesLabel = messagesTabLabel(flow);
const tabs = useMemo<TabItem[]>(
() => [
...(messagesLabel == null
? []
: [
{
value: TAB_MESSAGES,
label: messagesLabel,
rightSlot: <CountBadge count={flow.messageCount} color="info" showZero />,
},
]),
{
value: TAB_RESPONSE,
renderButton: ({ buttonProps, isActive }) => (
@@ -114,6 +128,8 @@ function FlowPane({ flow }: { flow: Flow }) {
},
],
[
messagesLabel,
flow.messageCount,
pretty,
mime,
flow.requestSize,
@@ -133,6 +149,7 @@ function FlowPane({ flow }: { flow: Flow }) {
)}
>
<HStack space={2} className="w-full shrink-0">
{streamIsOpen(flow) && <LoadingIcon size="sm" />}
{flow.cancelled && flow.status == null ? (
<span>Cancelled</span>
) : (
@@ -209,6 +226,9 @@ function FlowPane({ flow }: { flow: Flow }) {
</Banner>
)}
<Tabs
// A stream opens on its messages; moving between streams keeps the tab chosen
key={flow.streamKind == null ? "http" : "stream"}
defaultValue={messagesLabel == null ? undefined : TAB_MESSAGES}
tabs={tabs}
label="Flow"
className="ml-3 mr-3 mb-3 min-h-0 flex-1"
@@ -240,6 +260,11 @@ function FlowPane({ flow }: { flow: Flow }) {
<TabContent value={TAB_QUERY}>
<FlowQuery flow={flow} />
</TabContent>
{messagesLabel != null && (
<TabContent value={TAB_MESSAGES}>
<FlowMessages flow={flow} />
</TabContent>
)}
</Tabs>
</div>
</div>
+131
View File
@@ -0,0 +1,131 @@
import type { Flow } from "@yaakapp-internal/proxy-lib";
import {
type EventStreamColumns,
EventStreamViewer,
HStack,
type StreamEvent,
type StreamPayloadView,
} from "@yaakapp-internal/ui";
import { useCallback, useMemo } from "react";
import { useFlowMessages, useMessageSource } from "../hooks/useFlowMessages";
import { base64ToBytes } from "../lib/body";
import { grpcStatusText, messageToStreamEvent, streamIsOpen } from "../lib/messages";
const WEBSOCKET_COLUMNS: EventStreamColumns = {
direction: true,
kind: "Type",
preview: "Message",
size: true,
time: true,
};
const SSE_COLUMNS: EventStreamColumns = {
kind: "Event",
kindWidth: "9.5rem",
preview: "Data",
size: true,
time: true,
};
const GRPC_COLUMNS: EventStreamColumns = {
direction: true,
kind: "Type",
preview: "Message",
size: true,
time: true,
};
/**
* A streaming flow's messages: a WebSocket's frames, an event stream's events, a gRPC call's
* messages and status, following new ones while the stream is open. The selected message's
* payload opens below as text or a hexdump; a gRPC message's also decoded, with its schema or
* without one.
*/
export function FlowMessages({ flow }: { flow: Flow }) {
const source = useMessageSource();
const { messages, loading, error } = useFlowMessages(flow.id, source, flow.messageCount);
const events = useMemo(() => messages.map(messageToStreamEvent), [messages]);
const kind = flow.streamKind;
const grpc = kind === "grpc" || kind === "grpc_web";
const columns = kind === "sse" ? SSE_COLUMNS : grpc ? GRPC_COLUMNS : WEBSOCKET_COLUMNS;
const noun = kind === "sse" ? "Event" : "Message";
const catchUp = useMemo(
() => ({
label: (count: number) => `${count} new ${noun.toLowerCase()}${count === 1 ? "" : "s"}`,
}),
[noun],
);
const loadPayload = useCallback(
async (event: StreamEvent) => {
const res = await source.payload(flow.id, Number(event.key));
return { bytes: base64ToBytes(res.data) };
},
[flow.id, source],
);
const payloadViews = useCallback(
(event: StreamEvent): StreamPayloadView[] | null => {
if (!grpc || event.direction === "info") return null;
const decode = (schemaless: boolean) => async () => {
const decoded = await source.decodeGrpc(flow.id, Number(event.key), schemaless);
const note = [
decoded.messageType == null ? null : `Decoded as ${decoded.messageType}`,
decoded.note,
]
.filter(Boolean)
.join(". ");
return { text: decoded.json, language: "json" as const, note: note || null };
};
return [
{ value: "decoded", label: "Decoded", type: "text", load: decode(false) },
{ value: "schemaless", label: "Schemaless", type: "text", load: decode(true) },
{ value: "raw", label: "Raw bytes", type: "hexdump" },
];
},
[flow.id, grpc, source],
);
const open = streamIsOpen(flow);
const count = Math.max(flow.messageCount, messages.length);
const header = (
<HStack space={2} className="pl-2 mb-1 h-xs font-mono text-xs text-text-subtle">
{kind === "websocket" && (
<>
{open ? (
<span className="text-success">CONNECTED</span>
) : flow.error != null ? (
<span className="text-danger">ERROR</span>
) : (
<span className="text-text-subtle">CLOSED</span>
)}
<span>&bull;</span>
</>
)}
<span>
{count} {count === 1 ? noun : `${noun}s`}
</span>
{grpc && flow.grpcStatus != null && (
<>
<span>&bull;</span>
<span className={flow.grpcStatus === 0 ? "text-success" : "text-danger"}>
{grpcStatusText(flow.grpcStatus, flow.grpcMessage)}
</span>
</>
)}
</HStack>
);
return (
<EventStreamViewer
events={events}
header={header}
error={error ?? (open ? null : flow.error)}
isLoading={loading && events.length === 0}
emptyMessage={open ? `Waiting for the first ${noun.toLowerCase()}` : `No ${noun}s`}
splitLayoutStorageKey="proxy_flow_messages"
columns={columns}
loadPayload={loadPayload}
payloadViews={payloadViews}
catchUp={catchUp}
/>
);
}
@@ -0,0 +1,80 @@
import type { Flow } from "@yaakapp-internal/proxy-lib";
import { useSetAtom } from "jotai";
import { useLayoutEffect, useMemo, useState } from "react";
import { FlowDetail } from "../components/FlowDetail";
import { FlowList } from "../components/FlowList";
import { ProxyEditorHost } from "../components/ProxyEditorHost";
import { MessageSourceContext } from "../hooks/useFlowMessages";
import { selectedFlowAtom } from "../lib/atoms";
import { flowWindowAtom } from "../lib/store";
import { fixtureSource, type StreamFixture, streamFixtures } from "./streamFixtures";
/**
* Dev only: a streaming flow's detail, opened on its Messages tab, over fixtures served the way
* the engine serves them. Open `/harness.html?stream=0&theme=dark`; add `&list` for the flow list
* beside it, holding every fixture's flow.
*/
export function MessagesHarness() {
const params = new URLSearchParams(location.search);
const [index, setIndex] = useState(Number(params.get("stream") ?? 0));
const fixture = streamFixtures[index] ?? streamFixtures[0];
if (fixture == null) return null;
return (
<ProxyEditorHost>
<div className="h-full w-full grid grid-rows-[auto_minmax(0,1fr)] gap-2 p-2 bg-surface">
<div className="flex gap-2 text-sm">
{streamFixtures.map((f, i) => (
<button
key={f.flow.id}
type="button"
className={i === index ? "text-text" : "text-text-subtle"}
onClick={() => setIndex(i)}
>
{f.label}
</button>
))}
</div>
<StreamDetail key={fixture.flow.id} fixture={fixture} />
</div>
</ProxyEditorHost>
);
}
/** Each fixture's flow as the list holds it, one after another, the shown one as it is now */
function listedFlows(shown: Flow): Flow[] {
return streamFixtures.map((f, i) => {
const flow = f.flow.id === shown.id ? shown : f.flow;
return { ...flow, number: 1410 + i, startedAt: `2026-11-05T21:41:1${i}.000` };
});
}
function StreamDetail({ fixture }: { fixture: StreamFixture }) {
const source = useMemo(() => fixtureSource(fixture), [fixture]);
const setSelected = useSetAtom(selectedFlowAtom);
const setWindow = useSetAtom(flowWindowAtom);
const [flow, setFlow] = useState(fixture.flow);
const withList = new URLSearchParams(location.search).has("list");
useLayoutEffect(() => {
const flows = listedFlows(flow);
setWindow({ flows, hasOlder: false, total: flows.length });
setSelected(flows.find((f) => f.id === flow.id) ?? flow);
}, [flow, setSelected, setWindow]);
// The count on the flow follows its messages, as the engine writes it
useLayoutEffect(
() => source.subscribe(() => setFlow((f) => ({ ...f, messageCount: f.messageCount + 1 }))),
[source],
);
return (
<MessageSourceContext.Provider value={source}>
{withList ? (
<div className="h-full min-h-0 grid grid-cols-[minmax(0,0.9fr)_minmax(0,1.1fr)]">
<FlowList className="min-h-0" />
<FlowDetail sideBySide />
</div>
) : (
<FlowDetail sideBySide={false} />
)}
</MessageSourceContext.Provider>
);
}
+4 -2
View File
@@ -4,16 +4,18 @@ import { createStore, Provider } from "jotai";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { FlowPanesHarness } from "./FlowPanesHarness";
import { MessagesHarness } from "./MessagesHarness";
import "../main.css";
const dark = new URLSearchParams(location.search).get("theme") !== "light";
const params = new URLSearchParams(location.search);
const dark = params.get("theme") !== "light";
applyThemeToDocument(dark ? defaultDarkTheme : defaultLightTheme);
createRoot(document.getElementById("root") as HTMLElement).render(
<StrictMode>
<QueryClientProvider client={new QueryClient()}>
<Provider store={createStore()}>
<FlowPanesHarness />
{params.has("stream") ? <MessagesHarness /> : <FlowPanesHarness />}
</Provider>
</QueryClientProvider>
</StrictMode>,
+372
View File
@@ -0,0 +1,372 @@
import type { DecodedGrpcMessage, Flow, FlowMessage } from "@yaakapp-internal/proxy-lib";
import type { MessageSource } from "../hooks/useFlowMessages";
/** A streaming flow with its messages and their payloads, for the Messages tab */
export interface StreamFixture {
label: string;
flow: Flow;
messages: FlowMessage[];
payloads: Uint8Array[];
/** Messages still to come while the harness runs, one at a time */
later?: { message: FlowMessage; payload: Uint8Array }[];
decoded?: Record<number, { decoded: DecodedGrpcMessage; schemaless: DecodedGrpcMessage }>;
}
const encode = (s: string) => new TextEncoder().encode(s);
const flowBase: Flow = {
id: "fl_stream",
number: 1410,
createdAt: "2026-11-05T21:41:12",
updatedAt: "2026-11-05T21:41:20",
startedAt: "2026-11-05T21:41:12.100",
method: "GET",
url: "https://gateway.discord.gg/?v=10&encoding=json",
clientHttpVersion: "HTTP/1.1",
upstreamHttpVersion: "HTTP/1.1",
remoteAddr: "162.159.135.234:443",
status: 101,
contentType: null,
requestHeaders: [{ name: "Upgrade", value: "websocket" }],
responseHeaders: [{ name: "Upgrade", value: "websocket" }],
requestSize: 0,
responseSize: 0,
requestTruncated: false,
responseTruncated: false,
elapsedHeadersMs: 88,
elapsedMs: 128_400,
error: null,
cancelled: false,
savedRequestId: null,
clientPid: 812,
clientName: "Discord",
clientBundleId: "com.hnc.Discord",
clientPath: "/Applications/Discord.app",
clientCwd: null,
streamKind: "websocket",
messageCount: 0,
grpcService: null,
grpcMethod: null,
grpcStatus: null,
grpcMessage: null,
};
/** Seconds past 21:41:12 as a stored timestamp */
function at(seconds: number): string {
const ms = Math.round(seconds * 1000);
const s = 12 + Math.floor(ms / 1000);
const m = 41 + Math.floor(s / 60);
const pad = (n: number, w = 2) => String(n).padStart(w, "0");
return `2026-11-05T21:${pad(m)}:${pad(s % 60)}.${pad(ms % 1000, 3)}`;
}
function build(
flowId: string,
rows: [number, FlowMessage["direction"], FlowMessage["kind"], Uint8Array, FlowMessage["meta"]?][],
): { messages: FlowMessage[]; payloads: Uint8Array[] } {
const messages = rows.map(([seconds, direction, kind, payload, meta], seq) => {
const text = new TextDecoder().decode(payload);
const binary = kind === "websocket_binary" || kind === "grpc_message";
return {
id: `fm_${flowId}_${seq}`,
flowId,
seq,
direction,
kind,
timestamp: at(seconds),
size: kind === "sse_event" ? (meta?.raw?.length ?? payload.length) : payload.length,
storedSize: payload.length,
truncated: false,
compressed: false,
error: null,
meta: meta ?? {},
preview:
binary || kind === "grpc_trailers"
? null
: kind === "websocket_close"
? (meta?.closeReason ?? null)
: text.slice(0, 200) || null,
} satisfies FlowMessage;
});
return { messages, payloads: rows.map((r) => r[3]) };
}
const json = (v: unknown) => encode(JSON.stringify(v));
const ws = build("fl_ws", [
[0.09, "server", "websocket_text", json({ op: 10, d: { heartbeat_interval: 41250 } })],
[0.11, "client", "websocket_text", json({ op: 2, d: { token: "mfa.••••", intents: 3276799 } })],
[
0.41,
"server",
"websocket_text",
json({ t: "READY", s: 1, op: 0, d: { v: 10, session_id: "5f1c…" } }),
],
[
1.02,
"server",
"websocket_binary",
Uint8Array.from([0x78, 0x9c, 0xab, 0x56, 0xca, 0x2f, 0x50, 0xb2, 0x32, 0xd4, 0x51, 0x02, 0x00]),
],
[41.25, "client", "websocket_text", json({ op: 1, d: 1 })],
[41.31, "server", "websocket_text", json({ op: 11 })],
[
43.3,
"server",
"websocket_text",
json({
t: "MESSAGE_CREATE",
s: 5,
op: 0,
d: { content: "shipping the proxy beta tonight?", author: { username: "mara" } },
}),
],
[60.0, "server", "websocket_ping", new Uint8Array()],
[60.0, "client", "websocket_pong", new Uint8Array()],
[82.5, "client", "websocket_text", json({ op: 1, d: 5 })],
[82.56, "server", "websocket_text", json({ op: 11 })],
[
128.3,
"client",
"websocket_close",
Uint8Array.from([0x03, 0xe8, 0x62, 0x79, 0x65]),
{ closeCode: 1000, closeReason: "bye" },
],
[128.4, "server", "websocket_close", Uint8Array.from([0x03, 0xe8]), { closeCode: 1000 }],
]);
const sseEvents: [string, unknown][] = [
[
"message_start",
{
type: "message_start",
message: { id: "msg_01HqX", model: "claude-opus-5-5", usage: { input_tokens: 18204 } },
},
],
[
"content_block_start",
{ type: "content_block_start", index: 0, content_block: { type: "text", text: "" } },
],
["ping", { type: "ping" }],
[
"content_block_delta",
{
type: "content_block_delta",
index: 0,
delta: { type: "text_delta", text: "The 402 comes from" },
},
],
[
"content_block_delta",
{
type: "content_block_delta",
index: 0,
delta: { type: "text_delta", text: " Stripe: the card on" },
},
],
[
"content_block_delta",
{
type: "content_block_delta",
index: 0,
delta: { type: "text_delta", text: " file was declined with" },
},
],
[
"content_block_delta",
{
type: "content_block_delta",
index: 0,
delta: { type: "text_delta", text: " insufficient_funds." },
},
],
["content_block_stop", { type: "content_block_stop", index: 0 }],
[
"message_delta",
{ type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 312 } },
],
["message_stop", { type: "message_stop" }],
];
function sse(flowId: string, count: number) {
return build(
flowId,
sseEvents.slice(0, count).map(([event, data], i) => {
const payload = json(data);
const raw = `event: ${event}\ndata: ${new TextDecoder().decode(payload)}\n\n`;
return [0.8 + i * (i < 3 ? 0.05 : 0.18), "server", "sse_event", payload, { event, raw }];
}),
);
}
const sseFlow: Flow = {
...flowBase,
method: "POST",
url: "https://api.anthropic.com/v1/messages",
clientHttpVersion: "HTTP/2",
upstreamHttpVersion: "HTTP/2",
status: 200,
contentType: "text/event-stream; charset=utf-8",
responseHeaders: [{ name: "content-type", value: "text/event-stream; charset=utf-8" }],
clientName: "claude",
clientBundleId: null,
clientPath: "/opt/homebrew/bin/claude",
streamKind: "sse",
elapsedMs: 2_610,
};
const sseDone = sse("fl_sse_done", sseEvents.length);
const sseOpen = sse("fl_sse_open", sseEvents.length);
// A string in field 1, as a server-streaming call's replies
function proto(text: string, n?: number): Uint8Array {
const bytes = encode(text);
const out = [0x0a, bytes.length, ...bytes];
if (n != null) out.push(0x10, n);
return Uint8Array.from(out);
}
const grpcReplies = ["us-east-1a ok", "us-east-1b ok", "us-east-1c degraded", "eu-west-1a ok"];
const grpc = build("fl_grpc", [
[0.02, "client", "grpc_message", proto("prod")],
...grpcReplies.map(
(r, i) =>
[0.31 + i * 0.42, "server", "grpc_message", proto(r, i + 1)] as [
number,
"server",
"grpc_message",
Uint8Array,
],
),
[2.1, "server", "grpc_trailers", encode("grpc-status: 0\r\n"), { grpcStatus: 0 }],
]);
const schema = {
id: "gs_1",
createdAt: "2026-11-05T20:00:00",
updatedAt: "2026-11-05T20:00:00",
hostPattern: "health.internal",
source: "reflection" as const,
protoPaths: [],
services: ["ops.Health"],
};
const grpcDecoded: StreamFixture["decoded"] = Object.fromEntries(
[["prod"], ...grpcReplies.map((r, i) => [r, i + 1])].map(([text, n], seq) => [
seq,
{
decoded: {
json: JSON.stringify(
seq === 0
? { environment: text }
: { zone: String(text).split(" ")[0], state: String(text).split(" ")[1], sequence: n },
null,
2,
),
messageType: seq === 0 ? "ops.WatchRequest" : "ops.ZoneHealth",
schema,
note: null,
},
schemaless: {
json: JSON.stringify(
[
{ field: 1, wireType: "len", string: text },
...(n == null ? [] : [{ field: 2, wireType: "varint", value: n }]),
],
null,
2,
),
messageType: null,
schema: null,
note: "Decoded without a schema: field names and types are guesses",
},
},
]),
);
export const streamFixtures: StreamFixture[] = [
{
label: "WebSocket",
flow: { ...flowBase, id: "fl_ws", messageCount: ws.messages.length },
...ws,
},
{
label: "SSE, open",
flow: { ...sseFlow, id: "fl_sse_open", elapsedMs: null, messageCount: 6 },
messages: sseOpen.messages.slice(0, 6),
payloads: sseOpen.payloads,
later: sseOpen.messages.slice(6).map((message) => ({
message,
payload: sseOpen.payloads[message.seq] ?? new Uint8Array(),
})),
},
{
label: "SSE, done",
flow: { ...sseFlow, id: "fl_sse_done", messageCount: sseDone.messages.length },
...sseDone,
},
{
label: "gRPC stream",
flow: {
...flowBase,
id: "fl_grpc",
method: "POST",
url: "https://health.internal/ops.Health/Watch",
clientHttpVersion: "HTTP/2",
upstreamHttpVersion: "HTTP/2",
status: 200,
contentType: "application/grpc",
responseHeaders: [{ name: "content-type", value: "application/grpc" }],
clientName: "grpcurl",
clientPath: "/opt/homebrew/bin/grpcurl",
streamKind: "grpc",
grpcService: "ops.Health",
grpcMethod: "Watch",
grpcStatus: 0,
elapsedMs: 2_100,
messageCount: grpc.messages.length,
},
...grpc,
decoded: grpcDecoded,
},
];
function base64(bytes: Uint8Array): string {
let binary = "";
for (const b of bytes) binary += String.fromCharCode(b);
return btoa(binary);
}
/** The fixture's messages as the engine would serve them, the later ones arriving every 900 ms */
export function fixtureSource(fixture: StreamFixture): MessageSource {
const messages = [...fixture.messages];
const listeners = new Set<(m: FlowMessage) => void>();
const later = [...(fixture.later ?? [])];
if (later.length > 0) {
const timer = setInterval(() => {
const next = later.shift();
if (next == null) return clearInterval(timer);
messages.push(next.message);
for (const l of listeners) l(next.message);
}, 900);
}
return {
list: async (_flowId, afterSeq, limit) => {
const after = messages.filter((m) => afterSeq == null || m.seq > afterSeq);
return { messages: after.slice(0, limit), total: messages.length };
},
subscribe: (callback) => {
listeners.add(callback);
return () => listeners.delete(callback);
},
payload: async (_flowId, seq) => ({
data: base64(fixture.payloads[seq] ?? new Uint8Array()),
truncated: false,
}),
decodeGrpc: async (_flowId, seq, schemaless) => {
const entry = fixture.decoded?.[seq];
if (entry == null) throw new Error(`Message ${seq} is not a gRPC message`);
return schemaless ? entry.schemaless : entry.decoded;
},
};
}
+140
View File
@@ -0,0 +1,140 @@
import type {
DecodedGrpcMessage,
FlowMessage,
GetMessagePayloadResponse,
ListMessagesResponse,
} from "@yaakapp-internal/proxy-lib";
import { createContext, useContext, useEffect, useRef, useState } from "react";
import { mergeMessages } from "../lib/messages";
import { listen, rpc } from "../lib/rpc";
/** Where a flow's messages come from: the engine, or fixtures in the harness */
export interface MessageSource {
list: (
flowId: string,
afterSeq: number | undefined,
limit: number,
) => Promise<ListMessagesResponse>;
/** Calls back with each message as it is written. Returns an unsubscribe function */
subscribe: (callback: (message: FlowMessage) => void) => () => void;
payload: (flowId: string, seq: number) => Promise<GetMessagePayloadResponse>;
decodeGrpc: (flowId: string, seq: number, schemaless: boolean) => Promise<DecodedGrpcMessage>;
}
export const engineMessageSource: MessageSource = {
list: (flowId, afterSeq, limit) => rpc("list_messages", { flowId, afterSeq, limit }),
subscribe: (callback) => listen("message_write", ({ message }) => callback(message)),
payload: (flowId, seq) => rpc("get_message_payload", { flowId, seq }),
decodeGrpc: (flowId, seq, schemaless) => rpc("decode_grpc_message", { flowId, seq, schemaless }),
};
/** Where the Messages tab reads from: the engine, unless the harness provides fixtures */
export const MessageSourceContext = createContext<MessageSource>(engineMessageSource);
export function useMessageSource(): MessageSource {
return useContext(MessageSourceContext);
}
/** Messages read in one call at most, while catching up */
const PAGE = 500;
interface State {
flowId: string;
messages: FlowMessage[];
loading: boolean;
error: string | null;
}
/**
* A flow's messages, kept up to date while it streams: read in pages after the last one held,
* and added as each is written. A message that does not follow on from the last one held (one
* written while a page loaded) reads the pages after it instead.
*/
export function useFlowMessages(flowId: string, source: MessageSource, messageCount: number) {
// Reads what's after the last message held, for a count that says there's more
const readMore = useRef<(() => void) | null>(null);
const [state, setState] = useState<State>({
flowId,
messages: [],
loading: true,
error: null,
});
useEffect(() => {
let cancelled = false;
let messages: FlowMessage[] = [];
let reading = false;
let readAgain = false;
let frame: number | null = null;
const publish = (loading: boolean, error: string | null = null) => {
if (cancelled) return;
if (frame != null) cancelAnimationFrame(frame);
frame = null;
setState({ flowId, messages, loading, error });
};
// A chatty stream is drawn at most once a frame
const publishSoon = () => {
if (frame != null || cancelled) return;
frame = requestAnimationFrame(() => {
frame = null;
if (!cancelled) setState({ flowId, messages, loading: false, error: null });
});
};
const readAfter = async () => {
if (reading) {
readAgain = true;
return;
}
reading = true;
try {
for (;;) {
readAgain = false;
const last = messages[messages.length - 1];
const page = await source.list(flowId, last?.seq, PAGE);
if (cancelled) return;
messages = mergeMessages(messages, page.messages);
// Shown as each page lands, so a stream that never pauses still shows what's read
if (page.messages.length < PAGE && !readAgain) break;
publishSoon();
}
publish(false);
} catch (e) {
publish(false, String(e));
} finally {
reading = false;
}
};
setState({ flowId, messages: [], loading: true, error: null });
readMore.current = () => void readAfter();
void readAfter();
const unsubscribe = source.subscribe((message) => {
if (message.flowId !== flowId) return;
const last = messages[messages.length - 1];
const next = last == null ? 0 : last.seq + 1;
if (!reading && message.seq === next) {
messages = [...messages, message];
publishSoon();
} else if (last == null || message.seq > last.seq) {
void readAfter();
}
});
return () => {
cancelled = true;
if (frame != null) cancelAnimationFrame(frame);
unsubscribe();
};
}, [flowId, source]);
// A message written before the subscription took hold is in neither the first page nor its
// events; the flow's count, written after its messages, says it's there to read.
const held = state.flowId === flowId ? state.messages.length : 0;
useEffect(() => {
if (messageCount > held) readMore.current?.();
}, [held, messageCount]);
// Another flow's, until the effect has started over for this one
return state.flowId === flowId ? state : { flowId, messages: [], loading: true, error: null };
}
+18
View File
@@ -6,7 +6,9 @@ import {
bodyFileName,
bodyImageType,
bytesToText,
emptyBodyText,
flowBodyQueryOptions,
viewerBody,
viewerText,
} from "./body";
import { rpc } from "./rpc";
@@ -225,3 +227,19 @@ describe("flowBodyQueryOptions", () => {
client.clear();
});
});
describe("a body that isn't there", () => {
test("a WebSocket's note reaches the viewer, which points at its messages", () => {
const note = "A WebSocket has no body after its 101 response. Its frames are its messages.";
const body = viewerBody({ data: "", truncated: false, storedSize: 0, note });
expect(body.note).toBe(note);
expect(emptyBodyText("response", body.note)).toBe("No body. See Messages.");
});
test("any other empty body says so as before", () => {
const body = viewerBody({ data: "", truncated: false, storedSize: 0 });
expect(body.note).toBeNull();
expect(emptyBodyText("response", body.note)).toBe("Empty");
expect(emptyBodyText("request", body.note)).toBe("No request body");
});
});
+25 -10
View File
@@ -4,7 +4,12 @@ import {
decodeBodyText,
strictUtf8Text,
} from "@yaakapp-internal/lib/decodeBodyText";
import type { FilterLanguage, Flow, FlowBody } from "@yaakapp-internal/proxy-lib";
import type {
FilterLanguage,
Flow,
FlowBody,
GetFlowBodyResponse,
} from "@yaakapp-internal/proxy-lib";
import type { CodeEditorProps } from "@yaakapp-internal/ui/editor";
import vkBeautify from "vkbeautify";
import { rpc } from "./rpc";
@@ -13,20 +18,30 @@ import { rpc } from "./rpc";
export function flowBodyQueryOptions(flow: Flow, which: FlowBody) {
return queryOptions({
queryKey: ["get_flow_body", flow.id, which, flow.updatedAt],
queryFn: async () => {
const res = await rpc("get_flow_body", { flowId: flow.id, which });
return {
bytes: base64ToBytes(res.data),
truncated: res.truncated,
storedSize: res.storedSize,
decodeError: res.decodeError ?? null,
};
},
queryFn: async () => viewerBody(await rpc("get_flow_body", { flowId: flow.id, which })),
// Reading a stored body fails the same way every time, so the error shows at once.
retry: false,
});
}
/** The body RPC's answer as the viewer reads it, with what to know of it beyond its bytes */
export function viewerBody(res: GetFlowBodyResponse) {
return {
bytes: base64ToBytes(res.data),
truncated: res.truncated,
storedSize: res.storedSize,
decodeError: res.decodeError ?? null,
/** Why there is no body, as a WebSocket has none after its 101 */
note: res.note ?? null,
};
}
/** What an empty body's pane says: a WebSocket's points at its messages */
export function emptyBodyText(which: FlowBody, note: string | null): string {
if (note != null) return "No body. See Messages.";
return which === "request" ? "No request body" : "Empty";
}
export function base64ToBytes(data: string): Uint8Array<ArrayBuffer> {
const binary = atob(data);
const bytes = new Uint8Array(binary.length);
+118
View File
@@ -0,0 +1,118 @@
import type { FlowMessage } from "@yaakapp-internal/proxy-lib";
import { describe, expect, test } from "vite-plus/test";
import {
closeText,
grpcStatusText,
mergeMessages,
messagesTabLabel,
messageToStreamEvent,
streamIsOpen,
} from "./messages";
function message(seq: number, patch: Partial<FlowMessage> = {}): FlowMessage {
return {
id: `fm_${seq}`,
flowId: "fl_1",
seq,
direction: "server",
kind: "websocket_text",
timestamp: "2026-11-06T09:30:00.000",
size: 5,
storedSize: 5,
truncated: false,
compressed: false,
error: null,
meta: {},
preview: "hello",
...patch,
};
}
describe("mergeMessages", () => {
test("appends what follows on", () => {
const merged = mergeMessages([message(0), message(1)], [message(2), message(3)]);
expect(merged.map((m) => m.seq)).toEqual([0, 1, 2, 3]);
});
test("drops repeats and keeps order when a page overlaps live messages", () => {
const merged = mergeMessages([message(0), message(2)], [message(1), message(2), message(3)]);
expect(merged.map((m) => m.seq)).toEqual([0, 1, 2, 3]);
});
test("keeps the same array when nothing came", () => {
const existing = [message(0)];
expect(mergeMessages(existing, [])).toBe(existing);
});
});
describe("messageToStreamEvent", () => {
test("a WebSocket frame keeps its direction, type, size and time", () => {
expect(messageToStreamEvent(message(4, { direction: "client" }))).toMatchObject({
key: "4",
direction: "sent",
kind: "text",
size: 5,
timestamp: "2026-11-06T09:30:00.000",
preview: "hello",
binary: false,
});
expect(messageToStreamEvent(message(5, { kind: "websocket_binary" })).binary).toBe(true);
});
test("a close says its code and reason, and warns when it wasn't a normal close", () => {
const normal = messageToStreamEvent(
message(6, { kind: "websocket_close", meta: { closeCode: 1000, closeReason: "bye" } }),
);
expect([normal.kind, normal.note, normal.warning]).toEqual(["close", "1000 bye", false]);
const abnormal = messageToStreamEvent(
message(7, { kind: "websocket_close", meta: { closeCode: 1011 } }),
);
expect([abnormal.note, abnormal.warning]).toEqual(["1011", true]);
});
test("an event is named by its event field, or message", () => {
const named = messageToStreamEvent(message(0, { kind: "sse_event", meta: { event: "tick" } }));
expect(named.kind).toBe("tick");
expect(messageToStreamEvent(message(1, { kind: "sse_event" })).kind).toBe("message");
});
test("a gRPC call's trailers are its status row", () => {
const status = messageToStreamEvent(
message(2, { kind: "grpc_trailers", meta: { grpcStatus: 12, grpcMessage: "not here" } }),
);
expect(status).toMatchObject({
direction: "info",
kind: "status",
note: "12 UNIMPLEMENTED: not here",
warning: true,
});
});
});
describe("labels", () => {
test("statuses and closes", () => {
expect(grpcStatusText(0)).toBe("0 OK");
expect(grpcStatusText(42)).toBe("42");
expect(grpcStatusText(null, "gone")).toBe("gone");
expect(closeText(null, null)).toBe("No status code");
});
test("the tab is Events for an event stream and Messages for the rest", () => {
expect(messagesTabLabel({ streamKind: "sse" })).toBe("Events");
expect(messagesTabLabel({ streamKind: "websocket" })).toBe("Messages");
expect(messagesTabLabel({ streamKind: null })).toBeNull();
});
test("a stream is open until it ends, fails or is cancelled", () => {
const open = {
streamKind: "websocket" as const,
elapsedMs: null,
error: null,
cancelled: false,
};
expect(streamIsOpen(open)).toBe(true);
expect(streamIsOpen({ ...open, elapsedMs: 10 })).toBe(false);
expect(streamIsOpen({ ...open, error: "reset" })).toBe(false);
expect(streamIsOpen({ ...open, streamKind: null })).toBe(false);
});
});
+132
View File
@@ -0,0 +1,132 @@
import type { Flow, FlowMessage, MessageKind } from "@yaakapp-internal/proxy-lib";
import type { StreamEvent } from "@yaakapp-internal/ui";
/** gRPC's status codes by number, as a call's status row names them */
const GRPC_STATUS = [
"OK",
"CANCELLED",
"UNKNOWN",
"INVALID_ARGUMENT",
"DEADLINE_EXCEEDED",
"NOT_FOUND",
"ALREADY_EXISTS",
"PERMISSION_DENIED",
"RESOURCE_EXHAUSTED",
"FAILED_PRECONDITION",
"ABORTED",
"OUT_OF_RANGE",
"UNIMPLEMENTED",
"INTERNAL",
"UNAVAILABLE",
"DATA_LOSS",
"UNAUTHENTICATED",
];
const KIND_LABELS: Record<MessageKind, string> = {
websocket_text: "text",
websocket_binary: "binary",
websocket_ping: "ping",
websocket_pong: "pong",
websocket_close: "close",
sse_event: "message",
grpc_message: "message",
grpc_trailers: "status",
};
/** A gRPC status as its row shows it: `0 OK`, `12 UNIMPLEMENTED: not here` */
export function grpcStatusText(status: number | null | undefined, message?: string | null) {
if (status == null) return message ?? "No status";
const name = GRPC_STATUS[status];
const code = name == null ? String(status) : `${status} ${name}`;
return message ? `${code}: ${message}` : code;
}
/** A WebSocket close as its row shows it: `1000 bye`, or that it had no code */
export function closeText(code: number | null | undefined, reason: string | null | undefined) {
const parts = [code == null ? "No status code" : String(code), reason ?? ""].filter(Boolean);
return parts.join(" ");
}
/** A stored message as the shared event stream viewer lists it */
export function messageToStreamEvent(message: FlowMessage): StreamEvent {
const { kind, meta } = message;
const base: StreamEvent = {
key: String(message.seq),
direction: message.direction === "client" ? "sent" : "received",
kind: KIND_LABELS[kind],
timestamp: message.timestamp,
size: message.size,
preview: message.preview,
binary: kind === "websocket_binary" || kind === "grpc_message",
truncated: message.truncated,
error: message.error,
};
switch (kind) {
case "sse_event":
return { ...base, kind: meta.event ?? "message", title: "Event Received" };
case "websocket_close":
return {
...base,
note: closeText(meta.closeCode, meta.closeReason),
title: message.direction === "client" ? "Closed by the App" : "Closed by the Server",
warning: meta.closeCode != null && meta.closeCode !== 1000 && meta.closeCode !== 1001,
};
case "websocket_ping":
case "websocket_pong":
return { ...base, title: kind === "websocket_ping" ? "Ping" : "Pong" };
case "grpc_trailers":
return {
...base,
direction: "info",
note: grpcStatusText(meta.grpcStatus, meta.grpcMessage),
title: "Call Status",
warning: meta.grpcStatus != null && meta.grpcStatus !== 0,
};
default:
return base;
}
}
/**
* `incoming` added to `existing`, both in order by seq, without repeats: a page and the
* messages that arrived while it loaded can overlap.
*/
export function mergeMessages(existing: FlowMessage[], incoming: FlowMessage[]): FlowMessage[] {
if (incoming.length === 0) return existing;
const last = existing[existing.length - 1];
if (last == null) return dedupeSorted(incoming);
const first = incoming[0];
// The usual case: what comes next follows on
if (first != null && first.seq > last.seq && isSorted(incoming)) {
return [...existing, ...incoming];
}
return dedupeSorted([...existing, ...incoming]);
}
function isSorted(messages: FlowMessage[]): boolean {
for (let i = 1; i < messages.length; i++) {
const prev = messages[i - 1];
const next = messages[i];
if (prev == null || next == null || next.seq <= prev.seq) return false;
}
return true;
}
function dedupeSorted(messages: FlowMessage[]): FlowMessage[] {
const bySeq = new Map<number, FlowMessage>();
for (const message of messages) bySeq.set(message.seq, message);
return [...bySeq.values()].sort((a, b) => a.seq - b.seq);
}
/** The Messages tab's name for a flow's stream, or null for a flow that isn't one */
export function messagesTabLabel(flow: Pick<Flow, "streamKind">): string | null {
if (flow.streamKind == null) return null;
return flow.streamKind === "sse" ? "Events" : "Messages";
}
/** Whether a stream is still open: it has no end, error or cancel yet */
export function streamIsOpen(
flow: Pick<Flow, "streamKind" | "elapsedMs" | "error" | "cancelled">,
): boolean {
return flow.streamKind != null && flow.elapsedMs == null && flow.error == null && !flow.cancelled;
}
+6 -3
View File
@@ -2,7 +2,8 @@
import type { ModelChangeEvent } from "./ModelChangeEvent";
/**
* One proxied request and its response. The bodies are in `blobs.sqlite`, not the row.
* One proxied request and its response. The bodies are in `blobs.sqlite`, not the row; a
* stream's are its messages, and read back from them (`bodies::from_messages`).
*/
export type Flow = { id: string,
/**
@@ -31,11 +32,13 @@ requestSize: number,
*/
responseSize: number,
/**
* Only the first `capture_body_limit` bytes of the body are stored.
* Only the first `capture_body_limit` bytes of the body are stored. For a body that is a
* stream's messages, a message was cut at the limit.
*/
requestTruncated: boolean,
/**
* Only the first `capture_body_limit` bytes of the body are stored.
* Only the first `capture_body_limit` bytes of the body are stored. For a body that is a
* stream's messages, a message was cut at the limit.
*/
responseTruncated: boolean,
/**
+10 -2
View File
@@ -58,7 +58,11 @@ path: string,
*/
cwd: string | null, };
export type DecodeGrpcMessageRequest = { flowId: string, seq: number, };
export type DecodeGrpcMessageRequest = { flowId: string, seq: number,
/**
* Decode without a schema even when one is found.
*/
schemaless?: boolean, };
/**
* A captured gRPC message as JSON.
@@ -201,7 +205,11 @@ storedSize: number,
/**
* Why the body failed to decode, in which case `data` is as it was on the wire.
*/
decodeError?: string, };
decodeError?: string,
/**
* What to know about the body beyond its bytes, as that a WebSocket has none.
*/
note?: string, };
export type GetMessagePayloadRequest = { flowId: string, seq: number, };
+408 -14
View File
@@ -1,9 +1,45 @@
use crate::models::{Flow, FlowBody, find_header};
use crate::db::ProxyQueryManager;
use crate::messages::{self, FlowMessage, MessageDirection, MessageKind};
use crate::models::{Flow, FlowBody, StreamKind, find_header};
use base64::Engine;
use base64::engine::general_purpose::STANDARD as BASE64;
use std::io::Cursor;
use tokio::io::AsyncReadExt;
use yaak_http::decompress::{ContentEncoding, streaming_decoder};
use yaak_models::blob_manager::BlobManager;
/// Messages read at a time while putting a body back together.
const MESSAGE_PAGE: usize = 500;
/// What a WebSocket's response body reads as: it has none.
pub const WEBSOCKET_BODY_NOTE: &str =
"A WebSocket has no body after its 101 response. Its frames are its messages.";
/// Whether a flow's body is its stream's messages rather than bytes stored on their own: an
/// event stream's response, a gRPC call's request, and its response when the server answered
/// in gRPC (a gateway's error page is a body like any other), and a WebSocket's response. Such a
/// body is not written to `blobs.sqlite`; reading it puts it back together from the messages.
///
/// A body with a Content-Encoding keeps its bytes instead: the messages are read from it decoded,
/// but only its bytes can say whether they decoded whole (gzip's checksum, an encoding the
/// stream's reader can't undo), and they read back through the body's decoder as any other.
pub fn from_messages(flow: &Flow, which: FlowBody) -> bool {
let encoding = find_header(flow.headers(which), "content-encoding").map(str::trim);
let encoded = encoding.is_some_and(|e| !e.is_empty() && !e.eq_ignore_ascii_case("identity"));
if encoded && flow.stream_kind != Some(StreamKind::Websocket) {
return false;
}
match (flow.stream_kind, which) {
(None, _) => false,
(Some(StreamKind::Websocket | StreamKind::Sse), FlowBody::Request) => false,
(Some(StreamKind::Websocket | StreamKind::Sse), FlowBody::Response) => true,
(Some(StreamKind::Grpc | StreamKind::GrpcWeb), FlowBody::Request) => true,
(Some(StreamKind::Grpc | StreamKind::GrpcWeb), FlowBody::Response) => {
yaak_proxy::detect_grpc(find_header(&flow.response_headers, "content-type")).is_some()
}
}
}
/// A flow's body as stored: the bytes on the wire, up to the capture limit.
pub fn read_raw_body(
blobs: &BlobManager,
@@ -25,16 +61,32 @@ pub struct DecodedBody {
pub truncated: bool,
/// Why decoding stopped before the end of the stored bytes.
pub decode_error: Option<String>,
/// What to know about the body beyond its bytes, as that a WebSocket has none.
pub note: Option<String>,
}
impl DecodedBody {
pub fn new(data: Vec<u8>, truncated: bool) -> Self {
Self { stored_size: data.len(), data, truncated, decode_error: None, note: None }
}
}
/// A flow's body decoded with its Content-Encoding, at most `limit` bytes of it. A body that
/// fails to decode, as one cut short does, keeps what decoded before the failure.
/// fails to decode, as one cut short does, keeps what decoded before the failure. A body that is
/// a stream's messages is put back together from them, decoded as they are.
pub async fn read_body(
db: &ProxyQueryManager,
blobs: &BlobManager,
flow: &Flow,
body: FlowBody,
limit: usize,
) -> Result<DecodedBody, String> {
// A gRPC call that ended while its upload still went on kept the upload's bytes instead.
if from_messages(flow, body)
&& !blobs.connect().body_exists(&Flow::body_id(&flow.id, body)).unwrap_or(false)
{
return message_body(db, blobs, flow, body, limit);
}
let raw = read_raw_body(blobs, &flow.id, body)?;
let stored_size = raw.len();
// A response that failed or was cancelled after its headers ended short on the wire.
@@ -49,7 +101,7 @@ pub async fn read_body(
let truncated = wire_truncated || raw.len() > limit;
let mut data = raw;
data.truncate(limit);
return Ok(DecodedBody { data, stored_size, truncated, decode_error: None });
return Ok(DecodedBody { data, stored_size, truncated, decode_error: None, note: None });
}
// One byte past the limit tells a body that fills it from one that overflows it.
@@ -64,7 +116,147 @@ pub async fn read_body(
};
let truncated = wire_truncated || decode_error.is_some() || data.len() > limit;
data.truncate(limit);
Ok(DecodedBody { data, stored_size, truncated, decode_error })
Ok(DecodedBody { data, stored_size, truncated, decode_error, note: None })
}
/// A body that is its stream's messages, as it was on the wire once decoded: an event stream's
/// events as they came, comments within an event included, and a gRPC call's messages framed
/// again (uncompressed, so flagged as such), with a gRPC-Web response's trailers frame, in base64
/// for `grpc-web-text`. Blocks of an event stream that were not events, as a keep-alive comment
/// alone is, are not kept, so are not in it.
fn message_body(
db: &ProxyQueryManager,
blobs: &BlobManager,
flow: &Flow,
which: FlowBody,
limit: usize,
) -> Result<DecodedBody, String> {
let Some(kind) = flow.stream_kind else {
return Ok(DecodedBody::new(Vec::new(), false));
};
if kind == StreamKind::Websocket {
return Ok(DecodedBody {
note: Some(WEBSOCKET_BODY_NOTE.into()),
..DecodedBody::new(Vec::new(), false)
});
}
let direction = match which {
FlowBody::Request => MessageDirection::Client,
FlowBody::Response => MessageDirection::Server,
};
let content_type = find_header(flow.headers(which), "content-type");
let base64_text = yaak_proxy::detect_grpc(content_type).is_some_and(|(_, text)| text);
// The status of a trailers-only response came in its headers, not a frame of its body.
let trailers_in_body = kind == StreamKind::GrpcWeb
&& which == FlowBody::Response
&& find_header(&flow.response_headers, "grpc-status").is_none();
// Enough to fill the limit, after base64 makes it a third longer.
let room = if base64_text { limit / 3 * 4 + 4 } else { limit };
// A response that failed or was cancelled after its headers ended short, as `read_body`
// says of one stored whole.
let mut truncated = which == FlowBody::Response
&& flow.status.is_some()
&& (flow.error.is_some() || flow.cancelled);
let mut out = Vec::new();
let mut after = None;
// Read a page at a time, and no further than the limit needs.
'pages: loop {
let page = messages::list(db, &flow.id, after, Some(MESSAGE_PAGE))?;
let Some(last) = page.last() else {
break;
};
after = Some(last.seq);
let full = page.len() == MESSAGE_PAGE;
for message in page {
if out.len() > room {
truncated = true;
break 'pages;
}
if message.direction != direction {
continue;
}
match message.kind {
MessageKind::SseEvent => {
let payload = messages::payload(db, blobs, &message)?;
out.extend_from_slice(&sse_event_lines(&message, &payload));
}
MessageKind::GrpcMessage | MessageKind::GrpcTrailers
if message.kind == MessageKind::GrpcMessage || trailers_in_body =>
{
let payload = messages::payload(db, blobs, &message)?;
let flag = if message.kind == MessageKind::GrpcMessage { 0 } else { 0x80 };
// A frame cut short declares more than it holds, so a reader would take the
// frames after it as its rest: the body ends there, cut.
if !grpc_frame(&mut out, flag, &message, &payload) {
truncated = true;
break 'pages;
}
}
_ => continue,
}
truncated |= message.truncated;
}
if !full {
break;
}
}
if base64_text {
out = BASE64.encode(&out).into_bytes();
}
let stored_size = out.len();
truncated |= out.len() > limit;
out.truncate(limit);
Ok(DecodedBody { data: out, stored_size, truncated, decode_error: None, note: None })
}
/// An event's lines as they came. Its raw lines are kept up to [`yaak_proxy::RAW_LIMIT`]; an
/// event longer than that is written again from its fields, as `event`, `id`, `retry` and a
/// `data` line for each line of its data.
fn sse_event_lines(message: &FlowMessage, payload: &[u8]) -> Vec<u8> {
if let Some(raw) = &message.meta.raw
&& i64::try_from(raw.len()).is_ok_and(|len| len == message.size)
{
return raw.as_bytes().to_vec();
}
let mut out = Vec::new();
let meta = &message.meta;
if let Some(event) = &meta.event {
out.extend_from_slice(format!("event: {event}\n").as_bytes());
}
if let Some(id) = &meta.event_id {
out.extend_from_slice(format!("id: {id}\n").as_bytes());
}
if let Some(retry) = meta.retry {
out.extend_from_slice(format!("retry: {retry}\n").as_bytes());
}
for line in payload.split(|b| *b == b'\n') {
out.extend_from_slice(b"data: ");
out.extend_from_slice(line);
out.push(b'\n');
}
out.push(b'\n');
out
}
/// Appends a gRPC length-prefixed message: its flag byte, its length, and its bytes.
/// A message decompressed is framed again uncompressed, at its decompressed length. One kept as
/// it came (never compressed, or failing to decompress) keeps its flag and the length it was
/// sent with, so one cut short (at the capture limit, or by the body ending partway through it)
/// reads back as it was on the wire, cut.
///
/// Returns whether the frame is whole: false when it declares more bytes than it holds.
fn grpc_frame(out: &mut Vec<u8>, flag: u8, message: &FlowMessage, payload: &[u8]) -> bool {
let as_sent = !message.compressed || message.error.is_some();
let (flag, length) = if as_sent {
(flag | u8::from(message.compressed), usize::try_from(message.size).unwrap_or(usize::MAX))
} else {
(flag, payload.len())
};
out.push(flag);
out.extend_from_slice(&u32::try_from(length).unwrap_or(u32::MAX).to_be_bytes());
out.extend_from_slice(payload);
payload.len() >= length
}
/// A body's text as the app's viewer reads it, as `decodeBodyText` in `@yaakapp-internal/lib`
@@ -107,12 +299,13 @@ fn strict_utf8(data: &[u8], truncated: bool) -> Option<String> {
/// A flow's body decoded as `read_body` does, or, when it fails to decode, the bytes as they were
/// on the wire, with `decode_error` saying why.
pub async fn read_body_or_raw(
db: &ProxyQueryManager,
blobs: &BlobManager,
flow: &Flow,
body: FlowBody,
limit: usize,
) -> Result<DecodedBody, String> {
let decoded = read_body(blobs, flow, body, limit).await?;
let decoded = read_body(db, blobs, flow, body, limit).await?;
if decoded.decode_error.is_none() {
return Ok(decoded);
}
@@ -127,9 +320,16 @@ mod tests {
use super::*;
use yaak_models::blob_manager::BodyChunkWriter;
fn proxy_db() -> (tempfile::TempDir, ProxyQueryManager) {
let dir = tempfile::tempdir().unwrap();
let db = ProxyQueryManager::new(&dir.path().join("proxy.db")).unwrap();
(dir, db)
}
#[tokio::test]
async fn response_failed_after_its_headers_is_truncated() {
let (_db, blobs, _rx) = yaak_models::init_in_memory().unwrap();
let (_dir, db) = proxy_db();
let mut writer =
BodyChunkWriter::new(blobs.clone(), Flow::body_id("fl_cut", FlowBody::Response));
writer.write(b"{\"rows\": [").unwrap();
@@ -141,18 +341,20 @@ mod tests {
..Default::default()
};
let body = read_body(&blobs, &cut, FlowBody::Response, 1024).await.unwrap();
let body = read_body(&db, &blobs, &cut, FlowBody::Response, 1024).await.unwrap();
assert_eq!((body.data.as_slice(), body.truncated), (&b"{\"rows\": ["[..], true));
// The request went out whole; the error is the response's.
let request = read_body(&blobs, &cut, FlowBody::Request, 1024).await.unwrap();
let request = read_body(&db, &blobs, &cut, FlowBody::Request, 1024).await.unwrap();
assert!(!request.truncated);
// With no headers there was never a response body to cut.
let refused = Flow { status: None, ..cut.clone() };
assert!(!read_body(&blobs, &refused, FlowBody::Response, 1024).await.unwrap().truncated);
assert!(
!read_body(&db, &blobs, &refused, FlowBody::Response, 1024).await.unwrap().truncated
);
// The client cancelling partway through cuts it short the same way.
let cancelled = Flow { error: None, cancelled: true, ..cut };
let body = read_body(&blobs, &cancelled, FlowBody::Response, 1024).await.unwrap();
let body = read_body(&db, &blobs, &cancelled, FlowBody::Response, 1024).await.unwrap();
assert_eq!((body.data.as_slice(), body.truncated), (&b"{\"rows\": ["[..], true));
}
@@ -160,6 +362,7 @@ mod tests {
async fn cancelled_gzip_response_keeps_what_decoded() {
use std::io::Write;
let (_db, blobs, _rx) = yaak_models::init_in_memory().unwrap();
let (_dir, db) = proxy_db();
let mut gzip = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default());
gzip.write_all(&[b'z'; 4096]).unwrap();
let gzip = gzip.finish().unwrap();
@@ -178,7 +381,7 @@ mod tests {
..Default::default()
};
let body = read_body(&blobs, &flow, FlowBody::Response, 8192).await.unwrap();
let body = read_body(&db, &blobs, &flow, FlowBody::Response, 8192).await.unwrap();
assert!(body.truncated);
assert_eq!(body.decode_error, None);
}
@@ -240,6 +443,7 @@ mod tests {
async fn deflate_request_bodies_decode_wrapped_or_raw() {
use std::io::Write;
let (_db, blobs, _rx) = yaak_models::init_in_memory().unwrap();
let (_dir, db) = proxy_db();
let logs = br#"[{"message":"hello","service":"browser"}]"#;
let mut zlib = flate2::write::ZlibEncoder::new(Vec::new(), flate2::Compression::default());
zlib.write_all(logs).unwrap();
@@ -252,7 +456,7 @@ mod tests {
("fl_raw", raw.finish().unwrap()),
] {
let flow = deflate_request(&blobs, id, &stored);
let body = read_body(&blobs, &flow, FlowBody::Request, 1024).await.unwrap();
let body = read_body(&db, &blobs, &flow, FlowBody::Request, 1024).await.unwrap();
assert_eq!(body.decode_error, None, "{id}");
assert_eq!((body.data.as_slice(), body.truncated), (&logs[..], false), "{id}");
}
@@ -261,15 +465,205 @@ mod tests {
#[tokio::test]
async fn undecodable_body_reads_as_it_was_on_the_wire() {
let (_db, blobs, _rx) = yaak_models::init_in_memory().unwrap();
let (_dir, db) = proxy_db();
let flow = deflate_request(&blobs, "fl_bad", b"\x00\x01 not deflate");
let decoded = read_body(&blobs, &flow, FlowBody::Request, 1024).await.unwrap();
let decoded = read_body(&db, &blobs, &flow, FlowBody::Request, 1024).await.unwrap();
assert!(decoded.decode_error.is_some());
let raw = read_body_or_raw(&blobs, &flow, FlowBody::Request, 1024).await.unwrap();
let raw = read_body_or_raw(&db, &blobs, &flow, FlowBody::Request, 1024).await.unwrap();
assert_eq!(raw.data, b"\x00\x01 not deflate");
assert!(!raw.truncated);
assert_eq!(raw.decode_error, decoded.decode_error);
let cut = read_body_or_raw(&blobs, &flow, FlowBody::Request, 4).await.unwrap();
let cut = read_body_or_raw(&db, &blobs, &flow, FlowBody::Request, 4).await.unwrap();
assert_eq!((cut.data.as_slice(), cut.truncated), (&b"\x00\x01 n"[..], true));
}
/// Stores `messages` for `flow_id` as the event loop does, payloads inline.
fn store_messages(
db: &ProxyQueryManager,
flow_id: &str,
messages: &[yaak_proxy::StreamMessage],
) {
db.with_conn(|c| {
for (seq, message) in messages.iter().enumerate() {
let row = FlowMessage::from_engine(flow_id, seq as i64, message);
messages::insert(c.conn().resolve(), &row, Some(&message.data)).unwrap();
}
});
}
fn stream_message(
direction: yaak_proxy::MessageDirection,
kind: yaak_proxy::MessageKind,
size: u64,
data: &[u8],
) -> yaak_proxy::StreamMessage {
yaak_proxy::StreamMessage {
direction,
kind,
at: std::time::SystemTime::now(),
size,
data: bytes::Bytes::copy_from_slice(data),
truncated: false,
compressed: false,
error: None,
}
}
/// An event's raw lines are kept up to a limit; past it, the event is written again from its
/// fields. Either way, nothing of the body was stored on its own.
#[tokio::test]
async fn event_stream_body_is_its_events() {
use yaak_proxy::{MessageDirection as D, MessageKind as K};
let (_db, blobs, _rx) = yaak_models::init_in_memory().unwrap();
let (_dir, db) = proxy_db();
let short = ": hello\nevent: tick\ndata: one\n\n";
let long_data = format!("{}\n{}", "a".repeat(3000), "b".repeat(3000));
let long_size = format!(
"event: big\nid: 7\ndata: {}\ndata: {}\n\n",
"a".repeat(3000),
"b".repeat(3000)
)
.len();
let sse = |event: &str, id: Option<&str>, raw: &str| K::SseEvent {
event: Some(event.into()),
id: id.map(String::from),
retry: None,
raw: raw.into(),
};
store_messages(
&db,
"fl_sse",
&[
stream_message(D::Server, sse("tick", None, short), short.len() as u64, b"one"),
stream_message(
D::Server,
sse("big", Some("7"), &"x".repeat(yaak_proxy::RAW_LIMIT)),
long_size as u64,
long_data.as_bytes(),
),
],
);
let flow =
Flow { id: "fl_sse".into(), stream_kind: Some(StreamKind::Sse), ..Default::default() };
let body = read_body(&db, &blobs, &flow, FlowBody::Response, 1 << 20).await.unwrap();
let expected = format!(
"{short}event: big\nid: 7\ndata: {}\ndata: {}\n\n",
"a".repeat(3000),
"b".repeat(3000)
);
assert_eq!(String::from_utf8(body.data).unwrap(), expected);
assert_eq!((body.truncated, body.decode_error, body.note), (false, None, None));
// The request is no stream, and reads from the blob store as any other.
assert!(!from_messages(&flow, FlowBody::Request));
let cut = read_body(&db, &blobs, &flow, FlowBody::Response, 10).await.unwrap();
assert_eq!((cut.data.as_slice(), cut.truncated), (&short.as_bytes()[..10], true));
// Ended by a failure or a cancel, it is cut short, however whole its events are.
let cancelled = Flow { status: Some(200), cancelled: true, ..flow.clone() };
assert!(
read_body(&db, &blobs, &cancelled, FlowBody::Response, 1 << 20)
.await
.unwrap()
.truncated
);
// With a Content-Encoding, the bytes are its record, whatever the encoding.
for encoding in ["gzip", "br"] {
let encoded = Flow {
response_headers: vec![crate::models::ProxyHeader {
name: "Content-Encoding".into(),
value: encoding.into(),
}],
..flow.clone()
};
assert!(!from_messages(&encoded, FlowBody::Response), "{encoding}");
}
}
/// A message cut at the capture limit declares more than it holds: the body ends with it,
/// so no reader takes the frames after it as its rest.
#[tokio::test]
async fn grpc_body_ends_at_a_cut_message() {
use yaak_proxy::{MessageDirection as D, MessageKind as K};
let (_db, blobs, _rx) = yaak_models::init_in_memory().unwrap();
let (_dir, db) = proxy_db();
let mut cut = stream_message(D::Server, K::GrpcMessage, 11, b"\x0a\x09Hel");
cut.truncated = true;
store_messages(
&db,
"fl_cut",
&[
stream_message(D::Server, K::GrpcMessage, 2, b"\x08\x01"),
cut,
stream_message(D::Server, K::GrpcMessage, 2, b"\x08\x02"),
],
);
let flow = Flow {
id: "fl_cut".into(),
stream_kind: Some(StreamKind::Grpc),
response_headers: vec![crate::models::ProxyHeader {
name: "content-type".into(),
value: "application/grpc".into(),
}],
..Default::default()
};
let body = read_body(&db, &blobs, &flow, FlowBody::Response, 1024).await.unwrap();
assert_eq!(body.data, b"\x00\x00\x00\x00\x02\x08\x01\x00\x00\x00\x00\x0b\x0a\x09Hel");
assert!(body.truncated);
}
#[tokio::test]
async fn grpc_web_text_body_is_its_frames_in_base64() {
use yaak_proxy::{MessageDirection as D, MessageKind as K};
let (_db, blobs, _rx) = yaak_models::init_in_memory().unwrap();
let (_dir, db) = proxy_db();
let trailers = K::GrpcTrailers { status: Some(0), message: None };
store_messages(
&db,
"fl_web",
&[
stream_message(D::Client, K::GrpcMessage, 2, b"\x08\x01"),
stream_message(D::Server, K::GrpcMessage, 2, b"\x08\x02"),
stream_message(D::Server, trailers, 16, b"grpc-status: 0\r\n"),
],
);
let header = |name: &str, value: &str| crate::models::ProxyHeader {
name: name.into(),
value: value.into(),
};
let flow = Flow {
id: "fl_web".into(),
stream_kind: Some(StreamKind::GrpcWeb),
request_headers: vec![header("content-type", "application/grpc-web-text")],
response_headers: vec![header("content-type", "application/grpc-web-text+proto")],
..Default::default()
};
let request = read_body(&db, &blobs, &flow, FlowBody::Request, 1024).await.unwrap();
assert_eq!(request.data, BASE64.encode(b"\x00\x00\x00\x00\x02\x08\x01").as_bytes());
let response = read_body(&db, &blobs, &flow, FlowBody::Response, 1024).await.unwrap();
let mut frames = b"\x00\x00\x00\x00\x02\x08\x02\x80\x00\x00\x00\x10".to_vec();
frames.extend_from_slice(b"grpc-status: 0\r\n");
assert_eq!(response.data, BASE64.encode(&frames).as_bytes());
// A trailers-only answer's status came in its headers, not a frame.
let trailers_only = Flow {
response_headers: vec![
header("content-type", "application/grpc-web"),
header("grpc-status", "0"),
],
..flow.clone()
};
let response =
read_body(&db, &blobs, &trailers_only, FlowBody::Response, 1024).await.unwrap();
assert_eq!(response.data, b"\x00\x00\x00\x00\x02\x08\x02");
// A gateway's error page in place of a gRPC answer is a body like any other.
let gateway = Flow { response_headers: vec![header("content-type", "text/html")], ..flow };
assert!(!from_messages(&gateway, FlowBody::Response));
assert!(from_messages(&gateway, FlowBody::Request));
}
}
+4 -3
View File
@@ -5,7 +5,7 @@
use crate::bodies::{self, DecodedBody};
use crate::ca::CaStatus;
use crate::control::{
self, ControlInfo, ControlStatus, ErrorBody, RecordingRequest, StartRequest,
self, ControlInfo, ControlStatus, ErrorBody, NOTE_HEADER, RecordingRequest, StartRequest,
SystemProxyRequest, TRUNCATED_HEADER,
};
use crate::db::ProxyQueryManager;
@@ -111,8 +111,9 @@ impl ControlClient {
let resp =
self.send(self.http.get(self.url(&format!("/flows/{}/{side}", encode(id))))).await?;
let truncated = resp.headers().get(TRUNCATED_HEADER).is_some_and(|v| v == "true");
let note = resp.headers().get(NOTE_HEADER).and_then(|v| v.to_str().ok()).map(String::from);
let data = resp.bytes().await.map_err(|e| e.to_string())?.to_vec();
Ok(DecodedBody { stored_size: data.len(), data, truncated, decode_error: None })
Ok(DecodedBody { note, ..DecodedBody::new(data, truncated) })
}
pub async fn har(&self, filter: &FlowFilter) -> Result<Har, String> {
@@ -225,7 +226,7 @@ impl OfflineStore {
pub async fn body(&self, id: &str, which: FlowBody) -> Result<DecodedBody, String> {
let flow = flows::get(&self.db, id)?;
bodies::read_body(&self.blobs, &flow, which, self.capture_body_limit).await
bodies::read_body(&self.db, &self.blobs, &flow, which, self.capture_body_limit).await
}
pub async fn har(&self, filter: &FlowFilter) -> Result<Har, String> {
+8 -2
View File
@@ -266,6 +266,8 @@ pub struct RemovedResponse {
/// Raw body headers: whether the body is cut short, at the capture limit or on the wire.
pub const TRUNCATED_HEADER: &str = "x-yaak-truncated";
/// Raw body headers: what to know about a body beyond its bytes, as that a WebSocket has none.
pub const NOTE_HEADER: &str = "x-yaak-note";
// -- Server --
@@ -544,7 +546,7 @@ async fn route(state: &ServerState, req: Request<Incoming>) -> Result<ControlRes
})?;
let payload = messages::payload(&ctx.db, &ctx.blobs, &message)?;
let (decoded, decode_error) = if message.kind == MessageKind::GrpcMessage {
match grpc::decode(&ctx.db, &ctx.blobs, &ctx.grpc, &flow, seq).await {
match grpc::decode(&ctx.db, &ctx.blobs, &ctx.grpc, &flow, seq, false).await {
Ok(decoded) => (Some(decoded), None),
Err(e) => (None, Some(e)),
}
@@ -639,11 +641,15 @@ fn found(ctx: &ProxyCtx, id: &str) -> Result<(), ApiError> {
async fn raw_body(ctx: &ProxyCtx, id: &str, which: FlowBody) -> Result<ControlResponse, ApiError> {
let flow = flows::find(&ctx.db, id)
.ok_or_else(|| ApiError::new(StatusCode::NOT_FOUND, format!("No flow {id}")))?;
let body = bodies::read_body(&ctx.blobs, &flow, which, ctx.capture_body_limit()?).await?;
let body =
bodies::read_body(&ctx.db, &ctx.blobs, &flow, which, ctx.capture_body_limit()?).await?;
let content_type =
find_header(flow.headers(which), "content-type").unwrap_or("application/octet-stream");
let mut resp = response(StatusCode::OK, content_type, body.data);
resp.headers_mut().insert(TRUNCATED_HEADER, body.truncated.to_string().parse().unwrap());
if let Some(note) = body.note.as_deref().and_then(|n| n.parse().ok()) {
resp.headers_mut().insert(NOTE_HEADER, note);
}
Ok(resp)
}
+10 -2
View File
@@ -254,6 +254,7 @@ mod tests {
stored_size: data.len(),
truncated: false,
decode_error: None,
note: None,
}
}
@@ -416,6 +417,7 @@ mod tests {
stored_size: 3,
truncated: false,
decode_error: None,
note: None,
};
let c = flow_to_request(&f, &data);
assert_eq!(c.request.body_type.as_deref(), Some("other"));
@@ -427,8 +429,13 @@ mod tests {
fn decoded_empty_body() {
let f = flow("POST", "https://x.test/", &[("Content-Encoding", "gzip")]);
// A gzip stream of nothing: stored bytes, but an empty body once decoded.
let data =
DecodedBody { data: Vec::new(), stored_size: 20, truncated: false, decode_error: None };
let data = DecodedBody {
data: Vec::new(),
stored_size: 20,
truncated: false,
decode_error: None,
note: None,
};
let c = flow_to_request(&f, &data);
assert!(c.request.headers.is_empty());
assert_eq!(c.dropped_headers[0].reason, DropReason::BodyDecoded);
@@ -450,6 +457,7 @@ mod tests {
stored_size: 4,
truncated: true,
decode_error: None,
note: None,
};
let c = flow_to_request(&f, &data);
assert_eq!(names(&c.request), vec!["Content-Type"]);
+4 -3
View File
@@ -715,18 +715,19 @@ pub async fn detail(
body_cap: usize,
) -> Result<FlowDetail, String> {
let flow = get(db, flow_id)?;
let request_body = preview(blobs, &flow, FlowBody::Request, body_cap).await?;
let response_body = preview(blobs, &flow, FlowBody::Response, body_cap).await?;
let request_body = preview(db, blobs, &flow, FlowBody::Request, body_cap).await?;
let response_body = preview(db, blobs, &flow, FlowBody::Response, body_cap).await?;
Ok(FlowDetail { flow, request_body, response_body })
}
async fn preview(
db: &ProxyQueryManager,
blobs: &BlobManager,
flow: &Flow,
which: FlowBody,
cap: usize,
) -> Result<Option<BodyPreview>, String> {
let body = bodies::read_body(blobs, flow, which, cap).await?;
let body = bodies::read_body(db, blobs, flow, which, cap).await?;
if body.data.is_empty() && !body.truncated {
return Ok(None);
}
+5 -1
View File
@@ -391,13 +391,14 @@ async fn find_schema(
}
}
/// Decodes a captured gRPC message.
/// Decodes a captured gRPC message, with its call's schema unless `schemaless_only`.
pub async fn decode(
db: &ProxyQueryManager,
blobs: &BlobManager,
state: &GrpcState,
flow: &Flow,
seq: i64,
schemaless_only: bool,
) -> Result<DecodedGrpcMessage, String> {
let message = messages::get(db, &flow.id, seq)?;
if message.kind != MessageKind::GrpcMessage {
@@ -407,6 +408,9 @@ pub async fn decode(
if message.compressed && message.error.is_some() {
return Err(message.error.unwrap_or_default());
}
if schemaless_only {
return Ok(schemaless(&payload, &message, None));
}
let (Some(service), Some(method)) = (&flow.grpc_service, &flow.grpc_method) else {
return Ok(schemaless(&payload, &message, Some("The call's path names no service".into())));
};
+9 -3
View File
@@ -152,8 +152,8 @@ pub async fn export(
) -> Result<Har, String> {
let mut entries = Vec::with_capacity(flows.len());
for flow in flows {
let request = bodies::read_body(blobs, flow, FlowBody::Request, limit).await?;
let response = bodies::read_body(blobs, flow, FlowBody::Response, limit).await?;
let request = bodies::read_body(db, blobs, flow, FlowBody::Request, limit).await?;
let response = bodies::read_body(db, blobs, flow, FlowBody::Response, limit).await?;
let mut entry = entry(flow, &request, &response);
if flow.stream_kind == Some(StreamKind::Websocket) {
entry.web_socket_messages = Some(websocket_messages(db, blobs, flow)?);
@@ -323,7 +323,13 @@ mod tests {
}
fn body(data: &[u8], truncated: bool) -> DecodedBody {
DecodedBody { data: data.to_vec(), stored_size: data.len(), truncated, decode_error: None }
DecodedBody {
data: data.to_vec(),
stored_size: data.len(),
truncated,
decode_error: None,
note: None,
}
}
fn at(second: u32) -> chrono::NaiveDateTime {
+419 -15
View File
@@ -607,7 +607,8 @@ impl ProxyCtx {
) -> Result<SaveFlowResponse, String> {
let flow = flows::get(&self.db, flow_id)?;
let limit = self.capture_body_limit()?;
let body = bodies::read_body(&self.blobs, &flow, FlowBody::Request, limit).await?;
let body =
bodies::read_body(&self.db, &self.blobs, &flow, FlowBody::Request, limit).await?;
let saved = ClientDb::open(&self.client_data_dir)?.save(&flow, &body, req)?;
let flow = Flow { saved_request_id: Some(saved.request.id.clone()), ..flow };
@@ -986,6 +987,10 @@ pub struct GetFlowBodyResponse {
#[serde(skip_serializing_if = "Option::is_none")]
#[ts(optional)]
pub decode_error: Option<String>,
/// What to know about the body beyond its bytes, as that a WebSocket has none.
#[serde(skip_serializing_if = "Option::is_none")]
#[ts(optional)]
pub note: Option<String>,
}
#[derive(Deserialize, TS)]
@@ -1121,6 +1126,10 @@ pub struct DecodeGrpcMessageRequest {
pub flow_id: String,
#[ts(type = "number")]
pub seq: i64,
/// Decode without a schema even when one is found.
#[serde(default)]
#[ts(optional, as = "Option<bool>")]
pub schemaless: bool,
}
#[derive(Deserialize, TS)]
@@ -1185,7 +1194,9 @@ async fn decode_grpc_message(
req: DecodeGrpcMessageRequest,
) -> Result<DecodedGrpcMessage, RpcError> {
let flow = find_flow(&ctx, &req.flow_id)?;
grpc::decode(&ctx.db, &ctx.blobs, &ctx.grpc, &flow, req.seq).await.map_err(rpc_error)
grpc::decode(&ctx.db, &ctx.blobs, &ctx.grpc, &flow, req.seq, req.schemaless)
.await
.map_err(rpc_error)
}
fn list_grpc_schemas(
@@ -1296,8 +1307,9 @@ async fn list_workspaces(
async fn preview_save(ctx: ProxyCtx, req: PreviewSaveRequest) -> Result<SavePreview, RpcError> {
let flow = find_flow(&ctx, &req.flow_id)?;
let limit = settings(&ctx)?.capture_body_limit;
let body =
bodies::read_body(&ctx.blobs, &flow, FlowBody::Request, limit).await.map_err(rpc_error)?;
let body = bodies::read_body(&ctx.db, &ctx.blobs, &flow, FlowBody::Request, limit)
.await
.map_err(rpc_error)?;
let conversion = convert::flow_to_request(&flow, &body);
let request = conversion.request;
let body = request.body_type.as_deref().map(|body_type| match body_type {
@@ -1372,13 +1384,15 @@ async fn get_flow_body(
) -> Result<GetFlowBodyResponse, RpcError> {
let flow = find_flow(&ctx, &req.flow_id)?;
let limit = settings(&ctx)?.capture_body_limit;
let body =
bodies::read_body_or_raw(&ctx.blobs, &flow, req.which, limit).await.map_err(rpc_error)?;
let body = bodies::read_body_or_raw(&ctx.db, &ctx.blobs, &flow, req.which, limit)
.await
.map_err(rpc_error)?;
Ok(GetFlowBodyResponse {
data: BASE64.encode(&body.data),
truncated: body.truncated,
stored_size: body.stored_size,
decode_error: body.decode_error,
note: body.note,
})
}
@@ -1390,8 +1404,13 @@ async fn save_flow_body(
) -> Result<SaveFlowBodyResponse, RpcError> {
let flow = find_flow(&ctx, &req.flow_id)?;
let limit = settings(&ctx)?.capture_body_limit;
let body =
bodies::read_body_or_raw(&ctx.blobs, &flow, req.which, limit).await.map_err(rpc_error)?;
let body = bodies::read_body_or_raw(&ctx.db, &ctx.blobs, &flow, req.which, limit)
.await
.map_err(rpc_error)?;
// Nothing to save; an empty file would say the body was empty.
if let Some(note) = body.note.filter(|_| body.data.is_empty()) {
return Err(rpc_error(note));
}
let saved = SaveFlowBodyResponse {
size: body.data.len(),
truncated: body.truncated,
@@ -1414,7 +1433,8 @@ async fn viewer_body(
which: FlowBody,
limit: usize,
) -> Result<bodies::DecodedBody, RpcError> {
let body = bodies::read_body(&ctx.blobs, flow, which, limit).await.map_err(rpc_error)?;
let body =
bodies::read_body(&ctx.db, &ctx.blobs, flow, which, limit).await.map_err(rpc_error)?;
match body.decode_error {
Some(e) => Err(rpc_error(e)),
None => Ok(body),
@@ -1567,6 +1587,22 @@ struct InFlight {
}
impl InFlight {
/// Stops writing the bodies its stream's messages carry, which are read back from them.
/// A request's bytes are kept while it uploads, as a call can end before its upload does,
/// with a message still partway in: they are dropped once the upload ends, or kept as its
/// record, cut, when the flow ends first.
fn drop_message_bodies(&mut self) {
if bodies::from_messages(&self.flow, FlowBody::Response) {
self.response_body = None;
}
}
/// Its bytes on the wire are its record, as for any body that isn't a stream's messages, an
/// encoded one included. Their cut at the capture limit is then the body's.
fn keeps_bytes(&self, which: FlowBody) -> bool {
!bodies::from_messages(&self.flow, which)
}
/// Something shown of the flow changed: one written while it streams is written again on
/// the stream flow interval, so it does not wait for a message to show it.
fn changed(&mut self) {
@@ -1681,6 +1717,22 @@ fn record_message(
f.flow.grpc_status = *status;
f.flow.grpc_message = message.clone();
}
// A body read back from its messages is cut where they are.
if message.truncated {
match message.direction {
yaak_proxy::MessageDirection::Client
if bodies::from_messages(&f.flow, FlowBody::Request) =>
{
f.flow.request_truncated = true
}
yaak_proxy::MessageDirection::Server
if bodies::from_messages(&f.flow, FlowBody::Response) =>
{
f.flow.response_truncated = true
}
_ => {}
}
}
let seq = f.next_seq;
f.next_seq += 1;
f.flow.message_count += 1;
@@ -1750,6 +1802,10 @@ impl FlowSink {
f.flow.grpc_service = Some(service.to_string());
f.flow.grpc_method = Some(method.to_string());
}
// Its messages are the record of the bodies they carry, which are not
// written again on their own. A gRPC response's body is known to be messages
// once its headers are, at its first chunk.
f.drop_message_bodies();
// Shown while it streams, rather than only once it ends.
self.write_stream_flow(f);
}
@@ -1773,7 +1829,9 @@ impl FlowSink {
ProxyEvent::RequestBodyChunk { id, len, data } => {
if let Some(f) = in_flight.get_mut(&id) {
f.flow.request_size += len as i64;
f.flow.request_truncated |= data.len() < len;
if f.keeps_bytes(FlowBody::Request) {
f.flow.request_truncated |= data.len() < len;
}
write_body_chunk(&mut f.request_body, &data);
f.changed();
}
@@ -1781,8 +1839,16 @@ impl FlowSink {
ProxyEvent::RequestBodyComplete { id, size, truncated } => {
if let Some(f) = in_flight.get_mut(&id) {
f.flow.request_size = size as i64;
f.flow.request_truncated = truncated;
finish_body(f.request_body.take());
if f.keeps_bytes(FlowBody::Request) {
f.flow.request_truncated = truncated;
finish_body(f.request_body.take());
} else if f.request_body.take().is_some() {
// The upload ended whole, its messages its record: its bytes go.
let body_id = Flow::body_id(&f.flow.id, FlowBody::Request);
if let Err(e) = blobs.with_tx(|b| b.delete_chunks(&body_id)) {
warn!("Failed to delete a stream's request bytes: {e}");
}
}
f.changed();
}
}
@@ -1805,7 +1871,10 @@ impl FlowSink {
ProxyEvent::ResponseBodyChunk { id, len, data } => {
if let Some(f) = in_flight.get_mut(&id) {
f.flow.response_size += len as i64;
f.flow.response_truncated |= data.len() < len;
f.drop_message_bodies();
if f.keeps_bytes(FlowBody::Response) {
f.flow.response_truncated |= data.len() < len;
}
write_body_chunk(&mut f.response_body, &data);
f.changed();
}
@@ -1820,7 +1889,9 @@ impl FlowSink {
} => {
if let Some(mut f) = in_flight.remove(&id) {
f.flow.response_size = size as i64;
f.flow.response_truncated = truncated;
if f.keeps_bytes(FlowBody::Response) {
f.flow.response_truncated = truncated;
}
f.flow.elapsed_ms = Some(clamp_ms(elapsed_ms));
f.flow.error = error;
f.flow.cancelled = cancelled;
@@ -1958,7 +2029,12 @@ impl FlowSink {
}
}
fn finish_flow(&self, f: InFlight) {
fn finish_flow(&self, mut f: InFlight) {
// Ended while its upload still went on: what came of it is kept, cut.
let upload_cut = bodies::from_messages(&f.flow, FlowBody::Request)
&& f.request_body.is_some()
&& f.flow.request_size > 0;
f.flow.request_truncated |= upload_cut;
finish_body(f.request_body);
finish_body(f.response_body);
let id = f.flow.id.clone();
@@ -2218,6 +2294,329 @@ mod tests {
}
}
/// A gRPC call's bodies are its messages: neither is written to the blob store, and each
/// reads back framed again, cut where a message was cut.
#[tokio::test(flavor = "multi_thread")]
async fn grpc_bodies_are_read_back_from_their_messages() {
use yaak_proxy::{MessageDirection as D, MessageKind as K};
let dir = tempfile::tempdir().unwrap();
let (events, _event_rx) = RpcEventEmitter::new();
let ctx = ProxyCtx::new(dir.path(), events).unwrap();
let (tx, event_loop) = event_loop(&ctx);
let send = |event| tx.send(event).unwrap();
send(ProxyEvent::RequestStart {
id: 1,
started_at: SystemTime::now(),
method: "POST".into(),
url: "https://api.example.com/pkg.Greeter/SayHello".into(),
http_version: "HTTP/2.0".into(),
connection: 1,
client_addr: "127.0.0.1:1".parse().unwrap(),
});
send(ProxyEvent::RequestHeader {
id: 1,
name: "content-type".into(),
value: "application/grpc".into(),
});
send(ProxyEvent::StreamStart { id: 1, kind: yaak_proxy::StreamKind::Grpc });
let request = b"\x00\x00\x00\x00\x05\x0a\x03Ada";
send(ProxyEvent::RequestBodyChunk {
id: 1,
len: request.len(),
data: bytes::Bytes::from_static(request),
});
send(ws_message(1, D::Client, K::GrpcMessage, b"\x0a\x03Ada"));
send(ProxyEvent::RequestBodyComplete {
id: 1,
size: request.len() as u64,
truncated: false,
});
send(ProxyEvent::ResponseStart {
id: 1,
status: 200,
http_version: "HTTP/2.0".into(),
remote_addr: None,
elapsed_ms: 1,
});
send(ProxyEvent::ResponseHeader {
id: 1,
name: "content-type".into(),
value: "application/grpc+proto".into(),
});
// Over the capture limit on the wire: the body stored only the limit's worth before.
let response = b"\x00\x00\x00\x00\x0b\x0a\x09Hello Ada";
send(ProxyEvent::ResponseBodyChunk {
id: 1,
len: response.len(),
data: bytes::Bytes::from_static(&response[..4]),
});
let mut cut = ws_message(1, D::Server, K::GrpcMessage, b"\x0a\x09Hel");
if let ProxyEvent::Message { message, .. } = &mut cut {
message.truncated = true;
message.size = 11;
}
send(cut);
let trailers = K::GrpcTrailers { status: Some(0), message: None };
send(ws_message(1, D::Server, trailers, b"grpc-status: 0\r\n"));
send(ProxyEvent::ResponseBodyComplete {
id: 1,
size: response.len() as u64,
truncated: true,
elapsed_ms: 5,
error: None,
cancelled: false,
});
drop(tx);
event_loop.join().unwrap();
let flow = flows::list(&ctx.db, &Default::default()).unwrap().remove(0);
assert_eq!((flow.message_count, flow.grpc_status), (3, Some(0)));
assert_eq!((flow.request_size, flow.response_size), (10, 16), "sizes on the wire");
assert_eq!((flow.request_truncated, flow.response_truncated), (false, true));
let blobs = ctx.blobs.connect();
assert!(!blobs.body_exists(&Flow::body_id(&flow.id, FlowBody::Request)).unwrap());
assert!(!blobs.body_exists(&Flow::body_id(&flow.id, FlowBody::Response)).unwrap());
let read = |which| bodies::read_body(&ctx.db, &ctx.blobs, &flow, which, 1 << 20);
let request_body = read(FlowBody::Request).await.unwrap();
assert_eq!((request_body.data.as_slice(), request_body.truncated), (&request[..], false));
// HTTP/2 trailers are no part of the body.
let response_body = read(FlowBody::Response).await.unwrap();
// Framed with the length it was sent with, so it reads back as it was on the wire, cut.
assert_eq!(response_body.data, b"\x00\x00\x00\x00\x0b\x0a\x09Hel");
assert!(response_body.truncated);
let har = har::export(&ctx.db, &ctx.blobs, &[flow], 1 << 20).await.unwrap();
assert_eq!(har.log.entries[0].response.content.size, 10);
}
/// A gzipped event stream keeps its bytes as well as its events: they read back through the
/// body's decoder, so one that decodes reads as its events did, and one that doesn't keeps
/// its bytes and says why.
#[tokio::test(flavor = "multi_thread")]
async fn encoded_event_streams_keep_their_bytes() {
use std::io::Write;
use yaak_proxy::{MessageDirection as D, MessageKind as K};
let dir = tempfile::tempdir().unwrap();
let (events, _event_rx) = RpcEventEmitter::new();
let ctx = ProxyCtx::new(dir.path(), events).unwrap();
let (tx, event_loop) = event_loop(&ctx);
let raw = "data: hi\n\n".to_string();
let mut gzip = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default());
gzip.write_all(raw.as_bytes()).unwrap();
let gzip = bytes::Bytes::from(gzip.finish().unwrap());
let bodies = [
(1, "https://a.example.com/events", gzip),
(
2,
"https://b.example.com/events",
bytes::Bytes::from_static(b"\x1f\x8b not really gzip"),
),
];
for (id, url, data) in bodies.clone() {
tx.send(ProxyEvent::RequestStart {
id,
started_at: SystemTime::now(),
method: "GET".into(),
url: url.into(),
http_version: "HTTP/1.1".into(),
connection: id,
client_addr: "127.0.0.1:1".parse().unwrap(),
})
.unwrap();
tx.send(ProxyEvent::ResponseStart {
id,
status: 200,
http_version: "HTTP/1.1".into(),
remote_addr: None,
elapsed_ms: 1,
})
.unwrap();
for (name, value) in [
("content-type", "text/event-stream"),
("content-encoding", "gzip"),
] {
let (name, value) = (name.into(), value.into());
tx.send(ProxyEvent::ResponseHeader { id, name, value }).unwrap();
}
tx.send(ProxyEvent::StreamStart { id, kind: yaak_proxy::StreamKind::Sse }).unwrap();
tx.send(ProxyEvent::ResponseBodyChunk { id, len: data.len(), data }).unwrap();
}
// The first one's bytes decoded into an event; the second's never did.
let event = K::SseEvent { event: None, id: None, retry: None, raw: raw.clone() };
let mut message = ws_message(1, D::Server, event, b"hi");
if let ProxyEvent::Message { message, .. } = &mut message {
message.size = raw.len() as u64;
}
tx.send(message).unwrap();
for (id, _, data) in bodies.clone() {
tx.send(ProxyEvent::ResponseBodyComplete {
id,
size: data.len() as u64,
truncated: false,
elapsed_ms: 5,
error: None,
cancelled: false,
})
.unwrap();
}
drop(tx);
event_loop.join().unwrap();
let flows = flows::list(&ctx.db, &Default::default()).unwrap();
let flow = |host: &str| flows.iter().find(|f| f.url.contains(host)).unwrap().clone();
let (decoded, undecoded) = (flow("a.example"), flow("b.example"));
assert_eq!(decoded.message_count, 1);
let read =
|flow| bodies::read_body_or_raw(&ctx.db, &ctx.blobs, flow, FlowBody::Response, 1024);
let body = read(&decoded).await.unwrap();
assert_eq!((body.data.as_slice(), body.decode_error), (raw.as_bytes(), None));
let body = read(&undecoded).await.unwrap();
assert_eq!(body.data, b"\x1f\x8b not really gzip");
assert!(body.decode_error.is_some());
}
#[tokio::test(flavor = "multi_thread")]
async fn encoded_grpc_bodies_that_never_decode_keep_their_bytes_and_cut() {
use yaak_proxy::{MessageDirection as D, MessageKind as K};
let dir = tempfile::tempdir().unwrap();
let (events, _event_rx) = RpcEventEmitter::new();
let ctx = ProxyCtx::new(dir.path(), events).unwrap();
let (tx, event_loop) = event_loop(&ctx);
let send = |event| tx.send(event).unwrap();
let header = |name: &str, value: &str| (name.to_string(), value.to_string());
send(ProxyEvent::RequestStart {
id: 1,
started_at: SystemTime::now(),
method: "POST".into(),
url: "https://api.example.com/pkg.Greeter/SayHello".into(),
http_version: "HTTP/2.0".into(),
connection: 1,
client_addr: "127.0.0.1:1".parse().unwrap(),
});
for (name, value) in [
header("content-type", "application/grpc"),
header("content-encoding", "gzip"),
] {
send(ProxyEvent::RequestHeader { id: 1, name, value });
}
send(ProxyEvent::StreamStart { id: 1, kind: yaak_proxy::StreamKind::Grpc });
// Cut at the capture limit: 4 of 30 bytes kept.
send(ProxyEvent::RequestBodyChunk {
id: 1,
len: 30,
data: bytes::Bytes::from_static(b"junk"),
});
send(ProxyEvent::RequestBodyComplete { id: 1, size: 30, truncated: true });
send(ProxyEvent::ResponseStart {
id: 1,
status: 200,
http_version: "HTTP/2.0".into(),
remote_addr: None,
elapsed_ms: 1,
});
for (name, value) in [
header("content-type", "application/grpc"),
header("content-encoding", "gzip"),
] {
send(ProxyEvent::ResponseHeader { id: 1, name, value });
}
send(ProxyEvent::ResponseBodyChunk {
id: 1,
len: 40,
data: bytes::Bytes::from_static(b"\x1f\x8bnope"),
});
// The status came in the HTTP/2 trailers, not from the body's bytes.
let trailers = K::GrpcTrailers { status: Some(0), message: None };
send(ws_message(1, D::Server, trailers, b"grpc-status: 0\r\n"));
send(ProxyEvent::ResponseBodyComplete {
id: 1,
size: 40,
truncated: true,
elapsed_ms: 5,
error: None,
cancelled: false,
});
drop(tx);
event_loop.join().unwrap();
let flow = flows::list(&ctx.db, &Default::default()).unwrap().remove(0);
assert_eq!((flow.request_truncated, flow.response_truncated), (true, true));
for (which, kept) in [
(FlowBody::Request, &b"junk"[..]),
(FlowBody::Response, b"\x1f\x8bnope"),
] {
// The bytes are kept, and read as a cut body is: what decoded of them, cut short.
assert_eq!(bodies::read_raw_body(&ctx.blobs, &flow.id, which).unwrap(), kept);
let body = bodies::read_body(&ctx.db, &ctx.blobs, &flow, which, 1024).await.unwrap();
assert!(body.truncated, "{which:?}");
}
}
/// A call that ends while its upload still goes on keeps what came of the upload, cut; one
/// whose upload ended whole keeps only its messages.
#[tokio::test(flavor = "multi_thread")]
async fn a_grpc_upload_outlived_by_its_call_keeps_its_bytes() {
use yaak_proxy::{MessageDirection as D, MessageKind as K};
let dir = tempfile::tempdir().unwrap();
let (events, _event_rx) = RpcEventEmitter::new();
let ctx = ProxyCtx::new(dir.path(), events).unwrap();
let (tx, event_loop) = event_loop(&ctx);
let send = |event| tx.send(event).unwrap();
send(ProxyEvent::RequestStart {
id: 1,
started_at: SystemTime::now(),
method: "POST".into(),
url: "https://api.example.com/pkg.Uploader/Upload".into(),
http_version: "HTTP/2.0".into(),
connection: 1,
client_addr: "127.0.0.1:1".parse().unwrap(),
});
send(ProxyEvent::RequestHeader {
id: 1,
name: "content-type".into(),
value: "application/grpc".into(),
});
send(ProxyEvent::StreamStart { id: 1, kind: yaak_proxy::StreamKind::Grpc });
// One whole message, and the start of the next.
let uploaded = b"\x00\x00\x00\x00\x02\x08\x01\x00\x00\x00\x00\x0a\x0a\x08par";
send(ProxyEvent::RequestBodyChunk {
id: 1,
len: uploaded.len(),
data: bytes::Bytes::from_static(uploaded),
});
send(ws_message(1, D::Client, K::GrpcMessage, b"\x08\x01"));
send(ProxyEvent::ResponseStart {
id: 1,
status: 200,
http_version: "HTTP/2.0".into(),
remote_addr: None,
elapsed_ms: 1,
});
send(ProxyEvent::ResponseHeader {
id: 1,
name: "content-type".into(),
value: "application/grpc".into(),
});
// The server answers and ends the call before the upload is done.
send(ProxyEvent::ResponseBodyComplete {
id: 1,
size: 0,
truncated: false,
elapsed_ms: 5,
error: None,
cancelled: false,
});
drop(tx);
event_loop.join().unwrap();
let flow = flows::list(&ctx.db, &Default::default()).unwrap().remove(0);
assert!(flow.request_truncated);
let body = bodies::read_body(&ctx.db, &ctx.blobs, &flow, FlowBody::Request, 1 << 20)
.await
.unwrap();
assert_eq!((body.data.as_slice(), body.truncated), (&uploaded[..], true));
}
#[tokio::test(flavor = "multi_thread")]
async fn websocket_messages_are_stored_and_exported() {
use yaak_proxy::{MessageDirection as D, MessageKind as K};
@@ -2275,6 +2674,11 @@ mod tests {
(Some("receive"), Some(2))
);
assert_eq!(sent[1]["data"], BASE64.encode(&big));
// No body after the 101, and it says why.
let body = bodies::read_body(&ctx.db, &ctx.blobs, &flow, FlowBody::Response, 1 << 20)
.await
.unwrap();
assert_eq!((body.data.len(), body.note.as_deref()), (0, Some(bodies::WEBSOCKET_BODY_NOTE)));
let names: Vec<_> = event_rx.try_iter().map(|e| e.event).collect();
assert_eq!(names.iter().filter(|n| **n == "message_write").count(), 3, "{names:?}");
+6 -3
View File
@@ -16,7 +16,8 @@ pub struct ProxyHeader {
pub value: String,
}
/// One proxied request and its response. The bodies are in `blobs.sqlite`, not the row.
/// One proxied request and its response. The bodies are in `blobs.sqlite`, not the row; a
/// stream's are its messages, and read back from them (`bodies::from_messages`).
#[derive(Debug, Clone, Default, Serialize, Deserialize, TS)]
#[serde(default, rename_all = "camelCase")]
#[ts(export, export_to = "gen_models.ts")]
@@ -48,9 +49,11 @@ pub struct Flow {
/// Bytes of the response body on the wire, captured or not.
#[ts(type = "number")]
pub response_size: i64,
/// Only the first `capture_body_limit` bytes of the body are stored.
/// Only the first `capture_body_limit` bytes of the body are stored. For a body that is a
/// stream's messages, a message was cut at the limit.
pub request_truncated: bool,
/// Only the first `capture_body_limit` bytes of the body are stored.
/// Only the first `capture_body_limit` bytes of the body are stored. For a body that is a
/// stream's messages, a message was cut at the limit.
pub response_truncated: bool,
/// Milliseconds from `started_at` to the response headers.
pub elapsed_headers_ms: Option<i32>,
+3 -1
View File
@@ -151,12 +151,14 @@ async fn flow_is_stored_with_its_bodies() {
assert_eq!(read_raw_body(&ctx.blobs, &flow.id, FlowBody::Request).unwrap(), b"hello proxy");
assert_eq!(read_raw_body(&ctx.blobs, &flow.id, FlowBody::Response).unwrap(), compressed);
let decoded = read_body(&ctx.blobs, &flow, FlowBody::Response, CAPTURE_LIMIT).await.unwrap();
let decoded =
read_body(&ctx.db, &ctx.blobs, &flow, FlowBody::Response, CAPTURE_LIMIT).await.unwrap();
let expected = DecodedBody {
data: b"hello proxy".to_vec(),
stored_size: compressed.len(),
truncated: false,
decode_error: None,
note: None,
};
assert_eq!(decoded, expected);
+143 -1
View File
@@ -7,6 +7,8 @@ use std::net::SocketAddr;
use std::path::Path;
use std::time::{Duration, Instant};
use base64::Engine;
use base64::engine::general_purpose::STANDARD as BASE64;
use bytes::Bytes;
use http_body_util::combinators::UnsyncBoxBody;
use http_body_util::{BodyExt, Full, StreamBody};
@@ -17,7 +19,8 @@ use hyper_util::rt::{TokioExecutor, TokioIo};
use hyper_util::server::conn::auto;
use serde_json::{Value, json};
use tokio::net::TcpListener;
use yaak_proxy_lib::models::Flow;
use yaak_proxy_lib::bodies::read_raw_body;
use yaak_proxy_lib::models::{Flow, FlowBody};
use yaak_proxy_lib::settings::ProxySettings;
use yaak_proxy_lib::{GrpcConfig, ProxyCtx};
use yaak_rpc::RpcEventEmitter;
@@ -149,6 +152,30 @@ async fn route(
.body(full(out))
.unwrap()
}
// A whole reply, then half of one, and the connection gives out.
"/pkg.Greeter/Cut" => {
let mut first = grpc_frame(0, &proto("whole", None));
first.extend(&grpc_frame(0, &proto("half of it", None))[..9]);
let frames = futures_util::stream::unfold(Some(first), |first| async move {
match first {
Some(first) => Some((Ok::<_, BoxError>(Frame::data(Bytes::from(first))), None)),
// After the bytes have gone out
None => {
tokio::time::sleep(Duration::from_millis(200)).await;
Some((Err("connection reset".into()), None))
}
}
});
Response::builder()
.header("content-type", "application/grpc-web+proto")
.body(StreamBody::new(frames).boxed_unsync())
.unwrap()
}
"/pkg.Down/Call" => Response::builder()
.status(502)
.header("content-type", "text/plain")
.body(full("upstream down"))
.unwrap(),
_ => Response::builder()
.header("content-type", "application/grpc-web+proto")
.body(full(grpc_frame(0x80, b"grpc-status: 12\r\ngrpc-message: not%20here\r\n")))
@@ -251,6 +278,29 @@ async fn server_sent_events_are_stored_while_the_stream_is_open() {
.unwrap();
assert_eq!(payload["data"], "c2Vjb25k", "\"second\" in base64");
// The events are the body's record: nothing of it went to the blob store, and it reads
// back as the client read it.
assert!(read_raw_body(&ctx.blobs, &ended.id, FlowBody::Response).unwrap().is_empty());
let body = rpc(&ctx, "get_flow_body", json!({ "flowId": ended.id, "which": "response" }))
.await
.unwrap();
let sent = "event: tick\nid: 1\ndata: first\n\ndata: second\n\n";
assert_eq!(body["data"], BASE64.encode(sent));
assert_eq!(
(body["truncated"].as_bool(), body["storedSize"].as_u64()),
(Some(false), Some(sent.len() as u64))
);
let path = dir.path().join("events.txt");
let saved = rpc(
&ctx,
"save_flow_body",
json!({ "flowId": ended.id, "which": "response", "path": path }),
)
.await
.unwrap();
assert_eq!(saved["raw"], false);
assert_eq!(std::fs::read_to_string(&path).unwrap(), sent);
// The app heard of the open flow, of each message, and of the end.
let events: Vec<_> = event_rx.try_iter().map(|e| e.event).collect();
let writes = |name: &str| events.iter().filter(|e| **e == name).count();
@@ -287,6 +337,20 @@ async fn grpc_web_calls_are_stored_and_decoded() {
(Some("pkg.Greeter"), Some("SayHello"))
);
assert_eq!((flow.grpc_status, flow.message_count), (Some(0), 3));
// Both bodies are the call's messages, read back framed as they were sent.
for (which, side) in [
(FlowBody::Request, "request"),
(FlowBody::Response, "response"),
] {
assert!(read_raw_body(&ctx.blobs, &flow.id, which).unwrap().is_empty(), "{side}");
}
let read =
|which: &str| rpc(&ctx, "get_flow_body", json!({ "flowId": flow.id, "which": which }));
assert_eq!(
read("request").await.unwrap()["data"],
BASE64.encode(grpc_frame(0, &proto("Ada", None)))
);
assert_eq!(read("response").await.unwrap()["data"], BASE64.encode(&body));
let failing = format!("http://{upstream}/pkg.Greeter/Missing");
client
@@ -306,6 +370,75 @@ async fn grpc_web_calls_are_stored_and_decoded() {
errors["flows"].as_array().unwrap().iter().map(|f| f["id"].clone()).collect();
assert_eq!(ids, vec![json!(failed.id)], "a non-zero status is a failed call");
// A gateway that answers with its own page: that body is stored as any other.
let gateway = format!("http://{upstream}/pkg.Down/Call");
client
.post(&gateway)
.header("content-type", "application/grpc-web+proto")
.body(grpc_frame(0, &proto("Cy", None)))
.send()
.await
.unwrap();
let down = wait_for(&ctx, &gateway, |f| f.elapsed_ms.is_some()).await;
assert_eq!(
read_raw_body(&ctx.blobs, &down.id, FlowBody::Response).unwrap(),
b"upstream down"
);
let page = rpc(&ctx, "get_flow_body", json!({ "flowId": down.id, "which": "response" }))
.await
.unwrap();
assert_eq!(page["data"], BASE64.encode("upstream down"));
// A connection that gives out partway through a message: what came of it is kept.
let cut_url = format!("http://{upstream}/pkg.Greeter/Cut");
let sent = client
.post(&cut_url)
.header("content-type", "application/grpc-web+proto")
.body(grpc_frame(0, &proto("Di", None)))
.send()
.await;
if let Ok(resp) = sent {
let _ = resp.bytes().await;
}
let cut = wait_for(&ctx, &cut_url, |f| f.elapsed_ms.is_some() || f.error.is_some()).await;
let cut = wait_for(&ctx, &cut_url, |f| f.id == cut.id && f.message_count == 3).await;
let listed = rpc(&ctx, "list_messages", json!({ "flowId": cut.id })).await.unwrap();
let last = &listed["messages"][2];
assert_eq!((last["truncated"].as_bool(), last["size"].as_i64()), (Some(true), Some(12)));
let cut_body = rpc(&ctx, "get_flow_body", json!({ "flowId": cut.id, "which": "response" }))
.await
.unwrap();
let mut cut_sent = grpc_frame(0, &proto("whole", None));
cut_sent.extend(&grpc_frame(0, &proto("half of it", None))[..9]);
assert_eq!(
cut_body["data"],
BASE64.encode(&cut_sent),
"every byte that came, framed as it was"
);
assert_eq!(cut_body["truncated"], true);
// The same bytes are what Save to File writes and what the HAR export carries.
let saved_path = dir.path().join("cut.bin");
let saved = rpc(
&ctx,
"save_flow_body",
json!({ "flowId": cut.id, "which": "response", "path": saved_path }),
)
.await
.unwrap();
assert_eq!(saved["truncated"], true);
assert_eq!(std::fs::read(&saved_path).unwrap(), cut_sent);
let har_path = dir.path().join("cut.har");
rpc(&ctx, "export_har", json!({ "ids": [cut.id], "path": har_path })).await.unwrap();
let har: Value = serde_json::from_slice(&std::fs::read(&har_path).unwrap()).unwrap();
let content = &har["log"]["entries"][0]["response"]["content"];
assert_eq!(content["_truncated"], true);
let text = content["text"].as_str().unwrap();
let exported = match content["encoding"].as_str() {
Some("base64") => BASE64.decode(text).unwrap(),
_ => text.as_bytes().to_vec(),
};
assert_eq!(exported, cut_sent);
// No schema, and reflection against the server fails: decoded by wire type alone.
let decode = json!({ "flowId": flow.id, "seq": 1 });
let schemaless = rpc(&ctx, "decode_grpc_message", decode.clone()).await.unwrap();
@@ -365,6 +498,15 @@ async fn grpc_web_calls_are_stored_and_decoded() {
let removed = rpc(&ctx, "remove_grpc_schema", json!({ "id": added["id"] })).await.unwrap();
assert_eq!(removed, true);
// Asked for schemaless, it is, with the schema there.
let mut forced = decode.clone();
forced["schemaless"] = json!(true);
let without = rpc(&ctx, "decode_grpc_message", forced).await.unwrap();
assert_eq!(without["messageType"], Value::Null);
let response_body: Bytes =
get(format!("/flows/{}/response-body", flow.id)).await.unwrap().bytes().await.unwrap();
assert_eq!(response_body, body, "the control API reads it back the same");
let after = rpc(&ctx, "decode_grpc_message", decode).await.unwrap();
assert_eq!(after["messageType"], Value::Null);
+1 -1
View File
@@ -43,7 +43,7 @@ impl BodyParser {
fn finish(&mut self) -> Vec<StreamMessage> {
match self {
Self::Sse(p) => p.finish(),
Self::Grpc(_) => Vec::new(),
Self::Grpc(p) => p.end().into_iter().collect(),
}
}
}
+50 -1
View File
@@ -19,7 +19,7 @@ const FLAG_TRAILERS: u8 = 0x80;
const PREFIX_LEN: usize = 5;
/// The gRPC flavor a request's `Content-Type` names, and whether it is gRPC-Web's base64 one.
pub(crate) fn detect(content_type: Option<&str>) -> Option<(StreamKind, bool)> {
pub fn detect(content_type: Option<&str>) -> Option<(StreamKind, bool)> {
let content_type = content_type?.trim().to_ascii_lowercase();
let essence = content_type.split(';').next().unwrap_or_default().trim();
if let Some(rest) = essence.strip_prefix("application/grpc-web") {
@@ -165,6 +165,31 @@ impl GrpcParser {
messages
}
/// The body ended: a message it ended partway through, as much of it as came, cut short and
/// as it came (not decompressed), so its bytes are still recorded. A prefix alone, with none
/// of a message's bytes yet, carries nothing to keep.
pub(crate) fn end(&mut self) -> Option<StreamMessage> {
let (flag, length, remaining, mut payload) = self.current.take()?;
let (data, _) = payload.take();
let compressed = flag & FLAG_COMPRESSED != 0;
// A gRPC-Web trailers frame stays one, its status read from what came when it can be.
let mut message = if flag & FLAG_TRAILERS != 0 {
let text = if compressed { "".into() } else { String::from_utf8_lossy(&data) };
trailers_message(self.direction, &text)
} else {
StreamMessage::new(self.direction, MessageKind::GrpcMessage)
};
message.data = data;
message.size = u64::from(length);
message.truncated = true;
message.compressed = compressed;
message.error = Some(format!(
"The body ended partway through this message, {} of its {length} bytes in",
length - remaining
));
Some(message)
}
fn finish(&mut self) -> StreamMessage {
let (flag, length, _, mut payload) = self.current.take().expect("a message being read");
let (data, truncated) = payload.take();
@@ -283,6 +308,30 @@ mod tests {
out
}
/// A body that ends partway through a message keeps what came of it, cut short.
#[test]
fn a_message_cut_off_by_the_end_is_kept() {
let mut parser = GrpcParser::new(MessageDirection::Server, None, false, 1024);
let mut stream = frame(0, b"whole");
stream.extend(&frame(0, b"half of it")[..8]);
let messages = parser.feed(&stream);
assert_eq!(messages.len(), 1);
let cut = parser.end().expect("the unfinished message");
assert_eq!((&cut.data[..], cut.size, cut.truncated), (&b"hal"[..], 10, true));
assert!(cut.error.as_deref().unwrap().contains("3 of its 10 bytes"));
// Nothing unfinished: nothing more.
assert!(parser.end().is_none());
// A trailers frame cut short is still a trailers frame.
let mut parser = GrpcParser::new(MessageDirection::Server, None, false, 1024);
parser.feed(&frame(FLAG_TRAILERS, b"grpc-status: 0\r\n")[..12]);
let cut = parser.end().expect("the unfinished trailers");
assert!(matches!(cut.kind, MessageKind::GrpcTrailers { .. }));
assert_eq!((&cut.data[..], cut.truncated), (&b"grpc-st"[..], true));
// A prefix alone carries none of a message's bytes.
parser.feed(&[0, 0]);
assert!(parser.end().is_none());
}
#[test]
fn detects_flavors() {
assert_eq!(detect(Some("application/grpc")), Some((StreamKind::Grpc, false)));
+1 -1
View File
@@ -32,7 +32,7 @@ use tokio::net::TcpListener;
pub use cert::CaStore;
use connection::handle_connection;
pub use grpc::service_and_method;
pub use grpc::{detect as detect_grpc, service_and_method};
pub use messages::{MessageDirection, MessageKind, RAW_LIMIT, StreamKind, StreamMessage};
use request::BoxBody;
+10 -1
View File
@@ -27,6 +27,15 @@ export interface SelectProps<T extends string> {
filterable?: boolean;
}
/** On macOS, where the host can say; an app with no platform host (the proxy) says no */
function isMacOs(): boolean {
try {
return platform.osType() === "macos";
} catch {
return false;
}
}
export function Select<T extends string>({
labelPosition = "top",
name,
@@ -66,7 +75,7 @@ export function Select<T extends string>({
<Label htmlFor={id} visuallyHidden={hideLabel} className={labelClassName} help={help}>
{label}
</Label>
{platform.osType() === "macos" && !filterable ? (
{isMacOs() && !filterable ? (
<HStack
space={2}
className={classNames(
@@ -1,7 +1,9 @@
import { useVirtualizer, type Virtualizer } from "@tanstack/react-virtual";
import classNames from "classnames";
import type { ReactElement, ReactNode, UIEvent } from "react";
import { useCallback, useLayoutEffect, useRef, useState } from "react";
import { IconButton } from "./IconButton";
import { Icon } from "../Icon";
import { IconButton } from "../IconButton";
interface Props<T> {
data: T[];
@@ -11,6 +13,14 @@ interface Props<T> {
focusable?: boolean;
/** Callback to expose the virtualizer for keyboard navigation */
onVirtualizerReady?: (virtualizer: Virtualizer<HTMLDivElement, Element>) => void;
/**
* Holds and catches up as the proxy's flow list does: once scrolled away from the end (or
* `holdSignal` changes), new items wait under a pill counting them, which scrolls back down.
* Without it, a button locks the scroll to the bottom again.
*/
catchUp?: { label: (count: number) => string };
/** Holds the scroll where it is whenever this changes, as selecting an item does */
holdSignal?: unknown;
}
export function AutoScroller<T>({
@@ -19,9 +29,15 @@ export function AutoScroller<T>({
header,
focusable = false,
onVirtualizerReady,
catchUp,
holdSignal,
}: Props<T>) {
const containerRef = useRef<HTMLDivElement>(null);
const [autoScroll, setAutoScroll] = useState<boolean>(true);
// How many items there were when the scroll was held, to count the new ones
const [heldAt, setHeldAt] = useState<number>(0);
const latestLength = useRef(data.length);
latestLength.current = data.length;
// The virtualizer
const rowVirtualizer = useVirtualizer({
@@ -35,6 +51,11 @@ export function AutoScroller<T>({
onVirtualizerReady?.(rowVirtualizer);
}, [rowVirtualizer, onVirtualizerReady]);
const hold = useCallback(() => {
setAutoScroll(false);
setHeldAt(latestLength.current);
}, []);
// Scroll to new items
const handleScroll = useCallback(
(e: UIEvent<HTMLDivElement>) => {
@@ -44,12 +65,21 @@ export function AutoScroller<T>({
const pixelsFromBottom = el.scrollHeight - (el.scrollTop + el.clientHeight);
const newAutoScroll = pixelsFromBottom <= 0;
if (newAutoScroll !== autoScroll) {
setAutoScroll(newAutoScroll);
if (newAutoScroll) setAutoScroll(true);
else hold();
}
},
[autoScroll],
[autoScroll, hold],
);
// Selecting an item holds the list where it is
const lastHoldSignal = useRef(holdSignal);
useLayoutEffect(() => {
if (Object.is(lastHoldSignal.current, holdSignal)) return;
lastHoldSignal.current = holdSignal;
if (catchUp != null && autoScroll) hold();
}, [autoScroll, catchUp, hold, holdSignal]);
// Scroll to bottom on count change
useLayoutEffect(() => {
if (!autoScroll) return;
@@ -62,9 +92,11 @@ export function AutoScroller<T>({
el.scrollTop = el.scrollHeight;
}, [autoScroll, data.length]);
const newCount = data.length - heldAt;
return (
<div className="h-full w-full relative grid grid-rows-[auto_minmax(0,1fr)]">
{!autoScroll && (
{!autoScroll && catchUp == null && (
<div className="absolute bottom-0 right-0 m-2">
<IconButton
title="Lock scroll to bottom"
@@ -77,6 +109,21 @@ export function AutoScroller<T>({
/>
</div>
)}
{!autoScroll && catchUp != null && newCount > 0 && (
<button
type="button"
onClick={() => setAutoScroll(true)}
className={classNames(
"absolute bottom-3 left-1/2 -translate-x-1/2 z-10",
"flex items-center gap-1.5 h-6 px-3 rounded-full",
"bg-surface border border-border shadow-lg text-text text-xs",
"hover:bg-surface-highlight",
)}
>
<Icon icon="arrow_down_to_line" size="sm" color="primary" />
{catchUp.label(newCount)}
</button>
)}
{header ?? <span aria-hidden />}
<div
ref={containerRef}
@@ -0,0 +1,110 @@
import { renderToStaticMarkup } from "react-dom/server";
import { describe, expect, test, vi } from "vite-plus/test";
import { isLargePayload, payloadText, shouldLoadText, StreamEventRow } from "./EventStreamViewer";
import type { StreamEvent } from "./streamEvents";
// The detail header's select asks the platform which OS it runs on
vi.mock("@yaakapp-internal/platform", () => ({ platform: { osType: () => "macos" } }));
const event: StreamEvent = {
key: "3",
direction: "sent",
kind: "text",
timestamp: "2026-11-06T09:30:00.250",
size: 2048,
preview: '{"op":1}',
};
describe("StreamEventRow", () => {
test("without columns, draws the client's row: arrow, labels and preview", () => {
const markup = renderToStaticMarkup(
<StreamEventRow
event={{ ...event, direction: "received", labels: ["7", "tick"] }}
preview="hello"
delta={null}
isActive={false}
onClick={() => {}}
/>,
);
expect(markup).toContain('title="Server Message"');
expect(markup).toContain("grid-cols-[auto_minmax(0,1fr)_auto]");
expect(markup.indexOf(">7<")).toBeLessThan(markup.indexOf(">tick<"));
expect(markup).toContain('<span class="truncate text-xs">hello</span>');
// No size or time without the columns asking for them
expect(markup).not.toContain("2 KB");
});
test("with columns, draws direction, kind, preview, size, delta and time in order", () => {
const markup = renderToStaticMarkup(
<StreamEventRow
event={event}
preview={event.preview}
delta={1500}
columns={{ direction: true, kind: "Type", size: true, time: true }}
isActive={false}
onClick={() => {}}
/>,
);
expect(markup).toContain("grid-template-columns:1rem 4rem minmax(0,1fr) 4.5rem 4.5rem 6.5rem");
expect(markup).toContain('title="Client Message"');
const order = [">text<", "{&quot;op&quot;:1}", "2 KB", "+1.5 s"].map((s) => markup.indexOf(s));
expect(order.every((i) => i >= 0)).toBe(true);
expect([...order].sort((a, b) => a - b)).toEqual(order);
});
test("an event stream's row has no direction column, and a note replaces the preview", () => {
const markup = renderToStaticMarkup(
<StreamEventRow
event={{ ...event, direction: "info", note: "12 UNIMPLEMENTED", warning: true }}
preview={null}
delta={null}
columns={{ kind: "Event", size: true }}
isActive={false}
onClick={() => {}}
/>,
);
expect(markup).not.toContain("Client Message");
expect(markup).toContain('class="text-xs text-warning">12 UNIMPLEMENTED<');
});
test("an empty binary payload reads as no content, a non-empty one as binary", () => {
const row = (size: number) =>
renderToStaticMarkup(
<StreamEventRow
event={{ ...event, preview: null, binary: true, size }}
preview={null}
delta={null}
columns={{ kind: "Type" }}
isActive={false}
onClick={() => {}}
/>,
);
expect(row(0)).toContain("No content");
expect(row(4)).toContain("Binary");
});
});
describe("payloadText", () => {
test("pretty-prints JSON and leaves other text as it is", () => {
const bytes = (s: string) => new TextEncoder().encode(s);
expect(payloadText(bytes('{"a":[1]}'))).toEqual({
text: '{\n "a": [\n 1\n ]\n}',
language: "json",
});
expect(payloadText(bytes("42"))).toEqual({ text: "42", language: "text" });
expect(payloadText(bytes("plain"))).toEqual({ text: "plain", language: "text" });
});
});
describe("large payloads", () => {
test("nothing is decoded or pretty-printed over 1 MB until asked to", () => {
const big = 2_000_000;
expect(isLargePayload(big, false)).toBe(true);
expect(isLargePayload(big, true)).toBe(false);
expect(isLargePayload(1000, false)).toBe(false);
// Nothing is decoded before the bytes are in, as only they say how large it decodes to
expect(shouldLoadText({ hasBytes: false, tooLarge: false })).toBe(false);
expect(shouldLoadText({ hasBytes: true, tooLarge: true })).toBe(false);
expect(shouldLoadText({ hasBytes: true, tooLarge: false })).toBe(true);
});
});
@@ -0,0 +1,492 @@
import classNames from "classnames";
import type { ReactNode } from "react";
import { useEffect, useMemo, useState } from "react";
import { formatSize } from "@yaakapp-internal/lib/formatSize";
import { Banner } from "../Banner";
import { Button } from "../Button";
import { useEditorHost } from "../EditorHost";
import { EmptyStateText } from "../EmptyStateText";
import { Icon } from "../Icon";
import { InlineCode } from "../InlineCode";
import { HStack, VStack } from "../Stacks";
import { HexdumpViewer } from "../viewers/HexdumpViewer";
import { type EventDetailAction, EventDetailHeader, EventViewer } from "./EventViewer";
import { EventViewerRow } from "./EventViewerRow";
import {
eventDeltas,
formatEventDelta,
formatEventTime,
type StreamEvent,
type StreamPayload,
type StreamPayloadText,
type StreamPayloadView,
} from "./streamEvents";
/** Which columns the list draws beside each event's preview */
export interface EventStreamColumns {
/** The direction arrow, for a stream that goes both ways */
direction?: boolean;
/** The kind column's heading, like `Type` or `Event`; no column when not given */
kind?: string;
/** The kind column's width, as CSS: rows are laid out one by one, so it can't fit its content */
kindWidth?: string;
size?: boolean;
/** The time each passed, and how long after the one before */
time?: boolean;
/** The preview column's heading */
preview?: string;
}
export interface EventStreamViewerProps {
events: StreamEvent[];
/** Where the list and detail split is remembered */
splitLayoutStorageKey: string;
defaultRatio?: number;
/** Above the list, as a connection's status */
header?: ReactNode;
error?: string | null;
isLoading?: boolean;
emptyMessage?: string;
/** Without columns, a row is the client's: its arrow, its labels and its preview */
columns?: EventStreamColumns;
/** The text a row previews, when it isn't the event's own `preview` */
getPreview?: (event: StreamEvent) => string | null;
/** Reads an event's whole payload, for the default detail */
loadPayload?: (event: StreamEvent) => Promise<StreamPayload>;
/** Ways to show an event's payload beyond its text and hexdump, as a gRPC message's decodes */
payloadViews?: (event: StreamEvent) => StreamPayloadView[] | null;
/** Replaces the default detail, which shows the payload `loadPayload` reads */
renderDetail?: (props: { event: StreamEvent; index: number; onClose: () => void }) => ReactNode;
/** Holds and catches up, as the proxy's flow list does, while more events arrive */
catchUp?: { label: (count: number) => string };
}
/** A stream's events as a list, with the selected one's payload below */
export function EventStreamViewer({
events,
splitLayoutStorageKey,
defaultRatio = 0.4,
header,
error,
isLoading,
emptyMessage,
columns,
getPreview,
loadPayload,
payloadViews,
renderDetail,
catchUp,
}: EventStreamViewerProps) {
const deltas = useMemo(() => (columns?.time ? eventDeltas(events) : null), [columns, events]);
return (
<EventViewer
events={events}
getEventKey={(event) => event.key}
error={error}
isLoading={isLoading}
emptyMessage={emptyMessage}
splitLayoutStorageKey={splitLayoutStorageKey}
defaultRatio={defaultRatio}
catchUp={catchUp}
header={
columns == null ? (
header
) : (
<div>
{header}
<ColumnHeadings columns={columns} />
</div>
)
}
renderRow={({ event, index, isActive, onClick }) => (
<StreamEventRow
event={event}
preview={getPreview ? getPreview(event) : event.preview}
delta={deltas?.[index] ?? null}
columns={columns}
isActive={isActive}
onClick={onClick}
/>
)}
renderDetail={
renderDetail ??
(({ event, onClose }) => (
<StreamEventDetail
event={event}
loadPayload={loadPayload}
views={payloadViews?.(event) ?? null}
onClose={onClose}
/>
))
}
/>
);
}
/** One event's row: the client's arrow, labels and preview, or the columns asked for */
export function StreamEventRow({
event,
preview,
delta,
columns,
isActive,
onClick,
}: {
event: StreamEvent;
preview: string | null;
/** Milliseconds since the event before, for the time columns */
delta: number | null;
columns?: EventStreamColumns;
isActive: boolean;
onClick: () => void;
}) {
const template = columns == null ? null : gridTemplate(columns);
if (columns == null || template == null) {
return (
<EventViewerRow
isActive={isActive}
onClick={onClick}
icon={<DirectionIcon event={event} />}
content={
<HStack space={2} className="items-center">
{event.labels != null && event.labels.length > 0 && (
<HStack space={1.5} alignItems="center">
{event.labels.map((label, i) => (
// oxlint-disable-next-line no-array-index-key -- labels may repeat
<EventLabel key={`${i}:${label}`} isActive={isActive}>
{label}
</EventLabel>
))}
</HStack>
)}
<span className="truncate text-xs">{preview}</span>
</HStack>
}
/>
);
}
const trailing: ReactNode[] = [];
if (columns.size) {
trailing.push(
<span className="text-text-subtlest">
{event.size == null ? "" : formatSize(event.size)}
</span>,
);
}
if (columns.time) {
trailing.push(
<span className="text-text-subtlest">{formatEventDelta(delta)}</span>,
<span className="opacity-70">{formatEventTime(event.timestamp)}</span>,
);
}
return (
<EventViewerRow
isActive={isActive}
onClick={onClick}
columns={template}
icon={columns.direction ? <DirectionIcon event={event} /> : null}
cells={{
kind:
columns.kind == null ? undefined : (
<span className={classNames(event.warning && "text-warning")}>{event.kind}</span>
),
trailing,
}}
content={<RowPreview event={event} preview={preview} />}
/>
);
}
function gridTemplate(columns: EventStreamColumns): string {
return [
columns.direction ? "1rem" : null,
columns.kind == null ? null : (columns.kindWidth ?? "4rem"),
"minmax(0,1fr)",
columns.size ? "4.5rem" : null,
columns.time ? "4.5rem 6.5rem" : null,
]
.filter((c) => c != null)
.join(" ");
}
function ColumnHeadings({ columns }: { columns: EventStreamColumns }) {
const template = gridTemplate(columns);
return (
<div className="px-1">
<div
style={{ gridTemplateColumns: template }}
className="grid gap-2 items-center px-1.5 h-xs text-xs text-text-subtlest border-b border-surface-highlight mb-1"
>
{columns.direction && <span />}
{columns.kind != null && <span>{columns.kind}</span>}
<span>{columns.preview ?? "Message"}</span>
{columns.size && <span className="text-right">Size</span>}
{columns.time && (
<>
<span className="text-right" title="Since the message before">
Delta
</span>
<span className="text-right">Time</span>
</>
)}
</div>
</div>
);
}
function RowPreview({ event, preview }: { event: StreamEvent; preview: string | null }) {
if (event.note != null) {
return (
<span className={classNames("text-xs", event.warning ? "text-warning" : "text-text-subtle")}>
{event.note}
</span>
);
}
if (preview != null && preview !== "") {
return <span className="text-xs">{preview.slice(0, 1000)}</span>;
}
if (event.binary && (event.size ?? 0) > 0) {
return <em className="italic text-text-subtlest">Binary</em>;
}
return <em className="italic text-text-subtlest">No content</em>;
}
function DirectionIcon({ event }: { event: StreamEvent }) {
if (event.direction === "info") {
return event.warning ? (
<Icon color="warning" icon="alert_triangle" />
) : (
<Icon color="secondary" icon="info" />
);
}
return event.direction === "sent" ? (
<Icon color="primary" title="Client Message" icon="arrow_big_up_dash" />
) : (
<Icon color="info" title="Server Message" icon="arrow_big_down_dash" />
);
}
function EventLabel({ children, isActive }: { children: ReactNode; isActive?: boolean }) {
return (
<InlineCode className={classNames("py-0", isActive && "relative overflow-hidden")}>
{isActive && <span className="absolute inset-0 bg-text opacity-5 pointer-events-none" />}
<span className="relative">{children}</span>
</InlineCode>
);
}
const LARGE_PAYLOAD = 1000 * 1000;
/** A payload too large to show until asked to: over 1 MB, and not yet asked */
export function isLargePayload(size: number, showLarge: boolean): boolean {
return !showLarge && size > LARGE_PAYLOAD;
}
/**
* Whether a payload's text view may load: decoding, parsing and pretty-printing it. Only once its
* bytes are in, so its size is known (a compressed gRPC message's is not until then), and not
* while it is too large to show.
*/
export function shouldLoadText({
hasBytes,
tooLarge,
}: {
hasBytes: boolean;
tooLarge: boolean;
}): boolean {
return hasBytes && !tooLarge;
}
/** The text and hexdump views every payload has */
function defaultViews(bytes: Uint8Array | null): StreamPayloadView[] {
return [
{
value: "message",
label: "Message",
type: "text",
load: async () => payloadText(bytes ?? new Uint8Array()),
},
{ value: "hexdump", label: "Hexdump", type: "hexdump" },
];
}
/** A payload's text, highlighted and pretty-printed as JSON when it is JSON */
export function payloadText(bytes: Uint8Array): StreamPayloadText {
const text = new TextDecoder("utf-8").decode(bytes);
try {
const parsed: unknown = JSON.parse(text);
if (parsed != null && typeof parsed === "object") {
return { text: JSON.stringify(parsed, null, 2), language: "json" };
}
} catch {
// Not JSON
}
return { text, language: "text" };
}
interface Loaded<T> {
data: T | null;
error: string | null;
loading: boolean;
}
function useLoaded<T>(load: (() => Promise<T>) | null, key: string): Loaded<T> {
const [state, setState] = useState<Loaded<T> & { key: string }>({
key: "",
data: null,
error: null,
loading: load != null,
});
// oxlint-disable-next-line react-hooks/exhaustive-deps -- reloads by key, not by callback identity
useEffect(() => {
if (load == null) return;
let cancelled = false;
setState({ key, data: null, error: null, loading: true });
load().then(
(data) => !cancelled && setState({ key, data, error: null, loading: false }),
(e) => !cancelled && setState({ key, data: null, error: String(e), loading: false }),
);
return () => {
cancelled = true;
};
}, [key]);
return state.key === key ? state : { data: null, error: null, loading: load != null };
}
function StreamEventDetail({
event,
loadPayload,
views: extraViews,
onClose,
}: {
event: StreamEvent;
loadPayload?: (event: StreamEvent) => Promise<StreamPayload>;
views: StreamPayloadView[] | null;
onClose: () => void;
}) {
const { Editor } = useEditorHost();
const payload = useLoaded(loadPayload ? () => loadPayload(event) : null, event.key);
const bytes = payload.data?.bytes ?? null;
const views = extraViews ?? defaultViews(bytes);
const [chosen, setChosen] = useState<Record<string, string>>({});
const defaultView = event.binary && extraViews == null ? "hexdump" : views[0]?.value;
const viewValue = chosen[event.key] ?? defaultView ?? "message";
const view = views.find((v) => v.value === viewValue) ?? views[0];
const [shownLarge, setShownLarge] = useState<Record<string, boolean>>({});
const showLarge = shownLarge[event.key] === true;
const tooLarge = isLargePayload(bytes?.length ?? event.size ?? 0, showLarge);
const textLoad =
view?.type === "text" && shouldLoadText({ hasBytes: bytes != null, tooLarge })
? view.load
: null;
const text = useLoaded(
textLoad,
`${event.key}:${view?.value}:${bytes == null ? 0 : 1}:${textLoad == null ? 0 : 1}`,
);
const setView = (value: string) => setChosen((c) => ({ ...c, [event.key]: value }));
const actions: EventDetailAction[] =
views.length > 2
? [
{
type: "select",
key: "payload-view",
label: "View as",
value: view?.value ?? "",
options: views.map((v) => ({ label: v.label, value: v.value })),
onChange: setView,
},
]
: (bytes?.length ?? 0) > 0 && views.length === 2
? [
{
key: "toggle-hexdump",
label: view?.type === "hexdump" ? "Show Message" : "Show Hexdump",
onClick: () =>
setView(
(view?.type === "hexdump"
? views.find((v) => v.type === "text")
: views.find((v) => v.type === "hexdump")
)?.value ?? viewValue,
),
},
]
: [];
const title = event.title ?? (event.direction === "sent" ? "Message Sent" : "Message Received");
const copyText =
view?.type === "hexdump" ? undefined : (text.data?.text ?? undefined) || undefined;
let body: ReactNode;
if (payload.error != null) {
body = <Banner color="danger">{payload.error}</Banner>;
} else if (payload.loading) {
body = null;
} else if (
(bytes == null || bytes.length === 0) &&
(extraViews == null || view?.type !== "text")
) {
// An empty payload has nothing to show as text or bytes; a decode of one may (an empty
// protobuf message is its defaults)
body = <EmptyStateText>No Content</EmptyStateText>;
} else if (tooLarge) {
body = (
<VStack space={2} className="italic text-text-subtlest">
Message previews larger than 1MB are hidden
<div>
<Button
onClick={() => setShownLarge((s) => ({ ...s, [event.key]: true }))}
color="secondary"
variant="border"
size="xs"
>
Try Showing
</Button>
</div>
</VStack>
);
} else if (view?.type === "hexdump" && bytes != null) {
body = <HexdumpViewer data={bytes} renderEditor={(props) => <Editor {...props} />} />;
} else if (text.error != null) {
body = <Banner color="danger">{text.error}</Banner>;
} else if (text.data != null) {
body = (
<div className="h-full grid grid-rows-[auto_minmax(0,1fr)] gap-1">
{text.data.note ? (
<div className="text-xs text-text-subtle">{text.data.note}</div>
) : (
<span aria-hidden />
)}
<Editor
key={`${event.key}:${view?.value}`}
language={text.data.language}
defaultValue={text.data.text}
wrapLines={false}
readOnly
stateKey={null}
/>
</div>
);
}
return (
<div className="h-full grid grid-rows-[auto_auto_minmax(0,1fr)]">
<EventDetailHeader
title={title}
timestamp={event.timestamp ?? undefined}
actions={actions}
copyText={copyText}
onClose={onClose}
/>
{event.truncated || event.error ? (
<Banner color={event.error ? "danger" : "notice"} className="mb-2 text-sm">
{event.error ?? "The message is cut at the capture limit."}
</Banner>
) : (
<span aria-hidden />
)}
{body}
</div>
);
}
@@ -0,0 +1,331 @@
import type { Virtualizer } from "@tanstack/react-virtual";
import classNames from "classnames";
import { format } from "date-fns";
import type { ReactNode } from "react";
import { useCallback, useMemo, useRef, useState } from "react";
import { useEventViewerKeyboard } from "../../hooks/useEventViewerKeyboard";
import { Banner } from "../Banner";
import { Button } from "../Button";
import { CopyIconButton } from "../CopyIconButton";
import { useEditorHost } from "../EditorHost";
import { IconButton } from "../IconButton";
import { Select, type SelectProps } from "../Select";
import { Separator } from "../Separator";
import { SplitLayout } from "../SplitLayout";
import { HStack } from "../Stacks";
import { AutoScroller } from "./AutoScroller";
interface EventViewerProps<T> {
/** Array of events to display */
events: T[];
/** Get unique key for each event */
getEventKey: (event: T, index: number) => string;
/** Render the event row - receives event, index, isActive, and onClick */
renderRow: (props: {
event: T;
index: number;
isActive: boolean;
onClick: () => void;
}) => ReactNode;
/** Render the detail pane for the selected event */
renderDetail?: (props: { event: T; index: number; onClose: () => void }) => ReactNode;
/** Optional header above the event list (e.g., connection status) */
header?: ReactNode;
/** Error message to display as a banner */
error?: string | null;
/** Key for SplitLayout state persistence */
splitLayoutStorageKey: string;
/** Default ratio for the split (0.0 - 1.0) */
defaultRatio?: number;
/** Enable keyboard navigation (arrow keys) */
enableKeyboardNav?: boolean;
/** Loading state */
isLoading?: boolean;
/** Message to show while loading */
loadingMessage?: string;
/** Message to show when no events */
emptyMessage?: string;
/** Callback when active index changes (for controlled state in parent) */
onActiveIndexChange?: (index: number | null) => void;
/**
* Holds and catches up as the proxy's flow list does: selecting an event or scrolling up holds
* the list, and new events wait under a pill that counts them
*/
catchUp?: { label: (count: number) => string };
}
export function EventViewer<T>({
events,
getEventKey,
renderRow,
renderDetail,
header,
error,
splitLayoutStorageKey,
defaultRatio = 0.4,
enableKeyboardNav = true,
isLoading = false,
loadingMessage = "Loading events...",
emptyMessage = "No events recorded",
onActiveIndexChange,
catchUp,
}: EventViewerProps<T>) {
const [activeIndex, setActiveIndexInternal] = useState<number | null>(null);
const [isPanelOpen, setIsPanelOpen] = useState(false);
// Wrap setActiveIndex to notify parent
const setActiveIndex = useCallback(
(indexOrUpdater: number | null | ((prev: number | null) => number | null)) => {
setActiveIndexInternal((prev) => {
const newIndex =
typeof indexOrUpdater === "function" ? indexOrUpdater(prev) : indexOrUpdater;
onActiveIndexChange?.(newIndex);
return newIndex;
});
},
[onActiveIndexChange],
);
const containerRef = useRef<HTMLDivElement>(null);
const virtualizerRef = useRef<Virtualizer<HTMLDivElement, Element> | null>(null);
const activeEvent = useMemo(
() => (activeIndex != null ? events[activeIndex] : null),
[activeIndex, events],
);
// Check if the event list container is focused
const isContainerFocused = useCallback(() => {
return containerRef.current?.contains(document.activeElement) ?? false;
}, []);
// Keyboard navigation
useEventViewerKeyboard({
totalCount: events.length,
activeIndex,
setActiveIndex,
virtualizer: virtualizerRef.current,
isContainerFocused,
enabled: enableKeyboardNav,
closePanel: () => setIsPanelOpen(false),
openPanel: () => setIsPanelOpen(true),
});
// Handle virtualizer ready callback
const handleVirtualizerReady = useCallback(
(virtualizer: Virtualizer<HTMLDivElement, Element>) => {
virtualizerRef.current = virtualizer;
},
[],
);
// Handle row click - select and open panel, scroll into view
const handleRowClick = useCallback(
(index: number) => {
setActiveIndex(index);
setIsPanelOpen(true);
// Scroll to ensure selected item is visible after panel opens
requestAnimationFrame(() => {
virtualizerRef.current?.scrollToIndex(index, { align: "auto" });
});
},
[setActiveIndex],
);
const handleClose = useCallback(() => {
setIsPanelOpen(false);
}, []);
if (isLoading) {
return <div className="p-3 text-text-subtlest italic">{loadingMessage}</div>;
}
if (events.length === 0 && !error) {
return <div className="p-3 text-text-subtlest italic">{emptyMessage}</div>;
}
return (
<div ref={containerRef} className="h-full">
<SplitLayout
layout="vertical"
storageKey={splitLayoutStorageKey}
defaultRatio={defaultRatio}
minHeightPx={72}
firstSlot={({ style }) => (
<div style={style} className="w-full h-full grid grid-rows-[auto_minmax(0,1fr)]">
{header ?? <span aria-hidden />}
<AutoScroller
data={events}
focusable={enableKeyboardNav}
onVirtualizerReady={handleVirtualizerReady}
catchUp={catchUp}
holdSignal={activeIndex}
header={
error && (
<Banner color="danger" className="m-3">
{error}
</Banner>
)
}
render={(event, index) => (
<div key={getEventKey(event, index)}>
{renderRow({
event,
index,
isActive: index === activeIndex,
onClick: () => handleRowClick(index),
})}
</div>
)}
/>
</div>
)}
secondSlot={
activeEvent != null && renderDetail && isPanelOpen
? ({ style }) => (
<div style={style} className="grid grid-rows-[auto_minmax(0,1fr)] bg-surface">
<div className="pb-3 px-2">
<Separator />
</div>
<div className="mx-2 overflow-y-auto">
{renderDetail({
event: activeEvent,
index: activeIndex ?? 0,
onClose: handleClose,
})}
</div>
</div>
)
: null
}
/>
</div>
);
}
export type EventDetailAction =
| {
type?: "button";
/** Unique key for React */
key: string;
/** Button label */
label: string;
/** Optional icon */
icon?: ReactNode;
/** Click handler */
onClick: () => void;
}
| {
type: "select";
/** Unique key for React */
key: string;
/** Select label */
label: string;
/** Selected value */
value: string;
/** Select options */
options: SelectProps<string>["options"];
/** Change handler */
onChange: (value: string) => void;
};
interface EventDetailHeaderProps {
title: string;
prefix?: ReactNode;
timestamp?: string;
actions?: EventDetailAction[];
copyText?: string | (() => Promise<string | null>);
onClose?: () => void;
}
export function EventDetailHeader({
title,
prefix,
timestamp,
actions,
copyText,
onClose,
}: EventDetailHeaderProps) {
const { copy } = useEditorHost();
const formattedTime = timestamp ? format(new Date(`${timestamp}Z`), "HH:mm:ss.SSS") : null;
return (
<div className="flex items-center justify-between gap-2 mb-2 h-xs">
<HStack space={2} className="items-center min-w-0">
{prefix}
<h3 className="font-semibold select-auto cursor-auto truncate">{title}</h3>
</HStack>
<HStack space={2} className="items-center">
{actions?.map((action) =>
action.type === "select" ? (
<div key={action.key} className="w-32">
<Select
name={action.key}
label={action.label}
hideLabel
size="xs"
value={action.value}
options={action.options}
onChange={action.onChange}
/>
</div>
) : (
<Button
key={action.key}
type="button"
variant="border"
size="xs"
onClick={action.onClick}
>
{action.icon}
{action.label}
</Button>
),
)}
{copyText != null && (
<CopyIconButton
text={copyText}
copy={copy}
size="xs"
title="Copy"
variant="border"
iconSize="sm"
/>
)}
{formattedTime && (
<span className="text-text-subtlest font-mono text-editor ml-2">{formattedTime}</span>
)}
{onClose != null && (
<div
className={classNames(
copyText != null ||
formattedTime ||
((actions ?? []).length > 0 && "border-l border-l-surface-highlight ml-2 pl-3"),
)}
>
<IconButton
color="custom"
className="text-text-subtle -mr-3"
size="xs"
icon="x"
title="Close event panel"
onClick={onClose}
/>
</div>
)}
</HStack>
</div>
);
}
@@ -0,0 +1,59 @@
import classNames from "classnames";
import { format } from "date-fns";
import type { CSSProperties, ReactNode } from "react";
interface EventViewerRowProps {
isActive: boolean;
onClick: () => void;
icon: ReactNode;
content: ReactNode;
timestamp?: string;
/**
* Cells after the icon and content, as a message list's type, size and time columns. When
* given, `columns` lays out the icon, `content` and these, and `timestamp` is not drawn.
*/
cells?: { kind?: ReactNode; trailing?: ReactNode[] };
/** The grid's `grid-template-columns`, for `cells` */
columns?: string;
}
export function EventViewerRow({
isActive,
onClick,
icon,
content,
timestamp,
cells,
columns,
}: EventViewerRowProps) {
const style: CSSProperties | undefined =
cells != null && columns != null ? { gridTemplateColumns: columns } : undefined;
return (
<div className="px-1">
<button
type="button"
onClick={onClick}
style={style}
className={classNames(
"w-full grid gap-2 items-center text-left",
style == null && "grid-cols-[auto_minmax(0,1fr)_auto]",
"px-1.5 h-xs font-mono text-editor cursor-default group focus:outline-hidden focus:text-text rounded-sm",
isActive && "bg-surface-active text-text!",
"text-text-subtle hover:text",
)}
>
{icon}
{cells?.kind != null && <div className="truncate">{cells.kind}</div>}
<div className="w-full truncate">{content}</div>
{style == null
? timestamp && <div className="opacity-50">{format(`${timestamp}Z`, "HH:mm:ss.SSS")}</div>
: cells?.trailing?.map((cell, i) => (
// oxlint-disable-next-line no-array-index-key -- fixed columns, in order
<div key={i} className="truncate text-right">
{cell}
</div>
))}
</button>
</div>
);
}
@@ -0,0 +1,53 @@
import { describe, expect, test } from "vite-plus/test";
import { eventDeltas, formatEventDelta, formatEventTime } from "./streamEvents";
describe("eventDeltas", () => {
test("measures each event from the one before it", () => {
const deltas = eventDeltas([
{ timestamp: "2026-11-06T09:30:00.000" },
{ timestamp: "2026-11-06T09:30:00.012" },
{ timestamp: "2026-11-06T09:30:01.512" },
{ timestamp: "2026-11-06T09:32:05.512" },
]);
expect(deltas).toEqual([null, 12, 1500, 124_000]);
expect(deltas.map(formatEventDelta)).toEqual(["", "+12 ms", "+1.5 s", "+2m 4s"]);
});
test("skips an undated event, measuring the next from the last dated one", () => {
expect(
eventDeltas([
{ timestamp: "2026-11-06T09:30:00.000" },
{ timestamp: null },
{ timestamp: "2026-11-06T09:30:00.250" },
]),
).toEqual([null, null, 250]);
});
test("never goes negative when timestamps tie or step back", () => {
expect(
eventDeltas([
{ timestamp: "2026-11-06T09:30:00.500" },
{ timestamp: "2026-11-06T09:30:00.400" },
]),
).toEqual([null, 0]);
});
test("reads timestamps with or without a zone as UTC", () => {
expect(
eventDeltas([
{ timestamp: "2026-11-06T09:30:00.000Z" },
{ timestamp: "2026-11-06T09:30:00.100" },
]),
).toEqual([null, 100]);
});
});
describe("formatEventTime", () => {
test("shows the local time of day to the millisecond", () => {
const local = new Date(Date.UTC(2026, 10, 6, 9, 30, 0, 7));
const pad = (n: number, w = 2) => String(n).padStart(w, "0");
const expected = `${pad(local.getHours())}:${pad(local.getMinutes())}:${pad(local.getSeconds())}.007`;
expect(formatEventTime("2026-11-06T09:30:00.007")).toBe(expected);
expect(formatEventTime(null)).toBe("");
});
});
@@ -0,0 +1,90 @@
import { format } from "date-fns";
import { formatMillis } from "../tags/HttpResponseDurationTag";
/**
* What the event stream viewer draws. Each app maps its own records onto these (the client the
* events of an SSE response, the proxy a stream's stored messages), so the viewer never imports
* either app's model types.
*/
/** Which side sent it: the app, the server, or neither, as a connection's status */
export type StreamEventDirection = "sent" | "received" | "info";
export interface StreamEvent {
/** Unique within the stream, and stable as more events arrive */
key: string;
direction: StreamEventDirection;
/** What kind it is, as its type column shows it: `text`, `close`, an SSE event's name */
kind: string | null;
/** Small chips before the preview, as the client's SSE event ids */
labels?: string[];
/** When it passed, in UTC without a zone (`2026-11-06T09:30:00.123`), as the models store it */
timestamp: string | null;
/** Bytes on the wire */
size: number | null;
/** The start of the payload as text, null when it's binary or empty */
preview: string | null;
/** In place of the preview, dimmed: a close's code and reason, a call's status */
note?: string | null;
/** The detail's title, like `Connection Closed`; by direction when not given */
title?: string;
/** Its payload is binary, so the detail opens on the hexdump */
binary?: boolean;
/** Its payload was cut at the capture limit */
truncated?: boolean;
/** Why its payload could not be read */
error?: string | null;
/** Coloured as a warning, as an error or a failed status */
warning?: boolean;
}
/** A way of showing an event's payload, as its body view's switch offers them */
export type StreamPayloadView =
| {
value: string;
label: string;
/** Text, with the language it's highlighted and formatted as */
type: "text";
load: () => Promise<StreamPayloadText>;
}
| { value: string; label: string; type: "hexdump" };
export interface StreamPayloadText {
text: string;
language: "json" | "text";
/** Shown above the text, as how a gRPC message was decoded */
note?: string | null;
}
/** An event's payload */
export interface StreamPayload {
bytes: Uint8Array;
}
/** Milliseconds from each event to the one before it, null for the first or an undated one */
export function eventDeltas(events: Pick<StreamEvent, "timestamp">[]): (number | null)[] {
let previous: number | null = null;
return events.map((event) => {
const at = parseTimestamp(event.timestamp);
const delta = at == null || previous == null ? null : Math.max(0, at - previous);
if (at != null) previous = at;
return delta;
});
}
/** A delta as its column shows it: `+12 ms`, `+1.5 s` */
export function formatEventDelta(delta: number | null): string {
return delta == null ? "" : `+${formatMillis(Math.round(delta))}`;
}
/** An event's time of day, to the millisecond, in the local zone */
export function formatEventTime(timestamp: string | null): string {
const at = parseTimestamp(timestamp);
return at == null ? "" : format(at, "HH:mm:ss.SSS");
}
function parseTimestamp(timestamp: string | null): number | null {
if (timestamp == null) return null;
const at = Date.parse(/[zZ]|[+-]\d\d:?\d\d$/.test(timestamp) ? timestamp : `${timestamp}Z`);
return Number.isNaN(at) ? null : at;
}
+19 -2
View File
@@ -41,6 +41,23 @@ export type {
} from "./components/EditorHost";
export { EditorHostProvider, useEditorHost } from "./components/EditorHost";
export { EmptyStateText } from "./components/EmptyStateText";
export { AutoScroller } from "./components/events/AutoScroller";
export type {
EventStreamColumns,
EventStreamViewerProps,
} from "./components/events/EventStreamViewer";
export { EventStreamViewer, payloadText } from "./components/events/EventStreamViewer";
export type { EventDetailAction } from "./components/events/EventViewer";
export { EventDetailHeader, EventViewer } from "./components/events/EventViewer";
export { EventViewerRow } from "./components/events/EventViewerRow";
export type {
StreamEvent,
StreamEventDirection,
StreamPayload,
StreamPayloadText,
StreamPayloadView,
} from "./components/events/streamEvents";
export { eventDeltas, formatEventDelta, formatEventTime } from "./components/events/streamEvents";
export type { ExternalLinkProps } from "./components/ExternalLink";
export { ExternalLink } from "./components/ExternalLink";
export { ConfirmLargeResponse } from "./components/http/ConfirmLargeResponse";
@@ -104,6 +121,8 @@ export { PairOrBulkEditor } from "./components/pairs/PairOrBulkEditor";
export { PillButton } from "./components/PillButton";
export type { RadioDropdownItem, RadioDropdownProps } from "./components/RadioDropdown";
export { RadioDropdown } from "./components/RadioDropdown";
export type { SelectProps } from "./components/Select";
export { Select } from "./components/Select";
export type { ErrorBoundaryProps } from "./components/ErrorBoundary";
export { ErrorBoundary } from "./components/ErrorBoundary";
export { FormattedError } from "./components/FormattedError";
@@ -128,8 +147,6 @@ export { Overlay } from "./components/Overlay";
export type { PlainInputProps } from "./components/PlainInput";
export { PlainInput } from "./components/PlainInput";
export { Portal } from "./components/Portal";
export type { SelectProps } from "./components/Select";
export { Select } from "./components/Select";
export type { SeparatorAction } from "./components/Separator";
export { Separator } from "./components/Separator";
export type { SettingRowBaseProps, SettingSnippetLanguage } from "./components/settings/SettingRow";