@fidt/saul-server 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -0,0 +1,464 @@
+import { Hono } from 'hono';
+export * from 'hono';
+export { Hono as WebServer } from 'hono';
+export { cors } from 'hono/cors';
+export { serve } from '@hono/node-server';
+export * from 'socket.io';
+export { createAdapter } from '@socket.io/redis-adapter';
+import * as zod from 'zod';
+export { zod as Zod };
+import { Readable, Writable } from 'stream';
+export * from 'zod-validation-error';
+
+declare class File {
+    private content;
+    metadata: {
+        name: string;
+        size: number;
+        type: string;
+    };
+    constructor(meta?: {
+        name: string;
+        size: number;
+        type: string;
+    });
+    private encodeBase64;
+    private decodeBase64;
+    /**
+     * Đọc tất cả nội dụng của file
+     */
+    read(): ArrayBuffer;
+    /**
+     * Ghi nội dung vào file
+     */
+    write(buffer: ArrayBuffer): void;
+}
+
+/**
+ * FILE DẠNG STREAM — cho file mà cả nội dung KHÔNG được phép nằm trong RAM.
+ *
+ * Khác `File` (buffered, giữ base64 trong bộ nhớ, trần vài chục MB), `FileStream` chỉ giữ
+ * metadata + một hàm mở nguồn. Byte chỉ chảy khi có người đọc, nên RAM là hằng số bất kể
+ * file 8MB hay 8GB.
+ *
+ * Dùng được ở CẢ HAI vị trí trong definition:
+ * - param      → chiều lên: multipart upload, gateway/downstream đưa `Readable` vào đây.
+ * - returnType → chiều xuống: handler trả về, runtime pipe thẳng ra browser.
+ *
+ * Khai kiểu nào là chọn hợp đồng đó. Transport KHÔNG được đánh tráo `File` thành
+ * `FileStream` hay ngược lại — một param có shape phụ thuộc transport là thứ tuyệt đối
+ * không được xảy ra.
+ */
+/** Brand để nhận diện qua ranh giới package — xem `FileStream.is`. */
+declare const FILE_STREAM_BRAND: unique symbol;
+interface FileStreamMetadata {
+    name: string;
+    /** Kích thước KHAI BÁO. `0` = không biết trước (dữ liệu sinh on-the-fly). */
+    size: number;
+    type: string;
+}
+declare class FileStream {
+    /** @internal Đánh dấu instance để `is()` nhận ra qua nhiều bản copy của package. */
+    readonly [FILE_STREAM_BRAND]: true;
+    readonly metadata: FileStreamMetadata;
+    private readonly source;
+    private consumed;
+    constructor(metadata: FileStreamMetadata, source: () => Readable);
+    /**
+     * Mở nguồn và trả về `Readable`.
+     *
+     * Gọi lần thứ hai sẽ NÉM. Một stream không phải là value: đọc hai lần thì lần thứ hai
+     * hoặc rỗng, hoặc mở lại nguồn và trả về dữ liệu đã cũ — cả hai đều là bug im lặng.
+     * Cần đọc nhiều lần thì `buffer()` một lần rồi tự giữ.
+     */
+    stream(): Readable;
+    /** Đã có ai đọc chưa — cho runtime biết có phải drain trước khi trả response không. */
+    get isConsumed(): boolean;
+    /** Đẩy toàn bộ nội dung vào một `Writable`, chờ tới khi xong. */
+    pipeTo(destination: Writable): Promise<void>;
+    /**
+     * Đọc hết vào một `Buffer`.
+     *
+     * `maxBytes` là BẮT BUỘC, không có mặc định: đây là escape hatch duy nhất ra khỏi mô hình
+     * streaming, và người dùng nó phải tự nói ra trần mình chấp nhận. Một `buffer()` không
+     * trần đặt giữa đường xử lý file 3GB sẽ giết process — mà chỉ giết trong production, với
+     * file lớn, chứ không bao giờ trong test.
+     */
+    buffer(maxBytes: number): Promise<Buffer>;
+    /**
+     * Có phải `FileStream` không.
+     *
+     * Dùng brand chứ KHÔNG dùng `instanceof`: gateway và downstream có thể resolve hai bản
+     * copy khác nhau của `@fidt/saul-server` (dual-package hazard), lúc đó `instanceof` trả
+     * `false` cho một object hoàn toàn hợp lệ — và nó hỏng theo kiểu chỉ lộ ra khi deploy
+     * thật, không bao giờ trong monorepo.
+     */
+    static is(value: unknown): value is FileStream;
+    /** Dựng từ một `Buffer` sẵn có — tiện cho test và cho handler trả dữ liệu nhỏ. */
+    static fromBuffer(metadata: Omit<FileStreamMetadata, 'size'> & {
+        size?: number;
+    }, data: Buffer): FileStream;
+}
+
+/**
+ * SaulException — lỗi NGHIỆP VỤ mà handler chủ động ném để từ chối một lời gọi.
+ *
+ * Khác `Error` trần ở đúng hai điểm, và cả hai đều là lý do nó tồn tại:
+ *
+ *  1. **Có `code`** đi qua được dây. Envelope lỗi của downstream mang cả `message` lẫn
+ *     `code`, gateway map sang ack `{ ok:false, error, code }`, client dựng lại thành
+ *     `SaulException` — nên client bắt được lỗi theo mã chứ không phải so khớp chuỗi tiếng
+ *     Việt. `Error` trần chỉ còn lại `message` sau chuyến đi.
+ *  2. **Là ý ĐỊNH từ chối, không phải sự cố.** Gateway log `Error` lạ như một lỗi server,
+ *     còn `SaulException` là câu trả lời hợp lệ ("bạn không được sub chat của người khác")
+ *     nên không cần ồn ào trong log.
+ *
+ * Chỗ dùng chính là validator của subscription: controller `sub<Model>` ném `SaulException`
+ * để từ chối, và cái ném đó nổi lên đúng chỗ client đang `catch` quanh vòng `for await`.
+ */
+declare class SaulException extends Error {
+    /** Mã ổn định để client rẽ nhánh. Mặc định là mã chung của một từ chối nghiệp vụ. */
+    readonly code: string;
+    constructor(message: string, code?: string);
+    /**
+     * Nhận diện KHÔNG dùng `instanceof`.
+     *
+     * Gateway, downstream và SDK có thể resolve ba bản copy vật lý khác nhau của package
+     * này (pnpm workspace + code sinh ra được copy vào từng service), nên `instanceof` sẽ
+     * trả false cho một SaulException hoàn toàn thật. Cùng lý do với `FileStream.is`.
+     */
+    static is(value: unknown): value is SaulException;
+}
+
+/**
+ * PREDICATE — điều kiện lọc mà client khai khi mở một subscription.
+ *
+ * File này CHỈ có kiểu, không có runtime: việc đánh giá predicate xảy ra ở GATEWAY (nó giữ
+ * socket và biết ai đang nghe gì), không ở downstream. Downstream chỉ cần đọc và thu hẹp
+ * predicate trong validator `sub<Model>` rồi trả về.
+ *
+ * Cú pháp `$`-prefix, cố ý KHÁC filter authz kiểu Directus (`_eq`, `_or`) ở
+ * `Permission.filter`. Hai thứ trả lời hai câu hỏi khác nhau — filter authz nói "được thấy
+ * BẢN GHI nào" và được forward xuống query storage; predicate nói "muốn nhận EVENT nào" và
+ * được Saul tự đánh giá in-memory. Trộn cú pháp sẽ khiến người đọc tưởng chúng thay nhau được.
+ */
+/** So sánh trên một field. Nhiều toán tử trong cùng object thì AND với nhau. */
+interface PredicateComparison<V> {
+    $eq?: V;
+    $ne?: V;
+    $gt?: V;
+    $gte?: V;
+    $lt?: V;
+    $lte?: V;
+    $in?: V[];
+    $nin?: V[];
+    /** Field có mặt trong payload hay không — nói về SỰ CÓ MẶT, không phải giá trị. */
+    $exists?: boolean;
+}
+/**
+ * Predicate trên một Model.
+ *
+ * Giá trị trần là shorthand của `$eq`: `{ chatId: 12 }` ≡ `{ chatId: { $eq: 12 } }`.
+ * Các key cùng cấp AND với nhau, nên `{}` khớp TẤT CẢ — đó là lý do validator `sub<Model>`
+ * mặc định TỪ CHỐI, và là lý do nên thu hẹp predicate thay vì chỉ kiểm rồi trả nguyên.
+ *
+ * KHÔNG có `$regex`: nó là đường ReDoS do client tự khai, chạy ở đường nóng của mọi lần push.
+ */
+type Predicate<T> = {
+    [K in keyof T]?: T[K] | PredicateComparison<T[K]>;
+} & {
+    $and?: Predicate<T>[];
+    $or?: Predicate<T>[];
+    $not?: Predicate<T>;
+};
+/**
+ * Một subscription đang mở, nhìn từ phía server.
+ *
+ * `id` do gateway sinh TRƯỚC khi gọi validator và truyền xuống qua `ctx.subId`, nên
+ * validator lưu lại được để về sau `sub<Model>.unsub(id)` thu hồi (vd user bị mời khỏi
+ * phòng chat trong lúc đang nghe).
+ */
+interface Sub<T> {
+    id: string;
+    predicate: Predicate<T>;
+}
+/**
+ * Gộp nhiều predicate bằng AND — cách chuẩn để validator THU HẸP thứ client xin.
+ *
+ * ```ts
+ * return narrow(predicate, { userId: { $eq: ctx.principal.sub } })
+ * ```
+ *
+ * Dùng `$and` thay vì trải phẳng bằng spread: spread sẽ để điều kiện sau GHI ĐÈ điều kiện
+ * trước trên cùng một field, tức là client khai `{ userId: { $eq: 'ai-đó' } }` rồi ràng
+ * buộc bảo mật ghi đè lên — đúng ý. Nhưng ở chiều ngược lại (`{...cứng, ...client}`) thì
+ * client ghi đè ràng buộc bảo mật. `$and` không có chiều nào để nhầm: mọi nhánh đều phải thoả.
+ */
+declare const narrow: <T>(...predicates: (Predicate<T> | null | undefined)[]) => Predicate<T>;
+
+/**
+ * LỖI CỦA CHUNK STORE, có mã máy-đọc-được.
+ *
+ * Cùng kiểu với `BinaryStreamError` của đường WebSocket: mỗi tình huống một `code`, và mã
+ * đó — chứ không phải chuỗi message — là thứ tầng trên map sang HTTP status. Một bảng map
+ * duy nhất, không handler nào tự viết status.
+ */
+type UploadErrorCode = 'UPLOAD_NOT_FOUND' | 'UPLOAD_EXISTS' | 'UPLOAD_EXPIRED' | 'UPLOAD_COMPLETED'
+/** Đang complete dở — một lời gọi complete khác đã chiếm chỗ. */
+ | 'UPLOAD_BUSY' | 'PART_OUT_OF_RANGE' | 'PART_IN_FLIGHT' | 'PART_TOO_LARGE' | 'PART_MISSING' | 'SIZE_MISMATCH' | 'CHECKSUM_MISMATCH' | 'DISK_BUDGET' | 'FORBIDDEN';
+declare class UploadError extends Error {
+    readonly code: UploadErrorCode;
+    constructor(code: UploadErrorCode, message: string);
+    static is(value: unknown): value is UploadError;
+}
+/**
+ * MÃ LỖI → HTTP STATUS. Bảng DUY NHẤT, và nó phải phủ hết `UploadErrorCode`.
+ *
+ * `Record<UploadErrorCode, number>` cố ý không optional: thêm một mã mới mà quên map thì
+ * TypeScript báo ngay, thay vì lặng lẽ trả 500 cho một lỗi vốn có nghĩa rõ ràng.
+ */
+declare const UPLOAD_ERROR_STATUS: Record<UploadErrorCode, number>;
+declare const uploadErrorStatus: (code: UploadErrorCode) => number;
+
+interface WritePartResult {
+    size: number;
+    /** sha256 hex của part — client dùng để retry có kiểm chứng. */
+    etag: string;
+}
+interface PartInfo {
+    partNumber: number;
+    size: number;
+}
+interface PartDiskStoreOptions {
+    /** Thư mục gốc. Mỗi upload một thư mục con. */
+    rootDir: string;
+    /** fsync mỗi part trước khi rename. Tắt = đổi durability-khi-crash lấy throughput. */
+    fsync?: boolean;
+}
+declare class PartDiskStore {
+    private readonly rootDir;
+    private readonly fsync;
+    constructor(options: PartDiskStoreOptions);
+    /**
+     * Thư mục của một upload.
+     *
+     * `assertSafeUploadId` chạy TRƯỚC `join` — đây là bề mặt path-traversal duy nhất của
+     * cả tính năng, và `join('/tmp', '../../etc')` là một đường dẫn hoàn toàn hợp lệ.
+     */
+    dirFor(uploadId: string): string;
+    private pathFor;
+    ensureDir(uploadId: string): Promise<void>;
+    /**
+     * Ghi một part. Trả về số byte thật và sha256.
+     *
+     * Bốn bước, thứ tự bắt buộc:
+     *   1. `open(tmp, 'wx')` — hai PUT cùng part cùng lúc thì một cái thua ngay, thay vì
+     *      hai writer xen kẽ vào cùng một file.
+     *   2. pipeline có đếm byte + hash — vượt trần là abort GIỮA CHỪNG, không đọc hết rồi
+     *      mới than.
+     *   3. fsync (nếu bật) rồi `rename` — rename trong cùng filesystem là atomic, nên
+     *      file `.part` xuất hiện là đã hoàn chỉnh, không có trạng thái nửa vời.
+     *   4. Chỉ khi rename xong mới coi như part tồn tại.
+     */
+    writePart(uploadId: string, partNumber: number, body: Readable, opts: {
+        maxBytes: number;
+        partCount: number;
+        declaredLength?: number;
+        expectedSha256?: string;
+    }): Promise<WritePartResult>;
+    /** Mở một part để đọc. Dùng bởi `concatParts`. */
+    createPartStream(uploadId: string, partNumber: number, partCount: number): Readable;
+    /** Các part ĐANG CÓ THẬT trên đĩa (không tính `.tmp`). */
+    listParts(uploadId: string): Promise<PartInfo[]>;
+    /** Xoá cả thư mục upload. Trả về số byte giải phóng. Idempotent. */
+    removeUpload(uploadId: string): Promise<number>;
+    /** Thư mục cũ hơn `olderThanMs` — ứng viên dọn rác. Xem `UploadSweeper`. */
+    listStaleDirs(olderThanMs: number, now?: number): Promise<string[]>;
+    /** Tổng byte đang chiếm — để đối chiếu lại counter, vốn trôi sau mỗi lần crash. */
+    totalBytes(): Promise<number>;
+}
+/**
+ * `uploadId` phải là UUID. Kiểm TRƯỚC mọi thao tác đường dẫn.
+ *
+ * Không dùng blacklist (`..`, `/`): danh sách cấm luôn thiếu một dạng nào đó
+ * (`%2e%2e`, null byte, tên dài quá giới hạn OS). Whitelist một hình dạng đã biết thì không.
+ */
+declare function assertSafeUploadId(uploadId: string): void;
+/** `partNumber` phải là số nguyên trong `1..partCount`. */
+declare function assertSafePartNumber(partNumber: number, partCount: number): void;
+
+type UploadState = 'open' | 'completing' | 'completed';
+interface UploadRecord {
+    uploadId: string;
+    module: string;
+    function: string;
+    /** Tên param kiểu FileStream của function đích. */
+    param: string;
+    /** Các param KHÔNG phải file của cùng lời gọi. */
+    params: Record<string, unknown>;
+    file: {
+        name: string;
+        size: number;
+        type: string;
+    };
+    chunkSize: number;
+    partCount: number;
+    /** Deadline TUYỆT ĐỐI do gateway quyết, không bao giờ gia hạn. */
+    hardExpiresAt: number;
+    /** Deadline TRƯỢT, gia hạn mỗi lần nhận được part. */
+    expiresAt: number;
+    idleTimeoutMs: number;
+    state: UploadState;
+    createdAt: number;
+}
+interface UploadRegistryOptions {
+    store: PartDiskStore;
+    /** Ngân sách đĩa của MÁY NÀY. Vượt thì từ chối init. */
+    maxDiskBytes: number;
+}
+declare class UploadRegistry {
+    private readonly records;
+    private readonly store;
+    private readonly maxDiskBytes;
+    /**
+     * Byte đang chiếm, đếm tăng dần. Đây là con số ƯỚC LƯỢNG — nó trôi sau mỗi lần crash,
+     * nên `UploadSweeper` định kỳ tính lại bằng `du` thật. Counter trôi mà không ai sửa thì
+     * ngân sách âm thầm khoá mọi upload, và không có gì trong log nói tại sao.
+     */
+    private usedBytes;
+    constructor(options: UploadRegistryOptions);
+    get diskUsedBytes(): number;
+    /** Đặt lại bộ đếm sau khi đối chiếu với đĩa thật. Xem `UploadSweeper`. */
+    setDiskUsedBytes(bytes: number): void;
+    init(record: Omit<UploadRecord, 'state' | 'createdAt' | 'expiresAt'>): Promise<UploadRecord>;
+    /**
+     * Record của một upload đang MỞ được.
+     *
+     * Hết hạn thì ném `UPLOAD_EXPIRED` chứ không `UPLOAD_NOT_FOUND`: hai thứ đó nói với
+     * client hai điều khác nhau — "id sai, đừng thử nữa" và "chậm quá, làm lại từ init".
+     */
+    get(uploadId: string, allowed?: UploadState[]): UploadRecord;
+    /** Có record nào không, bất kể trạng thái — cho abort idempotent và cho sweeper. */
+    peek(uploadId: string): UploadRecord | undefined;
+    list(): UploadRecord[];
+    /**
+     * Gia hạn deadline sau khi nhận được một part, và cộng chênh lệch byte vào bộ đếm.
+     *
+     * `delta` chứ không phải `size`: PUT lại một part là GHI ĐÈ, nên phần tăng thêm chỉ là
+     * hiệu số. Cộng nguyên `size` mỗi lần retry sẽ thổi phồng bộ đếm cho tới khi ngân sách
+     * khoá cả những upload hoàn toàn bình thường.
+     */
+    touch(uploadId: string, deltaBytes: number): void;
+    /**
+     * Chuyển sang `completing`, một lần duy nhất.
+     *
+     * Đây là chốt chống complete đồng thời: hai request cùng lúc thì cái thứ hai thấy state
+     * đã đổi và nhận `UPLOAD_BUSY`, thay vì cả hai cùng ghép file và cùng gọi handler.
+     */
+    beginComplete(uploadId: string): UploadRecord;
+    /** Quay lại `open` khi complete thất bại — cho client retry mà không mất part đã gửi. */
+    rollbackComplete(uploadId: string): void;
+    /** Xoá record + part trên đĩa. Idempotent. */
+    remove(uploadId: string): Promise<void>;
+    /**
+     * Ghi `meta.json` cạnh part.
+     *
+     * Ghi tmp rồi rename để không bao giờ có một `meta.json` cụt: sweeper đọc phải file cụt
+     * sẽ coi thư mục là rác và xoá một upload đang chạy dở.
+     */
+    private persist;
+    /** Đọc `meta.json` của một thư mục — cho sweeper phân biệt upload sống với rác. */
+    readPersisted(uploadId: string): Promise<UploadRecord | undefined>;
+}
+
+/**
+ * DỌN RÁC ĐỊNH KỲ cho chunk store.
+ *
+ * Ba việc, và việc thứ hai/thứ ba mới là lý do tồn tại của nó: một `setTimeout` per-upload
+ * (kiểu `BinaryStreamBuffer` đang dùng cho WS) chỉ dọn được thứ nó biết. Process chết giữa
+ * chừng thì timer chết theo, còn file thì ở lại đĩa mãi mãi.
+ *
+ *   1. Upload quá hạn        → xoá record + part.
+ *   2. Thư mục KHÔNG có record trong RAM và đã cũ → rác của một process đã chết, xoá.
+ *   3. Định kỳ đối chiếu bộ đếm byte với đĩa thật → counter trôi sau crash, mà counter trôi
+ *      thì ngân sách âm thầm khoá mọi upload và không có gì trong log nói tại sao.
+ */
+interface UploadSweeperOptions {
+    registry: UploadRegistry;
+    store: PartDiskStore;
+    intervalMs?: number;
+    /** Thư mục mồ côi phải cũ hơn ngần này mới xoá. Mặc định 2× idle timeout dài nhất. */
+    orphanGraceMs?: number;
+    /** Bao nhiêu tick thì đối chiếu lại bộ đếm với đĩa (quét `du` không rẻ). */
+    reconcileEvery?: number;
+}
+interface SweepResult {
+    expired: number;
+    orphans: number;
+    reconciledBytes?: number;
+}
+declare class UploadSweeper {
+    private readonly registry;
+    private readonly store;
+    private readonly intervalMs;
+    private readonly orphanGraceMs;
+    private readonly reconcileEvery;
+    private timer?;
+    private ticks;
+    constructor(options: UploadSweeperOptions);
+    /** Bắt đầu quét. `unref()` để timer dọn dẹp không giữ process sống. */
+    start(): void;
+    stop(): void;
+    sweep(now?: number): Promise<SweepResult>;
+}
+
+/**
+ * NỐI CÁC PART thành MỘT `Readable`, không buffer.
+ *
+ * `Readable.from(async generator)` cho backpressure đúng miễn phí: generator chỉ chạy tiếp
+ * khi consumer kéo, nên tốc độ đọc đĩa tự khớp tốc độ ghi ra downstream. Và vì generator
+ * chỉ mở part khi tới lượt, ở mọi thời điểm chỉ có **một** fd đang mở — RAM là
+ * `highWaterMark`, không phụ thuộc file 8MB hay 8GB.
+ *
+ * `finally { rs.destroy() }` không phải cho đường thành công (stream tự đóng khi hết) mà cho
+ * đường HUỶ: consumer `destroy()` giữa chừng sẽ ném vào generator, và không có `finally` thì
+ * part đang đọc dở giữ fd tới tận lúc GC.
+ */
+declare function concatParts(store: PartDiskStore, uploadId: string, partNumbers: number[], partCount: number): Readable;
+
+/**
+ * SUB-ROUTER `/saul/upload/*` — phía DOWNSTREAM của multipart upload.
+ *
+ * Gateway không lưu byte nào; nó bơm thẳng từng part sang đây. Nên đây mới là nơi part nằm
+ * trên đĩa và được ghép lại lúc complete.
+ *
+ * Router này KHÔNG tự gác quyền. Nó tin gateway, đúng như `POST /saul` đang tin — quyền đã
+ * được chốt ở `/upload/init` của gateway, trước byte đầu tiên. Đặt thêm một tầng authz ở đây
+ * mà không có token của user thì cũng chỉ là kiểm lại chính mình.
+ *
+ * Chỉ ba biến env, và cả ba đều nói về TÀI NGUYÊN CỦA MÁY NÀY. Mọi thứ thuộc về chính sách
+ * (deadline, chunk size, partCount) do gateway truyền xuống trong lời gọi init.
+ */
+interface UploadRouterOptions {
+    /** Gọi hàm đích sau khi đã ghép file. Runtime truyền `dispatch` của nó vào đây. */
+    dispatch: (body: {
+        module: string;
+        function: string;
+        params: Record<string, unknown>;
+    }) => Promise<unknown>;
+    rootDir?: string;
+    maxDiskBytes?: number;
+    fsync?: boolean;
+    /** Trần cứng một part. Gateway cũng gác, nhưng ở đây mới đếm byte THẬT. */
+    maxPartBytes?: number;
+    sweepIntervalMs?: number;
+}
+interface UploadSubsystem {
+    router: Hono;
+    registry: UploadRegistry;
+    store: PartDiskStore;
+    sweeper: UploadSweeper;
+}
+declare function createUploadSubsystem(options: UploadRouterOptions): UploadSubsystem;
+
+export { File, FileStream, type FileStreamMetadata, PartDiskStore, type PartDiskStoreOptions, type PartInfo, type Predicate, type PredicateComparison, SaulException, type Sub, type SweepResult, UPLOAD_ERROR_STATUS, UploadError, type UploadErrorCode, type UploadRecord, UploadRegistry, type UploadRegistryOptions, type UploadRouterOptions, type UploadState, type UploadSubsystem, UploadSweeper, type UploadSweeperOptions, type WritePartResult, assertSafePartNumber, assertSafeUploadId, concatParts, createUploadSubsystem, narrow, uploadErrorStatus };