@traffic-twin/sdk 0.0.0-stage → 0.1.0

package/dist/esm/sanitizer/sanitizer.d.ts

@@ -0,0 +1,149 @@
+import { type OMap } from './json.js';
+import { type Action, type Policy, type TemplateSeg } from './policy.js';
+export type NetError = 'timeout' | 'reset' | 'refused' | 'dns' | 'tls' | 'other';
+export type SampledBy = 'baggage' | 'subject' | 'trace' | 'random' | 'inherited';
+/** Normalized exchange (sanitizer.md 1). */
+export interface Exchange {
+    dir: 'inbound' | 'outbound';
+    service_name?: string;
+    url_base?: string;
+    method: string;
+    raw_path: Buffer;
+    /** undefined/null = the URL had no "?". */
+    raw_query?: Buffer | null;
+    /** A-FRAMEWORK-ID: identifier of the 3.4 table; required with framework_route. */
+    framework?: string;
+    framework_route?: string;
+    trace_id?: string;
+    inherited?: boolean;
+    req_headers: Array<[string, Buffer]>;
+    req_body?: Buffer;
+    req_body_total?: number | 'unknown';
+    req_body_consumed?: boolean;
+    req_body_decoded?: boolean;
+    status?: number;
+    net_error?: NetError;
+    resp_headers?: Array<[string, Buffer]>;
+    resp_body?: Buffer;
+    resp_body_total?: number | 'unknown';
+    resp_body_consumed?: boolean;
+    resp_body_decoded?: boolean;
+}
+export interface Decision {
+    sampled: boolean;
+    by: SampledBy;
+}
+export type Result = {
+    outcome: 'event';
+    out: OMap;
+    parts: Map<string, string>;
+    canonical: string;
+    sampledBy: SampledBy;
+} | {
+    outcome: 'not_sampled';
+    sampledBy: SampledBy;
+}
+/** 10.3 step 4: no event; the source counts it in `sanitizer_errors`. */
+ | {
+    outcome: 'too_large';
+    sampledBy: SampledBy;
+};
+export declare const MAX_EVENT_BYTES = 524288;
+interface HdrEntry {
+    out: string;
+    values: Buffer[];
+    origs: Set<string>;
+}
+interface Headers {
+    order: string[];
+    map: Map<string, HdrEntry>;
+}
+/** `token`: a ready output token (multipart file part, sanitizer.md 22.3); the value is then not read. */
+interface NamedEntry {
+    orig: string | null;
+    out: string;
+    value: Buffer;
+    noEq: boolean;
+    token?: string;
+}
+export declare function normalizeHeaders(list: Array<[string, Buffer]> | undefined): Headers;
+/** 8.1.5: `ct` from the normalized content-type value; undefined without the header. */
+export declare function contentType(h: Headers): string | undefined;
+interface Seg {
+    dec: string | null;
+}
+export declare function decomposePath(raw: Buffer): {
+    segs: Seg[];
+    truncated: boolean;
+};
+interface UrlBase {
+    invalid: boolean;
+    origin: string;
+    hostport: string;
+    /** Normalized host without port (an IPv6 literal keeps its lowercase text, without brackets). */
+    host: string;
+    /** Normalized port; null when absent or the scheme default. */
+    port: string | null;
+    /** The 16 bytes of a bracketed IPv6 literal (3.1 point 5, spec v1.5), else null. */
+    ip6: Uint8Array | null;
+}
+/** 3.1 normalization of `url_base`. */
+export declare function normalizeUrlBase(u: string | undefined): UrlBase;
+export declare const FRAMEWORKS: ReadonlySet<string>;
+/**
+ * 3.4 with A-FRAMEWORK-ID (normative since 1.1.1): normalizes `route` with the table of
+ * `framework`. Every segment must be a parameter syntax of that framework or a literal of
+ * the operation-key grammar; anything else (every "not normalizable" case) fails.
+ */
+export declare function normalizeFrameworkRoute(route: string, framework: string): TemplateSeg[] | null;
+export declare function bucketTime(s: string, unit: string): string | null;
+export declare function bucketNum(lex: string, a: Action): string;
+export interface KeyRef {
+    kid: string;
+    key: Buffer;
+}
+export declare class Sanitizer {
+    readonly policy: Policy;
+    readonly key: KeyRef;
+    readonly options: {
+        rand?: () => number;
+        rateOverrideBp?: number | null;
+    };
+    private readonly epochBuf;
+    constructor(policy: Policy, key: KeyRef, options?: {
+        rand?: () => number;
+        rateOverrideBp?: number | null;
+    });
+    mac(domain: string, value: Buffer): Buffer;
+    token(domain: string, value: Buffer): string;
+    rateBp(): number;
+    subjectValue(reqHeaders: Array<[string, Buffer]> | undefined): Buffer | null;
+    private hashSample;
+    private randomSample;
+    private readonly subjName;
+    /** Subject header value (as received) -> 1 sampled, 2 not sampled, 3 no usable subject. Per policy and key, bounded. */
+    private readonly subjCache;
+    /**
+     * Inbound decision straight from node's rawHeaders (flat latin1 strings) and the
+     * traceparent trace id, with no per-request allocation on the common paths. It returns the
+     * same decision as `decide()` on the same headers, or null when it cannot answer fast
+     * (baggage trusted, repeated subject header): the caller then uses `decide()`.
+     * The subject answer is remembered per header value: the HMAC and the parsing run once per
+     * distinct value (a user's cookie or token repeats on every request).
+     */
+    decideRaw(service: string, raw: readonly string[], traceId: string | undefined): Decision | null;
+    /** Sampling decision for an exchange (needs only the request line and headers). */
+    decide(ex: Pick<Exchange, 'dir' | 'service_name' | 'req_headers' | 'trace_id' | 'inherited'>, subject?: Buffer | null): Decision;
+    run(ex: Exchange, now: number | undefined, decision?: Decision): Result;
+}
+/**
+ * 9.0 decoding, one level, with an output cap (A-GZIP-STRICT): returns the decoded bytes,
+ * 'cap' when the output reaches `cap` bytes, or null on any error (truncated stream,
+ * bytes after the end of the stream, corrupt data).
+ */
+export declare function decodeBody(data: Buffer, zlibFormat: boolean, cap: number): Buffer | 'cap' | null;
+/** tt-cjson object from already serialized members (keys sorted by bytes). */
+export declare function composeCanonical(parts: Map<string, string>): string;
+/** 8.3 / 9.1: query string or form body into named entries. */
+export declare function parseUrlencoded(raw: Buffer): NamedEntry[];
+export {};