@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/modules/mongo/kv.js

@@ -91,6 +91,37 @@ var createMongoKv = ({ db, collection = "action_kv" }) => {
 				_id: key,
 				$expr: LIVE
 			}, [{ $set: { expiresAt: expiryIn(ttlSeconds) } }]);
+		},
+		/**
+		* Each branch is one update Mongo applies to the document atomically. Expecting a value, the filter names it.
+		* Expecting nothing is two cases: a lapsed document, taken over by a filter that matches only a lapsed one; and no
+		* document, inserted by an upsert whose filter no stored document satisfies — so a live one makes it collide on
+		* `_id`, which is the refusal, not an error. (An upsert may not filter with `$expr`, or this would be one step.)
+		*/
+		swap: async (key, expected, next, ttlSeconds) => {
+			const keysNow = await store();
+			const write = [{ $set: {
+				value: next,
+				expiresAt: ttlSeconds === void 0 ? null : expiryIn(ttlSeconds)
+			} }];
+			if (expected !== void 0) return (await keysNow.updateOne({
+				_id: key,
+				value: expected,
+				$expr: LIVE
+			}, write)).matchedCount === 1;
+			if ((await keysNow.updateOne({
+				_id: key,
+				$expr: { $not: [LIVE] }
+			}, write)).matchedCount === 1) return true;
+			try {
+				return (await keysNow.updateOne({
+					_id: key,
+					value: { $exists: false }
+				}, write, { upsert: true })).upsertedCount === 1;
+			} catch (error) {
+				if (error.code === DUPLICATE_KEY) return false;
+				throw error;
+			}
 		}
 	};
 };

package/dist/modules/mysql/accounts.js

@@ -1,3 +1,4 @@
+import { activityDue } from "../../core/auth/sessionActivity.js";
 import { execute, selectOne, selectRows } from "./query.js";
 import { createSessionStore } from "./sessions.js";
 //#region src/modules/mysql/accounts.ts
