@teepin/sdk 0.2.0 → 0.3.0-rc.1

package/dist/types/direct/downloads-plan.d.ts

@@ -0,0 +1,75 @@
+import { TeepinError } from '../errors.js';
+import type { StorageObject } from '../storage.js';
+/** A download is written into its target's path with this added, and renamed into place only when whole. */
+export declare const PART_SUFFIX = ".teepin-part";
+/**
+ * saved; skipped (the file there already has the object's size and SHA-256, or the key is a folder marker); failed
+ * (final: not found, replaced while read, damaged, a key that isn't a safe path); or pending (stopped by a passing
+ * error, kept in the run's journal with its part file, so running the download again goes on from its written pieces).
+ */
+export type DownloadStatus = 'saved' | 'skipped' | 'failed' | 'pending';
+/** One object's result from downloadFiles or downloadPrefix. One object's failure never fails another. */
+export interface DownloadResult {
+    /** The object's key. */
+    key: string;
+    /** Where it was written (or would have been). */
+    path: string;
+    status: DownloadStatus;
+    /** The object, for saved and skipped (not for a folder marker). */
+    object?: StorageObject;
+    /** Why it failed or is pending. */
+    error?: unknown;
+    /** It went on from pieces an earlier run had written. */
+    resumed: boolean;
+}
+/** A key that can't be written under the destination: not a safe path, a link leading out, or another key's file. */
+export declare class UnsafePathError extends TeepinError {
+    constructor(message: string);
+}
+/**
+ * Why one part of a key's path can't be a file name ("" when it can). On Windows also: its forbidden characters, a
+ * device name with or without an extension, and a trailing dot or space, which Windows drops, so the file would land
+ * under another name than the key's.
+ */
+export declare function partProblem(part: string, windows: boolean): string;
+/** A key's path split into its parts, each checked by partProblem: UnsafePathError for the first that can't be a name. */
+export declare function keyParts(rel: string, windows: boolean): string[];
+/** A path as names that ignore case see it (NFC, then upper and lower case, so a sharp s and "SS" are one), or as it is. */
+export declare function fold(path: string, insensitive: boolean): string;
+/** One key of a plan: where it goes and, when that's decided before anything is signed, its result. */
+export interface PlanEntry {
+    key: string;
+    path: string;
+    /** A folder marker (skipped) or a key that isn't a safe path (failed); undefined for a key to download. */
+    result?: DownloadResult;
+}
+export interface Plan {
+    /** In the order the keys came, one per key (the same key twice is one). */
+    entries: PlanEntry[];
+    /** Keys that would land on a file an earlier key does: failed, after the rest. */
+    collisions: DownloadResult[];
+}
+/** What a plan needs from the file system. */
+export interface PlanPaths {
+    /** Whether Windows' rules on names apply. */
+    windows: boolean;
+    /** Whether names under the destination ignore case. */
+    insensitive: boolean;
+    /** The target of a key whose parts are names: UnsafePathError when it isn't under the destination (a link leads out). */
+    target(parts: string[], rel: string): Promise<string>;
+    /** Where a key that isn't downloaded is said to go (only shown in its result). */
+    shown(rel: string): string;
+}
+/**
+ * (key, relative path) pairs to the plan: folder markers skipped, keys that aren't safe paths failed, and a key whose
+ * file another key already takes failed.
+ */
+export declare function plan(pairs: Iterable<readonly [string, string]>, paths: PlanPaths): Promise<Plan>;
+/** Errors that stop a whole run: what's left stays pending, to run again (a revoked key, no credit). */
+export declare function stopsRun(err: unknown): boolean;
+/**
+ * An error after which an object's download is kept, to go on with later: one that stops the run, the network, a busy
+ * or failing service, or the local disk (full, say: any failed system call).
+ */
+export declare function passing(err: unknown): boolean;
+//# sourceMappingURL=downloads-plan.d.ts.map

package/dist/types/direct/downloads-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloads-plan.d.ts","sourceRoot":"","sources":["../../../src/direct/downloads-plan.ts"],"names":[],"mappings":"AAeA,OAAO,EAAmE,WAAW,EAAqB,MAAM,cAAc,CAAC;AAC/H,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,4GAA4G;AAC5G,eAAO,MAAM,WAAW,iBAAiB,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAExE,0GAA0G;AAC1G,MAAM,WAAW,cAAc;IAC7B,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,mEAAmE;IACnE,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,mCAAmC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yDAAyD;IACzD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qHAAqH;AACrH,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAOD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CASlE;AAED,0HAA0H;AAC1H,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,CAOhE;AAED,4HAA4H;AAC5H,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,CAE/D;AAED,uGAAuG;AACvG,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,2GAA2G;IAC3G,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,IAAI;IACnB,2EAA2E;IAC3E,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,kFAAkF;IAClF,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,8CAA8C;AAC9C,MAAM,WAAW,SAAS;IACxB,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,WAAW,EAAE,OAAO,CAAC;IACrB,yHAAyH;IACzH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,kFAAkF;IAClF,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCtG;AAED,wGAAwG;AACxG,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAE9C;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAI7C"}

