@minionry/minion 0.7.36

package/dist/server/services/collab/session.js

@@ -0,0 +1,489 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { rebaseUpdates } from '@codemirror/collab';
+import { ChangeSet, Text } from '@codemirror/state';
+import { minimalChange } from './text-diff.js';
+import { COLLAB_DISK_CLIENT_ID, COLLAB_IDLE_MS, COLLAB_INGEST_WRITE_DELAY_MS, COLLAB_LOG_MAX_BYTES, COLLAB_LOG_MAX_ENTRIES, COLLAB_MAX_DOC_BYTES, COLLAB_PERSIST_DEBOUNCE_MS, COLLAB_PERSIST_MAX_WAIT_MS, COLLAB_STALE_MS, } from './types.js';
+export class CollabSession {
+    key;
+    host;
+    doc;
+    version = 0;
+    baseVersion = 0;
+    log = [];
+    logBytes = 0;
+    participants = new Map();
+    persistedText;
+    persistedVersion = 0;
+    lastWriteStat;
+    lastModifiedAt;
+    persistTimer = null;
+    persistCeilingTimer = null;
+    persistingNow = false;
+    ended = false;
+    constructor(key, host, initial) {
+        this.key = key;
+        this.host = host;
+        this.doc = textOf(initial.text);
+        this.persistedText = initial.text;
+        this.lastWriteStat = initial.stat;
+        this.lastModifiedAt = initial.modifiedAt;
+    }
+    join(req, requestPath) {
+        const existing = this.participants.get(req.clientID);
+        if (existing && existing.viewerId !== req.viewerId) {
+            this.host.unicast(req.viewerId, 'collabError', {
+                path: requestPath,
+                operation: 'collabJoin',
+                code: 'unsupported',
+                error: 'clientID is already in use by another device',
+            });
+            return;
+        }
+        const now = this.host.now();
+        const record = {
+            clientID: req.clientID,
+            viewerId: req.viewerId,
+            userId: req.userId,
+            name: req.name,
+            role: req.role,
+            canEdit: req.canEdit,
+            joinedAt: existing?.joinedAt ?? now,
+            idle: false,
+            active: req.active ?? existing?.active ?? true,
+            lastFrameAt: now,
+        };
+        this.participants.set(req.clientID, record);
+        this.host.unicast(req.viewerId, 'collabJoined', {
+            ...this.buildJoinedPayload(req),
+            path: requestPath,
+            clientID: req.clientID,
+            viewerId: req.viewerId,
+            canEdit: req.canEdit,
+        });
+        this.broadcastRoster();
+    }
+    buildJoinedPayload(req) {
+        const common = {
+            key: this.key,
+            version: this.version,
+            baseVersion: this.baseVersion,
+            participants: this.roster(),
+            persisted: { version: this.persistedVersion, modifiedAt: this.lastModifiedAt },
+        };
+        const resume = req.resume;
+        if (resume && resume.version >= this.baseVersion && resume.version <= this.version) {
+            return {
+                ...common,
+                resumed: true,
+                updates: this.logSince(resume.version).map(toWireUpdate),
+            };
+        }
+        return { ...common, resumed: false, doc: this.doc.toString() };
+    }
+    leave(clientID) {
+        if (!this.participants.delete(clientID))
+            return;
+        if (this.participants.size <= 1)
+            this.persist('leave');
+        this.broadcastRoster();
+    }
+    dropViewer(viewerId) {
+        let removed = false;
+        for (const [clientID, participant] of this.participants) {
+            if (participant.viewerId !== viewerId)
+                continue;
+            this.participants.delete(clientID);
+            removed = true;
+        }
+        if (!removed)
+            return false;
+        if (this.participants.size <= 1)
+            this.persist('leave');
+        this.broadcastRoster();
+        return true;
+    }
+    sweep() {
+        const now = this.host.now();
+        let rosterChanged = false;
+        for (const [clientID, participant] of this.participants) {
+            const quietFor = now - participant.lastFrameAt;
+            if (quietFor >= COLLAB_STALE_MS) {
+                this.participants.delete(clientID);
+                rosterChanged = true;
+                continue;
+            }
+            const idle = quietFor >= COLLAB_IDLE_MS;
+            if (idle !== participant.idle) {
+                participant.idle = idle;
+                rosterChanged = true;
+            }
+        }
+        if (!rosterChanged)
+            return;
+        if (this.participants.size <= 1)
+            this.persist('leave');
+        this.broadcastRoster();
+    }
+    dropSilentSince(cutoff) {
+        let removed = false;
+        for (const [clientID, participant] of this.participants) {
+            if (participant.lastFrameAt > cutoff)
+                continue;
+            this.participants.delete(clientID);
+            removed = true;
+        }
+        if (!removed)
+            return;
+        if (this.participants.size <= 1)
+            this.persist('leave');
+        this.broadcastRoster();
+    }
+    participantCount() {
+        return this.participants.size;
+    }
+    hasParticipant(clientID) {
+        return this.participants.has(clientID);
+    }
+    roster() {
+        return [...this.participants.values()].map(({ lastFrameAt: _lastFrameAt, ...participant }) => participant);
+    }
+    broadcastRoster() {
+        this.host.broadcast('collabRoster', { key: this.key, participants: this.roster() });
+    }
+    push(clientID, viewerId, atVersion, updates) {
+        const participant = this.participants.get(clientID);
+        if (!participant) {
+            this.rejectPush(viewerId, clientID, 'not_participant');
+            return;
+        }
+        participant.lastFrameAt = this.host.now();
+        if (participant.idle) {
+            participant.idle = false;
+            this.broadcastRoster();
+        }
+        const rejection = this.acceptPush(participant, atVersion, updates);
+        if (rejection)
+            this.rejectPush(viewerId, clientID, rejection.reason);
+    }
+    acceptPush(participant, atVersion, updates) {
+        if (!participant.canEdit)
+            return { reason: 'read_only' };
+        if (!Number.isInteger(atVersion))
+            return { reason: 'malformed' };
+        if (atVersion > this.version)
+            return { reason: 'ahead' };
+        if (atVersion < this.baseVersion)
+            return { reason: 'stale' };
+        const parsed = this.parseUpdates(atVersion, updates);
+        if (!parsed)
+            return { reason: 'malformed' };
+        const rebased = atVersion < this.version ? rebaseUpdates(parsed, this.overSince(atVersion)) : parsed;
+        if (rebased.length === 0)
+            return { reason: 'duplicate' };
+        if (rebased[0].changes.length !== this.doc.length)
+            return { reason: 'malformed' };
+        const finalLength = rebased[rebased.length - 1].changes.newLength;
+        if (finalLength > COLLAB_MAX_DOC_BYTES)
+            return { reason: 'too_large' };
+        const fromVersion = this.version;
+        for (const update of rebased) {
+            this.applyAccepted(update.changes, update.clientID);
+        }
+        this.host.broadcast('collabUpdate', {
+            key: this.key,
+            fromVersion,
+            toVersion: this.version,
+            updates: rebased.map(toWireUpdate),
+        });
+        this.schedulePersist();
+        return null;
+    }
+    parseUpdates(atVersion, updates) {
+        if (!Array.isArray(updates) || updates.length === 0)
+            return null;
+        let expectedLength = this.lengthAtVersion(atVersion);
+        const parsed = [];
+        for (const update of updates) {
+            if (!update || typeof update.clientID !== 'string' || !update.clientID)
+                return null;
+            if (update.clientID === COLLAB_DISK_CLIENT_ID)
+                return null;
+            let changes;
+            try {
+                changes = ChangeSet.fromJSON(update.changes);
+            }
+            catch {
+                return null;
+            }
+            if (changes.length !== expectedLength)
+                return null;
+            expectedLength = changes.newLength;
+            parsed.push({ changes, clientID: update.clientID });
+        }
+        return parsed;
+    }
+    lengthAtVersion(version) {
+        if (version >= this.version)
+            return this.doc.length;
+        return this.log[version - this.baseVersion].changes.length;
+    }
+    overSince(version) {
+        return this.logSince(version).map((entry) => ({
+            changes: entry.changes.desc,
+            clientID: entry.clientID,
+        }));
+    }
+    logSince(version) {
+        return this.log.slice(Math.max(0, version - this.baseVersion));
+    }
+    applyAccepted(changes, clientID) {
+        this.doc = changes.apply(this.doc);
+        this.version += 1;
+        const byteSize = estimateChangeBytes(changes);
+        this.log.push({ version: this.version, changes, clientID, at: this.host.now(), byteSize });
+        this.logBytes += byteSize;
+        this.trimLog();
+    }
+    trimLog() {
+        while (this.log.length > COLLAB_LOG_MAX_ENTRIES ||
+            (this.log.length > 1 && this.logBytes > COLLAB_LOG_MAX_BYTES)) {
+            const dropped = this.log.shift();
+            if (!dropped)
+                break;
+            this.logBytes -= dropped.byteSize;
+            this.baseVersion = dropped.version;
+        }
+        if (this.logBytes < 0)
+            this.logBytes = 0;
+    }
+    rejectPush(viewerId, clientID, reason) {
+        this.host.unicast(viewerId, 'collabPushRejected', {
+            key: this.key,
+            clientID,
+            reason,
+            version: this.version,
+            baseVersion: this.baseVersion,
+        });
+    }
+    cursor(clientID, version, selection, active) {
+        const participant = this.participants.get(clientID);
+        if (!participant)
+            return false;
+        participant.lastFrameAt = this.host.now();
+        let rosterChanged = false;
+        if (participant.idle) {
+            participant.idle = false;
+            rosterChanged = true;
+        }
+        if (active !== undefined && active !== participant.active) {
+            participant.active = active;
+            rosterChanged = true;
+        }
+        if (rosterChanged)
+            this.broadcastRoster();
+        this.host.broadcast('collabCursor', {
+            key: this.key,
+            clientID,
+            version,
+            selection: normalizeSelection(selection),
+        });
+        return true;
+    }
+    touch(clientID) {
+        const participant = this.participants.get(clientID);
+        if (participant)
+            participant.lastFrameAt = this.host.now();
+    }
+    ingestDisk(newText) {
+        if (this.ended)
+            return false;
+        if (newText === this.persistedText)
+            return false;
+        const spec = minimalChange(this.persistedText, newText);
+        if (!spec)
+            return false;
+        const change = ChangeSet.of(spec, this.persistedText.length);
+        const over = this.logSince(this.persistedVersion);
+        let overDesc = null;
+        for (const entry of over) {
+            overDesc = overDesc ? overDesc.composeDesc(entry.changes.desc) : entry.changes.desc;
+        }
+        const rebasedChanges = overDesc ? change.map(overDesc) : change;
+        const fromVersion = this.version;
+        this.applyAccepted(rebasedChanges, COLLAB_DISK_CLIENT_ID);
+        this.host.broadcast('collabUpdate', {
+            key: this.key,
+            fromVersion,
+            toVersion: this.version,
+            updates: [{ changes: rebasedChanges.toJSON(), clientID: COLLAB_DISK_CLIENT_ID }],
+        });
+        this.persistedText = newText;
+        if (over.length === 0) {
+            this.persistedVersion = this.version;
+            this.refreshStatAfterExternalWrite();
+            this.host.broadcast('collabSaved', {
+                key: this.key,
+                version: this.version,
+                modifiedAt: this.lastModifiedAt,
+                bytes: Buffer.byteLength(newText, 'utf-8'),
+                source: 'ingest',
+            });
+        }
+        else {
+            this.schedulePersist(COLLAB_INGEST_WRITE_DELAY_MS, 'ingest');
+        }
+        return true;
+    }
+    refreshStatAfterExternalWrite() {
+        const stat = this.host.statFile();
+        if (stat) {
+            this.lastWriteStat = stat;
+            this.lastModifiedAt = new Date(stat.mtimeMs).toISOString();
+        }
+    }
+    isDirty() {
+        return this.doc.toString() !== this.persistedText;
+    }
+    lastStat() {
+        return this.lastWriteStat;
+    }
+    persistedContent() {
+        return this.persistedText;
+    }
+    schedulePersist(delayMs = COLLAB_PERSIST_DEBOUNCE_MS, source = 'debounce') {
+        if (this.ended)
+            return;
+        if (this.persistTimer)
+            clearTimeout(this.persistTimer);
+        this.persistTimer = setTimeout(() => {
+            this.persistTimer = null;
+            this.persist(source);
+        }, delayMs);
+        if (!this.persistCeilingTimer) {
+            this.persistCeilingTimer = setTimeout(() => {
+                this.persistCeilingTimer = null;
+                this.persist(source);
+            }, COLLAB_PERSIST_MAX_WAIT_MS);
+        }
+    }
+    clearPersistTimers() {
+        if (this.persistTimer) {
+            clearTimeout(this.persistTimer);
+            this.persistTimer = null;
+        }
+        if (this.persistCeilingTimer) {
+            clearTimeout(this.persistCeilingTimer);
+            this.persistCeilingTimer = null;
+        }
+    }
+    persist(source) {
+        if (this.ended || this.persistingNow)
+            return;
+        this.clearPersistTimers();
+        if (!this.isDirty()) {
+            this.catchUpPersistedVersion(source);
+            return;
+        }
+        this.persistingNow = true;
+        try {
+            this.ingestPendingDiskChange();
+            const text = this.doc.toString();
+            if (text === this.persistedText) {
+                this.catchUpPersistedVersion(source);
+                return;
+            }
+            const result = this.host.writeToDisk(text);
+            if (!result.success) {
+                console.error(`[collab] persist failed key=${this.key}: ${result.error ?? 'unknown error'}`);
+                return;
+            }
+            this.persistedText = text;
+            this.persistedVersion = this.version;
+            if (result.stat) {
+                this.lastWriteStat = result.stat;
+                this.lastModifiedAt = new Date(result.stat.mtimeMs).toISOString();
+            }
+            this.host.broadcast('collabSaved', {
+                key: this.key,
+                version: this.version,
+                modifiedAt: this.lastModifiedAt,
+                bytes: result.bytes ?? Buffer.byteLength(text, 'utf-8'),
+                source,
+            });
+        }
+        finally {
+            this.persistingNow = false;
+        }
+    }
+    catchUpPersistedVersion(source) {
+        if (this.persistedVersion === this.version)
+            return;
+        this.persistedVersion = this.version;
+        this.host.broadcast('collabSaved', {
+            key: this.key,
+            version: this.version,
+            modifiedAt: this.lastModifiedAt,
+            bytes: Buffer.byteLength(this.persistedText, 'utf-8'),
+            source,
+        });
+    }
+    ingestPendingDiskChange() {
+        const stat = this.host.statFile();
+        if (!stat)
+            return;
+        const known = this.lastWriteStat;
+        if (known && stat.mtimeMs === known.mtimeMs && stat.size === known.size)
+            return;
+        const onDisk = this.host.readFromDisk();
+        if (onDisk === null || onDisk === this.persistedText)
+            return;
+        this.ingestDisk(onDisk);
+    }
+    end(reason, options = {}) {
+        if (this.ended)
+            return;
+        if (options.persist)
+            this.persist(reason === 'shutdown' ? 'shutdown' : 'leave');
+        this.clearPersistTimers();
+        this.ended = true;
+        this.participants.clear();
+        this.host.broadcast('collabEnded', { key: this.key, reason });
+    }
+    isEnded() {
+        return this.ended;
+    }
+    getVersion() {
+        return this.version;
+    }
+    getBaseVersion() {
+        return this.baseVersion;
+    }
+    text() {
+        return this.doc.toString();
+    }
+}
+function textOf(value) {
+    return Text.of(value.split('\n'));
+}
+function toWireUpdate(entry) {
+    return { changes: entry.changes.toJSON(), clientID: entry.clientID };
+}
+function estimateChangeBytes(changes) {
+    try {
+        return JSON.stringify(changes.toJSON()).length;
+    }
+    catch {
+        return 256;
+    }
+}
+function normalizeSelection(selection) {
+    if (!selection)
+        return null;
+    const { anchor, head } = selection;
+    if (!Number.isInteger(anchor) || !Number.isInteger(head))
+        return null;
+    if (anchor < 0 || head < 0)
+        return null;
+    return { anchor, head };
+}

