matrix-nodejs-homeserver 0.0.0-stage → 0.2.0

package/dist/adapters/cluster.js

@@ -0,0 +1,249 @@
+import { localCluster } from "../core/cluster.js";
+import { randomUUID } from "node:crypto";
+//#region src/adapters/cluster.ts
+/** Per-process queue so each instance holds at most one remote lock per key. */
+function localQueue() {
+	const tails = /* @__PURE__ */ new Map();
+	return async (key, fn) => {
+		const run = (tails.get(key) ?? Promise.resolve()).then(fn, fn);
+		const settled = run.catch(() => {});
+		tails.set(key, settled);
+		try {
+			return await run;
+		} finally {
+			if (tails.get(key) === settled) tails.delete(key);
+		}
+	};
+}
+const PG_CHANNEL = "matrix_cluster";
+const MAX_NOTIFY_PAYLOAD = 7e3;
+/**
+* Cluster adapter backed by PostgreSQL (`pg` Pool): sequences, advisory locks,
+* LISTEN/NOTIFY pub/sub and an expiring key-value table. Lets several homeserver
+* instances share one database.
+*/
+function postgresCluster(pool, options = {}) {
+	const seq = `"${options.tablePrefix ?? ""}cluster_sequences"`;
+	const kv = `"${options.tablePrefix ?? ""}cluster_kv"`;
+	const handlers = /* @__PURE__ */ new Map();
+	const queue = localQueue();
+	let listener = null;
+	let cleanup = null;
+	const ready = (async () => {
+		const setup = await pool.connect();
+		try {
+			await setup.query("BEGIN");
+			await setup.query("SELECT pg_advisory_xact_lock(hashtextextended('matrix_cluster_setup', 0))");
+			await setup.query(`CREATE TABLE IF NOT EXISTS ${seq} (name TEXT PRIMARY KEY, value BIGINT NOT NULL)`);
+			await setup.query(`CREATE TABLE IF NOT EXISTS ${kv} (key TEXT PRIMARY KEY, value TEXT NOT NULL, expires_at BIGINT)`);
+			await setup.query("COMMIT");
+		} catch (err) {
+			await setup.query("ROLLBACK").catch(() => {});
+			throw err;
+		} finally {
+			setup.release();
+		}
+		listener = await pool.connect();
+		listener.on("notification", (msg) => {
+			if (msg.channel !== PG_CHANNEL || !msg.payload) return;
+			(async () => {
+				let parsed = JSON.parse(msg.payload);
+				if (parsed.ref) {
+					const res = await pool.query(`SELECT value FROM ${kv} WHERE key = $1`, [parsed.ref]);
+					if (!res.rows[0]) return;
+					parsed = JSON.parse(res.rows[0].value);
+				}
+				for (const h of handlers.get(parsed.channel) ?? []) h(parsed.message);
+			})().catch(() => {});
+		});
+		await listener.query(`LISTEN ${PG_CHANNEL}`);
+		cleanup = setInterval(() => void pool.query(`DELETE FROM ${kv} WHERE expires_at IS NOT NULL AND expires_at < $1`, [Date.now()]).catch(() => {}), 6e4);
+		cleanup.unref?.();
+	})();
+	ready.catch(() => {});
+	const q = async (text, values) => {
+		await ready;
+		return pool.query(text, values);
+	};
+	return {
+		async nextId(name) {
+			const res = await q(`INSERT INTO ${seq} (name, value) VALUES ($1, 1) ON CONFLICT (name) DO UPDATE SET value = ${seq}.value + 1 RETURNING value`, [name]);
+			return Number(res.rows[0].value);
+		},
+		async currentId(name) {
+			const res = await q(`SELECT value FROM ${seq} WHERE name = $1`, [name]);
+			return res.rows[0] ? Number(res.rows[0].value) : 0;
+		},
+		async advance(name, value) {
+			await q(`INSERT INTO ${seq} (name, value) VALUES ($1, $2) ON CONFLICT (name) DO UPDATE SET value = GREATEST(${seq}.value, EXCLUDED.value)`, [name, value]);
+		},
+		lock(key, fn) {
+			return queue(key, async () => {
+				await ready;
+				const client = await pool.connect();
+				try {
+					await client.query("SELECT pg_advisory_lock(hashtextextended($1, 0))", [key]);
+					try {
+						return await fn();
+					} finally {
+						await client.query("SELECT pg_advisory_unlock(hashtextextended($1, 0))", [key]);
+					}
+				} finally {
+					client.release();
+				}
+			});
+		},
+		async publish(channel, message) {
+			let payload = JSON.stringify({
+				channel,
+				message
+			});
+			if (payload.length > MAX_NOTIFY_PAYLOAD) {
+				const ref = `pubsub:${randomUUID()}`;
+				await q(`INSERT INTO ${kv} (key, value, expires_at) VALUES ($1, $2, $3)`, [
+					ref,
+					payload,
+					Date.now() + 6e4
+				]);
+				payload = JSON.stringify({ ref });
+			}
+			await q("SELECT pg_notify($1, $2)", [PG_CHANNEL, payload]);
+		},
+		subscribe(channel, handler) {
+			let set = handlers.get(channel);
+			if (!set) handlers.set(channel, set = /* @__PURE__ */ new Set());
+			set.add(handler);
+		},
+		async get(key) {
+			const res = await q(`SELECT value FROM ${kv} WHERE key = $1 AND (expires_at IS NULL OR expires_at > $2)`, [key, Date.now()]);
+			return res.rows[0] ? JSON.parse(res.rows[0].value) : null;
+		},
+		async set(key, value, ttlMs) {
+			await q(`INSERT INTO ${kv} (key, value, expires_at) VALUES ($1, $2, $3) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, expires_at = EXCLUDED.expires_at`, [
+				key,
+				JSON.stringify(value),
+				ttlMs ? Date.now() + ttlMs : null
+			]);
+		},
+		async setIfAbsent(key, value, ttlMs) {
+			const now = Date.now();
+			return ((await q(`INSERT INTO ${kv} (key, value, expires_at) VALUES ($1, $2, $3)
+         ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, expires_at = EXCLUDED.expires_at
+         WHERE ${kv}.expires_at IS NOT NULL AND ${kv}.expires_at <= $4 RETURNING key`, [
+				key,
+				JSON.stringify(value),
+				ttlMs ? now + ttlMs : null,
+				now
+			])).rowCount ?? 0) > 0;
+		},
+		async delete(key) {
+			await q(`DELETE FROM ${kv} WHERE key = $1`, [key]);
+		},
+		async entries(prefix) {
+			const escaped = prefix.replace(/[\\%_]/g, (c) => `\\${c}`);
+			return (await q(`SELECT key, value FROM ${kv} WHERE key LIKE $1 AND (expires_at IS NULL OR expires_at > $2)`, [`${escaped}%`, Date.now()])).rows.map((r) => [r.key, JSON.parse(r.value)]);
+		},
+		async close() {
+			if (cleanup) clearInterval(cleanup);
+			if (listener) {
+				await listener.query(`UNLISTEN ${PG_CHANNEL}`).catch(() => {});
+				listener.release();
+			}
+		}
+	};
+}
+const UNLOCK = `if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end`;
+const EXTEND = `if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("pexpire", KEYS[1], ARGV[2]) else return 0 end`;
+/**
+* Cluster adapter backed by Redis (ioredis API). Pass two connections: one for
+* commands and one dedicated to subscriptions.
+*/
+function redisCluster(opts) {
+	const { client, subscriber } = opts;
+	const prefix = opts.prefix ?? "matrix:";
+	const channel = `${prefix}cluster`;
+	const handlers = /* @__PURE__ */ new Map();
+	const queue = localQueue();
+	const ready = subscriber.subscribe(channel);
+	subscriber.on("message", (ch, raw) => {
+		if (ch !== channel) return;
+		try {
+			const { channel: name, message } = JSON.parse(raw);
+			for (const h of handlers.get(name) ?? []) h(message);
+		} catch {}
+	});
+	const k = (key) => `${prefix}${key}`;
+	return {
+		async nextId(name) {
+			return Number(await client.incr(k(`seq:${name}`)));
+		},
+		async currentId(name) {
+			return Number(await client.get(k(`seq:${name}`)) ?? 0);
+		},
+		async advance(name, value) {
+			await client.eval(`local v = tonumber(redis.call("get", KEYS[1]) or "0") if v < tonumber(ARGV[1]) then redis.call("set", KEYS[1], ARGV[1]) end return 1`, 1, k(`seq:${name}`), value);
+		},
+		lock(key, fn) {
+			return queue(key, async () => {
+				const lockKey = k(`lock:${key}`);
+				const token = randomUUID();
+				const ttl = 3e4;
+				for (let delay = 5;; delay = Math.min(delay * 2, 200)) {
+					if (await client.set(lockKey, token, "PX", ttl, "NX") === "OK") break;
+					await new Promise((r) => setTimeout(r, delay));
+				}
+				const renew = setInterval(() => void client.eval(EXTEND, 1, lockKey, token, ttl).catch(() => {}), ttl / 3);
+				try {
+					return await fn();
+				} finally {
+					clearInterval(renew);
+					await client.eval(UNLOCK, 1, lockKey, token).catch(() => {});
+				}
+			});
+		},
+		async publish(name, message) {
+			await ready;
+			await client.publish(channel, JSON.stringify({
+				channel: name,
+				message
+			}));
+		},
+		subscribe(name, handler) {
+			let set = handlers.get(name);
+			if (!set) handlers.set(name, set = /* @__PURE__ */ new Set());
+			set.add(handler);
+		},
+		async get(key) {
+			const v = await client.get(k(`kv:${key}`));
+			return v === null ? null : JSON.parse(v);
+		},
+		async set(key, value, ttlMs) {
+			if (ttlMs) await client.set(k(`kv:${key}`), JSON.stringify(value), "PX", ttlMs);
+			else await client.set(k(`kv:${key}`), JSON.stringify(value));
+		},
+		async setIfAbsent(key, value, ttlMs) {
+			return (ttlMs ? await client.set(k(`kv:${key}`), JSON.stringify(value), "PX", ttlMs, "NX") : await client.set(k(`kv:${key}`), JSON.stringify(value), "NX")) === "OK";
+		},
+		async delete(key) {
+			await client.del(k(`kv:${key}`));
+		},
+		async entries(keyPrefix) {
+			const out = [];
+			let cursor = "0";
+			const pattern = `${k(`kv:${keyPrefix}`).replace(/[*?[\]]/g, (c) => `\\${c}`)}*`;
+			do {
+				const [next, keys] = await client.scan(cursor, "MATCH", pattern, "COUNT", 200);
+				cursor = next;
+				if (keys.length) {
+					const values = await client.mget(...keys);
+					keys.forEach((key, i) => {
+						if (values[i] !== null) out.push([key.slice(k("kv:").length), JSON.parse(values[i])]);
+					});
+				}
+			} while (cursor !== "0");
+			return out;
+		}
+	};
+}
+//#endregion
+export { localCluster, postgresCluster, redisCluster };

