@antasphere/chassis-server 1.0.0

package/dist/files/serve.js

@@ -0,0 +1,71 @@
+import { Readable } from 'node:stream';
+import { isValidMediaType } from '@antasphere/chassis-contract';
+import { blobKey } from '../storage/driver.js';
+import { contentDispositionFor, parseRangeHeader } from './http.js';
+/**
+ * Stream one content-addressed blob: immutable ETag (= the sha), 304, single
+ * Range (206/416), safe-serving disposition + nosniff (docs/security/security.md —
+ * user content never renders on the app origin). Shared by the files content
+ * route and the tool's asset download; both resolve METADATA first and
+ * only then hand the bytes question here.
+ */
+export async function serveBlob(c, opts) {
+    // Content-addressed: the ETag IS the content hash, immutable forever.
+    const etag = `"${opts.sha256}"`;
+    // Defensive sanitization at the header set (PLT-5, PRDCT-1358): the
+    // contract now refuses a non-RFC-7231 contentType at commit, but versions
+    // are IMMUTABLE — a value committed before that gate (or through any
+    // future path that skips it) would make the `Headers` constructor throw on
+    // every serve of the asset, an unrepairable anonymous 500. An invalid
+    // stored value degrades to octet-stream instead of poisoning the route.
+    const contentType = isValidMediaType(opts.contentType) ? opts.contentType : 'application/octet-stream';
+    const baseHeaders = {
+        'content-type': contentType,
+        'x-content-type-options': 'nosniff',
+        'content-disposition': opts.contentDisposition ?? contentDispositionFor(contentType, opts.filename),
+        'accept-ranges': 'bytes',
+        etag,
+        'cache-control': 'private, max-age=31536000, immutable',
+        ...(opts.extraHeaders ?? {})
+    };
+    if (c.req.header('if-none-match') === etag) {
+        return c.body(null, 304, baseHeaders);
+    }
+    // The metadata row is shared (Postgres) but the blob must be reachable
+    // from THIS replica before any status line is committed: with local
+    // storage behind a multi-replica load balancer the bytes live on another
+    // replica's private disk, and streaming ahead sent 200 + headers, then
+    // died mid-body — silent truncation the client cannot distinguish from
+    // the real file (scale drill, I2). The clean 404 is a safety net, not a
+    // supported topology: multi-replica requires shared storage
+    // (STORAGE_DRIVER=s3), docs/self-hosting/deployment-profiles.md.
+    const key = opts.storageKey ?? blobKey(opts.workspaceId, opts.sha256);
+    if (!(await opts.storage.exists(key))) {
+        opts.logger.error({ key, driver: opts.storage.name }, 'blob unreachable: metadata row exists but storage has no bytes (local storage behind multiple replicas?)');
+        return c.json({ error: { code: 'not_found', message: 'File content not available' } }, 404);
+    }
+    const parsed = parseRangeHeader(c.req.header('range'), opts.sizeBytes);
+    if (parsed.kind === 'unsatisfiable') {
+        return c.body(null, 416, { ...baseHeaders, 'content-range': `bytes */${opts.sizeBytes}` });
+    }
+    const isPartial = parsed.kind === 'range';
+    const start = isPartial ? parsed.range.start : 0;
+    const end = isPartial ? parsed.range.end : opts.sizeBytes - 1;
+    const length = opts.sizeBytes === 0 ? 0 : end - start + 1;
+    const headers = {
+        ...baseHeaders,
+        'content-length': String(length),
+        ...(isPartial ? { 'content-range': `bytes ${start}-${end}/${opts.sizeBytes}` } : {})
+    };
+    const status = isPartial ? 206 : 200;
+    if (opts.headOnly || opts.sizeBytes === 0) {
+        return c.body(null, status, headers);
+    }
+    const nodeStream = await opts.storage.getStream(key, isPartial ? parsed.range : undefined);
+    // Backpressure rides Readable.toWeb; a client abort must destroy the
+    // source or every seek-away leaks a descriptor/S3 socket.
+    c.req.raw.signal.addEventListener('abort', () => nodeStream.destroy());
+    const web = Readable.toWeb(nodeStream);
+    return c.body(web, status, headers);
+}
+//# sourceMappingURL=serve.js.map