package/dist/server/services/collab/text-diff.js

@@ -0,0 +1,28 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { ChangeSet } from '@codemirror/state';
+export function minimalChange(base, next) {
+    if (base === next)
+        return null;
+    const minLen = Math.min(base.length, next.length);
+    let prefixLen = 0;
+    while (prefixLen < minLen && base[prefixLen] === next[prefixLen]) {
+        prefixLen++;
+    }
+    let baseSuffixStart = base.length;
+    let nextSuffixStart = next.length;
+    while (baseSuffixStart > prefixLen &&
+        nextSuffixStart > prefixLen &&
+        base[baseSuffixStart - 1] === next[nextSuffixStart - 1]) {
+        baseSuffixStart--;
+        nextSuffixStart--;
+    }
+    return {
+        from: prefixLen,
+        to: baseSuffixStart,
+        insert: next.slice(prefixLen, nextSuffixStart),
+    };
+}
+export function toChangeSet(spec, length) {
+    return ChangeSet.of(spec, length);
+}

package/dist/server/services/collab/types.js

@@ -0,0 +1,19 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+export const COLLAB_MAX_DOC_BYTES = 1_048_576;
+export const COLLAB_MAX_SESSIONS = 64;
+export const COLLAB_PERSIST_DEBOUNCE_MS = 800;
+export const COLLAB_PERSIST_MAX_WAIT_MS = 5_000;
+export const COLLAB_INGEST_WRITE_DELAY_MS = 100;
+export const COLLAB_WATCH_DEBOUNCE_MS = 100;
+export const COLLAB_WATCH_MISSING_GRACE_MS = 250;
+export const COLLAB_LOG_MAX_ENTRIES = 10_000;
+export const COLLAB_LOG_MAX_BYTES = 8 * 1024 * 1024;
+export const COLLAB_DRAIN_GRACE_MS = 15_000;
+export const COLLAB_DETACH_GRACE_MS = 60_000;
+export const COLLAB_IDLE_MS = 300_000;
+export const COLLAB_STALE_MS = 600_000;
+export const COLLAB_DISK_CLIENT_ID = 'disk';
+export const COLLAB_EVENT_BUFFER_MAX_EVENTS = 5_000;
+export const COLLAB_EVENT_BUFFER_MAX_AGE_MS = 15 * 60 * 1000;
+export const COLLAB_EVENT_BUFFER_MAX_BYTES = 8 * 1024 * 1024;