A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
feat(desktop): add the engine host protocol and sqlite cache
Hampus7a925a253e9b
diff --git a/fluxer_desktop/src/engine/CacheDatabase.ts b/fluxer_desktop/src/engine/CacheDatabase.tsnew file mode 100644index 000000000..2a1c0446a--- /dev/null+++ b/fluxer_desktop/src/engine/CacheDatabase.ts@@ -0,0 +1,498 @@+// SPDX-License-Identifier: AGPL-3.0-or-later++import * as fs from 'node:fs';+import {DatabaseSync, type SQLOutputValue, type StatementSync} from 'node:sqlite';+import type {EngineClock, EngineTimer} from '@electron/engine/EngineClock';+import type {+ AccountEngineSnapshotCursor,+ AccountEngineSnapshotEntries,+} from '@fluxer/desktop_ipc/src/AccountEngineContract';+import {ACCOUNT_ENGINE_CORE_SCHEMA_EPOCH_OFFSET} from '@fluxer/desktop_ipc/src/AccountEngineCoreContract';+import {isRecord} from '@fluxer/record_utils/src/RecordGuards';++const ENGINE_CACHE_EPOCH = 1;+const CACHE_COMMIT_INTERVAL_MS = 250;+const CACHE_COMMIT_MAX_OPS = 4000;+export const CACHE_ACCOUNT_MAX_ROWS = 2_000_000;+export const CACHE_ACCOUNT_MAX_VALUE_BYTES = 1024 * 1024 * 1024;+const MENTION_PRUNE_SLACK = 50;+const SQLITE_PRIMARY_RESULT_MASK = 0xff;+const SQLITE_CORRUPT = 11;+const SQLITE_NOTADB = 26;++const SCHEMA = `+CREATE TABLE IF NOT EXISTS meta(key TEXT PRIMARY KEY, value TEXT);+CREATE TABLE IF NOT EXISTS rows(account_key TEXT, entity TEXT, key TEXT, value TEXT,+ PRIMARY KEY(account_key, entity, key)) WITHOUT ROWID;+CREATE TABLE IF NOT EXISTS cursors(account_key TEXT PRIMARY KEY, session_id TEXT, schema_epoch INTEGER, updated_at INTEGER);+CREATE TABLE IF NOT EXISTS summaries(account_key TEXT PRIMARY KEY, json TEXT, updated_at INTEGER);+CREATE TABLE IF NOT EXISTS mentions(account_key TEXT, message_id TEXT, created_at INTEGER, json TEXT,+ PRIMARY KEY(account_key, message_id)) WITHOUT ROWID;+CREATE INDEX IF NOT EXISTS mentions_by_time ON mentions(account_key, created_at DESC, message_id DESC);+`;++interface CacheAccountUsage {+ rows: number;+ bytes: number;+}++interface CacheOpenReport {+ readonly reset: 'none' | 'epoch' | 'corrupt';+ readonly memoryFallback: string | null;+}++function prefixUpperBound(prefix: string): string | null {+ const codePoints = Array.from(prefix);+ const last = codePoints.pop()?.codePointAt(0);+ if (last === undefined || last >= 0x10ffff) {+ return null;+ }+ return codePoints.join('') + String.fromCodePoint(last + 1);+}++function removeDatabaseFiles(path: string): void {+ for (const suffix of ['', '-wal', '-shm']) {+ fs.rmSync(`${path}${suffix}`, {force: true});+ }+}++function closeQuietly(db: DatabaseSync | null): void {+ try {+ db?.close();+ } catch {}+}++function readStoredEpoch(db: DatabaseSync): string | null {+ const row = db.prepare('SELECT value FROM meta WHERE key = ?').get('schema_epoch') as+ | {value: string | null}+ | undefined;+ return row?.value ?? null;+}++function writeStoredEpoch(db: DatabaseSync, schemaEpoch: string): void {+ db.prepare('INSERT OR REPLACE INTO meta(key, value) VALUES (?, ?)').run('schema_epoch', schemaEpoch);+}++function openMemoryDatabase(schemaEpoch: string): DatabaseSync {+ const db = new DatabaseSync(':memory:');+ db.exec(SCHEMA);+ writeStoredEpoch(db, schemaEpoch);+ return db;+}++function ensurePrivateFile(path: string): void {+ const handle = fs.openSync(path, 'a', 0o600);+ fs.closeSync(handle);+ try {+ fs.chmodSync(path, 0o600);+ } catch {}+}++interface Statements {+ readonly getMeta: StatementSync;+ readonly setMeta: StatementSync;+ readonly getRow: StatementSync;+ readonly rowLength: StatementSync;+ readonly upsertRow: StatementSync;+ readonly deleteRow: StatementSync;+ readonly rowsByEntity: StatementSync;+ readonly rowsByRange: StatementSync;+ readonly rowsFrom: StatementSync;+ readonly deleteEntity: StatementSync;+ readonly entityUsage: StatementSync;+ readonly allRows: StatementSync;+ readonly deleteAccountRows: StatementSync;+ readonly getCursor: StatementSync;+ readonly setCursor: StatementSync;+ readonly deleteCursor: StatementSync;+ readonly setSummary: StatementSync;+ readonly allSummaries: StatementSync;+ readonly deleteSummary: StatementSync;+ readonly insertMention: StatementSync;+ readonly pruneMentions: StatementSync;+ readonly listMentions: StatementSync;+ readonly deleteMentions: StatementSync;+ readonly countMentions: StatementSync;+ readonly accountUsage: StatementSync;+}++export class CacheDatabase {+ private readonly path: string;+ private readonly clock: EngineClock;+ private db: DatabaseSync;+ private statements: Statements;+ private readonly usage = new Map<string, CacheAccountUsage>();+ private readonly mentionCounts = new Map<string, number>();+ private inTransaction = false;+ private pendingOps = 0;+ private commitTimer: EngineTimer | null = null;+ private closed = false;+ readonly openReport: CacheOpenReport;++ constructor(path: string, snapshotSchemaEpoch: number, clock: EngineClock) {+ this.path = path;+ this.clock = clock;+ const schemaEpoch = String(ENGINE_CACHE_EPOCH * ACCOUNT_ENGINE_CORE_SCHEMA_EPOCH_OFFSET + snapshotSchemaEpoch);+ try {+ const {db, reset} = this.openFile(schemaEpoch);+ this.db = db;+ this.openReport = {reset, memoryFallback: null};+ } catch (error) {+ this.db = openMemoryDatabase(schemaEpoch);+ this.openReport = {reset: 'none', memoryFallback: error instanceof Error ? error.message : String(error)};+ }+ this.statements = this.prepareStatements();+ }++ getMeta(key: string): string | null {+ const row = this.statements.getMeta.get(key) as {value: string | null} | undefined;+ return row?.value ?? null;+ }++ setMeta(key: string, value: string): void {+ this.write(() => this.statements.setMeta.run(key, value));+ }++ usageFor(accountKey: string): CacheAccountUsage {+ const usage = this.mutableUsage(accountKey);+ return {rows: usage.rows, bytes: usage.bytes};+ }++ getRow(accountKey: string, entity: string, key: string): string | null {+ const row = this.statements.getRow.get(accountKey, entity, key) as {value: string} | undefined;+ return row?.value ?? null;+ }++ rowsByPrefix(accountKey: string, entity: string, prefix: string): Array<{key: string; value: string}> {+ const upper = prefixUpperBound(prefix);+ let rows: Array<Record<string, SQLOutputValue>>;+ if (prefix.length === 0) {+ rows = this.statements.rowsByEntity.all(accountKey, entity);+ } else if (upper === null) {+ rows = this.statements.rowsFrom.all(accountKey, entity, prefix);+ } else {+ rows = this.statements.rowsByRange.all(accountKey, entity, prefix, upper);+ }+ const result: Array<{key: string; value: string}> = [];+ for (const row of rows as Array<{key: string; value: string}>) {+ if (prefix.length === 0 || row.key.startsWith(prefix)) {+ result.push({key: row.key, value: row.value});+ }+ }+ return result;+ }++ upsertRow(accountKey: string, entity: string, key: string, value: string): void {+ const previous = this.statements.rowLength.get(accountKey, entity, key) as {size: number} | undefined;+ const usage = this.mutableUsage(accountKey);+ this.write(() => this.statements.upsertRow.run(accountKey, entity, key, value));+ if (previous === undefined) {+ usage.rows += 1;+ usage.bytes += Buffer.byteLength(value, 'utf8');+ } else {+ usage.bytes += Buffer.byteLength(value, 'utf8') - previous.size;+ }+ }++ deleteRow(accountKey: string, entity: string, key: string): void {+ const previous = this.statements.rowLength.get(accountKey, entity, key) as {size: number} | undefined;+ if (previous === undefined) {+ return;+ }+ const usage = this.mutableUsage(accountKey);+ this.write(() => this.statements.deleteRow.run(accountKey, entity, key));+ usage.rows -= 1;+ usage.bytes -= previous.size;+ }++ deleteRowsByPrefix(accountKey: string, entity: string, prefix: string): void {+ for (const row of this.rowsByPrefix(accountKey, entity, prefix)) {+ this.deleteRow(accountKey, entity, row.key);+ }+ }++ replaceEntity(accountKey: string, entity: string, entries: ReadonlyArray<readonly [string, string]>): void {+ const previous = this.statements.entityUsage.get(accountKey, entity) as {rows: number; bytes: number | null};+ const usage = this.mutableUsage(accountKey);+ this.write(() => {+ this.statements.deleteEntity.run(accountKey, entity);+ for (const [key, value] of entries) {+ this.statements.upsertRow.run(accountKey, entity, key, value);+ }+ }, entries.length + 1);+ usage.rows += entries.length - previous.rows;+ let bytes = 0;+ for (const [, value] of entries) {+ bytes += Buffer.byteLength(value, 'utf8');+ }+ usage.bytes += bytes - (previous.bytes ?? 0);+ }++ readCursor(accountKey: string): AccountEngineSnapshotCursor | null {+ const row = this.statements.getCursor.get(accountKey) as+ | {session_id: string | null; schema_epoch: number | null; updated_at: number}+ | undefined;+ if (row === undefined) {+ return null;+ }+ return {sessionId: row.session_id, schemaEpoch: row.schema_epoch, updatedAt: row.updated_at};+ }++ writeCursor(accountKey: string, cursor: AccountEngineSnapshotCursor): void {+ this.write(() =>+ this.statements.setCursor.run(accountKey, cursor.sessionId, cursor.schemaEpoch, Math.floor(cursor.updatedAt)),+ );+ }++ captureAccount(accountKey: string): AccountEngineSnapshotEntries {+ const entries: AccountEngineSnapshotEntries = {};+ for (const row of this.statements.allRows.iterate(accountKey) as Iterable<{+ entity: string;+ key: string;+ value: string;+ }>) {+ let entity = entries[row.entity];+ if (entity === undefined) {+ entity = {};+ entries[row.entity] = entity;+ }+ entity[row.key] = row.value;+ }+ return entries;+ }++ deleteAccountSnapshot(accountKey: string): void {+ this.write(() => {+ this.statements.deleteAccountRows.run(accountKey);+ this.statements.deleteCursor.run(accountKey);+ }, 2);+ this.usage.delete(accountKey);+ }++ purgeAccount(accountKey: string): void {+ this.write(() => {+ this.statements.deleteAccountRows.run(accountKey);+ this.statements.deleteCursor.run(accountKey);+ this.statements.deleteSummary.run(accountKey);+ this.statements.deleteMentions.run(accountKey);+ }, 4);+ this.usage.delete(accountKey);+ this.mentionCounts.delete(accountKey);+ this.commit();+ try {+ this.db.exec('PRAGMA wal_checkpoint(TRUNCATE)');+ } catch {}+ }++ writeSummary(accountKey: string, json: string): void {+ this.write(() => this.statements.setSummary.run(accountKey, json, this.clock.now()));+ }++ readSummaries(): Map<string, string> {+ const summaries = new Map<string, string>();+ for (const row of this.statements.allSummaries.all() as Array<{account_key: string; json: string}>) {+ summaries.set(row.account_key, row.json);+ }+ return summaries;+ }++ insertMention(accountKey: string, messageId: string, createdAt: number, json: string, keep: number): void {+ this.write(() => this.statements.insertMention.run(accountKey, messageId, createdAt, json));+ const count = (this.mentionCounts.get(accountKey) ?? this.countMentions(accountKey) - 1) + 1;+ if (count <= keep + MENTION_PRUNE_SLACK) {+ this.mentionCounts.set(accountKey, count);+ return;+ }+ this.write(() => this.statements.pruneMentions.run(accountKey, accountKey, keep));+ this.mentionCounts.set(accountKey, keep);+ }++ listMentions(accountKey: string, limit: number): Array<string> {+ return (this.statements.listMentions.all(accountKey, limit) as Array<{json: string}>).map((row) => row.json);+ }++ private countMentions(accountKey: string): number {+ return (this.statements.countMentions.get(accountKey) as {count: number}).count;+ }++ knownAccountKeys(): Set<string> {+ const keys = new Set<string>();+ for (const query of [+ 'SELECT account_key FROM cursors',+ 'SELECT account_key FROM summaries',+ 'SELECT DISTINCT account_key FROM mentions',+ 'SELECT DISTINCT account_key FROM rows',+ ]) {+ for (const row of this.db.prepare(query).all() as Array<{account_key: string}>) {+ keys.add(row.account_key);+ }+ }+ return keys;+ }++ commit(): void {+ if (this.commitTimer !== null) {+ this.clock.clearTimeout(this.commitTimer);+ this.commitTimer = null;+ }+ this.pendingOps = 0;+ if (!this.inTransaction) {+ return;+ }+ this.inTransaction = false;+ this.db.exec('COMMIT');+ }++ close(): void {+ if (this.closed) {+ return;+ }+ this.commit();+ this.closed = true;+ try {+ this.db.exec('PRAGMA wal_checkpoint(TRUNCATE)');+ } catch {}+ this.db.close();+ }++ private write<T>(run: () => T, ops = 1): T {+ if (this.closed) {+ throw new Error('The account engine cache is closed');+ }+ if (!this.inTransaction) {+ this.db.exec('BEGIN');+ this.inTransaction = true;+ }+ const result = run();+ this.pendingOps += ops;+ if (this.pendingOps >= CACHE_COMMIT_MAX_OPS) {+ this.commit();+ } else if (this.commitTimer === null) {+ this.commitTimer = this.clock.setTimeout(() => {+ this.commitTimer = null;+ this.commit();+ }, CACHE_COMMIT_INTERVAL_MS);+ }+ return result;+ }++ private mutableUsage(accountKey: string): CacheAccountUsage {+ let usage = this.usage.get(accountKey);+ if (usage === undefined) {+ const stored = this.statements.accountUsage.get(accountKey) as {rows: number; bytes: number | null};+ usage = {rows: stored.rows, bytes: stored.bytes ?? 0};+ this.usage.set(accountKey, usage);+ }+ return usage;+ }++ private openFile(schemaEpoch: string): {db: DatabaseSync; reset: CacheOpenReport['reset']} {+ let reset: CacheOpenReport['reset'] = 'none';+ let db = this.tryOpen();+ if (db === null) {+ reset = 'corrupt';+ removeDatabaseFiles(this.path);+ db = this.tryOpen();+ if (db === null) {+ throw new Error(`The account engine cache at ${this.path} cannot be opened`);+ }+ }+ try {+ const storedEpoch = readStoredEpoch(db);+ if (storedEpoch !== schemaEpoch) {+ if (storedEpoch !== null) {+ reset = 'epoch';+ db.close();+ removeDatabaseFiles(this.path);+ db = this.tryOpen();+ if (db === null) {+ throw new Error(`The account engine cache at ${this.path} cannot be recreated`);+ }+ }+ writeStoredEpoch(db, schemaEpoch);+ }+ } catch (error) {+ closeQuietly(db);+ throw error;+ }+ return {db, reset};+ }++ private tryOpen(): DatabaseSync | null {+ let db: DatabaseSync | null = null;+ try {+ ensurePrivateFile(this.path);+ db = new DatabaseSync(this.path);+ db.exec('PRAGMA journal_mode=WAL');+ db.exec('PRAGMA synchronous=NORMAL');+ db.exec('PRAGMA cache_size=-65536');+ db.exec('PRAGMA busy_timeout=2000');+ db.exec('PRAGMA secure_delete=ON');+ const check = db.prepare('PRAGMA quick_check').all() as Array<Record<string, unknown>>;+ const verdict = check.length === 1 ? Object.values(check[0])[0] : null;+ if (verdict !== 'ok') {+ db.close();+ return null;+ }+ db.exec(SCHEMA);+ return db;+ } catch (error) {+ closeQuietly(db);+ if (!isRecord(error) || error.code !== 'ERR_SQLITE_ERROR' || typeof error.errcode !== 'number') {+ throw error;+ }+ const primaryCode = error.errcode & SQLITE_PRIMARY_RESULT_MASK;+ if (primaryCode !== SQLITE_CORRUPT && primaryCode !== SQLITE_NOTADB) {+ throw error;+ }+ return null;+ }+ }++ private prepareStatements(): Statements {+ const db = this.db;+ return {+ getMeta: db.prepare('SELECT value FROM meta WHERE key = ?'),+ setMeta: db.prepare('INSERT OR REPLACE INTO meta(key, value) VALUES (?, ?)'),+ getRow: db.prepare('SELECT value FROM rows WHERE account_key = ? AND entity = ? AND key = ?'),+ rowLength: db.prepare(+ 'SELECT octet_length(value) AS size FROM rows WHERE account_key = ? AND entity = ? AND key = ?',+ ),+ upsertRow: db.prepare('INSERT OR REPLACE INTO rows(account_key, entity, key, value) VALUES (?, ?, ?, ?)'),+ deleteRow: db.prepare('DELETE FROM rows WHERE account_key = ? AND entity = ? AND key = ?'),+ rowsByEntity: db.prepare('SELECT key, value FROM rows WHERE account_key = ? AND entity = ?'),+ rowsByRange: db.prepare(+ 'SELECT key, value FROM rows WHERE account_key = ? AND entity = ? AND key >= ? AND key < ?',+ ),+ rowsFrom: db.prepare('SELECT key, value FROM rows WHERE account_key = ? AND entity = ? AND key >= ?'),+ deleteEntity: db.prepare('DELETE FROM rows WHERE account_key = ? AND entity = ?'),+ entityUsage: db.prepare(+ 'SELECT count(*) AS rows, total(octet_length(value)) AS bytes FROM rows WHERE account_key = ? AND entity = ?',+ ),+ allRows: db.prepare('SELECT entity, key, value FROM rows WHERE account_key = ?'),+ deleteAccountRows: db.prepare('DELETE FROM rows WHERE account_key = ?'),+ getCursor: db.prepare('SELECT session_id, schema_epoch, updated_at FROM cursors WHERE account_key = ?'),+ setCursor: db.prepare(+ 'INSERT OR REPLACE INTO cursors(account_key, session_id, schema_epoch, updated_at) VALUES (?, ?, ?, ?)',+ ),+ deleteCursor: db.prepare('DELETE FROM cursors WHERE account_key = ?'),+ setSummary: db.prepare('INSERT OR REPLACE INTO summaries(account_key, json, updated_at) VALUES (?, ?, ?)'),+ allSummaries: db.prepare('SELECT account_key, json FROM summaries'),+ deleteSummary: db.prepare('DELETE FROM summaries WHERE account_key = ?'),+ insertMention: db.prepare(+ 'INSERT OR REPLACE INTO mentions(account_key, message_id, created_at, json) VALUES (?, ?, ?, ?)',+ ),+ pruneMentions: db.prepare(+ 'DELETE FROM mentions WHERE account_key = ? AND message_id NOT IN (SELECT message_id FROM mentions WHERE account_key = ? ORDER BY created_at DESC, message_id DESC LIMIT ?)',+ ),+ listMentions: db.prepare(+ 'SELECT json FROM mentions WHERE account_key = ? ORDER BY created_at DESC, message_id DESC LIMIT ?',+ ),+ deleteMentions: db.prepare('DELETE FROM mentions WHERE account_key = ?'),+ countMentions: db.prepare('SELECT count(*) AS count FROM mentions WHERE account_key = ?'),+ accountUsage: db.prepare(+ 'SELECT count(*) AS rows, total(octet_length(value)) AS bytes FROM rows WHERE account_key = ?',+ ),+ };+ }+}diff --git a/fluxer_desktop/src/engine/EngineClock.ts b/fluxer_desktop/src/engine/EngineClock.tsnew file mode 100644index 000000000..1062d63fd--- /dev/null+++ b/fluxer_desktop/src/engine/EngineClock.ts@@ -0,0 +1,21 @@+// SPDX-License-Identifier: AGPL-3.0-or-later++export type EngineTimer = unknown;++export interface EngineClock {+ now(): number;+ setTimeout(callback: () => void, delayMs: number): EngineTimer;+ clearTimeout(timer: EngineTimer): void;+ random(): number;+}++export const systemClock: EngineClock = Object.freeze({+ now: () => Date.now(),+ setTimeout: (callback: () => void, delayMs: number) => {+ const timer = setTimeout(callback, Math.max(0, delayMs));+ timer.unref?.();+ return timer;+ },+ clearTimeout: (timer: EngineTimer) => clearTimeout(timer as ReturnType<typeof setTimeout>),+ random: () => Math.random(),+});diff --git a/fluxer_desktop/src/engine/HostChannel.ts b/fluxer_desktop/src/engine/HostChannel.tsnew file mode 100644index 000000000..63e8052bf--- /dev/null+++ b/fluxer_desktop/src/engine/HostChannel.ts@@ -0,0 +1,105 @@+// SPDX-License-Identifier: AGPL-3.0-or-later++import type {EngineToHostMessage, HostToEngineMessage} from '@electron/engine/HostProtocol';++export interface EngineMessagePort {+ postMessage(message: unknown): void;+ close(): void;+ onMessage(listener: (message: unknown) => void): void;+ onClose(listener: () => void): void;+}++interface RawPort {+ postMessage(message: unknown): void;+ close(): void;+ on(event: string, listener: (...args: Array<unknown>) => void): unknown;+ start?: () => void;+}++function isMessageEventLike(value: unknown): value is {data: unknown; ports: unknown} {+ return typeof value === 'object' && value !== null && 'data' in value && 'ports' in value;+}++function wrapEngineMessagePort(raw: RawPort): EngineMessagePort {+ return {+ postMessage: (message) => raw.postMessage(message),+ close: () => raw.close(),+ onMessage: (listener) => {+ raw.on('message', (event: unknown) => listener(isMessageEventLike(event) ? event.data : event));+ raw.start?.();+ },+ onClose: (listener) => {+ raw.on('close', () => listener());+ },+ };+}++export type HostMessageListener = (message: HostToEngineMessage, port: EngineMessagePort | null) => void;++interface ParentPortLike {+ postMessage(message: unknown): void;+ on(event: 'message', listener: (event: unknown) => void): unknown;+}++function extractPort(event: unknown, data: unknown): RawPort | null {+ if (isMessageEventLike(event) && Array.isArray(event.ports) && event.ports.length > 0) {+ return event.ports[0] as RawPort;+ }+ const candidate = (data as {port?: unknown} | null)?.port;+ if (typeof candidate === 'object' && candidate !== null && 'postMessage' in candidate) {+ return candidate as RawPort;+ }+ return null;+}++export class HostChannel {+ private readonly post: (message: EngineToHostMessage) => void;+ private listener: HostMessageListener | null = null;++ private constructor(+ post: (message: EngineToHostMessage) => void,+ subscribe: (deliver: (event: unknown) => void) => void,+ ) {+ this.post = post;+ subscribe((event) => {+ const data = isMessageEventLike(event) ? event.data : event;+ if (typeof data !== 'object' || data === null || typeof (data as {type?: unknown}).type !== 'string') {+ return;+ }+ const raw = extractPort(event, data);+ this.listener?.(data as HostToEngineMessage, raw === null ? null : wrapEngineMessagePort(raw));+ });+ }++ static async connect(): Promise<HostChannel> {+ const electronParent = (process as unknown as {parentPort?: ParentPortLike}).parentPort;+ if (electronParent != null) {+ return new HostChannel(+ (message) => electronParent.postMessage(message),+ (deliver) => electronParent.on('message', deliver),+ );+ }+ const {parentPort} = await import('node:worker_threads');+ if (parentPort != null) {+ return new HostChannel(+ (message) => parentPort.postMessage(message),+ (deliver) => parentPort.on('message', deliver),+ );+ }+ if (typeof process.send === 'function') {+ return new HostChannel(+ (message) => process.send?.(message),+ (deliver) => process.on('message', deliver),+ );+ }+ throw new Error('The account engine has no host to talk to');+ }++ onMessage(listener: HostMessageListener): void {+ this.listener = listener;+ }++ send(message: EngineToHostMessage): void {+ this.post(message);+ }+}diff --git a/fluxer_desktop/src/engine/HostProtocol.ts b/fluxer_desktop/src/engine/HostProtocol.tsnew file mode 100644index 000000000..129244173--- /dev/null+++ b/fluxer_desktop/src/engine/HostProtocol.ts@@ -0,0 +1,119 @@+// SPDX-License-Identifier: AGPL-3.0-or-later++import {ACCOUNT_ENGINE_LIMITS, type AccountEngineAccountSummary} from '@fluxer/desktop_ipc/src/AccountEngineContract';+import {isObjectLike} from '@fluxer/record_utils/src/RecordGuards';++export const ACCOUNT_ENGINE_HOST_PROTOCOL_VERSION = 1;++export interface EngineAccountRecord {+ readonly accountKey: string;+ readonly userId: string;+ readonly instanceKey: string;+ readonly token: string;+ readonly gatewayEndpoint: string;+ readonly apiEndpoint: string;+ readonly isValid: boolean;+ readonly lastActive: number;+}++export type EnginePowerEvent = 'suspend' | 'resume' | 'lock-screen' | 'unlock-screen' | 'online' | 'offline';++export interface EngineInitMessage {+ readonly type: 'init';+ readonly protocol: number;+ readonly cachePath: string;+ readonly foregroundHint: string | null;+ readonly accounts: ReadonlyArray<EngineAccountRecord>;+ readonly accountsComplete: boolean;+ readonly preferWebSocket: boolean;+ readonly trustedCertificates: ReadonlyArray<string>;+}++export type HostToEngineMessage =+ | EngineInitMessage+ | {readonly type: 'accounts'; readonly accounts: ReadonlyArray<EngineAccountRecord>}+ | {readonly type: 'attachRenderer'}+ | {readonly type: 'detachRenderer'}+ | {+ readonly type: 'admitResult';+ readonly requestId: number;+ readonly ok: boolean;+ readonly url: string | null;+ readonly address: string | null;+ readonly error: string | null;+ }+ | {+ readonly type: 'httpResult';+ readonly requestId: number;+ readonly ok: boolean;+ readonly status: number;+ readonly body: string | null;+ readonly error: string | null;+ }+ | {+ readonly type: 'tokenPersisted';+ readonly accountKey: string;+ readonly previousToken: string;+ readonly token: string;+ readonly outcome: EngineTokenPersistOutcome;+ }+ | {readonly type: 'power'; readonly event: EnginePowerEvent}+ | {readonly type: 'shutdown'};++export type EngineTokenPersistOutcome = 'persisted' | 'rejected' | 'renderer';++export type EngineLogLevel = 'debug' | 'info' | 'warn' | 'error';++export type EngineToHostMessage =+ | {readonly type: 'ready'; readonly transport: 'native' | 'websocket'; readonly transportError: string | null}+ | {readonly type: 'admit'; readonly requestId: number; readonly accountKey: string; readonly url: string}+ | {+ readonly type: 'http';+ readonly requestId: number;+ readonly accountKey: string;+ readonly method: 'POST';+ readonly path: string;+ readonly body: string | null;+ }+ | {readonly type: 'tokenRotated'; readonly accountKey: string; readonly previousToken: string; readonly token: string}+ | {readonly type: 'summaries'; readonly summaries: ReadonlyArray<AccountEngineAccountSummary>}+ | {readonly type: 'removed'; readonly accountKeys: ReadonlyArray<string>}+ | {readonly type: 'health'; readonly rss: number; readonly heapUsed: number; readonly sessions: number}+ | {readonly type: 'log'; readonly level: EngineLogLevel; readonly message: string; readonly detail: string | null}+ | {readonly type: 'shutdownComplete'};++const TOKEN_MAX_LENGTH = 4096;++function isBoundedString(value: unknown, max: number): value is string {+ return typeof value === 'string' && value.length > 0 && value.length <= max;+}++export function parseEngineAccountRecord(value: unknown): EngineAccountRecord | null {+ if (!isObjectLike(value)) {+ return null;+ }+ const record = value;+ if (+ !isBoundedString(record.accountKey, ACCOUNT_ENGINE_LIMITS.accountKeyMaxChars) ||+ !isBoundedString(record.userId, 64) ||+ !isBoundedString(record.instanceKey, ACCOUNT_ENGINE_LIMITS.accountKeyMaxChars) ||+ !isBoundedString(record.token, TOKEN_MAX_LENGTH) ||+ !isBoundedString(record.gatewayEndpoint, ACCOUNT_ENGINE_LIMITS.endpointMaxChars) ||+ !isBoundedString(record.apiEndpoint, ACCOUNT_ENGINE_LIMITS.endpointMaxChars) ||+ typeof record.isValid !== 'boolean' ||+ typeof record.lastActive !== 'number' ||+ !Number.isFinite(record.lastActive)+ ) {+ return null;+ }+ return {+ accountKey: record.accountKey,+ userId: record.userId,+ instanceKey: record.instanceKey,+ token: record.token,+ gatewayEndpoint: record.gatewayEndpoint,+ apiEndpoint: record.apiEndpoint,+ isValid: record.isValid,+ lastActive: record.lastActive,+ };+}