@hot-updater/plugin-remote-config 0.0.0-stage → 1.0.0-rc.41

package/dist/client/index.mjs

@@ -0,0 +1,207 @@
+import { ownEntry } from "../shared/ownEntry.mjs";
+import { parseRemoteConfigFetchResponse, remoteConfigRequestPath } from "../shared/wire.mjs";
+import { defineClientPlugin } from "@hot-updater/protocol";
+//#region src/client/index.ts
+const DEFAULT_MINIMUM_FETCH_INTERVAL_MS = 432e5;
+const BOOLEAN_TRUTHY_VALUES = /* @__PURE__ */ new Set([
+	"1",
+	"true",
+	"t",
+	"yes",
+	"y",
+	"on"
+]);
+const FETCHED_KEY = "fetched";
+const ACTIVE_KEY = "active";
+const LAST_FETCH_STATUS_KEY = "lastFetchStatus";
+const createValue = (text, source) => Object.freeze({
+	asString: () => text,
+	asNumber: () => {
+		const number = Number(text);
+		return Number.isNaN(number) ? 0 : number;
+	},
+	asBoolean: () => BOOLEAN_TRUTHY_VALUES.has(text.toLowerCase()),
+	getSource: () => source
+});
+const parseStored = (text, extra) => {
+	if (text === null) return null;
+	try {
+		const value = JSON.parse(text);
+		if (typeof value !== "object" || value === null) return null;
+		const record = value;
+		if (parseRemoteConfigFetchResponse(record) === null || record.etag !== null && typeof record.etag !== "string" || !extra(record)) return null;
+		return record;
+	} catch {
+		return null;
+	}
+};
+const isFetchStatus = (value) => value === "success" || value === "failure";
+const deviceContext = (context) => ({
+	platform: context.platform,
+	appVersion: context.appVersion,
+	channel: context.getChannel(),
+	cohort: context.getCohort(),
+	fingerprintHash: context.getFingerprintHash()
+});
+/**
+* Remote Config for the app: in-app defaults, values a server running the
+* `remoteConfig()` plugin picks for this device, and a fetch and activate
+* step between them. Add it to `HotUpdater.init`'s `plugins`, and read it
+* from the instance `init` returns, as `hotUpdater.remoteConfig`. It fetches
+* from the `baseURL`, request headers, and timeout configured there.
+*
+* @example
+* ```ts
+* import { HotUpdater, remoteConfig } from "@hot-updater/react-native";
+*
+* export const hotUpdater = HotUpdater.init({
+*   baseURL,
+*   plugins: [
+*     remoteConfig({ defaults: { welcome_message: "Welcome", max_items: 20 } }),
+*   ],
+* });
+*
+* hotUpdater.remoteConfig.fetchAndActivate().catch(() => {});
+* hotUpdater.remoteConfig.getString("welcome_message");
+* ```
+*/
+const remoteConfig = (options = {}) => {
+	const minimumFetchIntervalMs = options.minimumFetchIntervalMs ?? DEFAULT_MINIMUM_FETCH_INTERVAL_MS;
+	if (typeof minimumFetchIntervalMs !== "number" || !Number.isFinite(minimumFetchIntervalMs) || minimumFetchIntervalMs < 0) throw new TypeError("[HotUpdater] remoteConfig({ minimumFetchIntervalMs }) must be a non-negative number.");
+	const defaults = Object.fromEntries(Object.entries(options.defaults ?? {}).map(([key, value]) => [key, String(value)]));
+	return defineClientPlugin({
+		id: "remoteConfig",
+		setup: (context) => ({ api: createRemoteConfigClient(context, {
+			defaults,
+			minimumFetchIntervalMs
+		}) })
+	});
+};
+/** The client a plugin's `setup` creates, over the values stored on the device. */
+const createRemoteConfigClient = (context, { defaults, minimumFetchIntervalMs }) => {
+	let active = parseStored(context.storage.get(ACTIVE_KEY), () => true);
+	let fetched = parseStored(context.storage.get(FETCHED_KEY), (record) => typeof record.context === "string" && typeof record.fetchedAtMs === "number");
+	const storedStatus = context.storage.get(LAST_FETCH_STATUS_KEY);
+	let lastFetchStatus = isFetchStatus(storedStatus) ? storedStatus : fetched === null ? "no-fetch-yet" : "success";
+	let inFlight = null;
+	let snapshot = null;
+	const listeners = /* @__PURE__ */ new Set();
+	const notify = () => {
+		snapshot = null;
+		for (const listener of listeners) try {
+			listener();
+		} catch (error) {
+			console.warn("[HotUpdater] A remoteConfig listener threw.", error);
+		}
+	};
+	const store = (key, value) => {
+		try {
+			context.storage.set(key, value);
+		} catch (error) {
+			console.warn(`[HotUpdater] remoteConfig could not store its ${key} values.`, error);
+		}
+	};
+	const setStatus = (status) => {
+		lastFetchStatus = status;
+		store(LAST_FETCH_STATUS_KEY, status);
+	};
+	const getValue = (key) => {
+		const remote = ownEntry(active?.values, key);
+		if (remote !== void 0) return createValue(remote, "remote");
+		const fallback = ownEntry(defaults, key);
+		return fallback === void 0 ? null : createValue(fallback, "default");
+	};
+	const fetchFromServer = async (device) => {
+		const contextKey = JSON.stringify(device);
+		let response;
+		try {
+			response = await context.fetch(remoteConfigRequestPath(device), { headers: fetched === null || fetched.etag === null ? {} : { "if-none-match": fetched.etag } });
+		} catch (error) {
+			setStatus("failure");
+			throw new Error("[HotUpdater] Remote Config could not be fetched.", { cause: error });
+		}
+		const fetchedAtMs = context.now();
+		if (response.status === 304 && fetched !== null) {
+			fetched = {
+				...fetched,
+				context: contextKey,
+				fetchedAtMs
+			};
+			store(FETCHED_KEY, JSON.stringify(fetched));
+			setStatus("success");
+			return;
+		}
+		if (!response.ok) {
+			setStatus("failure");
+			throw new Error(response.status === 404 ? "[HotUpdater] The server answered 404 to GET /remote-config: it runs without the remoteConfig() plugin." : `[HotUpdater] Remote Config fetch failed with HTTP ${response.status}.`);
+		}
+		const body = parseRemoteConfigFetchResponse(await response.json().catch(() => null));
+		if (body === null) {
+			setStatus("failure");
+			throw new Error("[HotUpdater] The server's GET /remote-config answer is not Remote Config values.");
+		}
+		fetched = {
+			version: body.version,
+			values: body.values,
+			etag: response.headers.get("etag"),
+			context: contextKey,
+			fetchedAtMs
+		};
+		store(FETCHED_KEY, JSON.stringify(fetched));
+		setStatus("success");
+	};
+	const fetchValues = (options) => {
+		const device = deviceContext(context);
+		if (options?.force !== true && inFlight === null && fetched !== null && fetched.context === JSON.stringify(device) && context.now() - fetched.fetchedAtMs < minimumFetchIntervalMs) return Promise.resolve();
+		inFlight ??= fetchFromServer(device).finally(() => {
+			inFlight = null;
+		});
+		return inFlight;
+	};
+	const activate = async () => {
+		if (fetched === null) return false;
+		const next = {
+			version: fetched.version,
+			values: fetched.values,
+			etag: fetched.etag
+		};
+		if (active !== null && active.version === next.version && JSON.stringify(active.values) === JSON.stringify(next.values)) return false;
+		active = next;
+		store(ACTIVE_KEY, JSON.stringify(active));
+		notify();
+		return true;
+	};
+	return Object.freeze({
+		getValue,
+		getString: (key) => getValue(key)?.asString() ?? null,
+		getNumber: (key) => getValue(key)?.asNumber() ?? null,
+		getBoolean: (key) => getValue(key)?.asBoolean() ?? null,
+		getAll: () => {
+			snapshot ??= Object.freeze(Object.fromEntries([.../* @__PURE__ */ new Set([...Object.keys(defaults), ...Object.keys(active?.values ?? {})])].map((key) => [key, getValue(key)])));
+			return snapshot;
+		},
+		fetch: (options) => fetchValues(options),
+		activate,
+		fetchAndActivate: async (options) => {
+			await fetchValues(options);
+			return activate();
+		},
+		get lastFetchStatus() {
+			return lastFetchStatus;
+		},
+		get fetchedAtMs() {
+			return fetched?.fetchedAtMs ?? null;
+		},
+		get activeVersion() {
+			return active?.version ?? 0;
+		},
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		}
+	});
+};
+//#endregion
+export { remoteConfig };

