@teepin/sdk 0.2.1 → 0.3.0

package/dist/cjs/direct/downloads-plan.js.map

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

package/dist/cjs/direct/engine.js

@@ -0,0 +1,405 @@
+"use strict";
+// Copyright 2026 TEEPIN Project
+// Licensed under the Apache License, Version 2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPassing = exports.isThrottle = exports.storageOutcome = exports.waitDelayMs = exports.RetryBudget = exports.AdaptiveLimit = exports.nextPack = exports.planPacks = exports.packedSize = exports.envNumber = exports.streamPartSize = exports.directPartSize = exports.tooSlow = exports.formatSpeed = exports.packObjectLimit = exports.packTarget = exports.SpeedMeter = exports.SPEED_WEIGHT = exports.SPEED_SAMPLE_BYTES = exports.PACK_MIN_TARGET = exports.REQUEST_MS = exports.PART_RULES = exports.STREAM_CONCURRENCY = exports.STREAM_PART_BYTES = exports.MAX_PART_STORED = exports.MAX_DIRECT_PARTS = exports.MIN_PART_BYTES = exports.DEFAULT_PART_BYTES = exports.MAX_REBUILDS = exports.COMMIT_VERIFY_TRIES = exports.SIGN_MARGIN_MS = exports.UPLOAD_WAIT_ENV = exports.DEFAULT_UPLOAD_WAIT_MS = exports.CONCURRENCY_ENV = exports.MAX_CONCURRENCY = exports.START_CONCURRENCY = exports.PACK_OBJECT_LIMIT = exports.PACK_MAX_OBJECTS = exports.PACK_TARGET_BYTES = void 0;
+// The rules of direct uploads that don't depend on how bytes are sent (TEEPIN-STORAGE-DESIGN.md sections 17, 22 and
+// 24): what goes into a pack, how many requests may be in flight, when to retry, and what a storage network's answer
+// means. The same rules as the Python SDK's _engine.py, so the two can't drift apart in behaviour.
+const client_js_1 = require("../client.js");
+const errors_js_1 = require("../errors.js");
+const tws1_js_1 = require("./tws1.js");
+/** A pack is closed at about this many bytes as stored (section 12.4): one of the storage network's efficient writes. */
+exports.PACK_TARGET_BYTES = 9 * 2 ** 20;
+/** The most objects in one pack (the control plane's cap). */
+exports.PACK_MAX_OBJECTS = 1000;
+/** Objects up to this size go into packs; larger ones are uploaded in parts. */
+exports.PACK_OBJECT_LIMIT = 16 * 2 ** 20;
+/** Packs and parts in flight: where the adaptive limit starts, and its ceiling. */
+exports.START_CONCURRENCY = 4;
+exports.MAX_CONCURRENCY = 32;
+exports.CONCURRENCY_ENV = 'TEEPIN_UPLOAD_CONCURRENCY';
+/** How long an upload waits for an unavailable storage network or control plane, in ms (section 17.4). */
+exports.DEFAULT_UPLOAD_WAIT_MS = 600000;
+exports.UPLOAD_WAIT_ENV = 'TEEPIN_UPLOAD_WAIT';
+/** A signature closer than this to its expiry is renewed before use, in ms. */
+exports.SIGN_MARGIN_MS = 60000;
+/** How often a commit that answers "verifying" is asked again before the pack is sent again (section 19.13). */
+exports.COMMIT_VERIFY_TRIES = 4;
+/** Times a pack's files are reserved again (conflict, bad bytes) before they fail. */
+exports.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.
+ */
+exports.DEFAULT_PART_BYTES = 16 * 2 ** 20;
+exports.MIN_PART_BYTES = 5 * 2 ** 20;
+exports.MAX_DIRECT_PARTS = 3000;
+exports.MAX_PART_STORED = 5 * 2 ** 30;
+/** A stream's part size when neither its size nor a part size is given: about 187 GiB at most, in 3,000 parts. */
+exports.STREAM_PART_BYTES = 64 * 2 ** 20;
+/**
+ * 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.
+ */
+exports.STREAM_CONCURRENCY = 4;
+exports.PART_RULES = Object.freeze({
+    defaultBytes: exports.DEFAULT_PART_BYTES,
+    minBytes: exports.MIN_PART_BYTES,
+    maxParts: exports.MAX_DIRECT_PARTS,
+    streamBytes: exports.STREAM_PART_BYTES,
+});
+/**
+ * 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.
+ */
+exports.REQUEST_MS = 240000;
+/** A pack's target never shrinks below one TWS1 segment (a pack still always holds at least one object). */
+exports.PACK_MIN_TARGET = tws1_js_1.SEGMENT_SIZE;
+/** A PUT smaller than this isn't measured: its time is mostly the round trip, not the link. */
+exports.SPEED_SAMPLE_BYTES = 256 * 2 ** 10;
+/** How far each measured PUT moves the estimate (an exponential moving average of bytes and of time). */
+exports.SPEED_WEIGHT = 0.3;
+/**
+ * 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.
+ */
+class SpeedMeter {
+    ms = exports.REQUEST_MS;
+    /** The smallest PUT measured (SPEED_SAMPLE_BYTES; tests lower it). */
+    minBytes = exports.SPEED_SAMPLE_BYTES;
+    bytes = 0;
+    time = 0;
+    fixed;
+    /** A PUT of nbytes that succeeded in elapsedMs. */
+    observe(nbytes, elapsedMs) {
+        if (nbytes < this.minBytes || !(elapsedMs > 0))
+            return;
+        this.sample(nbytes, elapsedMs);
+    }
+    sample(nbytes, elapsedMs) {
+        if (this.time <= 0) {
+            this.bytes = nbytes;
+            this.time = elapsedMs;
+        }
+        else {
+            this.bytes += exports.SPEED_WEIGHT * (nbytes - this.bytes);
+            this.time += exports.SPEED_WEIGHT * (elapsedMs - this.time);
+        }
+    }
+    /**
+     * 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, elapsedMs) {
+        if (nbytes < this.minBytes || !(elapsedMs > 0))
+            return;
+        const measured = this.time > 0 ? this.bytes / this.time : undefined; // bytes per ms
+        this.sample(measured === undefined ? nbytes : Math.min(nbytes, measured * elapsedMs), elapsedMs);
+    }
+    /** Fixes the measured speed in bytes per second (tests); undefined goes back to measuring. */
+    set(bytesPerSecond) {
+        this.fixed = bytesPerSecond;
+    }
+    /** Bytes per second, or undefined before anything is measured. */
+    get bytesPerSecond() {
+        if (this.fixed !== undefined)
+            return this.fixed;
+        return this.time > 0 ? (this.bytes / this.time) * 1000 : undefined;
+    }
+    /** The speed and budget for the part-size rule, or undefined before anything is measured. */
+    get link() {
+        const bps = this.bytesPerSecond;
+        return bps === undefined ? undefined : { bytesPerSecond: bps, ms: this.ms };
+    }
+    /** The most bytes one request carries within ms at the measured speed; undefined before anything is measured. */
+    requestBytes() {
+        const bps = this.bytesPerSecond;
+        return bps === undefined ? undefined : Math.floor((bps * this.ms) / 1000);
+    }
+}
+exports.SpeedMeter = SpeedMeter;
+/** A pack's target size: target (9 MiB), or less when requestBytes (the measured speed's budget) is smaller, never below floor. */
+function packTarget(requestBytes, target = exports.PACK_TARGET_BYTES, floor = exports.PACK_MIN_TARGET) {
+    if (requestBytes === undefined)
+        return target;
+    return Math.max(floor, Math.min(target, requestBytes));
+}
+exports.packTarget = packTarget;
+/**
+ * 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.
+ */
+function packObjectLimit(requestBytes, limit = exports.PACK_OBJECT_LIMIT, minPart = exports.MIN_PART_BYTES) {
+    if (requestBytes === undefined)
+        return limit;
+    return Math.min(limit, Math.max(requestBytes, minPart));
+}
+exports.packObjectLimit = packObjectLimit;
+function formatSpeed(bytesPerSecond) {
+    if (bytesPerSecond >= 2 ** 20)
+        return `${(bytesPerSecond / 2 ** 20).toFixed(1)} MiB/s`;
+    return `${(bytesPerSecond / 2 ** 10).toFixed(1)} KiB/s`;
+}
+exports.formatSpeed = formatSpeed;
+const mib = (n) => `${Number((n / 2 ** 20).toFixed(4))} MiB`;
+/**
+ * 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.
+ */
+function tooSlow(name, size, speed, partCap, rules = exports.PART_RULES) {
+    const why = partCap < rules.minBytes
+        ? `even a ${mib(rules.minBytes)} part would take over ${Number((speed.ms / 60000).toFixed(2))} minutes to send`
+        : `parts can be at most ${mib(partCap)}, and it would need more than ${rules.maxParts.toLocaleString('en-US')} of them`;
+    const what = size > 0 ? `${size} bytes` : 'this stream';
+    return new errors_js_1.TooLargeError({
+        statusCode: 413,
+        message: `${name || 'the upload'}: the connection to storage measured ${formatSpeed(speed.bytesPerSecond)}; at that speed ${why}, so ${what} is too large to send over this connection`,
+        code: 'connection_speed',
+        reason: 'connection_speed',
+    });
+}
+exports.tooSlow = tooSlow;
+/**
+ * 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.
+ */
+function directPartSize(size, want = 0, rules = exports.PART_RULES, speed, name = '') {
+    return partSize(size, size, want, rules, speed, name);
+}
+exports.directPartSize = directPartSize;
+function partSize(size, declared, want, rules, speed, name) {
+    let p = Math.max(want > 0 ? want : rules.defaultBytes, rules.minBytes);
+    p = Math.ceil(p / tws1_js_1.SEGMENT_SIZE) * tws1_js_1.SEGMENT_SIZE;
+    let cap = 0;
+    if (speed) {
+        cap = Math.floor(Math.floor((speed.bytesPerSecond * speed.ms) / 1000) / tws1_js_1.SEGMENT_SIZE) * tws1_js_1.SEGMENT_SIZE;
+        if (cap < rules.minBytes)
+            throw tooSlow(name, declared, speed, cap, rules);
+        p = Math.min(p, cap);
+    }
+    while (Math.ceil(size / p) > rules.maxParts)
+        p *= 2;
+    if (speed && p > cap) {
+        // Doubling passed the cap: the smallest whole-segment size that fits, if the cap allows it (over the size before
+        // doubling, so over the smallest part).
+        const fit = Math.ceil(Math.ceil(size / rules.maxParts) / tws1_js_1.SEGMENT_SIZE) * tws1_js_1.SEGMENT_SIZE;
+        if (fit > cap)
+            throw tooSlow(name, declared, speed, cap, rules);
+        p = fit;
+    }
+    if ((0, tws1_js_1.partOf)(size, p, 1).storedSize > exports.MAX_PART_STORED) {
+        throw new errors_js_1.TeepinError(`${size} bytes needs parts over ${exports.MAX_PART_STORED} bytes; it is too large to upload`);
+    }
+    return p;
+}
+/**
+ * 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.
+ */
+function streamPartSize(expectedSize = 0, want = 0, rules = exports.PART_RULES, speed, name = '') {
+    if (expectedSize > 0)
+        return partSize(expectedSize, expectedSize, want, rules, speed, name);
+    return partSize(1, 0, want > 0 ? want : rules.streamBytes, rules, speed, name);
+}
+exports.streamPartSize = streamPartSize;
+/** A positive number from the environment (Node only; browsers have none), else def. */
+function envNumber(name, def) {
+    const env = globalThis.process?.env;
+    const v = Number(env?.[name] ?? '');
+    return Number.isFinite(v) && v > 0 ? v : def;
+}
+exports.envNumber = envNumber;
+/** A pack's size: each object's needle and TWS1 bytes. */
+function packedSize(sizes) {
+    return sizes.reduce((n, s) => n + tws1_js_1.NEEDLE_HEADER_SIZE + (0, tws1_js_1.storedSize)(s), 0);
+}
+exports.packedSize = packedSize;
+/**
+ * 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.
+ */
+function planPacks(items, sizeOf, keyOf, target = exports.PACK_TARGET_BYTES, maxObjects = exports.PACK_MAX_OBJECTS) {
+    const packs = [];
+    let pending = items;
+    while (pending.length) {
+        const [pack, rest] = nextPack(pending, sizeOf, keyOf, target, maxObjects);
+        packs.push(pack);
+        pending = rest;
+    }
+    return packs;
+}
+exports.planPacks = planPacks;
+/**
+ * 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).
+ */
+function nextPack(items, sizeOf, keyOf, target = exports.PACK_TARGET_BYTES, maxObjects = exports.PACK_MAX_OBJECTS) {
+    const pack = [];
+    const keys = new Set();
+    const waiting = new Set(); // keys of items left for a later pack, in this pass
+    let size = 0;
+    const rest = [];
+    for (const it of items) {
+        const n = tws1_js_1.NEEDLE_HEADER_SIZE + (0, tws1_js_1.storedSize)(sizeOf(it));
+        const k = keyOf(it);
+        const fits = !pack.length || (size + n <= target && pack.length < maxObjects);
+        if (fits && !keys.has(k) && !waiting.has(k)) {
+            pack.push(it);
+            keys.add(k);
+            size += n;
+        }
+        else {
+            rest.push(it);
+            waiting.add(k);
+        }
+    }
+    return [pack, rest];
+}
+exports.nextPack = nextPack;
+/**
+ * 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.
+ */
+class AdaptiveLimit {
+    ceiling;
+    limit;
+    inFlight = 0;
+    priority = false;
+    waiters = [];
+    constructor(start = exports.START_CONCURRENCY, ceiling = exports.MAX_CONCURRENCY) {
+        this.ceiling = Math.max(1, ceiling);
+        this.limit = Math.min(Math.max(1, start), this.ceiling);
+    }
+    free() {
+        return this.inFlight < Math.floor(this.limit);
+    }
+    /** A slot now, if one is free (putObject's dispatch, which priority doesn't hold back). */
+    tryAcquire() {
+        if (!this.free())
+            return false;
+        this.inFlight++;
+        return true;
+    }
+    /** Waits for a slot that putObject's callers aren't waiting for. An abort ends the wait with the signal's reason. */
+    async acquire(signal) {
+        for (;;) {
+            signal?.throwIfAborted();
+            if (this.free() && !this.priority) {
+                this.inFlight++;
+                return;
+            }
+            await new Promise((resolve, reject) => {
+                const wake = () => {
+                    signal?.removeEventListener('abort', onAbort);
+                    resolve();
+                };
+                const onAbort = () => {
+                    this.waiters = this.waiters.filter((w) => w !== wake);
+                    reject(signal?.reason);
+                };
+                this.waiters.push(wake);
+                signal?.addEventListener('abort', onAbort, { once: true });
+            });
+        }
+    }
+    setPriority(on) {
+        const changed = this.priority !== on;
+        this.priority = on;
+        if (changed && !on)
+            this.wakeAll();
+    }
+    release(outcome = 'ok') {
+        this.inFlight = Math.max(0, this.inFlight - 1);
+        if (outcome === 'ok')
+            this.limit = Math.min(this.ceiling, this.limit + 1 / this.limit);
+        else if (outcome === 'throttled')
+            this.limit = Math.max(1, this.limit / 2);
+        this.wakeAll();
+    }
+    wakeAll() {
+        const woken = this.waiters;
+        this.waiters = [];
+        for (const w of woken)
+            w();
+    }
+}
+exports.AdaptiveLimit = AdaptiveLimit;
+/** 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). */
+class RetryBudget {
+    ratio;
+    burst;
+    tokens;
+    constructor(ratio = 0.1, burst = 10) {
+        this.ratio = ratio;
+        this.burst = burst;
+        this.tokens = burst;
+    }
+    onRequest() {
+        this.tokens = Math.min(this.burst, this.tokens + this.ratio);
+    }
+    tryRetry() {
+        if (this.tokens < 1)
+            return false;
+        this.tokens -= 1;
+        return true;
+    }
+}
+exports.RetryBudget = RetryBudget;
+/**
+ * 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).
+ */
+function waitDelayMs(round, retryAfterMs) {
+    if (retryAfterMs)
+        return Math.min(retryAfterMs, 300000);
+    const base = Math.min(5000 * 2 ** round, 300000);
+    return base * (0.75 + Math.random() * 0.25);
+}
+exports.waitDelayMs = waitDelayMs;
+/** What a PUT to the storage network ended in (undefined: success). */
+function storageOutcome(err) {
+    if (err === undefined || err === null)
+        return 'sent';
+    if (err instanceof errors_js_1.ConnectionError)
+        return (0, client_js_1.certainlyUnsent)(err.cause) ? 'unsent' : 'unknown';
+    if (err instanceof errors_js_1.APIError) {
+        const s = err.statusCode;
+        if (s === 412)
+            return 'sent';
+        if (s === 401 || s === 403)
+            return 'resign';
+        if (s === 400 && (err.code === 'BadDigest' || err.message.includes('BadDigest')))
+            return 'bad';
+        if (s === 429 || s >= 500)
+            return 'busy';
+    }
+    return 'refused';
+}
+exports.storageOutcome = storageOutcome;
+function isThrottle(err) {
+    return err instanceof errors_js_1.APIError && (err.statusCode === 429 || err.statusCode === 503);
+}
+exports.isThrottle = isThrottle;
+/** A control-plane failure worth waiting out: the network, a busy or failing server (the client has already retried it). */
+function isPassing(err) {
+    if (err instanceof errors_js_1.ConnectionError)
+        return true;
+    return err instanceof errors_js_1.APIError && (err.statusCode === 429 || err.statusCode >= 500);
+}
+exports.isPassing = isPassing;
+//# sourceMappingURL=engine.js.map