package/dist/adapters/media.d.ts

@@ -0,0 +1,50 @@
+//#region src/adapters/media.d.ts
+export interface MediaMetadata {
+  contentType: string | null;
+  filename: string | null;
+  size: number;
+}
+/** Stores the bytes of uploaded media. Metadata is kept in the database. */
+export interface MediaAdapter {
+  put(mediaId: string, data: Uint8Array, meta: MediaMetadata): Promise<void>;
+  get(mediaId: string): Promise<Uint8Array | null>;
+  delete?(mediaId: string): Promise<void>;
+  /** Maximum upload size in bytes. Default: 50 MiB. */
+  maxUploadSize?: number;
+}
+export interface ThumbnailRequest {
+  width: number;
+  height: number;
+  method: "crop" | "scale";
+  animated: boolean;
+}
+/**
+ * Produces a thumbnail. Return null to fall back to serving the original file
+ * (e.g. for unsupported formats).
+ */
+export type Thumbnailer = (data: Uint8Array, contentType: string, request: ThumbnailRequest) => Promise<{
+  data: Uint8Array;
+  contentType: string;
+} | null>;
+/** Minimal structural type of the `sharp` image library. */
+type SharpLike = (input: Uint8Array, options?: {
+  animated?: boolean;
+}) => {
+  resize(opts: {
+    width: number;
+    height: number;
+    fit: "cover" | "inside";
+    withoutEnlargement?: boolean;
+  }): {
+    toFormat(format: "webp" | "png" | "jpeg"): {
+      toBuffer(): Promise<Uint8Array>;
+    };
+  };
+};
+/** Thumbnailer backed by `sharp`: `thumbnailer: sharpThumbnailer(sharp)`. */
+export declare function sharpThumbnailer(sharp: SharpLike): Thumbnailer;
+export declare function memoryMedia(): MediaAdapter;
+/** Stores media as files inside `directory`. */
+export declare function filesystemMedia(directory: string): MediaAdapter;
+//#endregion
+export {};