package/dist/server/api.cjs

@@ -0,0 +1,175 @@
+const require_template = require("./template.cjs");
+let _hot_updater_plugin_core = require("@hot-updater/plugin-core");
+//#region src/server/api.ts
+const ACTIVE_ID = "active";
+/** How long a server answers fetches from the active template it read last. */
+const ACTIVE_CACHE_TTL_MS = 5e3;
+const MAX_DESCRIPTION_LENGTH = 256;
+const MAX_VERSIONS_PAGE = 100;
+/**
+* An argument the API refuses, such as a negative `baseVersion`; the admin
+* routes answer it with `400`.
+*/
+var RemoteConfigInputError = class extends TypeError {
+	name = "RemoteConfigInputError";
+};
+const normalizeDescription = (description) => {
+	if (description === void 0 || description === null) return null;
+	if (typeof description !== "string") throw new RemoteConfigInputError("A version description is text.");
+	const trimmed = description.trim();
+	if (trimmed.length > MAX_DESCRIPTION_LENGTH) throw new RemoteConfigInputError(`A version description holds up to ${MAX_DESCRIPTION_LENGTH} characters.`);
+	return trimmed.length === 0 ? null : trimmed;
+};
+const requireVersionNumber = (value, name) => {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new RemoteConfigInputError(`${name} must be a non-negative integer.`);
+	return value;
+};
+/** A template as its `json` column stores it; validation made it plain JSON. */
+const toColumn = (template) => template;
+const fromColumn = (value) => value;
+const toVersion = (row) => Object.freeze({
+	version: row.version,
+	description: row.description,
+	updateType: row.update_type === "ROLLBACK" ? "ROLLBACK" : "PUBLISH",
+	rollbackSource: row.rollback_source,
+	createdAtMs: row.created_at_ms
+});
+/** Remote Config's API over its tables. */
+const createRemoteConfigApi = ({ db, now }) => {
+	let cached = null;
+	let loading = null;
+	let generation = 0;
+	const readActive = async () => {
+		const row = await db.findOne("remote_config_active", { id: ACTIVE_ID });
+		return row === null ? {
+			version: 0,
+			template: require_template.EMPTY_REMOTE_CONFIG_TEMPLATE,
+			updatedAtMs: null
+		} : {
+			version: row.version,
+			template: fromColumn(row.template),
+			updatedAtMs: row.updated_at_ms
+		};
+	};
+	/** The active template for fetches: one read per server every few seconds at most. */
+	const servedActive = () => {
+		if (cached !== null && cached.expiresAt > now()) return Promise.resolve(cached.active);
+		if (loading !== null) return loading;
+		const started = generation;
+		const read = readActive().then((active) => {
+			if (generation === started) cached = {
+				active,
+				expiresAt: now() + ACTIVE_CACHE_TTL_MS
+			};
+			return active;
+		}).finally(() => {
+			if (loading === read) loading = null;
+		});
+		loading = read;
+		return read;
+	};
+	const commit = async (input) => {
+		const attempt = () => db.transaction(async (tx) => {
+			const active = await tx.findOne("remote_config_active", { id: ACTIVE_ID });
+			const currentVersion = active?.version ?? 0;
+			if (currentVersion !== input.baseVersion) return {
+				status: "conflict",
+				currentVersion
+			};
+			const version = currentVersion + 1;
+			const at = now();
+			const row = {
+				version,
+				template: toColumn(input.template),
+				description: input.description,
+				update_type: input.rollbackSource === null ? "PUBLISH" : "ROLLBACK",
+				rollback_source: input.rollbackSource,
+				created_at_ms: at
+			};
+			tx.create("remote_config_versions", row);
+			if (active === null) tx.create("remote_config_active", {
+				id: ACTIVE_ID,
+				version,
+				template: toColumn(input.template),
+				updated_at_ms: at
+			});
+			else tx.update("remote_config_active", active, {
+				version,
+				template: toColumn(input.template),
+				updated_at_ms: at
+			});
+			return {
+				status: "published",
+				version: toVersion(row)
+			};
+		});
+		try {
+			const result = await attempt();
+			if (result.status === "published") {
+				generation += 1;
+				cached = null;
+				loading = null;
+			}
+			return result;
+		} catch (error) {
+			if (error instanceof _hot_updater_plugin_core.DatabaseConstraintError && (error.reason === "exists" || error.reason === "unique")) return {
+				status: "conflict",
+				currentVersion: (await readActive()).version
+			};
+			throw error;
+		}
+	};
+	return Object.freeze({
+		getActive: readActive,
+		publish: async ({ template, baseVersion, description }) => commit({
+			template: require_template.validateRemoteConfigTemplate(template),
+			baseVersion: requireVersionNumber(baseVersion, "baseVersion"),
+			description: normalizeDescription(description),
+			rollbackSource: null
+		}),
+		rollback: async ({ version, baseVersion, description }) => {
+			const source = await db.findOne("remote_config_versions", { version: requireVersionNumber(version, "version") });
+			if (source === null) return { status: "not_found" };
+			return commit({
+				template: fromColumn(source.template),
+				baseVersion: requireVersionNumber(baseVersion, "baseVersion"),
+				description: normalizeDescription(description) ?? `Rollback to version ${source.version}`,
+				rollbackSource: source.version
+			});
+		},
+		listVersions: async ({ limit = 20, cursor } = {}) => {
+			if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_VERSIONS_PAGE) throw new RemoteConfigInputError(`limit must be an integer from 1 to ${MAX_VERSIONS_PAGE}.`);
+			const page = await db.findMany("remote_config_versions", {
+				index: "byVersion",
+				where: {},
+				order: "desc",
+				limit,
+				...cursor === void 0 ? {} : { cursor }
+			});
+			return Object.freeze({
+				versions: Object.freeze(page.rows.map(toVersion)),
+				...page.next === void 0 ? {} : { next: page.next }
+			});
+		},
+		getVersion: async (version) => {
+			const row = await db.findOne("remote_config_versions", { version: requireVersionNumber(version, "version") });
+			return row === null ? null : Object.freeze({
+				...toVersion(row),
+				template: fromColumn(row.template)
+			});
+		},
+		resolve: async (context) => {
+			const active = await servedActive();
+			return {
+				version: active.version,
+				values: require_template.resolveRemoteConfigValues(active.template, {
+					...context,
+					now: context.now ?? now()
+				})
+			};
+		}
+	});
+};
+//#endregion
+exports.RemoteConfigInputError = RemoteConfigInputError;
+exports.createRemoteConfigApi = createRemoteConfigApi;