package/dist/types/direct/engine.d.ts

@@ -0,0 +1,191 @@
+import { TooLargeError } from '../errors.js';
+/** A pack is closed at about this many bytes as stored (section 12.4): one of the storage network's efficient writes. */
+export declare const PACK_TARGET_BYTES: number;
+/** The most objects in one pack (the control plane's cap). */
+export declare const PACK_MAX_OBJECTS = 1000;
+/** Objects up to this size go into packs; larger ones are uploaded in parts. */
+export declare const PACK_OBJECT_LIMIT: number;
+/** Packs and parts in flight: where the adaptive limit starts, and its ceiling. */
+export declare const START_CONCURRENCY = 4;
+export declare const MAX_CONCURRENCY = 32;
+export declare const CONCURRENCY_ENV = "TEEPIN_UPLOAD_CONCURRENCY";
+/** How long an upload waits for an unavailable storage network or control plane, in ms (section 17.4). */
+export declare const DEFAULT_UPLOAD_WAIT_MS = 600000;
+export declare const UPLOAD_WAIT_ENV = "TEEPIN_UPLOAD_WAIT";
+/** A signature closer than this to its expiry is renewed before use, in ms. */
+export declare const SIGN_MARGIN_MS = 60000;
+/** How often a commit that answers "verifying" is asked again before the pack is sent again (section 19.13). */
+export declare const COMMIT_VERIFY_TRIES = 4;
+/** Times a pack's files are reserved again (conflict, bad bytes) before they fail. */
+export declare const MAX_REBUILDS = 3;
+/**
+ * A large object's parts (section 21.2): 16 MiB of plaintext by default, at least 5 MiB, a multiple of TWS1's 64 KiB
+ * segment, and at most 3,000 of them; each at most 5 GiB as stored.
+ */
+export declare const DEFAULT_PART_BYTES: number;
+export declare const MIN_PART_BYTES: number;
+export declare const MAX_DIRECT_PARTS = 3000;
+export declare const MAX_PART_STORED: number;
+/** A stream's part size when neither its size nor a part size is given: about 187 GiB at most, in 3,000 parts. */
+export declare const STREAM_PART_BYTES: number;
+/**
+ * A stream's parts in flight unless the caller says: each holds its ciphertext in memory, so with the reader's parts a
+ * stream holds at most about (STREAM_CONCURRENCY + 3) x its part size.
+ */
+export declare const STREAM_CONCURRENCY = 4;
+/** The part-size rules directPartSize and streamPartSize apply: an upload engine keeps its own copy (tests shrink it). */
+export interface PartRules {
+    /** A part's plaintext bytes unless asked for (DEFAULT_PART_BYTES). */
+    defaultBytes: number;
+    /** The fewest plaintext bytes a part may hold (MIN_PART_BYTES). */
+    minBytes: number;
+    /** The most parts an object may have (MAX_DIRECT_PARTS). */
+    maxParts: number;
+    /** A stream's part size with no hint (STREAM_PART_BYTES). */
+    streamBytes: number;
+}
+export declare const PART_RULES: Readonly<PartRules>;
+/**
+ * Slow links (section 22.7): one request to the storage network should take at most about this long (ms) at the
+ * measured speed. Packs, and the parts of uploads created from then on, shrink to fit it.
+ */
+export declare const REQUEST_MS = 240000;
+/** A pack's target never shrinks below one TWS1 segment (a pack still always holds at least one object). */
+export declare const PACK_MIN_TARGET: number;
+/** A PUT smaller than this isn't measured: its time is mostly the round trip, not the link. */
+export declare const SPEED_SAMPLE_BYTES: number;
+/** How far each measured PUT moves the estimate (an exponential moving average of bytes and of time). */
+export declare const SPEED_WEIGHT = 0.3;
+/** A measured speed, for the part-size rule: bytes per second, and how long (ms) one request may take. */
+export interface LinkSpeed {
+    bytesPerSecond: number;
+    ms: number;
+}
+/**
+ * The upload speed to the storage network, measured from completed PUTs (section 22.7): a moving estimate per client,
+ * of bytes over time, so a long transfer counts for more than a short one. Failed PUTs, and ones under
+ * minBytes, aren't measured. Until a PUT is measured, requestBytes is undefined and today's sizes hold. set (tests)
+ * fixes the speed; ms is the per-request budget.
+ */
+export declare class SpeedMeter {
+    ms: number;
+    /** The smallest PUT measured (SPEED_SAMPLE_BYTES; tests lower it). */
+    minBytes: number;
+    private bytes;
+    private time;
+    private fixed?;
+    /** A PUT of nbytes that succeeded in elapsedMs. */
+    observe(nbytes: number, elapsedMs: number): void;
+    private sample;
+    /**
+     * A PUT of nbytes that timed out on its own timer after elapsedMs, with no answer: evidence of a slow link (section
+     * 22.7). Taken as an upper bound, weighted like a completed PUT: at most nbytes over elapsedMs, and never above the
+     * speed measured so far, so it can only lower the estimate. nbytes is the request's size: fetch doesn't say how much
+     * of it was written.
+     */
+    observeTimeout(nbytes: number, elapsedMs: number): void;
+    /** Fixes the measured speed in bytes per second (tests); undefined goes back to measuring. */
+    set(bytesPerSecond: number | undefined): void;
+    /** Bytes per second, or undefined before anything is measured. */
+    get bytesPerSecond(): number | undefined;
+    /** The speed and budget for the part-size rule, or undefined before anything is measured. */
+    get link(): LinkSpeed | undefined;
+    /** The most bytes one request carries within ms at the measured speed; undefined before anything is measured. */
+    requestBytes(): number | undefined;
+}
+/** A pack's target size: target (9 MiB), or less when requestBytes (the measured speed's budget) is smaller, never below floor. */
+export declare function packTarget(requestBytes: number | undefined, target?: number, floor?: number): number;
+/**
+ * The largest object that goes into a pack; a larger one goes in parts. limit (16 MiB), or on a slow link (section 22.7)
+ * the bytes one request carries at the measured speed (requestBytes), but never under minPart: an object a pack request
+ * couldn't carry in time goes in parts, which the part rule sizes for the link.
+ */
+export declare function packObjectLimit(requestBytes: number | undefined, limit?: number, minPart?: number): number;
+export declare function formatSpeed(bytesPerSecond: number): string;
+/**
+ * TooLargeError with reason connection_speed: name (size bytes, 0 for a stream of unknown size) can't be sent at the
+ * measured speed. partCap is the largest part the speed allows.
+ */
+export declare function tooSlow(name: string, size: number, speed: LinkSpeed, partCap: number, rules?: Readonly<PartRules>): TooLargeError;
+/**
+ * The part size for a large object of size bytes when want (0 for the default) is asked for: at least MIN_PART_BYTES,
+ * rounded up to whole segments, doubled until the parts fit in MAX_DIRECT_PARTS.
+ *
+ * A slow link (section 22.7): with speed measured (undefined before anything is), a part carries at most speed.ms of
+ * it, rounded down to whole segments. When that cap is under the smallest part, or the parts can't fit in the most
+ * parts under it, TooLargeError with reason connection_speed, before anything is created or sent.
+ */
+export declare function directPartSize(size: number, want?: number, rules?: Readonly<PartRules>, speed?: LinkSpeed, name?: string): number;
+/**
+ * The part size for a stream whose size isn't known (section 22.1, E2 b). It fixes the largest stream: MAX_DIRECT_PARTS
+ * of it. expectedSize, a hint, chooses it as for a known size; with neither hint nor want, STREAM_PART_BYTES. A
+ * measured speed caps it as for a known size.
+ */
+export declare function streamPartSize(expectedSize?: number, want?: number, rules?: Readonly<PartRules>, speed?: LinkSpeed, name?: string): number;
+/** A positive number from the environment (Node only; browsers have none), else def. */
+export declare function envNumber(name: string, def: number): number;
+/** A pack's size: each object's needle and TWS1 bytes. */
+export declare function packedSize(sizes: readonly number[]): number;
+/**
+ * Packs for items, in order: each closes when the next item would take it past target bytes or maxObjects objects,
+ * and never holds one key twice (a second write to a key waits for the next pack, and writes to one key keep their
+ * order). An item bigger than target gets a pack of its own.
+ */
+export declare function planPacks<T>(items: readonly T[], sizeOf: (it: T) => number, keyOf: (it: T) => string, target?: number, maxObjects?: number): T[][];
+/**
+ * The first of planPacks's packs, and the items left for later ones: a planner that packs as it goes, so each pack
+ * takes the target the speed measured by then allows (section 22.7).
+ */
+export declare function nextPack<T>(items: readonly T[], sizeOf: (it: T) => number, keyOf: (it: T) => string, target?: number, maxObjects?: number): [pack: T[], rest: T[]];
+/** A slot's outcome when it is released: ok, throttled (or a timeout), or failed. */
+export type Outcome = 'ok' | 'throttled' | 'failed';
+/**
+ * How many packs or parts may be in flight (section 17.8): starts at 4, adds about one per round of successes, halves
+ * on a throttle or a timeout, and never passes its ceiling.
+ *
+ * priority is set while putObject calls wait for a slot: a run's acquire() then waits too, so a freed slot goes to them
+ * (tryAcquire) before the run's next pack, and a long run never makes a putObject wait for its end.
+ */
+export declare class AdaptiveLimit {
+    readonly ceiling: number;
+    limit: number;
+    inFlight: number;
+    priority: boolean;
+    private waiters;
+    constructor(start?: number, ceiling?: number);
+    private free;
+    /** A slot now, if one is free (putObject's dispatch, which priority doesn't hold back). */
+    tryAcquire(): boolean;
+    /** Waits for a slot that putObject's callers aren't waiting for. An abort ends the wait with the signal's reason. */
+    acquire(signal?: AbortSignal): Promise<void>;
+    setPriority(on: boolean): void;
+    release(outcome?: Outcome): void;
+    private wakeAll;
+}
+/** A token bucket that caps retries at about a tenth of requests, plus a burst, so an incident doesn't become a retry storm (section 17.6). */
+export declare class RetryBudget {
+    readonly ratio: number;
+    readonly burst: number;
+    tokens: number;
+    constructor(ratio?: number, burst?: number);
+    onRequest(): void;
+    tryRetry(): boolean;
+}
+/**
+ * The wait in ms before the next round when storage or the control plane is unavailable: from 5 s, doubling to 5
+ * minutes, with jitter; a server's Retry-After when it sent one (section 17.6).
+ */
+export declare function waitDelayMs(round: number, retryAfterMs?: number): number;
+/**
+ * sent: the bytes are there (200), or an earlier attempt put them there (412). resign: the signature was refused
+ * (expired, or another value): sign again. bad: refused as not the bytes signed (400 BadDigest). busy: wait and try
+ * again (429, 5xx). unsent: never sent, safe to send again at once. unknown: sent, but no answer came: commit first
+ * (section 17.1, rule 5). refused: anything else, a bug or an unsupported request, never retried in a loop.
+ */
+export type StorageOutcome = 'sent' | 'resign' | 'bad' | 'busy' | 'unsent' | 'unknown' | 'refused';
+/** What a PUT to the storage network ended in (undefined: success). */
+export declare function storageOutcome(err: unknown): StorageOutcome;
+export declare function isThrottle(err: unknown): boolean;
+/** A control-plane failure worth waiting out: the network, a busy or failing server (the client has already retried it). */
+export declare function isPassing(err: unknown): boolean;
+//# sourceMappingURL=engine.d.ts.map