package/dist/adapters/media.js

@@ -0,0 +1,63 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+//#region src/adapters/media.ts
+/** Thumbnailer backed by `sharp`: `thumbnailer: sharpThumbnailer(sharp)`. */
+function sharpThumbnailer(sharp) {
+	return async (data, contentType, req) => {
+		if (!/^image\/(png|jpeg|gif|webp|avif|tiff)$/.test(contentType)) return null;
+		const animated = req.animated && (contentType === "image/gif" || contentType === "image/webp");
+		const format = animated ? "webp" : contentType === "image/jpeg" ? "jpeg" : "png";
+		return {
+			data: await sharp(data, { animated }).resize({
+				width: req.width,
+				height: req.height,
+				fit: req.method === "crop" ? "cover" : "inside",
+				withoutEnlargement: true
+			}).toFormat(format).toBuffer(),
+			contentType: `image/${format}`
+		};
+	};
+}
+function memoryMedia() {
+	const store = /* @__PURE__ */ new Map();
+	return {
+		async put(id, data) {
+			store.set(id, data);
+		},
+		async get(id) {
+			return store.get(id) ?? null;
+		},
+		async delete(id) {
+			store.delete(id);
+		}
+	};
+}
+/** Stores media as files inside `directory`. */
+function filesystemMedia(directory) {
+	const root = resolve(directory);
+	const path = (id) => {
+		const file = resolve(root, id.replace(/[^A-Za-z0-9_-]/g, "_"));
+		if (dirname(file) !== root) throw new Error("Invalid media ID");
+		return file;
+	};
+	let ready = null;
+	return {
+		async put(id, data) {
+			ready ??= mkdir(directory, { recursive: true });
+			await ready;
+			await writeFile(path(id), data);
+		},
+		async get(id) {
+			try {
+				return await readFile(path(id));
+			} catch {
+				return null;
+			}
+		},
+		async delete(id) {
+			await rm(path(id), { force: true });
+		}
+	};
+}
+//#endregion
+export { filesystemMedia, memoryMedia, sharpThumbnailer };