package/dist/server/api.d.cts

@@ -0,0 +1,85 @@
+import { RemoteConfigFetchResponse } from "../shared/wire.cjs";
+import { RemoteConfigEvaluationContext, RemoteConfigTemplate } from "./template.cjs";
+import "@hot-updater/plugin-core";
+//#region src/server/api.d.ts
+/** A published version's record, without its template. */
+interface RemoteConfigVersion {
+  readonly version: number;
+  readonly description: string | null;
+  /** `ROLLBACK` when the version copies `rollbackSource`. */
+  readonly updateType: "PUBLISH" | "ROLLBACK";
+  readonly rollbackSource: number | null;
+  readonly createdAtMs: number;
+}
+interface RemoteConfigVersionDetail extends RemoteConfigVersion {
+  readonly template: RemoteConfigTemplate;
+}
+/** The template devices receive now. */
+interface RemoteConfigActive {
+  /** 0, with an empty template, before the first publish. */
+  readonly version: number;
+  readonly template: RemoteConfigTemplate;
+  readonly updatedAtMs: number | null;
+}
+/**
+ * How a publish or a rollback ended: `conflict` when another publish moved
+ * the active version past `baseVersion` first, so a stale edit never
+ * replaces a newer template.
+ */
+type RemoteConfigPublishResult = {
+  readonly status: "published";
+  readonly version: RemoteConfigVersion;
+} | {
+  readonly status: "conflict";
+  readonly currentVersion: number;
+};
+interface RemoteConfigVersionsPage {
+  /** Newest first. */
+  readonly versions: readonly RemoteConfigVersion[];
+  /** Pass as `cursor` for the next page; absent on the last one. */
+  readonly next?: string;
+}
+/** `hotUpdater.api.remoteConfig`. */
+interface RemoteConfigApi {
+  /** The active template and its version. */
+  getActive(): Promise<RemoteConfigActive>;
+  /**
+   * Validates and publishes a template as the next version. Throws
+   * `RemoteConfigValidationError` for an invalid template.
+   */
+  publish(input: {
+    readonly template: unknown;
+    /** The version the edit started from; 0 before the first publish. */
+    readonly baseVersion: number;
+    readonly description?: string;
+  }): Promise<RemoteConfigPublishResult>;
+  /** Publishes a copy of an earlier version; `not_found` when it does not exist. */
+  rollback(input: {
+    readonly version: number;
+    readonly baseVersion: number;
+    readonly description?: string;
+  }): Promise<RemoteConfigPublishResult | {
+    readonly status: "not_found";
+  }>;
+  /** One page of published versions, newest first. */
+  listVersions(input?: {
+    readonly limit?: number;
+    readonly cursor?: string;
+  }): Promise<RemoteConfigVersionsPage>;
+  /** One version with its template, or null. */
+  getVersion(version: number): Promise<RemoteConfigVersionDetail | null>;
+  /**
+   * What a device with this context receives from `GET /remote-config`, at
+   * `context.now` or, without it, now.
+   */
+  resolve(context: RemoteConfigEvaluationContext): Promise<RemoteConfigFetchResponse>;
+}
+/**
+ * An argument the API refuses, such as a negative `baseVersion`; the admin
+ * routes answer it with `400`.
+ */
+declare class RemoteConfigInputError extends TypeError {
+  readonly name = "RemoteConfigInputError";
+}
+//#endregion
+export { RemoteConfigActive, RemoteConfigApi, RemoteConfigInputError, RemoteConfigPublishResult, RemoteConfigVersion, RemoteConfigVersionDetail, RemoteConfigVersionsPage };

