Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions docs/architecture/desktop-downloads.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Desktop downloads

`GET /api/download/<asset>` (`functions/api/download/[asset].ts`) counts a download
intent and redirects to the Stable installer for one platform. It never answers with
an error page: when no installer can be resolved it redirects to
`https://github.com/ScientFactory/scient-desktop/releases/latest`, which lists every
installer, and records `download_failed` with the reason, GitHub's HTTP status or error
name, elapsed time, attempts, and `fallback: "release_page"`.

## Where the release comes from

`resolveLatestDesktopRelease` (`functions/_lib/latest-release.ts`) tries, in order:

1. The data-center edge cache (five minutes).
2. **ScientFactory's mirror**, while the release mirror worker has confirmed it within the
last six hours. Installers redirect to `downloads.scientfactory.com`. GitHub is not
contacted.
3. **GitHub's latest release handoff**
(`releases/latest/download/scient-release-handoff.json`). A missing response, timeout or
5xx is retried once; a 4xx, including a 403/429 refusal, is not. Each attempt has four
seconds.
4. The mirror however old it is, when GitHub fails.

Every source is validated by `parseReleaseHandoff` (`src/lib/release-handoff.ts`): the
official provenance repository, the four required installers, sizes and SHA-256 digests.
Redirect targets must pass `isOfficialDesktopReleaseDownload`: the canonical GitHub release
download path, or `downloads.scientfactory.com/scient-desktop/v<semver>/<installer>`.

## The mirror

The `scientfactory-release-mirror` worker (`workers/release-mirror/`) runs every ten minutes
against the `scient-downloads` R2 bucket, the same bucket that serves Scient Agent's copies.
Each run:

1. Reads GitHub's latest handoff and validates it.
2. For each required installer, keeps an existing `scient-desktop/<tag>/<name>` whose size
and recorded SHA-256 match. A missing installer is streamed from the GitHub release into
R2 with the handoff's SHA-256 and `If-None-Match: *`; R2 refuses the write when the bytes
do not match. An existing installer with a different digest is never replaced: the run
fails, because the current pointer and year-long caches may still serve those bytes. A
changed installer needs a new release tag.
3. Writes `scient-desktop/stable.json` last, as a compare-and-swap on the pointer version the
run observed at its start: the handoff, GitHub's Last-Modified, `mirroredAt`, and
`checkedAt`. If another run wrote the pointer meanwhile, this run reports `superseded`
and leaves it, so a slow run that saw an older release cannot undo a newer promotion.

A failed run leaves the previous pointer untouched, so the pointer only names installers
that are in the bucket. Older versions stay in the bucket.

Deploy the worker with `bun run mirror:deploy`. The Pages project reads the bucket through
its `DESKTOP_DOWNLOADS` binding in `wrangler.jsonc`.

## Why

Before this, every cold edge cache asked GitHub for the handoff while the visitor waited,
and any refusal or error ended in a JSON 503. In November 2026 roughly a quarter of the
download attempts on some days failed that way, each in about 0.3 seconds, during bursts
of simultaneous requests against an expired cache. GitHub's status was not recorded, so
the specific refusal is unknown; the mirror and the release-page fallback remove the
dependency rather than tune around it.
15 changes: 14 additions & 1 deletion functions/_lib/events.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,14 @@ export interface SiteEvent {
readonly destinationPath?: string | null;
readonly failureStage?: string | null;
readonly failureReason?: string | null;
/** Download failures: GitHub's final HTTP status, or null when none arrived. */
readonly upstreamStatus?: number | null;
/** Download failures: the error name when GitHub sent no usable response. */
readonly upstreamError?: string | null;
readonly upstreamElapsedMs?: number | null;
readonly upstreamAttempts?: number | null;
/** Download failures: where the visitor was sent instead of an installer. */
readonly fallback?: "release_page" | null;
readonly sessionId?: string | null;
}

