@saptools/cf-live-trace 0.1.5 → 0.1.8

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 declare const CF_LIVE_TRACE_GLOBAL_NAME = "__SAPTOOLS_CF_LIVE_TRACE__";
-declare const CF_LIVE_TRACE_RUNTIME_VERSION = 1;
+declare const CF_LIVE_TRACE_RUNTIME_VERSION = 3;
 interface RuntimeInstallOptions {
     readonly appId: string;
     readonly instance: string;
@@ -14,7 +14,7 @@ interface StopExpressionOptions {
 }
 declare const CF_LIVE_TRACE_RUNTIME_SOURCE: string;
 declare function buildInstallExpression(options: RuntimeInstallOptions): string;
-declare function buildDrainExpression(maxCount: number, maxTransportBodyBytes: number): string;
+declare function buildDrainExpression(maxCount: number, maxTransportBodyBytes: number, acknowledgedDrainId?: string | null): string;
 declare function buildStopExpression(options: StopExpressionOptions): string;
 
 type LiveTraceLifecycleState = "idle" | "preparing" | "enabling-ssh" | "starting-inspector" | "opening-tunnel" | "injecting" | "streaming" | "stopping" | "stopped" | "error";
@@ -87,6 +87,7 @@ interface LiveTraceUrlSummary {
     readonly latestSeenAt: string;
 }
 interface DrainParseResult {
+    readonly drainId: string | null;
     readonly events: readonly LiveTraceEvent[];
     readonly droppedCount: number;
     readonly queueSize: number;
@@ -133,11 +134,137 @@ interface PreviewTruncationResult {
     readonly preview: string;
     readonly truncated: boolean;
 }
-declare function truncatePreview(preview: string, maxChars: number): PreviewTruncationResult;
+declare function truncatePreview(preview: string, maxBytes: number): PreviewTruncationResult;
 
 declare function buildUrlSummaries(events: readonly LiveTraceEvent[]): LiveTraceUrlSummary[];
 declare function normalizeEventUrl(event: LiveTraceEvent): string;
 
+interface TraceTargetIdentity {
+    readonly region?: string;
+    readonly apiEndpoint?: string;
+    readonly org: string;
+    readonly space: string;
+    readonly app: string;
+    readonly instance: string;
+}
+interface TraceSession {
+    readonly sessionId: string;
+    readonly createdAt: string;
+    readonly target: TraceTargetIdentity;
+    readonly directory: string;
+    readonly eventsDirectory: string;
+    readonly manifestPath: string;
+}
+interface StoredTraceEvent {
+    readonly version: 1;
+    readonly sessionId: string;
+    readonly requestId: string;
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly target: TraceTargetIdentity;
+    readonly requestBodyFormat: TraceBodyFormat;
+    readonly responseBodyFormat: TraceBodyFormat;
+    readonly event: LiveTraceEvent;
+}
+interface StoredTraceEventFile extends StoredTraceEvent {
+    readonly backupPath: string;
+}
+interface TraceSessionSummary {
+    readonly sessionId: string;
+    readonly createdAt: string;
+    readonly target: TraceTargetIdentity;
+    readonly eventCount: number;
+    readonly directory: string;
+}
+interface CreateTraceSessionInput {
+    readonly target: CfLiveTraceTarget;
+}
+interface TraceStoreOptions {
+    readonly saptoolsRoot?: string;
+    readonly now?: () => Date;
+    readonly sessionId?: string;
+    readonly requestId?: () => string;
+}
+type TraceEventVisitor = (record: StoredTraceEventFile) => boolean | Promise<boolean>;
+declare function traceSessionsRoot(saptoolsRoot?: string): string;
+declare function createTraceSession(input: CreateTraceSessionInput, options?: TraceStoreOptions): Promise<TraceSession>;
+declare function writeTraceEvent(session: TraceSession, event: LiveTraceEvent, options?: TraceStoreOptions): Promise<StoredTraceEventFile>;
+declare function readTraceEvent(sessionId: string, requestId: string, options?: TraceStoreOptions): Promise<StoredTraceEventFile>;
+declare function listTraceEvents(sessionId: string, options?: TraceStoreOptions): Promise<readonly StoredTraceEventFile[]>;
+declare function visitTraceEvents(sessionId: string, visitor: TraceEventVisitor, options?: TraceStoreOptions): Promise<void>;
+declare function listTraceSessions(options?: TraceStoreOptions): Promise<readonly TraceSessionSummary[]>;
+declare function pruneTraceSessions(options?: TraceStoreOptions): Promise<number>;
+
+type TraceBodyFormat = "empty" | "json" | "xml" | "html" | "form" | "text" | "binary" | "unknown";
+interface CompactTraceEvent {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly requestId: string;
+    readonly timestamp: string;
+    readonly instance: string;
+    readonly method: string;
+    readonly path: string;
+    readonly url: string;
+    readonly normalizedUrl: string;
+    readonly status: number | null;
+    readonly durationMs: number | null;
+    readonly requestBytes: number;
+    readonly responseBytes: number;
+    readonly requestBodyFormat: TraceBodyFormat;
+    readonly responseBodyFormat: TraceBodyFormat;
+    readonly requestBodyPreview: string;
+    readonly requestBodyPreviewRemainingChars: number;
+    readonly responseBodyPreview: string;
+    readonly responseBodyPreviewRemainingChars: number;
+    readonly requestBodyTruncated: boolean;
+    readonly responseBodyTruncated: boolean;
+    readonly droppedBeforeEvent: number;
+    readonly source: "runtime-http";
+    readonly traceId: string;
+    readonly correlationId: string | null;
+}
+declare function detectBodyFormat(body: string, headers: Record<string, string>): TraceBodyFormat;
+declare function compactTraceEvent(record: StoredTraceEvent): CompactTraceEvent;
+
+type TraceBodySide = "request" | "response";
+type TraceSearchBodySide = TraceBodySide | "both";
+interface TraceBodyInspectionOptions {
+    readonly body: TraceBodySide;
+    readonly path?: string;
+    readonly limit?: number;
+    readonly maxRows?: number;
+}
+interface TraceBodyInspectionRow {
+    readonly path: string;
+    readonly type: string;
+    readonly value: string;
+}
+interface TraceBodyInspectionResult {
+    readonly rows: readonly TraceBodyInspectionRow[];
+    readonly totalRows: number;
+    readonly rowsTruncated: boolean;
+}
+interface TraceSearchOptions {
+    readonly body: TraceSearchBodySide;
+    readonly limit: number;
+    readonly previewLength?: number;
+}
+interface TraceSearchMatch {
+    readonly sessionId: string;
+    readonly requestId: string;
+    readonly timestamp: string;
+    readonly method: string;
+    readonly normalizedUrl: string;
+    readonly status: number | null;
+    readonly body: TraceBodySide;
+    readonly path: string;
+    readonly offset?: number;
+    readonly preview: string;
+}
+declare function inspectTraceBody(record: StoredTraceEvent, options: TraceBodyInspectionOptions): readonly TraceBodyInspectionRow[];
+declare function inspectTraceBodyResult(record: StoredTraceEvent, options: TraceBodyInspectionOptions): TraceBodyInspectionResult;
+declare function searchTraceRecords(records: readonly StoredTraceEvent[], searchTerm: string, options: TraceSearchOptions): readonly TraceSearchMatch[];
+
 interface RunCfOptions {
     readonly cfHomeDir?: string;
     readonly command?: string;
@@ -181,7 +308,7 @@ declare function createSecretRedactor(secrets: readonly string[]): (message: str
 interface LiveTraceSessionOptions {
     readonly target: CfLiveTraceTarget;
     readonly onState?: (event: LiveTraceStateEvent) => void;
-    readonly onEvents?: (events: readonly LiveTraceEvent[]) => void;
+    readonly onEvents?: (events: readonly LiveTraceEvent[]) => void | Promise<void>;
     readonly onSummary?: (summary: ReturnType<typeof buildUrlSummaries>) => void;
     readonly onLog?: (message: string) => void;
 }
@@ -197,11 +324,12 @@ interface LiveTraceDependencies {
 declare class LiveTraceSession {
     private readonly options;
     private readonly dependencies;
-    private readonly events;
+    private readonly summaryEvents;
     private consecutiveDrainTimeouts;
-    private drainInFlight;
+    private drainTask;
     private inspectorClient;
     private pollTimer;
+    private pendingDrainAcknowledgement;
     private state;
     private stopRequested;
     private tunnelHandle;
@@ -214,9 +342,13 @@ declare class LiveTraceSession {
     private attachInspector;
     private installRuntimeHook;
     private startPolling;
+    private startDrain;
+    private clearDrainTask;
     private drainTraceEvents;
     private publishDrainedEvents;
+    private publishSummary;
     private handleDrainFailure;
+    private handleEventHandlerFailure;
     private stopRuntimeTrace;
     private closeInspectorClient;
     private stopTunnel;
@@ -229,4 +361,4 @@ declare class LiveTraceSession {
     private reportInspectorStartup;
 }
 
-export { CF_LIVE_TRACE_GLOBAL_NAME, CF_LIVE_TRACE_RUNTIME_SOURCE, CF_LIVE_TRACE_RUNTIME_VERSION, type CfDependencies, type CfLiveTraceTarget, type DrainParseOptions, type DrainParseResult, type InspectorRuntimeClient, type InspectorStartupResult, type LiveTraceDependencies, type LiveTraceEvent, type LiveTraceLifecycleState, LiveTraceSession, type LiveTraceSessionOptions, type LiveTraceStartOptions, type LiveTraceStateEvent, type LiveTraceStopOptions, type LiveTraceStopReason, type LiveTraceUrlSummary, type PortForwardHandle, type PortForwardParams, type PortForwardProcess, type PreviewTruncationResult, type RunCfOptions, type RuntimeInstallOptions, type StopExpressionOptions, type TunnelDependencies, type TunnelOpenResult, type TunnelReadyResult, buildCfSshArgs, buildDrainExpression, buildInspectorSignalCommand, buildInstallExpression, buildStopExpression, buildUrlSummaries, createSecretRedactor, normalizeEventUrl, openInspectorTunnel, parseDrainResult, prepareCfSession, startNodeInspector, truncatePreview, tryStartNodeInspector };
+export { CF_LIVE_TRACE_GLOBAL_NAME, CF_LIVE_TRACE_RUNTIME_SOURCE, CF_LIVE_TRACE_RUNTIME_VERSION, type CfDependencies, type CfLiveTraceTarget, type CompactTraceEvent, type CreateTraceSessionInput, type DrainParseOptions, type DrainParseResult, type InspectorRuntimeClient, type InspectorStartupResult, type LiveTraceDependencies, type LiveTraceEvent, type LiveTraceLifecycleState, LiveTraceSession, type LiveTraceSessionOptions, type LiveTraceStartOptions, type LiveTraceStateEvent, type LiveTraceStopOptions, type LiveTraceStopReason, type LiveTraceUrlSummary, type PortForwardHandle, type PortForwardParams, type PortForwardProcess, type PreviewTruncationResult, type RunCfOptions, type RuntimeInstallOptions, type StopExpressionOptions, type StoredTraceEvent, type StoredTraceEventFile, type TraceBodyFormat, type TraceBodyInspectionOptions, type TraceBodyInspectionResult, type TraceBodyInspectionRow, type TraceBodySide, type TraceEventVisitor, type TraceSearchBodySide, type TraceSearchMatch, type TraceSearchOptions, type TraceSession, type TraceSessionSummary, type TraceStoreOptions, type TraceTargetIdentity, type TunnelDependencies, type TunnelOpenResult, type TunnelReadyResult, buildCfSshArgs, buildDrainExpression, buildInspectorSignalCommand, buildInstallExpression, buildStopExpression, buildUrlSummaries, compactTraceEvent, createSecretRedactor, createTraceSession, detectBodyFormat, inspectTraceBody, inspectTraceBodyResult, listTraceEvents, listTraceSessions, normalizeEventUrl, openInspectorTunnel, parseDrainResult, prepareCfSession, pruneTraceSessions, readTraceEvent, searchTraceRecords, startNodeInspector, traceSessionsRoot, truncatePreview, tryStartNodeInspector, visitTraceEvents, writeTraceEvent };