package/dist/cjs/direct/engine.js.map

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

package/dist/cjs/direct/formats.js

@@ -0,0 +1,44 @@
+"use strict";
+// Copyright 2026 TEEPIN Project
+// Licensed under the Apache License, Version 2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openServerV1 = exports.SOURCE_API = exports.SOURCE_STORAGE = exports.FORMATS = exports.FORMAT_PLAIN = exports.FORMAT_SERVER = exports.FORMAT_TWS1 = void 0;
+// The three formats objects are stored in, as a read session names them (TEEPIN-STORAGE-DESIGN.md sections 17.7 and
+// 21.3), a port of teepin-python's _formats.py:
+//
+// - tws1: encrypted on the device (tws1.ts), read by segment;
+// - teepin-v1: encrypted by Teepin when it staged a small object (teepin-core's crypt.go): one AES-256-GCM message,
+//   nonce, ciphertext and tag, bound to the session's associated_data. It is read whole and its tag checked before
+//   any byte is used;
+// - plain: stored as is (objects written before encryption).
+//
+// A session's source says where the bytes are: storage (fetched with the signed requests) or api (an object still in
+// the API's old stage, which isn't read: reads.ts's stagedError).
+//
+// Crypto is WebCrypto only, so the same code runs in Node 20+ and browsers.
+const errors_js_1 = require("../errors.js");
+exports.FORMAT_TWS1 = 'tws1';
+exports.FORMAT_SERVER = 'teepin-v1';
+exports.FORMAT_PLAIN = 'plain';
+exports.FORMATS = [exports.FORMAT_TWS1, exports.FORMAT_SERVER, exports.FORMAT_PLAIN];
+exports.SOURCE_STORAGE = 'storage';
+exports.SOURCE_API = 'api';
+const SERVER_NONCE_SIZE = 12;
+const SERVER_TAG_SIZE = 16;
+/** A teepin-v1 object's plaintext, after its tag is checked; DataIntegrityError if it doesn't authenticate. */
+async function openServerV1(key, stored, associatedData) {
+    if (key.length !== 32)
+        throw new errors_js_1.DataIntegrityError('a teepin-v1 key is 32 bytes', 'format');
+    if (stored.length < SERVER_NONCE_SIZE + SERVER_TAG_SIZE)
+        throw new errors_js_1.DataIntegrityError('the object is too short to be encrypted', 'truncated');
+    const k = await crypto.subtle.importKey('raw', key, 'AES-GCM', false, ['decrypt']);
+    const params = { name: 'AES-GCM', iv: stored.subarray(0, SERVER_NONCE_SIZE), additionalData: associatedData };
+    try {
+        return new Uint8Array(await crypto.subtle.decrypt(params, k, stored.subarray(SERVER_NONCE_SIZE)));
+    }
+    catch {
+        throw new errors_js_1.DataIntegrityError('the object failed authentication', 'segment');
+    }
+}
+exports.openServerV1 = openServerV1;
+//# sourceMappingURL=formats.js.map

