Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(ok): report platform and version on download + update telemetry (#3412)

mike-inkeepc285219f70f0
diff --git a/.changeset/update-telemetry-platform-and-to-version.md b/.changeset/update-telemetry-platform-and-to-version.md
new file mode 100644
index 000000000..9dbe80520
--- /dev/null
+++ b/.changeset/update-telemetry-platform-and-to-version.md
@@ -0,0 +1,5 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+Auto-update telemetry now reports which platform and version an update landed on. The desktop updater tags each artifact fetch with the version it is installing, and the update proxy records the operating system and architecture alongside the artifact type. Previously only the macOS zip carried a version — the Windows and Linux installers use version-less names that stable resolves through GitHub's `latest` alias, so every Windows and Linux stable update was counted with no version at all, and architecture was invisible on every platform. The new header is sent only when the updater is pointed at the openknowledge.ai proxy, never on the GitHub fallback, and the proxy prefers the version it can derive itself over the one the client claims.
diff --git a/docs/src/app/download/beta/route.test.ts b/docs/src/app/download/beta/route.test.ts
index e52f5154b..a7f4a00b8 100644
--- a/docs/src/app/download/beta/route.test.ts
+++ b/docs/src/app/download/beta/route.test.ts
@@ -60,6 +60,13 @@ describe('GET /download/beta', () => {
expect(_lastCapture?.event).toBe('dmg_downloaded');
expect(_lastCapture?.distinctId).toBe('visitor-9');
expect(_lastCapture?.properties?.channel).toBe('beta');
+ // The resolver serves DMG_ASSET_NAME and nothing else, so the reported
+ // platform is fixed. If beta ever gains Windows/Linux builds, this fails
+ // rather than silently attributing them to macOS.
+ expect(_lastCapture?.properties?.os).toBe('macos');
+ expect(_lastCapture?.properties?.arch).toBe('arm64');
+ expect(_lastCapture?.properties?.format).toBe('dmg');
+ expect(TEST_DMG_URL.endsWith('.dmg')).toBe(true);
});
test('302 to the stale LKG URL and still counts', async () => {
diff --git a/docs/src/app/download/beta/route.ts b/docs/src/app/download/beta/route.ts
index e15151d15..9efbdddc2 100644
--- a/docs/src/app/download/beta/route.ts
+++ b/docs/src/app/download/beta/route.ts
@@ -33,7 +33,19 @@ export async function GET(request: Request): Promise<Response> {
captureServerEvent({
event: 'dmg_downloaded',
distinctId: resolveDistinctId(request),
- properties: { channel: 'beta', ...attribution(request) },
+ properties: {
+ channel: 'beta',
+ // Hardcoded, not resolved from `?os=`: the beta resolver matches
+ // DMG_ASSET_NAME and nothing else, so this route can only ever serve
+ // the macOS build no matter what a link asks for. Reporting the target
+ // it actually served keeps the platform split honest — and makes the
+ // missing Windows/Linux beta channel visible as an absence rather than
+ // as untyped events. Widen these the day the resolver does.
+ os: 'macos',
+ arch: 'arm64',
+ format: 'dmg',
+ ...attribution(request),
+ },
});
}
return toRedirectResponse(redirect);
diff --git a/docs/src/app/updates/[channel]/[...path]/route.test.ts b/docs/src/app/updates/[channel]/[...path]/route.test.ts
index 039d8d127..440cf641f 100644
--- a/docs/src/app/updates/[channel]/[...path]/route.test.ts
+++ b/docs/src/app/updates/[channel]/[...path]/route.test.ts
@@ -71,6 +71,8 @@ describe('GET /updates/[channel]/[...path]', () => {
expect(_lastCapture?.properties?.to_version).toBe('0.20.0');
expect(_lastCapture?.properties?.from_version).toBe('0.19.1');
expect(_lastCapture?.properties?.ua_class).toBe('electron');
+ expect(_lastCapture?.properties?.os).toBe('macos');
+ expect(_lastCapture?.properties?.arch).toBe('arm64');
});
test('beta zip parses the prerelease version and counts (no from_version header)', async () => {
@@ -190,7 +192,7 @@ describe('GET /updates/[channel]/[...path]', () => {
expect(_lastCapture).toBeNull();
});
- test('Windows stable exe counts with artifact_type=exe and no to_version (versionless name)', async () => {
+ test('Windows stable exe counts with artifact_type=exe and no to_version when the updater sends no header', async () => {
_lastCapture = null;
const file = 'OpenKnowledge-Setup-x64.exe';
const res = await call('stable', [file], { 'x-ok-from-version': '0.19.1' });
@@ -200,6 +202,46 @@ describe('GET /updates/[channel]/[...path]', () => {
expect(_lastCapture?.properties?.artifact_type).toBe('exe');
expect(_lastCapture?.properties?.to_version).toBeUndefined();
expect(_lastCapture?.properties?.from_version).toBe('0.19.1');
+ expect(_lastCapture?.properties?.os).toBe('windows');
+ expect(_lastCapture?.properties?.arch).toBe('x64');
+ });
+
+ test('a versionless stable installer takes to_version from the updater header', async () => {
+ // The whole reason the header exists: exe/deb/rpm names carry no version
+ // and stable's `latest` alias resolves no tag, so without it every Windows
+ // and Linux stable update is attributed to no version at all.
+ _lastCapture = null;
+ const res = await call('stable', ['OpenKnowledge-Setup-arm64.exe'], {
+ 'x-ok-from-version': '0.19.1',
+ 'x-ok-to-version': '0.20.0',
+ });
+ expect(res.status).toBe(302);
+ expect(_lastCapture?.properties?.to_version).toBe('0.20.0');
+ expect(_lastCapture?.properties?.from_version).toBe('0.19.1');
+ });
+
+ test('an ill-formed x-ok-to-version is dropped, not forwarded to analytics', async () => {
+ _lastCapture = null;
+ const res = await call('stable', ['OpenKnowledge-amd64.deb'], {
+ 'x-ok-to-version': '0.20.0; DROP TABLE',
+ });
+ expect(res.status).toBe(302);
+ expect(_lastCapture?.properties?.to_version).toBeUndefined();
+ });
+
+ test('server-derived versions outrank the header, which is only a client claim', async () => {
+ // A filename version and a resolved beta tag both describe what this
+ // redirect actually serves; a lying header must not be able to overwrite
+ // either, or a client could rewrite another release's adoption numbers.
+ _lastCapture = null;
+ await call('stable', ['OpenKnowledge-0.20.0-arm64-mac.zip'], {
+ 'x-ok-to-version': '9.9.9',
+ });
+ expect(_lastCapture?.properties?.to_version).toBe('0.20.0');
+
+ _lastCapture = null;
+ await call('beta', ['OpenKnowledge-arm64.deb'], { 'x-ok-to-version': '9.9.9' });
+ expect(_lastCapture?.properties?.to_version).toBe('0.20.0-beta.4');
});
test('Linux beta deb counts with to_version derived from the resolved beta tag', async () => {
@@ -211,9 +253,11 @@ describe('GET /updates/[channel]/[...path]', () => {
expect(_lastCapture?.event).toBe('app_update_downloaded');
expect(_lastCapture?.properties?.artifact_type).toBe('deb');
expect(_lastCapture?.properties?.to_version).toBe('0.20.0-beta.4');
+ expect(_lastCapture?.properties?.os).toBe('linux');
+ expect(_lastCapture?.properties?.arch).toBe('arm64');
});
- test('Linux stable rpm counts with artifact_type=rpm and no to_version (versionless name)', async () => {
+ test('Linux stable rpm counts with artifact_type=rpm and no to_version when the updater sends no header', async () => {
_lastCapture = null;
const file = 'OpenKnowledge-x86_64.rpm';
const res = await call('stable', [file]);
@@ -223,6 +267,36 @@ describe('GET /updates/[channel]/[...path]', () => {
// Symmetric with the beta deb's resolved-tag assertion: the stable alias
// resolves no tag, so a regression that propagates one must fail here.
expect(_lastCapture?.properties?.to_version).toBeUndefined();
+ expect(_lastCapture?.properties?.os).toBe('linux');
+ expect(_lastCapture?.properties?.arch).toBe('x64');
+ });
+
+ test('every packager arch spelling normalizes onto one analytics vocabulary', async () => {
+ // dpkg says amd64, rpm says x86_64/aarch64, electron-builder says x64 —
+ // ungrouped, one platform would read as several in a breakdown.
+ const cases: ReadonlyArray<readonly [string, string, string]> = [
+ ['OpenKnowledge-Setup-arm64.exe', 'windows', 'arm64'],
+ ['OpenKnowledge-amd64.deb', 'linux', 'x64'],
+ ['OpenKnowledge-aarch64.rpm', 'linux', 'arm64'],
+ ['OpenKnowledge-0.20.0-universal-mac.zip', 'macos', 'universal'],
+ ];
+ for (const [file, os, arch] of cases) {
+ _lastCapture = null;
+ const res = await call('stable', [file]);
+ expect(res.status).toBe(302);
+ expect(_lastCapture?.properties?.os, file).toBe(os);
+ expect(_lastCapture?.properties?.arch, file).toBe(arch);
+ }
+ });
+
+ test('an unrecognized arch token is dropped, not forwarded to analytics', async () => {
+ // Bounded cardinality: a future packager spelling must arrive as an absent
+ // property a dashboard shows as a gap, never as a new free-form value.
+ _lastCapture = null;
+ const res = await call('stable', ['OpenKnowledge-riscv64.deb']);
+ expect(res.status).toBe(302);
+ expect(_lastCapture?.properties?.os).toBe('linux');
+ expect(_lastCapture?.properties?.arch).toBeUndefined();
});
test('a manifest-lookalike name that is not a real channel file → 404', async () => {
diff --git a/docs/src/app/updates/[channel]/[...path]/route.ts b/docs/src/app/updates/[channel]/[...path]/route.ts
index b55ca920e..4f91631b2 100644
--- a/docs/src/app/updates/[channel]/[...path]/route.ts
+++ b/docs/src/app/updates/[channel]/[...path]/route.ts
@@ -41,9 +41,15 @@ const ARTIFACT_VERSION =
// arch-suffixed by electron-builder exactly as the client computes it).
const MANIFEST = /^(?:latest|beta)(?:-mac|-linux(?:-arm64)?)?\.yml$/;
const BETA_TAG_FROM_URL = /\/releases\/download\/([^/]+)\//;
-// Validates the attacker-controlled x-ok-from-version header before it lands in
-// analytics, so it cannot pollute PostHog with high-cardinality junk.
-const FROM_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?$/;
+// Validates the attacker-controlled x-ok-from-version / x-ok-to-version headers
+// before they land in analytics, so they cannot pollute PostHog with
+// high-cardinality junk.
+const HEADER_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?$/;
+
+function headerVersion(request: Request, name: string): string | undefined {
+ const raw = request.headers.get(name);
+ return raw && HEADER_VERSION.test(raw) ? raw : undefined;
+}
// A beta tag as cut by the cadence (`v0.20.0-beta.4`) — used to derive
// `to_version` for the versionless installers on the beta channel.
const VERSION_FROM_TAG = /^v(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)$/;
@@ -52,6 +58,53 @@ const resolveBeta = createBetaResolver();
type ArtifactType = 'manifest' | 'zip' | 'blockmap' | 'dmg' | 'exe' | 'deb' | 'rpm' | 'other';
+type UpdateOs = 'macos' | 'windows' | 'linux';
+type UpdateArch = 'arm64' | 'x64' | 'universal';
+
+/**
+ * The artifact a platform's updater installs is unique to that platform, so the
+ * container names the OS outright: Squirrel.Mac takes the zip, NSIS the exe,
+ * and Linux the package its install came from.
+ */
+const OS_BY_ARTIFACT: Partial<Record<ArtifactType, UpdateOs>> = {
+ zip: 'macos',
+ exe: 'windows',
+ deb: 'linux',
+ rpm: 'linux',
+};
+
+/**
+ * Each artifact spells its architecture the way its own packager does —
+ * electron-builder's `arm64`/`x64`, dpkg's `amd64`, rpm's `x86_64`/`aarch64`.
+ * Mapping them onto one vocabulary keeps a single `arch` dimension in
+ * analytics, and it is deliberately the same vocabulary `download-targets.ts`
+ * emits on `dmg_downloaded`, so downloads and updates slice identically.
+ * Unknown tokens fall out as undefined rather than reaching PostHog — same
+ * bounded-cardinality discipline as the from_version guard.
+ */
+const ARCH_BY_TOKEN: Record<string, UpdateArch> = {
+ arm64: 'arm64',
+ aarch64: 'arm64',
+ x64: 'x64',
+ amd64: 'x64',
+ x86_64: 'x64',
+ // No universal build ships today, so this has no download-side peer — but
+ // the mac-zip name admits one, so classify it rather than dropping it.
+ universal: 'universal',
+};
+
+/**
+ * The arch token is the last hyphen-delimited segment before the extension on
+ * every counted artifact (`…-arm64-mac.zip`, `…-Setup-x64.exe`,
+ * `…-amd64.deb`, `…-x86_64.rpm`); `-mac` is the one suffix that follows it.
+ */
+const ARCH_TOKEN = /-([A-Za-z0-9_]+)(?:-mac)?\.(?:zip|exe|deb|rpm)$/;
+
+function archOf(filename: string): UpdateArch | undefined {
+ const token = ARCH_TOKEN.exec(filename)?.[1];
+ return token ? ARCH_BY_TOKEN[token] : undefined;
+}
+
function classify(filename: string): ArtifactType {
if (MANIFEST.test(filename)) return 'manifest';
// Covers both `*.zip.blockmap` and `*.dmg.blockmap` (the release uploads both).
@@ -125,22 +178,31 @@ export async function GET(
// Count the artifacts electron-updater actually installs: the versioned mac
// zip (a bare `.zip` with no embedded version is not an updater artifact),
// and the Windows/Linux installers, whose versionless names carry no
- // to_version — beta fills it from the resolved tag; stable's `latest` alias
- // leaves it undefined (the from_version + channel still tell the story).
- // Humans download installers from the release page / docs links, never
- // through this proxy, and userAgentProperties surfaces any exceptions.
+ // to_version of their own — beta fills it from the resolved tag, and stable's
+ // `latest` alias resolves nothing, so there the updater's own header is the
+ // only source. Humans download installers from the release page / docs links,
+ // never through this proxy, and userAgentProperties surfaces any exceptions.
const counted =
(type === 'zip' && version != null) || type === 'exe' || type === 'deb' || type === 'rpm';
if (counted) {
- const rawFrom = request.headers.get('x-ok-from-version');
captureServerEvent({
event: 'app_update_downloaded',
distinctId: resolveDistinctId(request),
properties: {
channel,
artifact_type: type,
- to_version: version ?? resolvedTagVersion,
- from_version: rawFrom && FROM_VERSION.test(rawFrom) ? rawFrom : undefined,
+ // artifact_type already implies the OS, but only to a reader who knows
+ // the mapping — os/arch make the platform split directly groupable and
+ // name the dimension the same way `dmg_downloaded` does, so a download
+ // and the updates that follow it join on one vocabulary.
+ os: OS_BY_ARTIFACT[type],
+ arch: archOf(filename),
+ // Server-derived sources win: the filename and the resolved tag both
+ // name what this redirect actually serves, while the header is only
+ // the client's claim about what it is installing. It is the last
+ // resort, not an override.
+ to_version: version ?? resolvedTagVersion ?? headerVersion(request, 'x-ok-to-version'),
+ from_version: headerVersion(request, 'x-ok-from-version'),
// Confirms updates really come from electron-updater and surfaces any
// scraper/browser traffic hitting the update feed.
...userAgentProperties(request),
diff --git a/packages/desktop/src/main/auto-updater.ts b/packages/desktop/src/main/auto-updater.ts
index 1fda7b199..72a0b3656 100644
--- a/packages/desktop/src/main/auto-updater.ts
+++ b/packages/desktop/src/main/auto-updater.ts
@@ -1115,7 +1115,8 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa
const onUpdateAvailable = (info: { version?: string }): void => {
logger.info('update-available', { version: info.version });
- const offerClass = classifyOffer(info.version);
+ const offeredVersion = info.version;
+ const offerClass = classifyOffer(offeredVersion);
if (offerClass !== 'same-channel') {
logger.warn('update-available vetoed', {
reason: offerClass,
@@ -1134,6 +1135,22 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa
return;
}
markCheckSucceeded();
+ // Tag the artifact fetch with the version being installed. The Windows and
+ // Linux installers carry version-less names and stable resolves them
+ // through GitHub's `latest` alias, so the proxy has nothing to parse and
+ // those updates would otherwise land in analytics with no `to_version` at
+ // all — only the macOS zip embeds its version. electron-updater reads
+ // `requestHeaders` when `downloadUpdate()` runs, not when the feed is
+ // configured, so setting it here reaches the artifact request; it is safe
+ // to do only because `autoDownload = false` puts that call below us rather
+ // than in a race with this handler. Guarded on the proxy feed so the
+ // GitHub fallback (which nulls these headers) never grows a custom one.
+ if (usingProxyFeed && offeredVersion) {
+ updater.requestHeaders = {
+ ...updater.requestHeaders,
+ 'x-ok-to-version': offeredVersion,
+ };
+ }
// `autoDownload = false`, so we kick off the download explicitly only
// after the channel-match check passes. Defensive catch: rejections also
// surface through the `error` event handler, but a synchronous reject
diff --git a/packages/desktop/tests/integration/auto-updater.test.ts b/packages/desktop/tests/integration/auto-updater.test.ts
index b898b0d75..a2fd906c6 100644
--- a/packages/desktop/tests/integration/auto-updater.test.ts
+++ b/packages/desktop/tests/integration/auto-updater.test.ts
@@ -512,6 +512,48 @@ describe('startAutoUpdater — initial configuration (parent §8.10 LOCKED)', ()
});
});
+ test('proxyFeed: an accepted offer tags the artifact fetch with x-ok-to-version', () => {
+ // Windows/Linux installers have version-less names and stable resolves
+ // them through GitHub's `latest` alias, so this header is the proxy's only
+ // way to know which version an update landed on. It must be set before
+ // downloadUpdate runs — electron-updater reads requestHeaders there.
+ const { rig } = makeRig({
+ appVersion: '0.4.0',
+ proxyFeed: { base: PROXY_BASE, channels: new Set(['latest']) },
+ });
+ rig.updater.emit('update-available', { version: '0.5.0' });
+ expect(rig.updater.downloadUpdate).toHaveBeenCalled();
+ expect(rig.updater.requestHeaders).toEqual({
+ 'x-ok-from-version': '0.4.0',
+ 'x-ok-channel': 'stable',
+ 'x-ok-to-version': '0.5.0',
+ });
+ });
+
+ test('proxyFeed: a vetoed cross-channel offer does NOT tag a to-version', () => {
+ // No download happens, so tagging one would attribute a version to an
+ // update that was never fetched.
+ const { rig } = makeRig({
+ appVersion: '0.4.0',
+ proxyFeed: { base: PROXY_BASE, channels: new Set(['latest']) },
+ });
+ rig.updater.emit('update-available', { version: '0.6.0-beta.0' });
+ expect(rig.updater.downloadUpdate).not.toHaveBeenCalled();
+ expect(rig.updater.requestHeaders).toEqual({
+ 'x-ok-from-version': '0.4.0',
+ 'x-ok-channel': 'stable',
+ });
+ });
+
+ test('proxyFeed off: an accepted offer leaves GitHub-bound headers untouched', () => {
+ // The GitHub fallback nulls these headers; growing a custom one here would
+ // send OpenKnowledge telemetry to github.com.
+ const { rig } = makeRig({ appVersion: '0.4.0' });
+ rig.updater.emit('update-available', { version: '0.5.0' });
+ expect(rig.updater.downloadUpdate).toHaveBeenCalled();
+ expect(rig.updater.requestHeaders).toBeNull();
+ });
+
test('proxyFeed: default-off — channel not in the set leaves the GitHub default', () => {
const { rig } = makeRig({
appVersion: '0.4.0', // stable build