sh3-server 0.8.1 → 0.9.0

package/dist/doc-store/store.d.ts

@@ -0,0 +1,71 @@
+/**
+ * TenantDocStore — single entry point for tenant-document operations.
+ *
+ * Owns the write pipeline: version bump (primary) or pending (replica),
+ * policy-resolved syncMode caching, reserved-metadata filter, tick advance,
+ * conflict bucket on Mode B mismatch. Consumed by the docs HTTP router
+ * and by the ServerShardContext.documents(tenant) API.
+ */
+import type { DocumentMeta, SyncPolicy, ConflictFile } from 'sh3-core';
+import type { PolicyCache } from './policy.js';
+import type { TickCounter } from './tick.js';
+import type { PeerRoles } from './roles.js';
+import type { ConflictBucket, ConflictRef } from './conflicts.js';
+export interface TenantDocStoreDeps {
+    dataDir: string;
+    policy: PolicyCache;
+    tick: TickCounter;
+    roles: PeerRoles;
+    conflicts: ConflictBucket;
+}
+export interface ApplyFromPeerInput {
+    shardId: string;
+    path: string;
+    content: string | Buffer;
+    incomingVersion: number;
+    expectedLocalVersion: number;
+    origin: string;
+    deleted?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export type ApplyResult = {
+    applied: true;
+    version: number;
+} | {
+    applied: false;
+    reason: 'stale' | 'conflict' | 'conflict-extended';
+};
+export declare class TenantDocStore {
+    #private;
+    readonly roles: PeerRoles;
+    constructor(deps: TenantDocStoreDeps);
+    /** Root filesystem directory this store reads/writes under. */
+    get dataDir(): string;
+    /** Synchronous tenant enumeration for shard-ctx's `tenants()` entry point. */
+    listTenantsSync(): string[];
+    /**
+     * Persist `__sync__/policy.json` for a tenant and refresh the cached
+     * `syncMode` on every existing doc so subsequent reads match the new
+     * policy without a restart.
+     */
+    writePolicy(tenant: string, policy: SyncPolicy): Promise<void>;
+    read(tenant: string, shardId: string, path: string): Promise<string | null>;
+    readMeta(tenant: string, shardId: string, path: string): Promise<Record<string, unknown> | null>;
+    exists(tenant: string, shardId: string, path: string): Promise<boolean>;
+    list(tenant: string, shardId: string): Promise<DocumentMeta[]>;
+    listAll(tenant: string): Promise<(DocumentMeta & {
+        shardId: string;
+    })[]>;
+    getTick(tenant: string): Promise<number>;
+    readPolicy(tenant: string): Promise<SyncPolicy | null>;
+    invalidatePolicy(tenant: string): void;
+    write(tenant: string, shardId: string, path: string, content: string | Buffer, metadata?: Record<string, unknown>): Promise<{
+        version: number;
+        syncState: 'synced' | 'pending';
+    }>;
+    delete(tenant: string, shardId: string, path: string): Promise<void>;
+    applyFromPeer(tenant: string, input: ApplyFromPeerInput): Promise<ApplyResult>;
+    listConflicts(tenant: string): Promise<ConflictRef[]>;
+    readConflict(tenant: string, shardId: string, path: string): Promise<ConflictFile | null>;
+    resolveConflict(tenant: string, shardId: string, path: string, choice: 'local' | string | Buffer): Promise<void>;
+}

package/dist/doc-store/store.js

@@ -0,0 +1,336 @@
+/**
+ * TenantDocStore — single entry point for tenant-document operations.
+ *
+ * Owns the write pipeline: version bump (primary) or pending (replica),
+ * policy-resolved syncMode caching, reserved-metadata filter, tick advance,
+ * conflict bucket on Mode B mismatch. Consumed by the docs HTTP router
+ * and by the ServerShardContext.documents(tenant) API.
+ */
+import { readFile, writeFile, mkdir, rm, readdir, stat } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { resolveSyncMode } from './policy.js';
+import { filterReservedMeta } from './reserved.js';
+import { readMeta, writeMeta } from './meta.js';
+export class TenantDocStore {
+    #dataDir;
+    #policy;
+    #tick;
+    roles;
+    #conflicts;
+    constructor(deps) {
+        this.#dataDir = deps.dataDir;
+        this.#policy = deps.policy;
+        this.#tick = deps.tick;
+        this.roles = deps.roles;
+        this.#conflicts = deps.conflicts;
+    }
+    /** Root filesystem directory this store reads/writes under. */
+    get dataDir() { return this.#dataDir; }
+    /** Synchronous tenant enumeration for shard-ctx's `tenants()` entry point. */
+    listTenantsSync() {
+        const { readdirSync, existsSync } = require('node:fs');
+        const root = join(this.#dataDir, 'docs');
+        if (!existsSync(root))
+            return [];
+        return readdirSync(root, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    /**
+     * Persist `__sync__/policy.json` for a tenant and refresh the cached
+     * `syncMode` on every existing doc so subsequent reads match the new
+     * policy without a restart.
+     */
+    async writePolicy(tenant, policy) {
+        const p = join(this.#dataDir, 'docs', tenant, '__sync__', 'policy.json');
+        await mkdir(dirname(p), { recursive: true });
+        await writeFile(p, JSON.stringify(policy, null, 2));
+        this.#policy.invalidate(tenant);
+        const all = await this.listAll(tenant);
+        for (const entry of all) {
+            const meta = await readMeta(this.#dataDir, tenant, entry.shardId, entry.path);
+            if (!meta)
+                continue;
+            const newMode = resolveSyncMode(policy, entry.path);
+            if (meta.syncMode !== newMode) {
+                await writeMeta(this.#dataDir, tenant, entry.shardId, entry.path, { ...meta, syncMode: newMode });
+            }
+        }
+    }
+    // ---------- path helpers ----------
+    #contentPath(tenant, shardId, path) {
+        return join(this.#dataDir, 'docs', tenant, shardId, path);
+    }
+    // ---------- reads ----------
+    async read(tenant, shardId, path) {
+        try {
+            return await readFile(this.#contentPath(tenant, shardId, path), 'utf-8');
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    async readMeta(tenant, shardId, path) {
+        return readMeta(this.#dataDir, tenant, shardId, path);
+    }
+    async exists(tenant, shardId, path) {
+        try {
+            await stat(this.#contentPath(tenant, shardId, path));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async list(tenant, shardId) {
+        const root = join(this.#dataDir, 'docs', tenant, shardId);
+        return this.#enumerate(root, root, tenant, shardId);
+    }
+    async listAll(tenant) {
+        const root = join(this.#dataDir, 'docs', tenant);
+        const out = [];
+        let entries;
+        try {
+            entries = await readdir(root, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+        for (const e of entries) {
+            if (!e.isDirectory())
+                continue;
+            if (e.name.startsWith('__'))
+                continue; // reserved
+            const shardDir = join(root, e.name);
+            for (const m of await this.#enumerate(shardDir, shardDir, tenant, e.name)) {
+                out.push({ ...m, shardId: e.name });
+            }
+        }
+        return out;
+    }
+    async #enumerate(current, base, tenant, shardId) {
+        const out = [];
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return out;
+            throw err;
+        }
+        for (const e of entries) {
+            const full = join(current, e.name);
+            if (e.isDirectory()) {
+                out.push(...(await this.#enumerate(full, base, tenant, shardId)));
+                continue;
+            }
+            const rel = relative(base, full).split(/[/\\]/).join('/');
+            const s = await stat(full);
+            const meta = await readMeta(this.#dataDir, tenant, shardId, rel);
+            out.push({
+                path: rel,
+                size: s.size,
+                lastModified: s.mtimeMs,
+                ...(meta ?? {}),
+            });
+        }
+        return out;
+    }
+    // ---------- policy / tick passthroughs ----------
+    async getTick(tenant) {
+        return this.#tick.get(tenant);
+    }
+    async readPolicy(tenant) {
+        return this.#policy.get(tenant);
+    }
+    invalidatePolicy(tenant) {
+        this.#policy.invalidate(tenant);
+    }
+    // ---------- Mode A write ----------
+    async write(tenant, shardId, path, content, metadata) {
+        const role = this.roles.get(tenant);
+        const policy = await this.#policy.get(tenant);
+        const syncMode = resolveSyncMode(policy, path);
+        const prev = await readMeta(this.#dataDir, tenant, shardId, path);
+        const prevKnown = typeof prev?.lastKnownVersion === 'number' ? prev.lastKnownVersion : 0;
+        let version;
+        let syncState;
+        let lastKnownVersion;
+        if (role === 'primary') {
+            version = prevKnown + 1;
+            lastKnownVersion = version;
+            syncState = 'synced';
+        }
+        else {
+            // replica
+            version = prevKnown;
+            lastKnownVersion = prevKnown;
+            syncState = syncMode === 'local-only' ? 'synced' : 'pending';
+        }
+        // Write content first.
+        const cp = this.#contentPath(tenant, shardId, path);
+        await mkdir(dirname(cp), { recursive: true });
+        await writeFile(cp, content);
+        // Then metadata.
+        const custom = filterReservedMeta(metadata);
+        const mergedMeta = {
+            ...custom,
+            version,
+            syncMode,
+            syncState,
+            lastKnownVersion,
+        };
+        await writeMeta(this.#dataDir, tenant, shardId, path, mergedMeta);
+        if (role === 'primary')
+            await this.#tick.bump(tenant);
+        return { version, syncState };
+    }
+    // ---------- Mode A delete ----------
+    async delete(tenant, shardId, path) {
+        const role = this.roles.get(tenant);
+        const prev = await readMeta(this.#dataDir, tenant, shardId, path);
+        const prevKnown = typeof prev?.lastKnownVersion === 'number' ? prev.lastKnownVersion : 0;
+        // Remove content.
+        try {
+            await rm(this.#contentPath(tenant, shardId, path));
+        }
+        catch (err) {
+            if (err?.code !== 'ENOENT')
+                throw err;
+        }
+        let version;
+        let syncState;
+        let lastKnownVersion;
+        if (role === 'primary') {
+            version = prevKnown + 1;
+            lastKnownVersion = version;
+            syncState = 'synced';
+        }
+        else {
+            version = prevKnown;
+            lastKnownVersion = prevKnown;
+            syncState = 'pending';
+        }
+        await writeMeta(this.#dataDir, tenant, shardId, path, {
+            version,
+            lastKnownVersion,
+            syncState,
+            deleted: true,
+        });
+        if (role === 'primary')
+            await this.#tick.bump(tenant);
+    }
+    // ---------- Mode B — applyFromPeer ----------
+    async applyFromPeer(tenant, input) {
+        const { shardId, path, content, incomingVersion, expectedLocalVersion, origin } = input;
+        const prev = await readMeta(this.#dataDir, tenant, shardId, path);
+        const prevVersion = typeof prev?.version === 'number' ? prev.version : 0;
+        const prevState = prev?.syncState;
+        if (!prev) {
+            await this.#overwriteFromPeer(tenant, shardId, path, content, incomingVersion, origin, input.deleted);
+            return { applied: true, version: incomingVersion };
+        }
+        if (prevState === 'synced') {
+            if (prevVersion === expectedLocalVersion) {
+                await this.#overwriteFromPeer(tenant, shardId, path, content, incomingVersion, origin, input.deleted);
+                return { applied: true, version: incomingVersion };
+            }
+            return { applied: false, reason: 'stale' };
+        }
+        if (prevState === 'pending') {
+            const localContent = (await this.read(tenant, shardId, path)) ?? '';
+            await this.#conflicts.append(tenant, shardId, path, {
+                origin: 'local',
+                version: prevVersion,
+                content: localContent,
+                at: Date.now(),
+            });
+            await this.#conflicts.append(tenant, shardId, path, {
+                origin,
+                version: incomingVersion,
+                content: typeof content === 'string' ? content : content.toString('utf-8'),
+                at: Date.now(),
+            });
+            const merged = { ...(prev ?? {}), syncState: 'conflict' };
+            await writeMeta(this.#dataDir, tenant, shardId, path, merged);
+            return { applied: false, reason: 'conflict' };
+        }
+        // prevState === 'conflict'
+        await this.#conflicts.append(tenant, shardId, path, {
+            origin,
+            version: incomingVersion,
+            content: typeof content === 'string' ? content : content.toString('utf-8'),
+            at: Date.now(),
+        });
+        return { applied: false, reason: 'conflict-extended' };
+    }
+    async #overwriteFromPeer(tenant, shardId, path, content, version, origin, deleted) {
+        const cp = this.#contentPath(tenant, shardId, path);
+        if (deleted) {
+            try {
+                await rm(cp);
+            }
+            catch (err) {
+                if (err?.code !== 'ENOENT')
+                    throw err;
+            }
+        }
+        else {
+            await mkdir(dirname(cp), { recursive: true });
+            await writeFile(cp, content);
+        }
+        const policy = await this.#policy.get(tenant);
+        const syncMode = resolveSyncMode(policy, path);
+        await writeMeta(this.#dataDir, tenant, shardId, path, {
+            version,
+            lastKnownVersion: version,
+            syncMode,
+            syncState: 'synced',
+            origin,
+            lastSyncedAt: Date.now(),
+            ...(deleted ? { deleted: true } : {}),
+        });
+        // Primary accepting a push advances tick; replica pulling doesn't.
+        if (this.roles.get(tenant) === 'primary')
+            await this.#tick.bump(tenant);
+    }
+    // ---------- conflicts ----------
+    async listConflicts(tenant) {
+        return this.#conflicts.list(tenant);
+    }
+    async readConflict(tenant, shardId, path) {
+        return this.#conflicts.read(tenant, shardId, path);
+    }
+    async resolveConflict(tenant, shardId, path, choice) {
+        const cf = await this.#conflicts.read(tenant, shardId, path);
+        if (!cf)
+            return;
+        let content;
+        if (choice === 'local') {
+            const branch = cf.branches.find((b) => b.origin === 'local');
+            if (!branch)
+                throw new Error('No local branch to resolve');
+            content = branch.content;
+        }
+        else if (typeof choice === 'string') {
+            const branch = cf.branches.find((b) => b.origin === choice);
+            if (!branch)
+                throw new Error(`No branch with origin ${choice}`);
+            content = branch.content;
+        }
+        else {
+            content = choice;
+        }
+        // Clear the conflict FIRST so the subsequent write doesn't see stale state.
+        await this.#conflicts.clear(tenant, shardId, path);
+        // Force syncState back to 'synced' baseline so Mode A write can transition normally.
+        const prev = (await readMeta(this.#dataDir, tenant, shardId, path)) ?? {};
+        await writeMeta(this.#dataDir, tenant, shardId, path, { ...prev, syncState: 'synced' });
+        await this.write(tenant, shardId, path, content);
+    }
+}

package/dist/doc-store/tick.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Per-tenant monotonic tick counter. Lives at
+ *   {dataDir}/docs/<tenant>/__sync__/tick.json  => { tick: number, bumpedAt: number }
+ *
+ * Incremented on every version-advancing write. Never decreases. Persisted
+ * synchronously before write acknowledgement. In-memory cached after first read.
+ */
+export declare class TickCounter {
+    #private;
+    constructor(dataDir: string);
+    get(tenant: string): Promise<number>;
+    bump(tenant: string): Promise<number>;
+}

package/dist/doc-store/tick.js

@@ -0,0 +1,52 @@
+/**
+ * Per-tenant monotonic tick counter. Lives at
+ *   {dataDir}/docs/<tenant>/__sync__/tick.json  => { tick: number, bumpedAt: number }
+ *
+ * Incremented on every version-advancing write. Never decreases. Persisted
+ * synchronously before write acknowledgement. In-memory cached after first read.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export class TickCounter {
+    #dataDir;
+    #byTenant = new Map();
+    constructor(dataDir) {
+        this.#dataDir = dataDir;
+    }
+    async get(tenant) {
+        if (this.#byTenant.has(tenant))
+            return this.#byTenant.get(tenant);
+        const loaded = await this.#load(tenant);
+        this.#byTenant.set(tenant, loaded);
+        return loaded;
+    }
+    async bump(tenant) {
+        const current = await this.get(tenant);
+        const next = current + 1;
+        this.#byTenant.set(tenant, next);
+        await this.#persist(tenant, next);
+        return next;
+    }
+    #path(tenant) {
+        return join(this.#dataDir, 'docs', tenant, '__sync__', 'tick.json');
+    }
+    async #load(tenant) {
+        try {
+            const raw = await readFile(this.#path(tenant), 'utf-8');
+            const parsed = JSON.parse(raw);
+            return typeof parsed.tick === 'number' && Number.isFinite(parsed.tick)
+                ? Math.max(0, Math.floor(parsed.tick))
+                : 0;
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return 0;
+            throw err;
+        }
+    }
+    async #persist(tenant, value) {
+        const p = this.#path(tenant);
+        await mkdir(dirname(p), { recursive: true });
+        await writeFile(p, JSON.stringify({ tick: value, bumpedAt: Date.now() }));
+    }
+}

package/dist/fs-backend.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Filesystem-backed DocumentBackend for sh3-server.
+ *
+ * Storage layout mirrors the docs HTTP API:
+ *   <docsDir>/<tenantId>/<shardId>/<path>
+ *
+ * where docsDir = <dataDir>/docs
+ */
+import type { DocumentBackend } from 'sh3-core';
+export declare function createFsDocumentBackend(dataDir: string): DocumentBackend;

package/dist/fs-backend.js

@@ -0,0 +1,105 @@
+/**
+ * Filesystem-backed DocumentBackend for sh3-server.
+ *
+ * Storage layout mirrors the docs HTTP API:
+ *   <docsDir>/<tenantId>/<shardId>/<path>
+ *
+ * where docsDir = <dataDir>/docs
+ */
+import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync, statSync, readdirSync, } from 'node:fs';
+import { join, dirname, relative, resolve, sep } from 'node:path';
+function collectFiles(dir, base) {
+    const results = [];
+    if (!existsSync(dir))
+        return results;
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...collectFiles(full, base));
+        }
+        else {
+            const stat = statSync(full);
+            results.push({
+                path: relative(base, full).replace(/\\/g, '/'),
+                size: stat.size,
+                lastModified: stat.mtimeMs,
+            });
+        }
+    }
+    return results;
+}
+class FsDocumentBackend {
+    #docsDir;
+    constructor(dataDir) {
+        this.#docsDir = join(dataDir, 'docs');
+    }
+    #resolve(tenantId, shardId, path) {
+        const base = resolve(this.#docsDir, tenantId, shardId);
+        const resolved = resolve(base, path);
+        if (resolved !== base && !resolved.startsWith(base + sep)) {
+            throw new Error(`Path escapes tenant/shard boundary: ${path}`);
+        }
+        return resolved;
+    }
+    async read(tenantId, shardId, path) {
+        const resolved = this.#resolve(tenantId, shardId, path);
+        if (!existsSync(resolved))
+            return null;
+        const buf = readFileSync(resolved);
+        try {
+            return new TextDecoder('utf-8', { fatal: true }).decode(buf);
+        }
+        catch {
+            return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+        }
+    }
+    async write(tenantId, shardId, path, content) {
+        const resolved = this.#resolve(tenantId, shardId, path);
+        mkdirSync(dirname(resolved), { recursive: true });
+        if (typeof content === 'string') {
+            writeFileSync(resolved, content, 'utf-8');
+        }
+        else {
+            writeFileSync(resolved, Buffer.from(content));
+        }
+    }
+    async delete(tenantId, shardId, path) {
+        const resolved = this.#resolve(tenantId, shardId, path);
+        if (existsSync(resolved))
+            unlinkSync(resolved);
+    }
+    async list(tenantId, shardId) {
+        const dir = join(this.#docsDir, tenantId, shardId);
+        return collectFiles(dir, dir);
+    }
+    async exists(tenantId, shardId, path) {
+        return existsSync(this.#resolve(tenantId, shardId, path));
+    }
+    async listAllShards(tenantId) {
+        const tenantDir = join(this.#docsDir, tenantId);
+        if (!existsSync(tenantDir))
+            return [];
+        return readdirSync(tenantDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    async listAllDocuments(tenantId) {
+        const tenantDir = join(this.#docsDir, tenantId);
+        if (!existsSync(tenantDir))
+            return [];
+        const out = [];
+        for (const entry of readdirSync(tenantDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const shardDir = join(tenantDir, entry.name);
+            for (const f of collectFiles(shardDir, shardDir)) {
+                out.push({ ...f, shardId: entry.name });
+            }
+        }
+        return out;
+    }
+}
+export function createFsDocumentBackend(dataDir) {
+    return new FsDocumentBackend(dataDir);
+}

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export declare function createServer(options?: ServerOptions): Promise<{
     users: UserStore;
     sessions: SessionStore;
     settings: SettingsStore;
+    docStore: import("./doc-store/store.js").TenantDocStore;
     start(): Promise<void>;
 }>;
 export { KeyStore } from './keys.js';