@kar-mi/spirit-vale-tools-capture 2.6.0 → 3.0.0

package/dist/capture/drop-diagnostics.d.ts

@@ -0,0 +1,42 @@
+import type { CapturedTransportPacket } from "../types.ts";
+/** Flows tracked before new ones are ignored. */
+export declare const DROP_FLOW_LIMIT = 64;
+/** Flows named in a summary. */
+export declare const DROP_FLOW_REPORT_COUNT = 5;
+/** Sequenced packets a flow must show before its verdict is trusted. */
+export declare const DROP_VERDICT_MIN_SAMPLES = 20;
+/**
+ * Fraction of consecutive sequence numbers above which a flow is called game traffic. A real stream
+ * sits far above this and traffic that merely parses as LiteNetLib far below, so it is not delicate.
+ */
+export declare const DROP_VERDICT_THRESHOLD = 0.25;
+export interface DroppedFlow {
+    flow: string;
+    packets: number;
+    verdict: "game traffic" | "unrelated" | "unknown";
+}
+/**
+ * Explains what unattributed capture is throwing away, without keeping any of it.
+ *
+ * A high give-up count reads as lost game traffic and usually is not. Per flow this keeps a count
+ * and one statistic - how often a LiteNetLib sequence number follows its predecessor - which tells
+ * a real stream from traffic that merely parses as one, since nothing else maintains a sequence.
+ * No payload is retained, so a summary is safe to share.
+ */
+export declare class DropDiagnostics {
+    private readonly flows;
+    /** Records a packet that could not be attributed and was given up on. */
+    record(packet: CapturedTransportPacket): void;
+    /**
+     * The busiest dropped flows, worst first, each with a verdict.
+     *
+     * Counts run for the whole session rather than since the last call, because a verdict needs
+     * accumulated sequence samples to settle. Callers reporting a windowed count should say so.
+     */
+    topFlows(limit?: number): DroppedFlow[];
+    /** Whether any dropped flow looks like game traffic - the only case worth acting on. */
+    get hasGameTraffic(): boolean;
+    reset(): void;
+    private countSequence;
+}
+//# sourceMappingURL=drop-diagnostics.d.ts.map

package/dist/capture/drop-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drop-diagnostics.d.ts","sourceRoot":"","sources":["../../src/capture/drop-diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,iDAAiD;AACjD,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,gCAAgC;AAChC,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAS3C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,cAAc,GAAG,WAAW,GAAG,SAAS,CAAC;CACnD;AAED;;;;;;;GAOG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IAEtD,yEAAyE;IACzE,MAAM,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAU5C;IAED;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,SAAyB,GAAG,WAAW,EAAE,CAKtD;IAED,wFAAwF;IACxF,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,OAAO,CAAC,aAAa;CAoBtB"}

package/dist/capture/duplicate-filter.d.ts

@@ -0,0 +1,39 @@
+import type { CapturedTransportPacket } from "../types.ts";
+/** How long a payload stays remembered. Relayed copies arrive within about a millisecond. */
+export declare const DUPLICATE_WINDOW_MS = 5;
+/** Entries retained before the oldest are evicted, mirroring the pending-packet ceiling. */
+export declare const DUPLICATE_ENTRY_LIMIT = 16384;
+export interface DuplicateFilterOptions {
+    windowMs?: number;
+    entryLimit?: number;
+}
+/**
+ * Suppresses the redundant copies a redirecting VPN puts on the wire.
+ *
+ * Relays such as ExitLag rewrite addresses and ports rather than encapsulating, and send a datagram
+ * over several routes at once, so one datagram is captured more than once. The key is the payload
+ * with the direction and local port, which a relay preserves, never the peer's endpoint, which it
+ * rewrites. Direction keeps a peer's echo of an identical control payload distinct; the local port
+ * keeps two sockets distinct when they send the same bytes at once, as two connections opening
+ * together do.
+ */
+export declare class DuplicateFilter {
+    private readonly windowMs;
+    private readonly entryLimit;
+    private readonly seen;
+    private suppressed;
+    constructor(options?: DuplicateFilterOptions);
+    /** Total copies suppressed since the last {@link takeSuppressedCount}. */
+    get suppressedCount(): number;
+    /**
+     * Reports whether a packet is the first sighting of its payload and should be decoded.
+     *
+     * Payload-free packets are always admitted; they carry nothing to tell copies apart.
+     */
+    admit(packet: CapturedTransportPacket, nowMs?: number): boolean;
+    /** Returns the suppressed count and resets it, for periodic reporting. */
+    takeSuppressedCount(): number;
+    reset(): void;
+    private evict;
+}
+//# sourceMappingURL=duplicate-filter.d.ts.map

