@hue-run/sdk 0.18.2 → 0.19.0

package/dist/blobs.d.ts

@@ -3,9 +3,11 @@ import { type MediaDigestMemo, type FileDigest } from "./inline-files.js";
 import { type ByteSource } from "./large-media.js";
 /**
  * Large values and binary media travel apart from their span through reservation, presigned PUT,
- * and completion. Text keeps a 16 KiB prefix. Binary media keeps digest metadata on its part.
- * Successful uploads are listed in `hue.blobs`; failures keep inline fallback or file metadata,
- * are reported as warnings, and are counted.
+ * and completion. Export hashes each value, writes its reference (text keeps a 16 KiB prefix,
+ * binary media digest metadata on its part) and its `hue.blobs` entry, and sends the record; the
+ * upload runs afterwards in the background, as Langfuse uploads media. A value refused when its
+ * record is exported keeps its inline fallback or file metadata; an upload that fails after export
+ * leaves its entry, which Hue reads as missing. Both are reported as warnings and counted.
  */
 /** The span attribute listing the values the SDK uploaded apart from the span: one compact JSON
  * object per value, `{"key", "sha256", "size", "content_type"}`, with an optional `name`. */
@@ -17,18 +19,28 @@ export declare const BLOB_PREFIX_BYTES: number;
 /** The entries one record's `hue.blobs` may list; Hue reads no more. */
 export declare const MAX_BLOB_ENTRIES = 64;
 /**
- * The values over the inline limit that queued spans may hold whole for upload at once, charged
- * apart from `maxQueueBytes` (a string as two bytes a code unit, bytes as themselves). A value
- * the budget cannot hold is cut when it is queued, as before uploads existed; a single value
- * larger than the whole budget is held while nothing else is.
+ * The values over the inline limit that queued records and unsettled uploads may hold whole at
+ * once, charged apart from `maxQueueBytes` (a string as two bytes a code unit, bytes as
+ * themselves): each is held until its record is exported and its upload settles. A value the
+ * budget cannot hold is cut when it is queued, as before uploads existed; a single value larger
+ * than the whole budget is held while nothing else is.
  */
 export declare const MAX_HELD_BLOB_BYTES: number;
-/** How long one export may spend uploading its values, on top of its requests. */
+/** The longest wait before an upload's next attempt, a `Retry-After` included. */
+export declare const MAX_RETRY_AFTER_MILLIS = 60000;
+/** How long one export may spend hashing its values: past it a value keeps its fallback. Also
+ * the import's least upload deadline, and part of an upload's lifetime. */
 export declare function uploadBudgetMillis(timeoutMillis: number): number;
+/** How long one upload may take from when its record's export queued it: six export timeouts for
+ * its requests and up to a minute of Retry-After of its own. */
+export declare function uploadLifetimeMillis(timeoutMillis: number): number;
 /** Why content kept its fallback instead of being uploaded. */
 export type FallbackReason = "unsupported" | "failed" | "tooLarge" | "budget";
 /** The fixed description of each fallback, as an export issue reports it. */
 export declare const FALLBACK_MESSAGES: Record<FallbackReason, string>;