package/dist/adapters/s3.d.ts

@@ -0,0 +1,33 @@
+import { MediaAdapter } from "./media.js";
+//#region src/adapters/s3.d.ts
+export interface S3MediaOptions {
+  bucket: string;
+  /** e.g. "us-east-1"; "auto" for Cloudflare R2. */
+  region: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  /** Temporary credentials (STS) also carry a session token. */
+  sessionToken?: string;
+  /**
+   * Service endpoint, for S3-compatible stores (MinIO, R2, Garage, Ceph...).
+   * Default: AWS, `https://s3.<region>.amazonaws.com`.
+   */
+  endpoint?: string;
+  /**
+   * Address the bucket as `<endpoint>/<bucket>/<key>` instead of `<bucket>.<endpoint>/<key>`.
+   * Default: true with a custom endpoint, false on AWS.
+   */
+  forcePathStyle?: boolean;
+  /** Key prefix for all objects, e.g. "matrix/media/". */
+  prefix?: string;
+  /** Maximum upload size in bytes. Default: 50 MiB. */
+  maxUploadSize?: number;
+  /** Per-request timeout in ms. Default: 30 s. */
+  timeoutMs?: number;
+}
+/**
+ * Media stored in an S3 bucket (AWS S3 or any S3-compatible store). Requests are signed with
+ * AWS Signature Version 4; no SDK is needed.
+ */
+export declare function s3Media(options: S3MediaOptions): MediaAdapter;
+//#endregion