package/dist/capture/duplicate-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplicate-filter.d.ts","sourceRoot":"","sources":["../../src/capture/duplicate-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE5E,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,4FAA4F;AAC5F,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,OAAO,CAAC,UAAU,CAAK;IAEvB,YAAY,OAAO,GAAE,sBAA2B,EAG/C;IAED,0EAA0E;IAC1E,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,uBAAuB,EAAE,KAAK,GAAE,MAAmB,GAAG,OAAO,CAa1E;IAED,0EAA0E;IAC1E,mBAAmB,IAAI,MAAM,CAI5B;IAED,KAAK,IAAI,IAAI,CAGZ;IAED,OAAO,CAAC,KAAK;CAQd"}

package/dist/capture/packet-capture.d.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from "node:events";
 import type { CapturedLiteNetLibPacket } from "../litenetlib/types.ts";
 import type { CapturedFishNetPacket } from "../fishnet/types.ts";
+import type { DroppedFlow } from "./drop-diagnostics.ts";
 import type { NpcapDevice, NpcapRuntime, NpcapStatus } from "./npcap.ts";
 import type { TargetSnapshotProvider } from "./target-tracker.ts";
 import type { CaptureConfig, CaptureConnectionEvent, CaptureTargetStatus, CapturedTcpPacket, CapturedTransportPacket, CapturedUdpPacket, CaptureState } from "../types.ts";
@@ -27,6 +28,11 @@ export declare class PacketCapture extends EventEmitter {
     private currentConnectionId?;
     private droppedPending;
     private droppedReportedAtMs;
+    private duplicateFilter;
+    private duplicateReportedAtMs;
+    private relayObserved;
+    private readonly dropDiagnostics;
+    private deviceLabel;
     private _state;
     constructor(dependencies?: PacketCaptureDependencies);
     get state(): CaptureState;
@@ -40,13 +46,18 @@ export declare class PacketCapture extends EventEmitter {
     on(event: "fishNetPacket", listener: (packet: CapturedFishNetPacket) => void): this;
     on(event: "connection", listener: (event: CaptureConnectionEvent) => void): this;
     on(event: "targetStatus", listener: (status: CaptureTargetStatus) => void): this;
+    on(event: "droppedFlows", listener: (flows: DroppedFlow[]) => void): this;
     on(event: "warning", listener: (message: string) => void): this;
     on(event: "error", listener: (error: Error) => void): this;
     on(event: "stopped", listener: () => void): this;
     start(config?: CaptureConfig): Promise<void>;
     stop(): Promise<void>;
     private poll;
+    /** Counts a packet given up on and folds it into the drop diagnostics. */
+    private recordDropped;
     private flushPending;
+    /** Reports copies a relay put on the wire, naming the adapter in case a better one exists. */
+    private reportSuppressedDuplicates;
     /** Reports packets given up on unattributed, which is how a connection loses its opening. */
     private reportDroppedPending;
     private emitTransportPacket;

package/dist/capture/packet-capture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"packet-capture.d.ts","sourceRoot":"","sources":["../../src/capture/packet-capture.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"packet-capture.d.ts","sourceRoot":"","sources":["../../src/capture/packet-capture.ts"],"names":[],"mappings":"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"}