Expand Down Expand Up @@ -110,7 +118,12 @@ export async function insertSiteEvent(
destination_path: cleanPath(event.destinationPath),
failure_stage: limited(event.failureStage, 80),
failure_reason: limited(event.failureReason, 120),
}).filter((entry): entry is [string, string] => entry[1] !== null),
upstream_status: event.upstreamStatus ?? null,
upstream_error: limited(event.upstreamError, 60),
upstream_elapsed_ms: event.upstreamElapsedMs ?? null,
upstream_attempts: event.upstreamAttempts ?? null,
fallback: event.fallback ?? null,
}).filter((entry): entry is [string, string | number] => entry[1] !== null),
);

const statements: D1PreparedStatement[] = [];
Expand Down
180 changes: 152 additions & 28 deletions functions/_lib/latest-release.test.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

import { LatestReleaseResolutionError, resolveLatestDesktopRelease } from "./latest-release";

Expand All @@ -24,21 +24,73 @@ const handoffFixture = {
],
};

const mirroredHandoff = {
...handoffFixture,
version: "0.6.4",
tag: "v0.6.4",
assets: handoffFixture.assets.map((asset) => ({
...asset,
name: asset.name.replace("0.6.5", "0.6.4"),
})),
};

const NOW = Date.parse("2026-11-13T12:00:00.000Z");

function handoffResponse(headers?: HeadersInit): Response {
return Response.json(handoffFixture, {
headers: { "Last-Modified": "Sat, 22 Aug 2026 01:50:58 GMT", ...headers },
});
}