package/dist/server/api.d.mts

@@ -0,0 +1,85 @@
+import { RemoteConfigFetchResponse } from "../shared/wire.mjs";
+import { RemoteConfigEvaluationContext, RemoteConfigTemplate } from "./template.mjs";
+import "@hot-updater/plugin-core";
+//#region src/server/api.d.ts
+/** A published version's record, without its template. */
+interface RemoteConfigVersion {
+  readonly version: number;
+  readonly description: string | null;
+  /** `ROLLBACK` when the version copies `rollbackSource`. */
+  readonly updateType: "PUBLISH" | "ROLLBACK";
+  readonly rollbackSource: number | null;
+  readonly createdAtMs: number;
+}
+interface RemoteConfigVersionDetail extends RemoteConfigVersion {
+  readonly template: RemoteConfigTemplate;
+}
+/** The template devices receive now. */
+interface RemoteConfigActive {
+  /** 0, with an empty template, before the first publish. */
+  readonly version: number;
+  readonly template: RemoteConfigTemplate;
+  readonly updatedAtMs: number | null;
+}
+/**
+ * How a publish or a rollback ended: `conflict` when another publish moved
+ * the active version past `baseVersion` first, so a stale edit never
+ * replaces a newer template.
+ */
+type RemoteConfigPublishResult = {
+  readonly status: "published";
+  readonly version: RemoteConfigVersion;
+} | {
+  readonly status: "conflict";
+  readonly currentVersion: number;
+};
+interface RemoteConfigVersionsPage {
+  /** Newest first. */
+  readonly versions: readonly RemoteConfigVersion[];
+  /** Pass as `cursor` for the next page; absent on the last one. */
+  readonly next?: string;
+}
+/** `hotUpdater.api.remoteConfig`. */
+interface RemoteConfigApi {
+  /** The active template and its version. */
+  getActive(): Promise<RemoteConfigActive>;
+  /**
+   * Validates and publishes a template as the next version. Throws
+   * `RemoteConfigValidationError` for an invalid template.
+   */
+  publish(input: {
+    readonly template: unknown;
+    /** The version the edit started from; 0 before the first publish. */
+    readonly baseVersion: number;
+    readonly description?: string;
+  }): Promise<RemoteConfigPublishResult>;
+  /** Publishes a copy of an earlier version; `not_found` when it does not exist. */
+  rollback(input: {
+    readonly version: number;
+    readonly baseVersion: number;
+    readonly description?: string;
+  }): Promise<RemoteConfigPublishResult | {
+    readonly status: "not_found";
+  }>;
+  /** One page of published versions, newest first. */
+  listVersions(input?: {
+    readonly limit?: number;
+    readonly cursor?: string;
+  }): Promise<RemoteConfigVersionsPage>;
+  /** One version with its template, or null. */
+  getVersion(version: number): Promise<RemoteConfigVersionDetail | null>;
+  /**
+   * What a device with this context receives from `GET /remote-config`, at
+   * `context.now` or, without it, now.
+   */
+  resolve(context: RemoteConfigEvaluationContext): Promise<RemoteConfigFetchResponse>;
+}
+/**
+ * An argument the API refuses, such as a negative `baseVersion`; the admin
+ * routes answer it with `400`.
+ */
+declare class RemoteConfigInputError extends TypeError {
+  readonly name = "RemoteConfigInputError";
+}
+//#endregion
+export { RemoteConfigActive, RemoteConfigApi, RemoteConfigInputError, RemoteConfigPublishResult, RemoteConfigVersion, RemoteConfigVersionDetail, RemoteConfigVersionsPage };