package/dist/files/serve.js.map

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

package/dist/files/service.d.ts

@@ -0,0 +1,69 @@
+import type { Readable } from 'node:stream';
+import { type SQL } from 'drizzle-orm';
+import { type Db, type DbConn, type FileRow } from '@antasphere/chassis-db';
+import { type StorageDriver } from '../storage/driver.js';
+import type { Logger } from '../logger.js';
+import { FileTooLargeError } from './spool.js';
+export { FileTooLargeError };
+/**
+ * Through-app streamed uploads: the body is spooled to DATA_DIR/tmp while
+ * sha256 + size accumulate (never buffered in memory), the size cap enforced
+ * mid-stream, then the spool streams into the driver under the
+ * content-addressed key. Upload of bytes that already exist for the
+ * workspace is idempotent — same row comes back.
+ */
+export declare class FileService {
+    private readonly db;
+    private readonly storage;
+    private readonly spoolDir;
+    private readonly logger;
+    constructor(db: Db, storage: StorageDriver, spoolDir: string, logger: Logger);
+    upload(opts: {
+        workspaceId: string;
+        createdBy: string;
+        originalName: string;
+        contentType: string;
+        body: Readable;
+        maxBytes: number;
+    }): Promise<{
+        file: FileRow;
+        deduplicated: boolean;
+    }>;
+    /**
+     * Records that this user pushed these exact bytes — on the fresh-insert AND
+     * the dedupe path. `files.created_by` only ever names the FIRST uploader,
+     * so it cannot answer "does this principal hold these bytes" once blob
+     * reads are per-resource authorized (SL-B1); this join table can. Idempotent.
+     */
+    private recordUploader;
+    /** Content-addressed lookup — the tool's asset pull path. */
+    getBySha(workspaceId: string, sha256: string): Promise<FileRow | null>;
+    /**
+     * `visibility` is the caller's per-blob authorization predicate over the
+     * `files` row (SL-B1): the files module stays tool-agnostic, so the
+     * wiring point injects the ADR 013 scope. `undefined` = the operator view
+     * (workspace admin/owner), which sees every blob in the workspace. An
+     * unauthorized blob is indistinguishable from a missing one — the handlers
+     * answer 404, never 403 (ADR 013's not-probeable posture).
+     */
+    get(workspaceId: string, id: string, visibility?: SQL | undefined): Promise<FileRow | null>;
+    list(workspaceId: string, opts: {
+        cursor?: string;
+        limit: number;
+        visibility?: SQL | undefined;
+    }): Promise<{
+        files: FileRow[];
+        nextCursor: string | null;
+    }>;
+    /**
+     * Soft-deletes the row and removes the blob (one row per (ws, sha) by
+     * constraint). `inUse` is the ADR 011 blob-delete guard: it runs INSIDE the
+     * delete transaction with the files row locked FOR UPDATE, so it serializes
+     * against version commits (which lock referenced rows FOR SHARE) — a blob
+     * can never be deleted and referenced concurrently. Returns 'in_use'
+     * without touching anything when the guard refuses.
+     */
+    delete(row: FileRow, inUse?: (tx: DbConn, row: FileRow) => Promise<boolean>): Promise<'deleted' | 'in_use'>;
+    spoolDirUsable(): Promise<boolean>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/files/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/files/service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAyB,KAAK,GAAG,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAwB,KAAK,EAAE,EAAE,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAClG,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAe,MAAM,YAAY,CAAC;AAE5D,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B;;;;;;GAMG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAHN,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;IAG3B,MAAM,CAAC,IAAI,EAAE;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,QAAQ,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,CAAC;IAoDrD;;;;;OAKG;YACW,cAAc;IAI5B,6DAA6D;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAU5E;;;;;;;OAOG;IACG,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,GAAG,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAU3F,IAAI,CACR,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,GAAG,GAAG,SAAS,CAAA;KAAE,GACrE,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAiC3D;;;;;;;OAOG;IACG,MAAM,CACV,GAAG,EAAE,OAAO,EACZ,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GACrD,OAAO,CAAC,SAAS,GAAG,QAAQ,CAAC;IA2B1B,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;CASzC"}

package/dist/files/service.js

@@ -0,0 +1,188 @@
+import { createReadStream } from 'node:fs';
+import { mkdir, stat } from 'node:fs/promises';
+import { and, desc, eq, isNull } from 'drizzle-orm';
+import { fileUploaders, files } from '@antasphere/chassis-db';
+import { blobKey } from '../storage/driver.js';
+import { cursorRowId, keysetBefore, pageOf } from '../pagination.js';
+import { FileTooLargeError, spoolUpload } from './spool.js';
+export { FileTooLargeError };
+/**
+ * Through-app streamed uploads: the body is spooled to DATA_DIR/tmp while
+ * sha256 + size accumulate (never buffered in memory), the size cap enforced
+ * mid-stream, then the spool streams into the driver under the
+ * content-addressed key. Upload of bytes that already exist for the
+ * workspace is idempotent — same row comes back.
+ */
+export class FileService {
+    db;
+    storage;
+    spoolDir;
+    logger;
+    constructor(db, storage, spoolDir, logger) {
+        this.db = db;
+        this.storage = storage;
+        this.spoolDir = spoolDir;
+        this.logger = logger;
+    }
+    async upload(opts) {
+        const spool = await spoolUpload(opts.body, opts.maxBytes, this.spoolDir);
+        const spoolPath = spool.path;
+        const size = spool.sizeBytes;
+        const sha256 = spool.sha256;
+        try {
+            // Idempotent per (workspace, sha): reuse (and revive) an existing row.
+            const [existing] = await this.db
+                .select()
+                .from(files)
+                .where(and(eq(files.workspaceId, opts.workspaceId), eq(files.sha256, sha256)))
+                .limit(1);
+            const key = blobKey(opts.workspaceId, sha256);
+            if (existing) {
+                if (!(await this.storage.exists(key))) {
+                    await this.storage.put(key, createReadStream(spoolPath), {
+                        contentType: existing.contentType,
+                        sizeBytes: size
+                    });
+                }
+                if (existing.deletedAt) {
+                    await this.db.update(files).set({ deletedAt: null }).where(eq(files.id, existing.id));
+                    existing.deletedAt = null;
+                }
+                await this.recordUploader(existing.id, opts.createdBy);
+                return { file: existing, deduplicated: true };
+            }
+            await this.storage.put(key, createReadStream(spoolPath), {
+                contentType: opts.contentType,
+                sizeBytes: size
+            });
+            const [row] = await this.db
+                .insert(files)
+                .values({
+                workspaceId: opts.workspaceId,
+                sha256,
+                sizeBytes: size,
+                contentType: opts.contentType,
+                originalName: opts.originalName,
+                createdBy: opts.createdBy
+            })
+                .returning();
+            await this.recordUploader(row.id, opts.createdBy);
+            return { file: row, deduplicated: false };
+        }
+        finally {
+            await spool.cleanup();
+        }
+    }
+    /**
+     * Records that this user pushed these exact bytes — on the fresh-insert AND
+     * the dedupe path. `files.created_by` only ever names the FIRST uploader,
+     * so it cannot answer "does this principal hold these bytes" once blob
+     * reads are per-resource authorized (SL-B1); this join table can. Idempotent.
+     */
+    async recordUploader(fileId, userId) {
+        await this.db.insert(fileUploaders).values({ fileId, userId }).onConflictDoNothing();
+    }
+    /** Content-addressed lookup — the tool's asset pull path. */
+    async getBySha(workspaceId, sha256) {
+        const [row] = await this.db
+            .select()
+            .from(files)
+            .where(and(eq(files.workspaceId, workspaceId), eq(files.sha256, sha256)))
+            .limit(1);
+        if (!row || row.deletedAt)
+            return null;
+        return row;
+    }
+    /**
+     * `visibility` is the caller's per-blob authorization predicate over the
+     * `files` row (SL-B1): the files module stays tool-agnostic, so the
+     * wiring point injects the ADR 013 scope. `undefined` = the operator view
+     * (workspace admin/owner), which sees every blob in the workspace. An
+     * unauthorized blob is indistinguishable from a missing one — the handlers
+     * answer 404, never 403 (ADR 013's not-probeable posture).
+     */
+    async get(workspaceId, id, visibility) {
+        const [row] = await this.db
+            .select()
+            .from(files)
+            .where(and(eq(files.id, id), eq(files.workspaceId, workspaceId), ...(visibility ? [visibility] : [])))
+            .limit(1);
+        if (!row || row.deletedAt)
+            return null;
+        return row;
+    }
+    async list(workspaceId, opts) {
+        const cursorId = cursorRowId(opts.cursor);
+        // The soft-delete filter MUST be SQL-side: a JS filter after the fetch
+        // would shrink pages below the limit and break cursor correctness. Same
+        // reason the ADR 013 visibility scope is a WHERE clause, not a post-filter.
+        const rows = await this.db
+            .select()
+            .from(files)
+            .where(and(eq(files.workspaceId, workspaceId), isNull(files.deletedAt), ...(opts.visibility ? [opts.visibility] : []), ...(cursorId
+            ? [
+                keysetBefore({
+                    table: files,
+                    id: files.id,
+                    createdAt: files.createdAt,
+                    workspaceId: files.workspaceId,
+                    cursorId,
+                    workspace: workspaceId
+                })
+            ]
+            : [])))
+            .orderBy(desc(files.createdAt), desc(files.id))
+            .limit(opts.limit + 1);
+        const { page, nextCursor } = pageOf(rows, opts.limit);
+        return { files: page, nextCursor };
+    }
+    /**
+     * Soft-deletes the row and removes the blob (one row per (ws, sha) by
+     * constraint). `inUse` is the ADR 011 blob-delete guard: it runs INSIDE the
+     * delete transaction with the files row locked FOR UPDATE, so it serializes
+     * against version commits (which lock referenced rows FOR SHARE) — a blob
+     * can never be deleted and referenced concurrently. Returns 'in_use'
+     * without touching anything when the guard refuses.
+     */
+    async delete(row, inUse) {
+        const outcome = await this.db.transaction(async (tx) => {
+            const [locked] = await tx
+                .select({ id: files.id, deletedAt: files.deletedAt })
+                .from(files)
+                .where(eq(files.id, row.id))
+                .for('update')
+                .limit(1);
+            // Already gone (raced another delete): idempotent success.
+            if (!locked || locked.deletedAt)
+                return 'deleted';
+            if (inUse && (await inUse(tx, row)))
+                return 'in_use';
+            await tx.update(files).set({ deletedAt: new Date() }).where(eq(files.id, row.id));
+            return 'deleted';
+        });
+        if (outcome === 'in_use')
+            return outcome;
+        // The soft-delete is authoritative; blob removal is best-effort cleanup —
+        // a storage failure must not fail the request (a re-upload self-heals via
+        // content addressing). Now that the driver surfaces real transport errors,
+        // swallow them here rather than in the driver.
+        try {
+            await this.storage.delete(blobKey(row.workspaceId, row.sha256));
+        }
+        catch (err) {
+            this.logger.error({ err, fileId: row.id }, 'blob delete failed — row soft-deleted, blob orphaned');
+        }
+        return 'deleted';
+    }
+    async spoolDirUsable() {
+        try {
+            await mkdir(this.spoolDir, { recursive: true });
+            const s = await stat(this.spoolDir);
+            return s.isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/files/service.js.map

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

package/dist/files/spool.d.ts

@@ -0,0 +1,21 @@
+import type { Readable } from 'node:stream';
+export declare class FileTooLargeError extends Error {
+    readonly limitBytes: number;
+    constructor(limitBytes: number);
+}
+export interface SpooledUpload {
+    /** The spool file, to stream into the driver. The caller MUST `cleanup()` in a finally. */
+    path: string;
+    sizeBytes: number;
+    sha256: string;
+    cleanup: () => Promise<void>;
+}
+/**
+ * Spool a request body to `spoolDir/<uuid>` while sha256 + size accumulate
+ * (never buffered in memory), the size cap enforced MID-STREAM — a body that
+ * lies about its Content-Length is cut at `maxBytes + 1`, and the partial
+ * spool file is removed before the error surfaces. Shared by the workspace
+ * file upload (files/service.ts) and the form file upload (forms/uploads.ts).
+ */
+export declare function spoolUpload(body: Readable, maxBytes: number, spoolDir: string): Promise<SpooledUpload>;
+//# sourceMappingURL=spool.d.ts.map

package/dist/files/spool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spool.d.ts","sourceRoot":"","sources":["../../src/files/spool.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAI5C,qBAAa,iBAAkB,SAAQ,KAAK;aACd,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAG/C;AAED,MAAM,WAAW,aAAa;IAC5B,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAwBxB"}

package/dist/files/spool.js

@@ -0,0 +1,47 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+export class FileTooLargeError extends Error {
+    limitBytes;
+    constructor(limitBytes) {
+        super(`file exceeds the ${limitBytes}-byte limit`);
+        this.limitBytes = limitBytes;
+    }
+}
+/**
+ * Spool a request body to `spoolDir/<uuid>` while sha256 + size accumulate
+ * (never buffered in memory), the size cap enforced MID-STREAM — a body that
+ * lies about its Content-Length is cut at `maxBytes + 1`, and the partial
+ * spool file is removed before the error surfaces. Shared by the workspace
+ * file upload (files/service.ts) and the form file upload (forms/uploads.ts).
+ */
+export async function spoolUpload(body, maxBytes, spoolDir) {
+    await mkdir(spoolDir, { recursive: true });
+    const path = join(spoolDir, randomUUID());
+    const hash = createHash('sha256');
+    let size = 0;
+    const meter = new Transform({
+        transform(chunk, _enc, cb) {
+            size += chunk.length;
+            if (size > maxBytes) {
+                cb(new FileTooLargeError(maxBytes));
+                return;
+            }
+            hash.update(chunk);
+            cb(null, chunk);
+        }
+    });
+    const cleanup = () => rm(path, { force: true });
+    try {
+        await pipeline(body, meter, createWriteStream(path, { flags: 'wx' }));
+    }
+    catch (e) {
+        await cleanup();
+        throw e;
+    }
+    return { path, sizeBytes: size, sha256: hash.digest('hex'), cleanup };
+}
+//# sourceMappingURL=spool.js.map

package/dist/files/spool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spool.js","sourceRoot":"","sources":["../../src/files/spool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACd;IAA5B,YAA4B,UAAkB;QAC5C,KAAK,CAAC,oBAAoB,UAAU,aAAa,CAAC,CAAC;QADzB,eAAU,GAAV,UAAU,CAAQ;IAE9C,CAAC;CACF;AAUD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAc,EACd,QAAgB,EAChB,QAAgB;IAEhB,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC;QAC1B,SAAS,CAAC,KAAa,EAAE,IAAI,EAAE,EAAE;YAC/B,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC;YACrB,IAAI,IAAI,GAAG,QAAQ,EAAE,CAAC;gBACpB,EAAE,CAAC,IAAI,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC;gBACpC,OAAO;YACT,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnB,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAClB,CAAC;KACF,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,iBAAiB,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACxE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,OAAO,EAAE,CAAC;QAChB,MAAM,CAAC,CAAC;IACV,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;AACxE,CAAC"}