function context() {
function mirrorBucket(checkedAt: string | null, body?: string): R2Bucket {
const text =
body ??
JSON.stringify({
schemaVersion: 1,
handoff: mirroredHandoff,
publishedAt: "2026-11-01T00:00:00.000Z",
mirroredAt: "2026-11-01T00:05:00.000Z",
checkedAt,
});
return {
get: vi.fn(async () =>
checkedAt === null && body === undefined
? null
: { size: text.length, text: async () => text },
),
} as unknown as R2Bucket;
}

function context(bucket?: R2Bucket) {
const pending: Array<Promise<unknown>> = [];
return {
request: new Request("https://scientfactory.com/api/releases/latest"),
env: bucket ? { DESKTOP_DOWNLOADS: bucket } : {},
waitUntil: (promise: Promise<unknown>) => pending.push(promise),
pending,
};
}

function emptyCache() {
const put = vi.fn();
vi.stubGlobal("caches", {
default: { match: vi.fn().mockResolvedValue(undefined), put, delete: vi.fn() },
});
return put;
}

function upstreamError(upstream: object) {
return expect.objectContaining<Partial<LatestReleaseResolutionError>>({
stage: "release_fetch",
reason: "upstream_unavailable",
upstream: expect.objectContaining(upstream),
});
}

beforeEach(() => {
vi.spyOn(console, "error").mockImplementation(() => undefined);
});

afterEach(() => {
vi.useRealTimers();
vi.unstubAllGlobals();
Expand Down Expand Up @@ -71,16 +123,98 @@ describe("latest release resolver", () => {
expect(new URL(key.url).searchParams.toString()).toBe(
new URLSearchParams({
source: "ScientFactory/scient-desktop",
schema: "handoff-v1",
schema: "handoff-v2",
}).toString(),
);
});

it("serves a fresh mirror without contacting GitHub", async () => {
vi.useFakeTimers({ now: NOW });
emptyCache();
const fetchMock = vi.fn<typeof fetch>();
vi.stubGlobal("fetch", fetchMock);

const release = await resolveLatestDesktopRelease(
context(mirrorBucket("2026-11-13T11:55:00.000Z")),
);

expect(fetchMock).not.toHaveBeenCalled();
expect(release.tag_name).toBe("v0.6.4");
expect(release.assets[0]?.browser_download_url).toBe(
"https://downloads.scientfactory.com/scient-desktop/v0.6.4/Scient-0.6.4-arm64.dmg",
);
});

it("prefers GitHub over a mirror the worker has not confirmed recently", async () => {
vi.useFakeTimers({ now: NOW });
emptyCache();
vi.stubGlobal("fetch", vi.fn<typeof fetch>().mockResolvedValue(handoffResponse()));

const release = await resolveLatestDesktopRelease(
context(mirrorBucket("2026-11-13T05:00:00.000Z")),
);

expect(release.tag_name).toBe("v0.6.5");
expect(release.assets[0]?.browser_download_url).toContain("github.com");
});

it("falls back to a stale mirror when GitHub refuses, without retrying the refusal", async () => {
vi.useFakeTimers({ now: NOW });
emptyCache();
const fetchMock = vi
.fn<typeof fetch>()
.mockResolvedValue(new Response("Too many requests", { status: 429 }));
vi.stubGlobal("fetch", fetchMock);

const release = await resolveLatestDesktopRelease(
context(mirrorBucket("2026-11-01T00:05:00.000Z")),
);

expect(release.tag_name).toBe("v0.6.4");
expect(release.assets[0]?.browser_download_url).toContain("downloads.scientfactory.com");
expect(fetchMock).toHaveBeenCalledTimes(1);
});

it("ignores an unreadable mirror pointer and resolves from GitHub", async () => {
emptyCache();
vi.stubGlobal("fetch", vi.fn<typeof fetch>().mockResolvedValue(handoffResponse()));

await expect(
resolveLatestDesktopRelease(context(mirrorBucket(null, '{"schemaVersion":1}'))),
).resolves.toMatchObject({ tag_name: "v0.6.5" });
});

it("retries a GitHub server error once", async () => {
vi.useFakeTimers();
emptyCache();
const fetchMock = vi
.fn<typeof fetch>()
.mockResolvedValueOnce(new Response(null, { status: 502 }))
.mockResolvedValueOnce(handoffResponse());
vi.stubGlobal("fetch", fetchMock);

const pending = resolveLatestDesktopRelease(context());
await vi.advanceTimersByTimeAsync(250);

await expect(pending).resolves.toMatchObject({ tag_name: "v0.6.5" });
expect(fetchMock).toHaveBeenCalledTimes(2);
});

it("reports GitHub's refusal with its status when there is no mirror", async () => {
const put = emptyCache();
vi.stubGlobal(
"fetch",
vi.fn<typeof fetch>().mockResolvedValue(new Response(null, { status: 429 })),
);

await expect(resolveLatestDesktopRelease(context())).rejects.toEqual(
upstreamError({ status: 429, error: null, attempts: 1 }),
);
expect(put).not.toHaveBeenCalled();
});

it("rejects an oversized handoff before parsing or caching it", async () => {
const put = vi.fn();
vi.stubGlobal("caches", {
default: { match: vi.fn().mockResolvedValue(undefined), put, delete: vi.fn() },
});
const put = emptyCache();
vi.stubGlobal(
"fetch",
vi
Expand All @@ -97,34 +231,24 @@ describe("latest release resolver", () => {
expect(put).not.toHaveBeenCalled();
});

it("aborts a stalled handoff request at the bounded timeout", async () => {
it("aborts each stalled attempt at the bounded timeout and names the timeout", async () => {
vi.useFakeTimers();
vi.stubGlobal("caches", {
default: {
match: vi.fn().mockResolvedValue(undefined),
put: vi.fn(),
delete: vi.fn(),
},
});
vi.stubGlobal(
"fetch",
vi.fn<typeof fetch>().mockImplementation(
(_input, init) =>
new Promise<Response>((_resolve, reject) => {
init?.signal?.addEventListener("abort", () => reject(new DOMException("Aborted")));
}),
),
emptyCache();
const fetchMock = vi.fn<typeof fetch>().mockImplementation(
(_input, init) =>
new Promise<Response>((_resolve, reject) => {
init?.signal?.addEventListener("abort", () => reject(new DOMException("Aborted")));
}),
);
vi.stubGlobal("fetch", fetchMock);

const pending = resolveLatestDesktopRelease(context());
const rejection = expect(pending).rejects.toEqual(
expect.objectContaining<Partial<LatestReleaseResolutionError>>({
stage: "release_fetch",
reason: "upstream_unavailable",
}),
upstreamError({ status: null, error: "TimeoutError", attempts: 2 }),
);
await vi.advanceTimersByTimeAsync(8_000);
await vi.advanceTimersByTimeAsync(4_000 + 250 + 4_000);
await rejection;
expect(fetchMock).toHaveBeenCalledTimes(2);
});

it("discards an invalid cached value and replaces it from the handoff", async () => {
Expand Down
Loading