package/dist/adapters/s3.js

@@ -0,0 +1,95 @@
+import { createHash, createHmac } from "node:crypto";
+//#region src/adapters/s3.ts
+const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+const hmac = (key, data) => createHmac("sha256", key).update(data).digest();
+const encodePath = (path) => path.split("/").map((s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)).join("/");
+/**
+* Media stored in an S3 bucket (AWS S3 or any S3-compatible store). Requests are signed with
+* AWS Signature Version 4; no SDK is needed.
+*/
+function s3Media(options) {
+	const endpoint = new URL(options.endpoint ?? `https://s3.${options.region}.amazonaws.com`);
+	const pathStyle = options.forcePathStyle ?? options.endpoint !== void 0;
+	const prefix = options.prefix ?? "";
+	const timeoutMs = options.timeoutMs ?? 3e4;
+	const objectUrl = (mediaId) => {
+		const key = prefix + mediaId.replace(/[^A-Za-z0-9_-]/g, "_");
+		const url = new URL(endpoint);
+		const base = endpoint.pathname.replace(/\/$/, "");
+		if (pathStyle) url.pathname = `${base}/${encodePath(options.bucket)}/${encodePath(key)}`;
+		else {
+			url.hostname = `${options.bucket}.${endpoint.hostname}`;
+			url.pathname = `${base}/${encodePath(key)}`;
+		}
+		return url;
+	};
+	const send = async (method, url, body, extra = {}) => {
+		const amzDate = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+		const day = amzDate.slice(0, 8);
+		const payloadHash = sha256(body ?? "");
+		const headers = {
+			host: url.host,
+			"x-amz-content-sha256": payloadHash,
+			"x-amz-date": amzDate,
+			...options.sessionToken ? { "x-amz-security-token": options.sessionToken } : {},
+			...Object.fromEntries(Object.entries(extra).map(([k, v]) => [k.toLowerCase(), v]))
+		};
+		const names = Object.keys(headers).sort();
+		const canonicalRequest = [
+			method,
+			url.pathname,
+			"",
+			names.map((n) => `${n}:${headers[n].trim()}\n`).join(""),
+			names.join(";"),
+			payloadHash
+		].join("\n");
+		const scope = `${day}/${options.region}/s3/aws4_request`;
+		const stringToSign = [
+			"AWS4-HMAC-SHA256",
+			amzDate,
+			scope,
+			sha256(canonicalRequest)
+		].join("\n");
+		const signingKey = hmac(hmac(hmac(hmac(`AWS4${options.secretAccessKey}`, day), options.region), "s3"), "aws4_request");
+		const signature = createHmac("sha256", signingKey).update(stringToSign).digest("hex");
+		const { host: _host, ...sent } = headers;
+		return fetch(url, {
+			method,
+			headers: {
+				...sent,
+				authorization: `AWS4-HMAC-SHA256 Credential=${options.accessKeyId}/${scope}, SignedHeaders=${names.join(";")}, Signature=${signature}`
+			},
+			body,
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+	};
+	const fail = async (what, res) => {
+		const text = await res.text().catch(() => "");
+		const code = /<Code>([^<]*)<\/Code>/.exec(text)?.[1];
+		throw new Error(`S3 ${what} failed: ${res.status}${code ? ` ${code}` : ""}`);
+	};
+	return {
+		maxUploadSize: options.maxUploadSize,
+		async put(mediaId, data, meta) {
+			const res = await send("PUT", objectUrl(mediaId), data, meta.contentType ? { "content-type": meta.contentType } : {});
+			if (!res.ok) await fail("upload", res);
+			await res.arrayBuffer();
+		},
+		async get(mediaId) {
+			const res = await send("GET", objectUrl(mediaId));
+			if (res.status === 404) {
+				await res.arrayBuffer();
+				return null;
+			}
+			if (!res.ok) await fail("download", res);
+			return new Uint8Array(await res.arrayBuffer());
+		},
+		async delete(mediaId) {
+			const res = await send("DELETE", objectUrl(mediaId));
+			if (!res.ok && res.status !== 404) await fail("delete", res);
+			await res.arrayBuffer();
+		}
+	};
+}
+//#endregion
+export { s3Media };