package/dist/types/direct/engine.d.ts.map

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

package/dist/types/direct/formats.d.ts

@@ -0,0 +1,9 @@
+export declare const FORMAT_TWS1 = "tws1";
+export declare const FORMAT_SERVER = "teepin-v1";
+export declare const FORMAT_PLAIN = "plain";
+export declare const FORMATS: readonly string[];
+export declare const SOURCE_STORAGE = "storage";
+export declare const SOURCE_API = "api";
+/** A teepin-v1 object's plaintext, after its tag is checked; DataIntegrityError if it doesn't authenticate. */
+export declare function openServerV1(key: Uint8Array, stored: Uint8Array, associatedData: Uint8Array): Promise<Uint8Array>;
+//# sourceMappingURL=formats.d.ts.map

package/dist/types/direct/formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.d.ts","sourceRoot":"","sources":["../../../src/direct/formats.ts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,WAAW,SAAS,CAAC;AAClC,eAAO,MAAM,aAAa,cAAc,CAAC;AACzC,eAAO,MAAM,YAAY,UAAU,CAAC;AACpC,eAAO,MAAM,OAAO,EAAE,SAAS,MAAM,EAA+C,CAAC;AAErF,eAAO,MAAM,cAAc,YAAY,CAAC;AACxC,eAAO,MAAM,UAAU,QAAQ,CAAC;AAKhC,+GAA+G;AAC/G,wBAAsB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAUvH"}

