@docmentis/udoc-server 0.0.0-stage → 0.8.0

package/dist/server.js

@@ -0,0 +1,103 @@
+// The udoc server: keeps documents, and serves them over HTTP through sessions
+// opened over what it keeps.
+//
+// A document is imported once — the upload opened, its ids minted — and kept in
+// a `DocumentStore` as its original, the upload as it arrived, and its
+// checkpoints, the udoc packages a later session reopens the latest of: `v0`
+// from the import, then one more each time it is checkpointed. What is kept is
+// the document; a session is a cache over it, one per document on a thread of
+// its own (see `@docmentis/udoc-node`): opened when a request needs it, kept
+// while requests keep coming, closed once idle or once too many are open, and
+// reopened from the store the next time. That is what lets a document outlive
+// the process, and what bounds how much the process holds. Streaming a
+// document's parts reads the store alone. Co-editing it is a collaboration: the
+// clients editing it together over its pooled session, held open while any is
+// connected, and every edit kept in the store as the document's edit log.
+//
+// Each piece is a file of its own: the store (`store.ts`), the session pool
+// over it (`session-pool.ts`), the collaborations over the pool
+// (`collaboration.ts`), and the routes — each family a table of its own, the
+// document routes (`document.ts`) and the package routes beneath them
+// (`package.ts`), matched by `route.ts`. Here they are built over one store.
+//
+// The server answers requests and WebSocket upgrades; it doesn't listen. Its
+// host hands it each one — `main.ts` from an HTTP server of its own, an
+// embedder from theirs — and answers itself any whose path no route has.
+import { UDocError } from "@docmentis/udoc-node";
+import { Collaborations } from "./collaboration.js";
+import { documentRoutes, noDocument } from "./document.js";
+import { HttpFailure, LICENSE_CODES, notFound } from "./http.js";
+import { readPackage } from "./package.js";
+import { answerRequest, answerUpgrade, has, targetOf } from "./route.js";
+import { SessionPool } from "./session-pool.js";
+const DEFAULT_MAX_UPLOAD_BYTES = 256 * 1024 * 1024;
+const DEFAULT_SESSION_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_SESSION_POOL = 32;
+/**
+ * The base a session this server opens over its store fetches its package
+ * from. It names no host: every URL under it is answered in-process, from the
+ * store, by the same code that answers the package routes.
+ */
+const KEPT_ORIGIN = "udoc-server://kept";
+/** Build the server over `options.store`: its routes are the document routes (see `documentRoutes`), beneath `options.basePath`. */
+export function createUDocServer(options) {
+    const { udoc, store, basePath = "" } = options;
+    const maxUploadBytes = options.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES;
+    const sessions = new SessionPool((id) => reopen(udoc, store, id), options.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS, options.sessionPool ?? DEFAULT_SESSION_POOL);
+    const collaborations = new Collaborations(store, sessions, maxUploadBytes);
+    /** Every route the server answers: each family's, in turn. */
+    const routes = [...documentRoutes({ udoc, store, sessions, collaborations, maxUploadBytes })];
+    const upgradeRoutes = routes.filter((route) => route.upgrade !== undefined);
+    return {
+        handleRequest(request, response) {
+            const target = targetOf(request, basePath);
+            if (!target || !has(routes, target.path))
+                return false;
+            void answerRequest(routes, target, request, response);
+            return true;
+        },
+        handleUpgrade(request, socket, head) {
+            const target = targetOf(request, basePath);
+            if (!target || !has(upgradeRoutes, target.path))
+                return false;
+            answerUpgrade(routes, target, { request, socket, head }).catch(() => socket.destroy());
+            return true;
+        },
+        async close() {
+            await collaborations.close();
+            await sessions.closeAll();
+        },
+    };
+}
+/**
+ * Open document `id` again from what is kept of it in `store`: its package,
+ * over the store — the latest checkpoint's parts and blobs read as the
+ * document needs them, the way a browser streams it, and the edit log applied
+ * by the open.
+ */
+async function reopen(udoc, store, id) {
+    try {
+        if (!(await store.getDescription(id)))
+            throw noDocument(id);
+        return await udoc.openRemote(`${KEPT_ORIGIN}/documents/${id}/package`, (url) => kept(store, id, url));
+    }
+    catch (error) {
+        if (error instanceof HttpFailure)
+            throw error;
+        const failure = UDocError.from(error);
+        if (LICENSE_CODES.has(failure.code))
+            throw failure;
+        // It opened once to be kept, so a failure now is this server's,
+        // not the caller's: it answers as one.
+        throw new UDocError("internal", failure.message, undefined, { cause: failure });
+    }
+}
+/** What a session this server opened over document `id`'s store asks for at `url`, read from the store. */
+async function kept(store, id, url) {
+    const base = `/documents/${id}/package`;
+    const { pathname, searchParams } = new URL(url);
+    if (pathname !== base && !pathname.startsWith(`${base}/`))
+        throw notFound();
+    return (await readPackage(store, id, pathname.slice(base.length), searchParams)).body;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/session-pool.d.ts

@@ -0,0 +1,19 @@
+import type { UDocSession } from "@docmentis/udoc-node";
+/**
+ * The open sessions, by document id: each opened on the first request that
+ * needs it, kept while requests keep coming, and closed once idle or once more
+ * than its size are open — least recently used first, and never while a request
+ * is using it. A closed one is opened again, from the store, by the next
+ * request for it.
+ */
+export declare class SessionPool {
+    #private;
+    constructor(open: (id: string) => Promise<UDocSession>, sessionTimeoutMs: number, size: number);
+    /** Run `use` on document `id`'s session, opening it if it isn't open. */
+    use<T>(id: string, use: (session: UDocSession) => Promise<T>): Promise<T>;
+    /** Close document `id`'s session, if one is open. */
+    close(id: string): Promise<void>;
+    /** Close every open session. */
+    closeAll(): Promise<void>;
+}
+//# sourceMappingURL=session-pool.d.ts.map

package/dist/session-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-pool.d.ts","sourceRoot":"","sources":["../src/session-pool.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAexD;;;;;;GAMG;AACH,qBAAa,WAAW;;gBAMR,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,EAAE,gBAAgB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAM9F,yEAAyE;IACnE,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAe/E,qDAAqD;IAC/C,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtC,gCAAgC;IAC1B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAoDlC"}

package/dist/session-pool.js

@@ -0,0 +1,95 @@
+// The sessions open over what the server keeps: a cache, one per document on
+// a thread of its own (see `@docmentis/udoc-node`) — opened when a request
+// needs it, kept while requests keep coming, closed once idle or once too many
+// are open, and reopened the next time. That is what bounds how much the
+// process holds.
+import { clearTimeout, setTimeout } from "node:timers";
+/**
+ * The open sessions, by document id: each opened on the first request that
+ * needs it, kept while requests keep coming, and closed once idle or once more
+ * than its size are open — least recently used first, and never while a request
+ * is using it. A closed one is opened again, from the store, by the next
+ * request for it.
+ */
+export class SessionPool {
+    #pooled = new Map();
+    #open;
+    #sessionTimeoutMs;
+    #size;
+    constructor(open, sessionTimeoutMs, size) {
+        this.#open = open;
+        this.#sessionTimeoutMs = sessionTimeoutMs;
+        this.#size = size;
+    }
+    /** Run `use` on document `id`'s session, opening it if it isn't open. */
+    async use(id, use) {
+        const pooled = this.#pooled.get(id) ?? this.#pool(id, this.#open(id));
+        pooled.busy++;
+        clearTimeout(pooled.idle);
+        pooled.idle = undefined;
+        this.#trim();
+        try {
+            return await use(await pooled.session);
+        }
+        finally {
+            pooled.busy--;
+            pooled.lastUsed = Date.now();
+            this.#settleIdle(id, pooled);
+        }
+    }
+    /** Close document `id`'s session, if one is open. */
+    async close(id) {
+        const pooled = this.#pooled.get(id);
+        if (pooled)
+            await this.#close(id, pooled);
+    }
+    /** Close every open session. */
+    async closeAll() {
+        await Promise.all([...this.#pooled].map(([id, pooled]) => this.#close(id, pooled)));
+    }
+    #pool(id, session) {
+        const pooled = { session, busy: 0, lastUsed: Date.now(), idle: undefined };
+        this.#pooled.set(id, pooled);
+        session.then(
+        // However it ends — closed here, or its engine gone — it is no
+        // longer this document's session, and the next request reopens.
+        (opened) => void opened.closed.then(() => this.#forget(id, pooled)), 
+        // An open that failed holds nothing; the next request tries again.
+        () => this.#forget(id, pooled));
+        return pooled;
+    }
+    /** Once nothing is using `pooled`, start its idle clock and keep to the pool's size. */
+    #settleIdle(id, pooled) {
+        if (pooled.busy > 0 || this.#pooled.get(id) !== pooled)
+            return;
+        pooled.idle = setTimeout(() => void this.#close(id, pooled), this.#sessionTimeoutMs);
+        // An idle clock is no reason for the process to stay up.
+        pooled.idle.unref();
+        this.#trim();
+    }
+    /** Close idle sessions, least recently used first, until no more than the pool's size are open. */
+    #trim() {
+        while (this.#pooled.size > this.#size) {
+            let oldest;
+            for (const entry of this.#pooled) {
+                if (entry[1].busy === 0 && (!oldest || entry[1].lastUsed < oldest[1].lastUsed))
+                    oldest = entry;
+            }
+            // Every open session is in use: the size is kept as they finish.
+            if (!oldest)
+                return;
+            void this.#close(...oldest);
+        }
+    }
+    async #close(id, pooled) {
+        this.#forget(id, pooled);
+        await pooled.session.then((session) => session.close(), () => { });
+    }
+    #forget(id, pooled) {
+        if (this.#pooled.get(id) !== pooled)
+            return;
+        clearTimeout(pooled.idle);
+        this.#pooled.delete(id);
+    }
+}
+//# sourceMappingURL=session-pool.js.map

package/dist/session-pool.js.map

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

package/dist/store.d.ts

@@ -0,0 +1,115 @@
+import type { FileFormat, UDocType } from "@docmentis/udoc-node";
+/** A document's upload, as it arrived, and the format it was imported as. */
+export interface Original {
+    bytes: Uint8Array;
+    format: FileFormat;
+}
+/** What is kept of one document when it is imported. */
+export interface KeptDocument {
+    original: Original;
+    /** Its first checkpoint, `v0`: the udoc package its import saved. */
+    checkpoint: Uint8Array;
+}
+/**
+ * A CRDT frontier as the engine writes it: `[peer, counter]` pairs, each a
+ * `u64`. A peer is random, past what a JS number holds exactly, so each is a
+ * `bigint`.
+ */
+export type Frontier = [peer: bigint, counter: bigint][];
+/** What a client opening a package needs to know of it. */
+export interface PackageDescription {
+    docType: UDocType;
+    /** Absent for a document not imported from a file. */
+    sourceFormat?: FileFormat;
+    /** The character a CSV source split its fields by; absent for any other source. */
+    sourceDelimiter?: string;
+    /** The latest checkpoint's version. */
+    baselineVersion: number;
+    /**
+     * Where the edit log replays from — present exactly when there is one:
+     * the latest checkpoint's own frontier, or, over `v0`, a flat baseline the
+     * whole log was made over, the empty frontier.
+     */
+    baselineFrontier?: Frontier;
+}
+/**
+ * A route's segments under `…/package` (docs/design/node-streaming.md): a
+ * part's kind in kebab-case and plural, its id's key — `replica-counter` in
+ * hex — and a blob's key. A route is held to them before it reaches a store,
+ * so none names a path outside.
+ */
+export declare const KINDS: RegExp;
+export declare const PART_ID: RegExp;
+export declare const BLOB_KEY: RegExp;
+/** Where the server keeps each document, by id. */
+export interface DocumentStore {
+    /** Keep a new document as `id`. Refused when `id` is already kept. */
+    put(id: string, document: KeptDocument): Promise<void>;
+    /** Document `id`'s original, or `undefined` when nothing is kept. */
+    getOriginal(id: string): Promise<Original | undefined>;
+    /** Document `id`'s latest checkpoint, or `undefined` when nothing is kept. */
+    getCheckpoint(id: string): Promise<Uint8Array | undefined>;
+    /**
+     * Keep `checkpoint`, the udoc package of document `id`'s checkpoint
+     * `version`, beside the earlier ones, as its latest; then forget each
+     * opaque part and blob kept beside them that it holds. Refused when no
+     * checkpoint is kept as `id`, or `version` is kept already.
+     */
+    putCheckpoint(id: string, version: number, checkpoint: Uint8Array): Promise<void>;
+    /** Document `id`'s package description, from its latest checkpoint, or `undefined` when it has none. */
+    getDescription(id: string): Promise<PackageDescription | undefined>;
+    /**
+     * One part of document `id`, as its JSON deflated — raw DEFLATE (RFC
+     * 1951) — by its route: `kinds`, its kind in kebab-case and plural, and
+     * `partId`, its id's key. Its latest checkpoint's, or an opaque part an
+     * edit brought, kept beside the checkpoints, or, held by neither, the
+     * newest earlier checkpoint's. `undefined` when there is no such part, or
+     * no checkpoint.
+     */
+    getPart(id: string, kinds: string, partId: string): Promise<Uint8Array | undefined>;
+    /**
+     * One blob of document `id`, deflated, by its key — found as a part is —
+     * or `undefined` when it has none.
+     */
+    getBlob(id: string, key: string): Promise<Uint8Array | undefined>;
+    /**
+     * Keep every part and blob of `parts` — a client's `opaque parts`,
+     * a zip in a package's own layout — beside document `id`'s checkpoints, by
+     * route. What is kept already stays as it was. Refused when nothing is
+     * kept as `id`.
+     */
+    putOpaqueParts(id: string, parts: Uint8Array): Promise<void>;
+    /**
+     * Document `id`'s edit log, or `undefined` when it has none: the one kept,
+     * or, for a document checkpointed before any edit was kept, its latest
+     * checkpoint's own.
+     */
+    getLog(id: string): Promise<Uint8Array | undefined>;
+    /**
+     * Keep `log` as document `id`'s edit log, in place of the one kept — whole
+     * or not at all. Refused when nothing is kept as `id`.
+     */
+    putLog(id: string, log: Uint8Array): Promise<void>;
+    /** Forget document `id`; answers whether anything was kept. */
+    delete(id: string): Promise<boolean>;
+}
+/**
+ * A {@link DocumentStore} over a directory: one directory per document, named
+ * by its id, holding its original, its checkpoints and its edit log.
+ */
+export declare class DirectoryDocumentStore implements DocumentStore {
+    #private;
+    constructor(directory: string);
+    put(id: string, document: KeptDocument): Promise<void>;
+    getOriginal(id: string): Promise<Original | undefined>;
+    getCheckpoint(id: string): Promise<Uint8Array | undefined>;
+    putCheckpoint(id: string, version: number, checkpoint: Uint8Array): Promise<void>;
+    getDescription(id: string): Promise<PackageDescription | undefined>;
+    getPart(id: string, kinds: string, partId: string): Promise<Uint8Array | undefined>;
+    getBlob(id: string, key: string): Promise<Uint8Array | undefined>;
+    putOpaqueParts(id: string, parts: Uint8Array): Promise<void>;
+    getLog(id: string): Promise<Uint8Array | undefined>;
+    putLog(id: string, log: Uint8Array): Promise<void>;
+    delete(id: string): Promise<boolean>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

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