+/** The fixed description of each failure of an upload that ran after its record was exported:
+ * the record lists the value under `hue.blobs`, and Hue reads it as missing. */
+export declare const LATE_FALLBACK_MESSAGES: Record<FallbackReason, string>;
 /** A span's own attribute value the redaction left whole for the upload step to place. */
 export interface OffloadCandidate {
     key: string;
@@ -84,6 +96,21 @@ export interface OffloadTally {
 }
 export declare function newTally(): OffloadTally;
 export declare function countFallback(tally: OffloadTally, reason: FallbackReason, traceId: string): void;
+/** Adds one tally's outcomes to another's. */
+export declare function mergeTally(into: OffloadTally, from: OffloadTally): void;
+/** Adds `from` to `into` once `settled` all settle. Built apart from the step that queued the
+ * uploads, so a pending upload keeps alive the two tallies alone, never that step's record. */
+export declare function mergeWhenSettled(into: OffloadTally, from: OffloadTally, settled: Promise<void>[]): Promise<void>;
+/** The uploads an export queued after placing its records, and what they came to once settled:
+ * each record's own are added when its placement returns. */
+export interface LateUploads {
+    tally: OffloadTally;
+    settled: Promise<void>[];
+    /** Told of each upload as it is queued: when it settles, how many of the bytes it charges its
+     * record holds too (none for bytes decoded or rewritten apart from the record), and when that
+     * charge is released. */
+    queued?(settled: Promise<void>, shared: number, released: Promise<void>): void;
+}
 /** A media type accepted by the upload contract. */
 export declare function isBlobContentType(value: unknown): value is string;
 /** The media type an uploaded text is stored under: JSON when it reads as a JSON object or array
@@ -106,8 +133,9 @@ export declare function digestOf(value: string | Uint8Array | ByteSource, deadli
 }>;
 /** The `hue.blobs` element for one uploaded value. */
 export declare function blobEntry(key: string, sha256: string, size: number, contentType: string, name?: string): string;
-/** What one export's uploads share: their deadline, and the export's hold for a receiver that
- * limited the rate (`wait` resolves false when the hold may not take `millis` more). */
+/** What an upload may spend: its deadline, and its wait before another attempt (`wait` resolves
+ * false when the wait was ended early or may not be taken). An export's own context bounds its
+ * hashing only. */
 export interface UploadContext {
     deadline: number;
     wait(millis: number): Promise<boolean>;
@@ -132,47 +160,93 @@ export interface UploaderOptions {
 }
 /**
  * Uploads values to Hue: reserves each with `POST /api/v1/otlp/blobs`, PUTs its bytes to the
- * presigned URL Hue answers (skipped when Hue already stores the value), and completes it. At
- * most {@link UPLOAD_CONCURRENCY} uploads run at once; every request has a deadline and none
- * follows a redirect. A receiver without the route (a 404 without Hue's JSON error, a 405 or
- * 501, or a 200 that is no reservation) is remembered for {@link UNSUPPORTED_PAUSE_MILLIS}, and a
- * transient failure or a refusal that is not about the value alone pauses uploads for
- * {@link FAILURE_PAUSE_MILLIS}, so values fall back to the inline cut instead of retrying.
+ * presigned URL Hue answers (skipped when Hue already stores the value), and completes it. An
+ * export queues its values ({@link enqueue}) and sends its records without waiting for them; the
+ * import stores each value before it sends its span ({@link store}). At most
+ * {@link UPLOAD_CONCURRENCY} uploads run at once, and {@link HASH_CONCURRENCY} hashes apart from
+ * them. A reservation or PUT that gets no answer, a 408, a 429 or a 5xx is tried
+ * {@link UPLOAD_ATTEMPTS} times; every request has a deadline and none follows a redirect. A
+ * receiver without the route (a 404 without Hue's JSON error, a 405 or 501, or a 200 that is no
+ * reservation) is remembered for {@link UNSUPPORTED_PAUSE_MILLIS}: values exported meanwhile keep
+ * their fallback, never an entry the receiver cannot resolve.
  */
 export declare class BlobUploader {
     private readonly options;
+    /** Until when the receiver is taken to lack the upload route. */
     private unsupportedUntil;
-    private pausedUntil;
     private closed;
-    private running;
-    private waiting;
+    private uploads;
+    private hashes;
+    private queued;
+    private queuedBytes;
+    /** What queued uploads keep alive, each charged once, from the first upload holding it until
+     * the last settles: two files read in place from one recorded string charge it once, whole. */
+    private holding;
+    private sleeps;
     private requests;
     private outcomes;
+    /** The first wait before another attempt, doubled each time; tests shorten it. */
+    private retryDelayMillis;
+    /** How long a queued upload may take; tests shorten it. */
+    private lifetimeMillis;
     constructor(options: UploaderOptions);
     /** Whether a value over the inline limit is worth holding whole for upload now. */
     available(): boolean;
     /** Whether the receiver lacks the upload route, as it last answered. */
     unsupported(): boolean;
-    /** Ends uploads in flight and refuses new ones: their values fall back to the inline cut. */
+    /** Ends uploads in flight, queued uploads and their waits, and refuses new ones: values not
+     * yet exported fall back to the inline cut, and uploads queued by exported records fail. */
     close(): void;
     /** Runs `work` once fewer than {@link UPLOAD_CONCURRENCY} uploads are in flight. */
     limit<R>(work: () => Promise<R>): Promise<R>;
+    /** The SHA-256 and size of `value` (see {@link digestOf}), hashed in a place of its own: an
+     * export never waits for an upload to hash its values. */
+    digest(value: string | Uint8Array | ByteSource, deadline: number): Promise<FileDigest>;
+    /** The bytes queued uploads keep alive until they settle. */
+    pendingBytes(): number;
     /** Why a value cannot be uploaded right now without trying, if it cannot. */
     refusal(): FallbackReason | undefined;
-    private pause;
+    /** Why the value cannot be uploaded at all, whatever Hue would answer. */
+    private invalid;
+    /**
+     * Queues `value`'s upload for an exported record, deciding now what the record lists: a value
+     * refused without trying (see {@link refusal}), invalid, or past the queue's
+     * {@link MAX_QUEUED_UPLOADS} uploads or {@link MAX_HELD_BLOB_BYTES} keeps its fallback. A queued
+     * upload runs within {@link uploadLifetimeMillis} of now, holding `value` until it settles;
+     * `done` never rejects. `bytes` is what it adds to {@link pendingBytes}: the strings it keeps
+     * alive that no other queued upload holds, charged until `released`, once the last upload
+     * holding them settles.
+     */
+    enqueue(traceId: string, key: string, value: string | Uint8Array | ByteSource, contentType: string, digest: FileDigest): {
+        ok: false;
+        reason: FallbackReason;
+    } | {
+        ok: true;
+        done: Promise<Outcome>;
+        bytes: number;
+        released: Promise<void>;
+    };
+    /** Waits `millis`; false when {@link close} ended the wait first. The timer keeps the process
+     * running, as an export in progress does, within the upload's lifetime. */
+    sleep(millis: number): Promise<boolean>;
+    /** Waits before attempt `attempt + 1`: `Retry-After` when the answer gave one, otherwise a
+     * second doubled each attempt with jitter, at most a minute. The upload's place is given up
+     * meanwhile, so uploads queued behind it run. False when the wait would pass the upload's
+     * deadline, was ended, or no place came free again before the deadline. */
+    private retryWait;
     /**
      * Stores `value` under `key` of the trace: reserved, uploaded unless Hue already holds it, and
      * completed. Only a fresh upload takes a {@link limit} slot: another reference to bytes the
      * trace is already storing shares that upload's outcome without one, so repeated files never
-     * hold the slots new files need. The caller must not hold a slot.
+     * hold the slots new files need. The caller must not hold a slot. Never rejects.
      */
     store(traceId: string, key: string, value: string | Uint8Array | ByteSource, contentType: string, digest: FileDigest, upload: UploadContext): Promise<Outcome>;
     private storeFresh;
     private jsonHeaders;
-    /** Reserves the value: Hue answers that it holds it already, or a presigned PUT. A rate limit
-     * is waited out within the export's hold, a transient refusal retried once. */
+    /** Reserves the value: Hue answers that it holds it already, or a presigned PUT. No answer, a
+     * 408, a 429 or a 5xx other than 501 is tried again, after its `Retry-After` when it gave one,
+     * within the upload's deadline. */
     private reserve;
-    private delay;
     /** A 200 answer read: `exists`, or an upload whose URL and headers are usable as given. */
     private reservation;
     /** The PUT of the value's bytes, with exactly the headers Hue signed. A source that no longer
@@ -187,34 +261,39 @@ export declare class BlobUploader {
      */
     private request;
 }
-/** Where one export's values are uploaded, and what it learned of them. */
+/** Where one record's values are uploaded, and what it learned of them. */
 export interface OffloadOptions {
     uploader: BlobUploader;
     traceId: string;
     /** The receiver's inline value limit. */
     valueBytes: number;
+    /** The deadline for hashing, and for a blocking store (no `background`) its uploads too. */
     upload: UploadContext;
     tally: OffloadTally;
     memo?: MediaDigestMemo;
     /** For tests: the length past which a long string is read in place (`LONG_STRING_UNITS`). */
     longUnits?: number;
+    /** Set by an export: values are placed as uploaded and their uploads queued, each counted in
+     * `background.tally` once it settles; `tally` counts the values refused when placed. Absent
+     * for the import, which stores each value, under the type Hue stores it as, before placing it. */
+    background?: LateUploads;
 }
 /**
  * A span's own attributes with each candidate placed: binary media becomes a digest, while
- * text media over 64 KiB retains a 16 KiB prefix after upload or a digest on failure.
- * A value still over the inline limit is uploaded and replaced by its first
- * 16 KiB (or cut to the limit), each upload listed under `hue.blobs`, each whole value cut or
+ * text media over 64 KiB retains a 16 KiB prefix once uploaded or queued, or a digest when
+ * refused. A value still over the inline limit is uploaded and replaced by its first 16 KiB (or
+ * cut to the limit when refused), each upload listed under `hue.blobs`, each whole value cut or
  * uploaded listed under `hue.truncated`. Every fallback is counted in the tally.
  */
 export declare function offloadAttributes(attributes: Record<string, unknown>, collector: OffloadCollector, options: OffloadOptions): Promise<Record<string, unknown>>;
 /**
  * A record's own attributes, and a log record's body, with each candidate placed (see
- * {@link offloadAttributes}). A file is uploaded and placed in its digest form (a text file in a
- * provider part keeps a 16 KiB prefix), its `hue.blobs` entry keyed `<attribute>#<pointer>` or, in
- * a log record's body, `body#<pointer>`. A file that is not uploaded keeps its bytes inline, except
- * in a span's own recorded messages, where it keeps its digest as before. A log record's values
- * over the inline limit are cut, never uploaded whole, and a body still over it is replaced by the
- * receiver's marker, as before.
+ * {@link offloadAttributes}). A file is uploaded (or, for an export, queued) and placed in its
+ * digest form (a text file in a provider part keeps a 16 KiB prefix), its `hue.blobs` entry keyed
+ * `<attribute>#<pointer>` or, in a log record's body, `body#<pointer>`. A file refused or not
+ * uploaded before it is placed keeps its bytes inline, except in a span's own recorded messages,
+ * where it keeps its digest as before. A log record's values over the inline limit are cut, never
+ * uploaded whole, and a body still over it is replaced by the receiver's marker, as before.
  */
 export declare function offloadRecord(attributes: Record<string, unknown>, collector: OffloadCollector, options: OffloadOptions): Promise<{
     attributes: Record<string, unknown>;