package/dist/cjs/direct/formats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.js","sourceRoot":"","sources":["../../../src/direct/formats.ts"],"names":[],"mappings":";AAAA,gCAAgC;AAChC,iDAAiD;;;AAEjD,oHAAoH;AACpH,gDAAgD;AAChD,EAAE;AACF,8DAA8D;AAC9D,oHAAoH;AACpH,mHAAmH;AACnH,sBAAsB;AACtB,6DAA6D;AAC7D,EAAE;AACF,qHAAqH;AACrH,kEAAkE;AAClE,EAAE;AACF,4EAA4E;AAE5E,4CAAkD;AAErC,QAAA,WAAW,GAAG,MAAM,CAAC;AACrB,QAAA,aAAa,GAAG,WAAW,CAAC;AAC5B,QAAA,YAAY,GAAG,OAAO,CAAC;AACvB,QAAA,OAAO,GAAsB,CAAC,mBAAW,EAAE,qBAAa,EAAE,oBAAY,CAAC,CAAC;AAExE,QAAA,cAAc,GAAG,SAAS,CAAC;AAC3B,QAAA,UAAU,GAAG,KAAK,CAAC;AAEhC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAC7B,MAAM,eAAe,GAAG,EAAE,CAAC;AAE3B,+GAA+G;AACxG,KAAK,UAAU,YAAY,CAAC,GAAe,EAAE,MAAkB,EAAE,cAA0B;IAChG,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE;QAAE,MAAM,IAAI,8BAAkB,CAAC,6BAA6B,EAAE,QAAQ,CAAC,CAAC;IAC7F,IAAI,MAAM,CAAC,MAAM,GAAG,iBAAiB,GAAG,eAAe;QAAE,MAAM,IAAI,8BAAkB,CAAC,yCAAyC,EAAE,WAAW,CAAC,CAAC;IAC9I,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IACnF,MAAM,MAAM,GAAiB,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,iBAAiB,CAAC,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;IAC5H,IAAI;QACF,OAAO,IAAI,UAAU,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;KACnG;IAAC,MAAM;QACN,MAAM,IAAI,8BAAkB,CAAC,kCAAkC,EAAE,SAAS,CAAC,CAAC;KAC7E;AACH,CAAC;AAVD,oCAUC"}