package/dist/types/direct/hpke.d.ts

@@ -0,0 +1,55 @@
+import { TeepinError } from '../errors.js';
+/** The suite's name, as the control plane reports it with an account key. */
+export declare const SUITE = "x25519-hkdfsha256-aes128gcm";
+export declare const KEM_ID = 32;
+export declare const KDF_ID = 1;
+export declare const AEAD_ID = 1;
+export declare const PUBLIC_KEY_SIZE = 32;
+export declare const PRIVATE_KEY_SIZE = 32;
+export declare const ENC_SIZE = 32;
+export declare const DATA_KEY_SIZE = 32;
+export declare const WRAPPED_KEY_SIZE: number;
+/** A wrapped key that does not open for this account and object. */
+export declare class UnwrapError extends TeepinError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** info for an object's wrapped key: the label, then the account's and the object's 16-byte ids. */
+export declare function keyInfo(accountId: Uint8Array, objectId: Uint8Array): Uint8Array;
+/**
+ * A raw 32-byte X25519 private key as a non-extractable WebCrypto key, for deriveBits. WebCrypto has no raw import
+ * for private keys, so it goes in as PKCS #8.
+ */
+export declare function importPrivateKey(privateKey: Uint8Array): Promise<CryptoKey>;
+/** The raw public key that belongs to a raw 32-byte private key. */
+export declare function publicKeyOf(privateKey: Uint8Array): Promise<Uint8Array>;
+/** One seal's ephemeral key pair: the WebCrypto private key and the raw public key, which becomes enc. */
+export interface EphemeralKey {
+    privateKey: CryptoKey;
+    publicKey: Uint8Array;
+}
+/** A single-shot base-mode seal to publicKey: enc | ciphertext, under a fresh ephemeral key. */
+export declare function seal(publicKey: Uint8Array, info: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
+/**
+ * seal under a given ephemeral key: only the RFC's own vectors need it. An ephemeral key used twice with one
+ * recipient gives the same AES-GCM key and nonce twice, which gives away both plaintexts' XOR. So the SDK only ever
+ * calls seal, which makes a fresh one each time, and a test checks that nothing under src calls sealWith. It takes
+ * the key per call, never from shared state another module could change.
+ */
+export declare function sealWith(ephemeral: EphemeralKey, publicKey: Uint8Array, info: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
+/**
+ * Opens the seq-th message of a base-mode context set up by enc. A single-shot seal is message 0. UnwrapError if it
+ * doesn't open.
+ */
+export declare function openSealed(privateKey: Uint8Array, enc: Uint8Array, info: Uint8Array, ciphertext: Uint8Array, aad?: Uint8Array, seq?: number): Promise<Uint8Array>;
+/** A new X25519 key pair, raw 32 bytes each: for tests and the fake API. */
+export declare function generateKeyPair(): Promise<{
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+}>;
+/** An object's data key, wrapped to its account's public key: 80 bytes. */
+export declare function wrapKey(publicKey: Uint8Array, accountId: Uint8Array, objectId: Uint8Array, dataKey: Uint8Array): Promise<Uint8Array>;
+/** The data key inside wrapped, which must have been wrapped for this account and object; UnwrapError otherwise. */
+export declare function unwrapKey(privateKey: Uint8Array, accountId: Uint8Array, objectId: Uint8Array, wrapped: Uint8Array): Promise<Uint8Array>;
+//# sourceMappingURL=hpke.d.ts.map

package/dist/types/direct/hpke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hpke.d.ts","sourceRoot":"","sources":["../../../src/direct/hpke.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,6EAA6E;AAC7E,eAAO,MAAM,KAAK,gCAAgC,CAAC;AACnD,eAAO,MAAM,MAAM,KAAS,CAAC;AAC7B,eAAO,MAAM,MAAM,IAAS,CAAC;AAC7B,eAAO,MAAM,OAAO,IAAS,CAAC;AAC9B,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,QAAQ,KAAK,CAAC;AAC3B,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,eAAO,MAAM,gBAAgB,QAAgC,CAAC;AAiB9D,oEAAoE;AACpE,qBAAa,WAAY,SAAQ,WAAW;gBAC9B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAUD,oGAAoG;AACpG,wBAAgB,OAAO,CAAC,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,GAAG,UAAU,CAG/E;AAqED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAUjF;AAsBD,oEAAoE;AACpE,wBAAsB,WAAW,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAE7E;AAED,0GAA0G;AAC1G,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,SAAS,CAAC;IACtB,SAAS,EAAE,UAAU,CAAC;CACvB;AAUD,gGAAgG;AAChG,wBAAsB,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,GAAE,UAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CAEvI;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,UAAU,EACrB,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,UAAU,EACrB,GAAG,GAAE,UAAkB,GACtB,OAAO,CAAC,UAAU,CAAC,CAUrB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,UAAU,EACtB,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,UAAU,EACtB,GAAG,GAAE,UAAkB,EACvB,GAAG,SAAI,GACN,OAAO,CAAC,UAAU,CAAC,CAarB;AAED,4EAA4E;AAC5E,wBAAsB,eAAe,IAAI,OAAO,CAAC;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,UAAU,CAAA;CAAE,CAAC,CAalG;AAID,2EAA2E;AAC3E,wBAAsB,OAAO,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAK1I;AAED,oHAAoH;AACpH,wBAAsB,SAAS,CAAC,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAQ7I"}

package/dist/types/direct/journal.d.ts

@@ -0,0 +1,55 @@
+/** What a journal holds: a run's own row, and its files, packs and large uploads (and their parts). */
+export type Table = 'run' | 'files' | 'packs' | 'uploads' | 'parts';
+/** One row: plain JSON values, so a file journal can write it as it is. */
+export type Row = Record<string, unknown>;
+/** One write in a batch: a row put (replacing any row with its id), or removed. */
+export type Entry = {
+    table: Table;
+    id: string;
+    row: Row;
+} | {
+    table: Table;
+    id: string;
+    remove: true;
+};
+/** A run's journal. Writes resolve once they are durable; a batch is written whole or not at all. */
+export interface Journal {
+    /** Whether the journal survives the process (a resumable run). */
+    readonly durable: boolean;
+    /** Puts row (replacing any row with its id), durably. */
+    put(table: Table, id: string, row: Row): Promise<void>;
+    /** Writes entries together: after a crash, all of them are there or none. */
+    write(entries: readonly Entry[]): Promise<void>;
+    /** A row by id, as last put. */
+    get(table: Table, id: string): Row | undefined;
+    /** Every row of a table, in the order their ids were first put. */
+    rows(table: Table): Row[];
+    /** A fresh id for a row of table, unique in this journal (the files of a run are numbered in order). */
+    nextId(table: Table): string;
+    close(): Promise<void>;
+}
+/** Rows as a journal keeps them in memory: the shared core of every journal. */
+export declare class Rows {
+    private readonly tables;
+    private readonly counters;
+    apply(entry: Entry): void;
+    get(table: Table, id: string): Row | undefined;
+    rows(table: Table): Row[];
+    nextId(table: Table): string;
+    /** Every row, as entries: what a file journal writes when it compacts. */
+    entries(): Entry[];
+}
+/** A run journaled in memory: not resumable after the process ends (browsers, and journal: false). */
+export declare class MemoryJournal implements Journal {
+    readonly durable = false;
+    private readonly data;
+    private closed;
+    put(table: Table, id: string, row: Row): Promise<void>;
+    write(entries: readonly Entry[]): Promise<void>;
+    get(table: Table, id: string): Row | undefined;
+    rows(table: Table): Row[];
+    nextId(table: Table): string;
+    close(): Promise<void>;
+    private check;
+}
+//# sourceMappingURL=journal.d.ts.map

package/dist/types/direct/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../../src/direct/journal.ts"],"names":[],"mappings":"AAQA,uGAAuG;AACvG,MAAM,MAAM,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpE,2EAA2E;AAC3E,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C,mFAAmF;AACnF,MAAM,MAAM,KAAK,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,GAAG,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC;AAExG,qGAAqG;AACrG,MAAM,WAAW,OAAO;IACtB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,6EAA6E;IAC7E,KAAK,CAAC,OAAO,EAAE,SAAS,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,gCAAgC;IAChC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC;IAC/C,mEAAmE;IACnE,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,GAAG,EAAE,CAAC;IAC1B,wGAAwG;IACxG,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;IAC7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,gFAAgF;AAChF,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAgBzB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS;IAK9C,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,GAAG,EAAE;IAIzB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAM5B,0EAA0E;IAC1E,OAAO,IAAI,KAAK,EAAE;CAKnB;AAED,sGAAsG;AACtG,qBAAa,aAAc,YAAW,OAAO;IAC3C,QAAQ,CAAC,OAAO,SAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,MAAM,CAAS;IAEjB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtD,KAAK,CAAC,OAAO,EAAE,SAAS,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS;IAI9C,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,GAAG,EAAE;IAIzB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAItB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,OAAO,CAAC,KAAK;CAGd"}

package/dist/types/direct/large.d.ts

@@ -0,0 +1,170 @@
+import type { StorageObject } from '../storage.js';
+import { type Json, type Progress, type Waits } from './common.js';
+import { type LinkSpeed } from './engine.js';
+import * as tws1 from './tws1.js';
+import type { DirectUploads, RunStore } from './uploads.js';
+/** Data that can be read at any offset: what a large upload sends parts from. */
+export interface PartSource {
+    size: number;
+    readAt(offset: number, length: number): Promise<Uint8Array>;
+    /** In one pass, the whole SHA-256 and each part's, where the source has a faster way than the default. */
+    hashParts?(partSize: number): Promise<{
+        whole: string;
+        parts: Map<number, string>;
+    }>;
+}
+/** A stream read a piece at a time: up to max bytes (fewer is fine), empty at its end. */
+export interface StreamSource {
+    pull(max: number, signal?: AbortSignal): Promise<Uint8Array>;
+    /** Lets go of the source, cancelling it if it wasn't read to its end. */
+    release(reason?: unknown): Promise<void>;
+}
+/** The upload can't go on: start again under a new create, with a fresh key. */
+export declare class Restart extends Error {
+    constructor(why: string);
+}
+export interface LargeOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+    ifNoneMatch?: boolean;
+    ifMatch?: string;
+    partSize: number;
+    /** The run's store, when it has one (its journal, and its directory for the data key). */
+    store?: RunStore;
+    fileId?: string;
+    path?: string;
+    partHashes?: Map<number, string>;
+}
+/** One large upload's state, journaled when it has a store. The methods tests replace are save and savePart. */
+export declare class Large implements Waits {
+    readonly bucket: string;
+    readonly key: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly readAt: (offset: number, length: number) => Promise<Uint8Array>;
+    id: string;
+    idem: string;
+    uploadId: string;
+    state: 'new' | 'sending' | 'completing' | 'completed' | 'failed';
+    dek?: Uint8Array;
+    header: Uint8Array;
+    stream?: tws1.Stream;
+    wrapped: string;
+    keyVersion: number;
+    /** Part number → its plaintext's SHA-256 (D1 a), taken in the same pass as the whole object's. */
+    plain: Map<number, string>;
+    resumed: boolean;
+    restarts: number;
+    waited: number;
+    throttled: boolean;
+    lastError: string;
+    readonly contentType: string;
+    readonly metadata: Record<string, string>;
+    readonly ifNoneMatch: boolean;
+    readonly ifMatch: string;
+    readonly partSize: number;
+    readonly partCount: number;
+    readonly store?: RunStore;
+    readonly fileId?: string;
+    readonly path?: string;
+    /** Whether the data key's file is written (and so must be deleted). */
+    private keyOnDisk;
+    constructor(bucket: string, key: string, size: number, sha256: string, readAt: (offset: number, length: number) => Promise<Uint8Array>, opts: LargeOptions);
+    /** Whether its journal survives the process (a resumable upload). */
+    get durable(): boolean;
+    private row;
+    private partRow;
+    /** The upload's state, journaled (with its data key first, on disk, while it has one). */
+    save(): Promise<void>;
+    savePart(number: number, plain: string, md5?: string, sha256?: string, state?: string): Promise<void>;
+    /** D1 (a): every part's hash before any byte leaves; then the data key, header and wrap, before any part is signed. */
+    saveCreated(): Promise<void>;
+    private saveKey;
+    /** Zeroes the data key and deletes its file (E3: promptly). */
+    forgetKey(): Promise<void>;
+    /** An upload a crashed run left in its journal. */
+    static fromRow(row: Json, readAt: (offset: number, length: number) => Promise<Uint8Array>, opts: Omit<LargeOptions, 'partSize' | 'partHashes'>): Promise<Large>;
+    /** A new create and a fresh key. The source's part hashes stay: they still catch a file that changed. */
+    reset(): Promise<void>;
+}
+/**
+ * A stream's upload: created without its size, its last part declared at its sign, and its size and SHA-256 brought by
+ * complete. Held in memory only: nothing could read the stream again to resume it.
+ */
+export declare class StreamUpload implements Waits {
+    readonly bucket: string;
+    readonly key: string;
+    readonly partSize: number;
+    readonly idem: string;
+    uploadId: string;
+    stream?: tws1.OpenStream;
+    wrapped: string;
+    keyVersion: number;
+    readonly path?: string;
+    /** The measured speed when it shrank the part size (section 22.7), else undefined. */
+    slow?: LinkSpeed;
+    waited: number;
+    throttled: boolean;
+    lastError: string;
+    readonly contentType: string;
+    readonly metadata: Record<string, string>;
+    readonly ifNoneMatch: boolean;
+    readonly ifMatch: string;
+    constructor(bucket: string, key: string, partSize: number, opts?: {
+        contentType?: string;
+        metadata?: Record<string, string>;
+        ifNoneMatch?: boolean;
+        ifMatch?: string;
+    });
+}
+type Upload = Large | StreamUpload;
+/** Large uploads and streams for one DirectUploads. The methods tests replace are sendSealed and completeStream. */
+export declare class Parts {
+    readonly up: DirectUploads;
+    constructor(up: DirectUploads);
+    /**
+     * Takes a large upload to its object. A final failure cancels it; an error after which it may resume (storage
+     * unavailable, a revoked key) keeps it, in its journal, when it has one on disk. An abort leaves a journaled upload
+     * for resumeUploads, and cancels one in memory, which nothing could resume.
+     */
+    run(u: Large, prog?: Progress, signal?: AbortSignal): Promise<StorageObject>;
+    /** Cancels the upload at the storage network: one call, best effort, never the control plane's rounds of waiting. */
+    abort(u: Upload, stopping?: boolean): Promise<void>;
+    private attempt;
+    private create;
+    private sendParts;
+    /**
+     * Part n's plaintext, read and hashed: journaled before its first byte leaves (D1 a), and the same as journaled on
+     * every later read (D1 b).
+     */
+    checkSource(u: Large, n: number): Promise<Uint8Array>;
+    private sign;
+    private sendPart;
+    /** Signs part n and sends it until storage holds it as signed; recheck reads the source again when storage holds other bytes. Replaced in tests. */
+    sendSealed(u: Upload, n: number, sealed: Uint8Array, md5: string, sha: string, extra: Json | undefined, recheck: (() => Promise<unknown>) | undefined, signal?: AbortSignal): Promise<void>;
+    private complete;
+    /**
+     * Uploads everything source yields, sealing and sending up to concurrency parts at once. Any failure, or an abort,
+     * cancels the upload (one call): a stream can't be read again.
+     */
+    runStream(s: StreamUpload, source: StreamSource, concurrency: number, prog?: Progress, signal?: AbortSignal): Promise<StorageObject>;
+    private streamAttempt;
+    private createStream;
+    /** Completes a stream's upload with the size and SHA-256 read. Replaced in tests. */
+    completeStream(s: StreamUpload, size: number, sha256: string, signal?: AbortSignal): Promise<StorageObject>;
+}
+/** Whether body is a stream (a ReadableStream or an async iterable) rather than data that can be read at any offset. */
+export declare function isStreamBody(body: unknown): body is ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+/** A ReadableStream or an async iterable, read a piece at a time: no piece is copied before it is taken. */
+export declare function streamSource(body: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>): StreamSource;
+/**
+ * head (what was read first, to choose the way), then the rest of inner. head is handed on and dropped as soon as its
+ * bytes are taken, not held for the upload.
+ */
+export declare function prefixed(head: Uint8Array, inner: StreamSource): StreamSource & {
+    readonly holding: boolean;
+};
+/** Up to n bytes from source, into one buffer (shorter only at the source's end). */
+export declare function readUpTo(source: StreamSource, n: number, signal?: AbortSignal): Promise<Uint8Array>;
+export {};
+//# sourceMappingURL=large.d.ts.map

package/dist/types/direct/large.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"large.d.ts","sourceRoot":"","sources":["../../../src/direct/large.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAqE,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AACtI,OAAO,EAAyC,KAAK,SAAS,EAAgB,MAAM,aAAa,CAAC;AAElG,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAQ5D,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5D,0GAA0G;IAC1G,SAAS,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC,CAAC;CACtF;AAED,0FAA0F;AAC1F,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7D,yEAAyE;IACzE,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED,gFAAgF;AAChF,qBAAa,OAAQ,SAAQ,KAAK;gBACpB,GAAG,EAAE,MAAM;CAIxB;AAOD,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,gHAAgH;AAChH,qBAAa,KAAM,YAAW,KAAK;IA8B/B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC;IAjC1E,EAAE,SAAW;IACb,IAAI,SAAW;IACf,QAAQ,SAAM;IACd,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAS;IACzE,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,UAAU,CAAS;IAC3B,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC;IACrB,OAAO,SAAM;IACb,UAAU,SAAK;IACf,kGAAkG;IAClG,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,OAAO,UAAS;IAChB,QAAQ,SAAK;IACb,MAAM,SAAK;IACX,SAAS,UAAS;IAClB,SAAS,SAAM;IACf,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,OAAO,CAAC,SAAS,CAAS;gBAGf,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,EACxE,IAAI,EAAE,YAAY;IAcpB,qEAAqE;IACrE,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,OAAO,CAAC,GAAG;IAwBX,OAAO,CAAC,OAAO;IAKf,0FAA0F;IACpF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAMrB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAK,EAAE,MAAM,SAAK,EAAE,KAAK,SAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrG,uHAAuH;IACjH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;YAOpB,OAAO;IAOrB,+DAA+D;IACzD,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAWhC,mDAAmD;WACtC,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,YAAY,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;IAmBrK,yGAAyG;IACnG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAU7B;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,KAAK;IAkBtC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAnB3B,QAAQ,CAAC,IAAI,SAAW;IACxB,QAAQ,SAAM;IACd,MAAM,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC;IACzB,OAAO,SAAM;IACb,UAAU,SAAK;IACf,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAa;IACnC,sFAAsF;IACtF,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,MAAM,SAAK;IACX,SAAS,UAAS;IAClB,SAAS,SAAM;IACf,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAGd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EACzB,IAAI,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO;CAOlH;AAED,KAAK,MAAM,GAAG,KAAK,GAAG,YAAY,CAAC;AAYnC,oHAAoH;AACpH,qBAAa,KAAK;IACJ,QAAQ,CAAC,EAAE,EAAE,aAAa;gBAAjB,EAAE,EAAE,aAAa;IAEtC;;;;OAIG;IACG,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAwClF,qHAAqH;IAC/G,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;YAIzC,OAAO;YAcP,MAAM;YAiCN,SAAS;IAmDvB;;;OAGG;IACG,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;YAoB7C,IAAI;YAWJ,QAAQ;IAWtB,oJAAoJ;IAC9I,UAAU,CACd,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,IAAI,GAAG,SAAS,EACvB,OAAO,EAAE,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,EAC7C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC;YA+CF,QAAQ;IAoBtB;;;OAGG;IACG,SAAS,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;YAmB5H,aAAa;YA4Fb,YAAY;IAwB1B,qFAAqF;IAC/E,cAAc,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;CAuBlH;AAID,wHAAwH;AACxH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,cAAc,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,CAG1G;AAED,4GAA4G;AAC5G,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GAAG,YAAY,CA+CvG;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,GAAG,YAAY,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAmB5G;AAED,qFAAqF;AACrF,wBAAsB,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAUzG"}