@@ -50,12 +51,15 @@ var createAccountStore = (db, t) => {
 		* check — deactivating somebody has to end the session they are already holding, not just the next login.
 		*/
 		findAccountByToken: async (token) => {
-			const row = await selectOne(db, `SELECT ${ACCOUNT_COLUMNS}, s.expires_at AS session_expires_at
+			const row = await selectOne(db, `SELECT ${ACCOUNT_COLUMNS}, s.id AS session_id, s.expires_at AS session_expires_at,
+                s.last_active_at AS session_last_active_at
            FROM ${t.session} s
            JOIN ${t.account} a ON a.id = s.account_id
           WHERE s.token = ? AND a.status = 'active'
           LIMIT 1`, [token]);
 			if (!row) return;
+			const now = Math.floor(Date.now() / 1e3);
+			if (row.session_id !== void 0 && activityDue(row.session_last_active_at, now)) execute(db, `UPDATE ${t.session} SET last_active_at = ? WHERE id = ?`, [now, row.session_id]).catch(() => void 0);
 			const { roles, permissions } = await loadAccess(row.id);
 			return {
 				id: row.id,
@@ -120,15 +124,18 @@ var createAccountStore = (db, t) => {
 				]);
 				return;
 			}
-			await execute(db, `INSERT INTO ${t.session} (account_id, token, expires_at, refresh_token, refresh_expires_at, user_agent, ip)
-         VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+			await execute(db, `INSERT INTO ${t.session}
+           (account_id, token, expires_at, refresh_token, refresh_expires_at, user_agent, ip, app_name, app_id)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
 				userId,
 				session.token,
 				session.expiresAt,
 				session.refreshToken ?? null,
 				session.refreshExpiresAt ?? null,
 				context?.client?.userAgent?.slice(0, 255) ?? null,
-				context?.client?.ip ?? null
+				context?.client?.ip ?? null,
+				context?.client?.app?.name.slice(0, 120) ?? null,
+				context?.client?.app?.softwareId?.slice(0, 64) ?? null
 			]);
 		},
 		/**
@@ -335,22 +342,25 @@ var createAccountStore = (db, t) => {
 		* read whole and written whole, and a text column that a human can read in a crisis beats one they cannot.
 		*/
 		loadMfa: async (userId) => {
-			const row = await selectOne(db, `SELECT secret, confirmed_at, recovery_codes FROM ${t.mfa} WHERE account_id = ? LIMIT 1`, [userId]);
+			const row = await selectOne(db, `SELECT secret, confirmed_at, recovery_codes, last_used_step FROM ${t.mfa} WHERE account_id = ? LIMIT 1`, [userId]);
 			if (!row) return;
 			return {
 				secret: row.secret,
 				...row.confirmed_at !== null ? { confirmedAt: row.confirmed_at } : {},
-				recoveryCodes: (row.recovery_codes ?? "").split("\n").filter(Boolean)
+				recoveryCodes: (row.recovery_codes ?? "").split("\n").filter(Boolean),
+				...row.last_used_step !== null ? { lastUsedStep: row.last_used_step } : {}
 			};
 		},
 		saveMfa: async (userId, mfaRecord) => {
-			await execute(db, `INSERT INTO ${t.mfa} (account_id, secret, confirmed_at, recovery_codes) VALUES (?, ?, ?, ?)
+			await execute(db, `INSERT INTO ${t.mfa} (account_id, secret, confirmed_at, recovery_codes, last_used_step) VALUES (?, ?, ?, ?, ?)
          ON DUPLICATE KEY UPDATE
-           secret = VALUES(secret), confirmed_at = VALUES(confirmed_at), recovery_codes = VALUES(recovery_codes)`, [
+           secret = VALUES(secret), confirmed_at = VALUES(confirmed_at), recovery_codes = VALUES(recovery_codes),
+           last_used_step = VALUES(last_used_step)`, [
 				userId,
 				mfaRecord.secret,
 				mfaRecord.confirmedAt ?? null,
-				(mfaRecord.recoveryCodes ?? []).join("\n")
+				(mfaRecord.recoveryCodes ?? []).join("\n"),
+				mfaRecord.lastUsedStep ?? null
 			]);
 		},
 		deleteMfa: async (userId) => {

package/dist/modules/mysql/index.d.ts

@@ -63,5 +63,6 @@ export { TABLE_NAMES, tableNames } from './config';
 export { SCHEMA_VERSION } from './schema';
 export type { MysqlConfig, TableKey, Tables } from './config';
 export type { AccountSeed, MysqlAdmin, SpaceTokenSeed } from './admin';
-export type { SessionStore, SessionSummary } from './sessions';
+export type { SessionStore } from './sessions';
+export type { SessionSummary } from '../../core/auth/api';
 export type { IdentityStore, LinkedIdentity } from './identities';

package/dist/modules/mysql/jobs/index.d.ts

@@ -1,5 +1,5 @@
 export { createMysqlJobQueue } from './jobQueue';
 export { createMysqlKv } from './kv';
-export { mysqlJobSchemaStatements } from './schema';
+export { mysqlJobSchemaStatements, mysqlJobSchemaUpgrades } from './schema';
 export type { MysqlJobQueue, MysqlJobQueueOptions } from './jobQueue';
 export type { MysqlKvOptions } from './kv';

package/dist/modules/mysql/jobs/kv.js

@@ -71,6 +71,36 @@ var createMysqlKv = ({ pool, tablePrefix = "", createTables = true }) => {
 		},
 		expire: async (key, ttlSeconds) => {
 			await execute(await db(), `UPDATE ${kv} SET expires_at = ${NOW_MS} + ? WHERE k = ? AND ${LIVE}`, [ttlSeconds * 1e3, key]);
+		},
+		/**
+		* Each branch is ONE statement MySQL applies under the row's lock, so two writers racing for the same key cannot
+		* both win. `affectedRows` counts the rows MATCHED because mysql2 connects with `FOUND_ROWS`: without it, writing
+		* back the value a key already holds would read as a refusal. The comparison is on bytes — the table's collation
+		* ignores case and trailing spaces, and "unchanged" has to mean the same bytes.
+		*/
+		swap: async (key, expected, next, ttlSeconds) => {
+			const expiry = ttlSeconds === void 0 ? "NULL" : `${NOW_MS} + ?`;
+			const lifetime = ttlSeconds === void 0 ? [] : [ttlSeconds * 1e3];
+			const pool = await db();
+			if (expected !== void 0) return (await execute(pool, `UPDATE ${kv} SET v = ?, expires_at = ${expiry}
+          WHERE k = ? AND ${LIVE} AND CAST(v AS BINARY) = CAST(? AS BINARY)`, [
+				next,
+				...lifetime,
+				key,
+				expected
+			])).affectedRows === 1;
+			if ((await execute(pool, `UPDATE ${kv} SET v = ?, expires_at = ${expiry} WHERE k = ? AND NOT ${LIVE}`, [
+				next,
+				...lifetime,
+				key
+			])).affectedRows === 1) return true;
+			const inserted = await execute(pool, `INSERT IGNORE INTO ${kv} (k, v, expires_at) VALUES (?, ?, ${expiry})`, [
+				key,
+				next,
+				...lifetime
+			]);
+			await sweep();
+			return inserted.affectedRows === 1;
 		}
 	};
 };

package/dist/modules/mysql/jobs/schema.d.ts

@@ -16,8 +16,17 @@ export declare const jobTables: (prefix?: string) => JobTables;
  * Instants are epoch milliseconds in `BIGINT`, read from the SERVER's clock; `history` and `input` are JSON kept as
  * text, because they are only ever read whole. Separate from the account store's schema and its version: a deployment
  * can use either without the other.
+ *
+ * A `kv` key is BYTES, as it is in Redis and in memory: under a collation `Board` and `board` — and `a` and `a ` — were
+ * one key here and two everywhere else. A value is a `MEDIUMTEXT`: a `TEXT` stops at 64 KB, and past it MySQL
+ * refuses the write, or cuts it short where it is not strict.
  */
 export declare const mysqlJobSchemaStatements: (prefix?: string) => string[];
+/**
+ * What brings a `kv` table made before the columns above up to them — for a deployment that runs its own migrations,
+ * once. `ensureJobTables` does it by itself, and only when the table needs it: the `ALTER` copies the table.
+ */
+export declare const mysqlJobSchemaUpgrades: (prefix?: string) => string[];
 /** The server's now, in epoch ms, as an SQL expression — what every comparison reads instead of a caller's clock. */
 export declare const NOW_MS = "CAST(ROUND(UNIX_TIMESTAMP(NOW(3)) * 1000) AS SIGNED)";
 /** Creates the tables once per process, on first use; a failure is retried by the next call rather than remembered. */

package/dist/modules/mysql/jobs/schema.js

@@ -1,4 +1,4 @@
-import { execute } from "../query.js";
+import { execute, selectRows } from "../query.js";
 //#region src/modules/mysql/jobs/schema.ts
 var PREFIX = /^[A-Za-z0-9_]*$/;
 /**
@@ -20,6 +20,10 @@ var CHARSET = "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci"
 * Instants are epoch milliseconds in `BIGINT`, read from the SERVER's clock; `history` and `input` are JSON kept as
 * text, because they are only ever read whole. Separate from the account store's schema and its version: a deployment
 * can use either without the other.
+*
+* A `kv` key is BYTES, as it is in Redis and in memory: under a collation `Board` and `board` — and `a` and `a ` — were
+* one key here and two everywhere else. A value is a `MEDIUMTEXT`: a `TEXT` stops at 64 KB, and past it MySQL
+* refuses the write, or cuts it short where it is not strict.
 */
 var mysqlJobSchemaStatements = (prefix = "") => {
 	const t = jobTables(prefix);
@@ -68,14 +72,26 @@ var mysqlJobSchemaStatements = (prefix = "") => {
       KEY action_schedules_due (enabled, next_run_at)
     ) ${CHARSET}`,
 		`CREATE TABLE IF NOT EXISTS ${t.kv} (
-      k VARCHAR(191) NOT NULL,
-      v TEXT NOT NULL,
+      k VARBINARY(764) NOT NULL,
+      v MEDIUMTEXT NOT NULL,
       expires_at BIGINT NULL,
       PRIMARY KEY (k),
       KEY action_kv_expires (expires_at)
     ) ${CHARSET}`
 	];
 };
+/**
+* What brings a `kv` table made before the columns above up to them — for a deployment that runs its own migrations,
+* once. `ensureJobTables` does it by itself, and only when the table needs it: the `ALTER` copies the table.
+*/
+var mysqlJobSchemaUpgrades = (prefix = "") => [`ALTER TABLE ${jobTables(prefix).kv} MODIFY k VARBINARY(764) NOT NULL, MODIFY v MEDIUMTEXT NOT NULL`];
+/** Whether the `kv` table still has the columns it was first made with. */
+var kvNeedsUpgrade = async (db, prefix) => {
+	const columns = await selectRows(db, `SELECT COLUMN_NAME AS name, DATA_TYPE AS type FROM INFORMATION_SCHEMA.COLUMNS
+    WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME IN ('k', 'v')`, [`${prefix}action_kv`]);
+	const typeOf = (name) => columns.find((column) => column.name === name)?.type.toLowerCase();
+	return typeOf("k") !== "varbinary" || typeOf("v") !== "mediumtext";
+};
 /** The server's now, in epoch ms, as an SQL expression — what every comparison reads instead of a caller's clock. */
 var NOW_MS = "CAST(ROUND(UNIX_TIMESTAMP(NOW(3)) * 1000) AS SIGNED)";
 /** Creates the tables once per process, on first use; a failure is retried by the next call rather than remembered. */
@@ -85,6 +101,7 @@ var ensureJobTables = (db, prefix, create) => {
 		if (!create) return;
 		ready ??= (async () => {
 			for (const statement of mysqlJobSchemaStatements(prefix)) await execute(db, statement);
+			if (await kvNeedsUpgrade(db, prefix)) for (const statement of mysqlJobSchemaUpgrades(prefix)) await execute(db, statement);
 		})().catch((error) => {
 			ready = void 0;
 			throw error;
@@ -93,4 +110,4 @@ var ensureJobTables = (db, prefix, create) => {
 	};
 };
 //#endregion
-export { NOW_MS, ensureJobTables, jobTables, mysqlJobSchemaStatements };
+export { NOW_MS, ensureJobTables, jobTables, mysqlJobSchemaStatements, mysqlJobSchemaUpgrades };

package/dist/modules/mysql/schema.js

@@ -196,6 +196,23 @@ var step3 = (t) => {
 		...addIndex(account, "account_pending_email_token", "(pending_email_token)")
 	];
 };
+/**
+* What tells one device from another in the account's session list: the application holding it, when it is not a
+* browser (`Plitzi CLI on carlos-mbp`, software `plitzi-cli`), and when it was last used — see `sessionActivity`.
+*/
+var step4 = (t) => {
+	const session = unquote(t.session);
+	return [
+		...addColumn(session, "app_name", "VARCHAR(120) NULL AFTER ip"),
+		...addColumn(session, "app_id", "VARCHAR(64) NULL AFTER app_name"),
+		...addColumn(session, "last_active_at", "BIGINT NULL AFTER created_at")
+	];
+};
+/**
+* The time step of the last second-factor code accepted, so the same code cannot sign in twice within the window it
+* stays valid for (RFC 6238 §5.2) — see `MfaRecord.lastUsedStep`.
+*/
+var step5 = (t) => [...addColumn(unquote(t.mfa), "last_used_step", "BIGINT NULL AFTER recovery_codes")];
 /** Append only. A released version is never edited — the deployments that already ran it would never see the change. */
 var STEPS = [
 	{
@@ -209,6 +226,14 @@ var STEPS = [
 	{
 		version: 3,
 		statements: step3
+	},
+	{
+		version: 4,
+		statements: step4
+	},
+	{
+		version: 5,
+		statements: step5
 	}
 ];
 var SCHEMA_VERSION = STEPS[STEPS.length - 1].version;

package/dist/modules/mysql/sessions.d.ts

@@ -1,16 +1,6 @@
 import { Tables } from './config';
 import { Queryable } from './query';
-/** One signed-in device, as somebody looking at their own account should see it. Never the credential itself. */
-export interface SessionSummary {
-    id: number;
-    userAgent?: string;
-    ip?: string;
-    /** Unix seconds. */
-    createdAt: number;
-    expiresAt: number;
-    /** This is the session asking. A device list without it invites someone to revoke the one they are using. */
-    current: boolean;
-}
+import { SessionSummary } from '../../core/auth/api';
 /**
  * The sessions of one account, as a thing that can be looked at and taken away one at a time.
  *

package/dist/modules/mysql/sessions.js

@@ -9,14 +9,19 @@ import { execute, selectRows } from "./query.js";
 */
 var createSessionStore = (db, t) => {
 	const list = async (accountId, currentToken) => {
-		return (await selectRows(db, `SELECT id, token, user_agent, ip, created_at, expires_at
+		return (await selectRows(db, `SELECT id, token, user_agent, ip, app_name, app_id, created_at, last_active_at, expires_at
          FROM ${t.session}
         WHERE account_id = ?
         ORDER BY created_at DESC`, [accountId])).map((row) => ({
 			id: row.id,
 			...row.user_agent ? { userAgent: row.user_agent } : {},
 			...row.ip ? { ip: row.ip } : {},
+			...row.app_name ? { app: {
+				name: row.app_name,
+				...row.app_id ? { softwareId: row.app_id } : {}
+			} } : {},
 			createdAt: Math.floor(row.created_at.getTime() / 1e3),
+			...row.last_active_at ? { lastActiveAt: row.last_active_at } : {},
 			expiresAt: row.expires_at,
 			current: currentToken !== void 0 && row.token === currentToken
 		}));

package/dist/modules/realtime/declarations.d.ts

@@ -0,0 +1,11 @@
+import { ChannelDeclarations, OfflineDataRaw } from '@plitzi/sdk-shared';
+type GetOfflineData = (spaceId: number, environment: string, revision?: number) => Promise<OfflineDataRaw | undefined>;
+/**
+ * The channels a space declares, read from its schema and remembered for a few seconds.
+ *
+ * A publish is checked against them on every message; reading the space's documents for each one would cost more
+ * than the message. A space that changes its channels is heard within the TTL.
+ */
+export declare const createChannelResolver: (getOfflineData: GetOfflineData) => (spaceId: number, environment: string, revision?: number) => Promise<ChannelDeclarations | undefined>;
+export type ChannelResolver = ReturnType<typeof createChannelResolver>;
+export {};

package/dist/modules/realtime/declarations.js

@@ -0,0 +1,26 @@
+//#region src/modules/realtime/declarations.ts
+/** How long a space's channels are remembered: a publish is frequent, and a space's settings change rarely. */
+var TTL_MS = 5e3;
+/**
+* The channels a space declares, read from its schema and remembered for a few seconds.
+*
+* A publish is checked against them on every message; reading the space's documents for each one would cost more
+* than the message. A space that changes its channels is heard within the TTL.
+*/
+var createChannelResolver = (getOfflineData) => {
+	const cache = /* @__PURE__ */ new Map();
+	return (spaceId, environment, revision) => {
+		const key = `${spaceId}:${environment}:${revision ?? ""}`;
+		const hit = cache.get(key);
+		if (hit && Date.now() - hit.at < TTL_MS) return hit.channels;
+		const channels = getOfflineData(spaceId, environment, revision).then((data) => data?.schema.settings.channels);
+		cache.set(key, {
+			at: Date.now(),
+			channels
+		});
+		channels.catch(() => cache.delete(key));
+		return channels;
+	};
+};
+//#endregion
+export { createChannelResolver };

package/dist/modules/realtime/grants.d.ts

@@ -0,0 +1,23 @@
+import { RealtimeSpace } from './hub';
+import { ActionKvAdapter } from '../actions/types';
+/** How long a grant opens its topic when the flow does not say: a day, which outlives any one visit. */
+export declare const DEFAULT_GRANT_SECONDS = 86400;
+/** The longest a grant may last: thirty days. A page that stays open longer asks its action for a new one. */
+export declare const MAX_GRANT_SECONDS: number;
+export type RealtimeGrants = {
+    /** A grant for `topic`, good for `ttlSeconds` — what `realtime.grant` hands the page. */
+    issue: (space: RealtimeSpace, topic: string, ttlSeconds?: number) => Promise<string>;
+    /** Whether `grant` was issued for exactly `topic` of this space, and has neither run out nor been revoked. */
+    opens: (space: RealtimeSpace, topic: string, grant: string) => Promise<boolean>;
+    /** `grant` no longer opens `topic` — or, with none named, no grant issued for it until now does. */
+    revoke: (space: RealtimeSpace, topic: string, grant?: string) => Promise<void>;
+};
+export declare const grantSeconds: (ttlSeconds: number | undefined) => number;
+/**
+ * The grants a server has issued, kept in the store its actions' `kv` uses — so a grant one replica issued opens the
+ * topic on whichever replica the page connects to, and nothing new has to be configured for it. A random token rather
+ * than a signature: there is no secret to share between replicas, and a grant is only ever as old as its lifetime.
+ *
+ * Keyed under `realtime-grant:`, a prefix no key a flow writes can reach (theirs are `kv:action:<space>:…`).
+ */
+export declare const createRealtimeGrants: (store: ActionKvAdapter) => RealtimeGrants;

package/dist/modules/realtime/grants.js

@@ -0,0 +1,61 @@
+import { randomBytes } from "node:crypto";
+//#region src/modules/realtime/grants.ts
+/** How long a grant opens its topic when the flow does not say: a day, which outlives any one visit. */
+var DEFAULT_GRANT_SECONDS = 86400;
+/** The longest a grant may last: thirty days. A page that stays open longer asks its action for a new one. */
+var MAX_GRANT_SECONDS = 2592e3;
+/** What a grant looks like on the wire: long enough to be unguessable, and nothing a query string has to escape. */
+var TOKEN = /^[A-Za-z0-9_-]{24,64}$/;
+var parseGrant = (raw) => {
+	try {
+		const value = JSON.parse(raw ?? "");
+		return typeof value === "object" && value !== null && "topic" in value && typeof value.topic === "string" && "generation" in value && typeof value.generation === "number" ? {
+			topic: value.topic,
+			generation: value.generation
+		} : void 0;
+	} catch {
+		return;
+	}
+};
+var grantSeconds = (ttlSeconds) => ttlSeconds === void 0 || !Number.isFinite(ttlSeconds) ? DEFAULT_GRANT_SECONDS : Math.min(MAX_GRANT_SECONDS, Math.max(60, Math.floor(ttlSeconds)));
+/**
+* The grants a server has issued, kept in the store its actions' `kv` uses — so a grant one replica issued opens the
+* topic on whichever replica the page connects to, and nothing new has to be configured for it. A random token rather
+* than a signature: there is no secret to share between replicas, and a grant is only ever as old as its lifetime.
+*
+* Keyed under `realtime-grant:`, a prefix no key a flow writes can reach (theirs are `kv:action:<space>:…`).
+*/
+var createRealtimeGrants = (store) => {
+	const key = ({ spaceId, environment }, grant) => `realtime-grant:${String(spaceId)}:${environment}:${grant}`;
+	/**
+	* How many times every grant of a topic was revoked at once. A grant carries the number it was issued under, so
+	* raising it voids them all — the ones in use and the ones not used yet — without a list of them to walk.
+	*/
+	const generationKey = ({ spaceId, environment }, topic) => `realtime-grant-generation:${String(spaceId)}:${environment}:${topic}`;
+	const generationOf = async (space, topic) => Number(await store.get(generationKey(space, topic))) || 0;
+	return {
+		issue: async (space, topic, ttlSeconds) => {
+			const grant = randomBytes(18).toString("base64url");
+			const stored = {
+				topic,
+				generation: await generationOf(space, topic)
+			};
+			await store.set(key(space, grant), JSON.stringify(stored), grantSeconds(ttlSeconds));
+			return grant;
+		},
+		opens: async (space, topic, grant) => {
+			if (!TOKEN.test(grant)) return false;
+			const stored = parseGrant(await store.get(key(space, grant)));
+			return stored?.topic === topic && stored.generation === await generationOf(space, topic);
+		},
+		revoke: async (space, topic, grant) => {
+			if (grant === void 0) {
+				await store.increment(generationKey(space, topic), 1);
+				return;
+			}
+			if (TOKEN.test(grant) && parseGrant(await store.get(key(space, grant)))?.topic === topic) await store.delete(key(space, grant));
+		}
+	};
+};
+//#endregion
+export { DEFAULT_GRANT_SECONDS, MAX_GRANT_SECONDS, createRealtimeGrants, grantSeconds };

package/dist/modules/realtime/handlers.d.ts

@@ -0,0 +1,74 @@
+import { ChannelResolver } from './declarations';
+import { RealtimeGrants } from './grants';
+import { RealtimeConnection, RealtimeHub, RealtimeSpace } from './hub';
+import { RawResponse } from '../../helpers/buildResponseHelpers';
+import { ChannelDeclaration, RealtimeSender, SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+export type RealtimeRefusal = {
+    topic: string;
+    /** `ungranted`: the channel is declared `grant: true`, and no grant the page sent opens this topic. */
+    reason: 'undeclared' | 'unauthenticated' | 'forbidden' | 'ungranted';
+};
+/** An answer in HTTP terms, whichever transport carries it: a status, and what went wrong when something did. */
+export type RealtimeAnswer = {
+    status: number;
+    error?: string;
+    reason?: string;
+    refused?: RealtimeRefusal[];
+};
+export declare const answer: (res: SSRResponseHelpers, { status, ...payload }: RealtimeAnswer) => void;
+/** What a page may open, decided once for either transport. */
+export type Admission = {
+    ok: false;
+    answer: RealtimeAnswer;
+} | {
+    ok: true;
+    space: RealtimeSpace;
+    user?: RealtimeSender['user'];
+    accepted: Map<string, ChannelDeclaration>;
+    /** The grant each accepted topic of a `grant: true` channel was opened with. */
+    granted: Map<string, string>;
+    refused: RealtimeRefusal[];
+};
+/**
+ * Which of the topics a page asked for (`?topics=a,b`) it may open: each checked against the channels the space
+ * declares and against the visitor's access. One that fails is reported, not a reason to refuse the rest; all failing
+ * is a `403`.
+ */
+export declare const admit: (req: SSRRequest, resolveChannels: ChannelResolver, grants: RealtimeGrants) => Promise<Admission>;
+/** A new connection for what was admitted, speaking through `send`. */
+export declare const connectionFor: (admission: Extract<Admission, {
+    ok: true;
+}>, send: RealtimeConnection["send"], end: RealtimeConnection["end"]) => RealtimeConnection;
+/**
+ * A page publishing, whichever way it arrived: only on a topic its connection subscribed to, only on a channel pages
+ * may send on, within its size and its rate — and stamped by the server with who sent it and when, whatever the
+ * message said.
+ */
+export declare const publishFrom: (hub: RealtimeHub, connection: RealtimeConnection, { topic, type, data }: {
+    topic?: unknown;
+    type?: unknown;
+    data?: unknown;
+}) => Promise<RealtimeAnswer>;
+export type SubscribeDeps = {
+    req: SSRRequest;
+    res: SSRResponseHelpers;
+    raw: RawResponse;
+    signal: AbortSignal;
+    hub: RealtimeHub;
+    resolveChannels: ChannelResolver;
+    grants: RealtimeGrants;
+};
+/**
+ * `GET /_realtime?topics=a,b` (and `&grants=g1,g2` for the topics of a `grant: true` channel) — one Server-Sent Events connection for every topic a page listens to.
+ *
+ * The first event, `ready`, tells the page its public name (`from`) and the secret its publishes carry. Resolves when
+ * the page goes.
+ */
+export declare const handleRealtimeSubscribe: ({ req, res, raw, signal, hub, resolveChannels, grants }: SubscribeDeps) => Promise<void>;
+export type PublishDeps = {
+    req: SSRRequest;
+    res: SSRResponseHelpers;
+    hub: RealtimeHub;
+};
+/** `POST /_realtime` `{ token, topic, type, data }` — a page on a Server-Sent Events connection, publishing. */
+export declare const handleRealtimePublish: ({ req, res, hub }: PublishDeps) => Promise<void>;