Skip to content

Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.

✨ Make the update check channel-aware and add the new-major notice (#2983)

Luke Vella6fe12bf9053c
diff --git a/apps/web/public/locales/en/app.json b/apps/web/public/locales/en/app.json
index 6e5d15363..d168ac2ee 100644
--- a/apps/web/public/locales/en/app.json
+++ b/apps/web/public/locales/en/app.json
@@ -812,6 +812,7 @@
"verifyEmail": "Verify your email",
"verifyEmailDescription": "Enter the 6-digit code we sent to <b>{email}</b>",
"verifyEmailTitle": "Verify your email",
+ "versionTileNewMajorNotice": "v{major} is available. Read the migration guide.",
"viewClosedPolls": "View closed polls",
"viewInvites": "View invites",
"viewPoll": "View poll",
diff --git a/apps/web/src/app/[locale]/control-panel/version-tile.tsx b/apps/web/src/app/[locale]/control-panel/version-tile.tsx
index 5d8789416..77ce9a29f 100644
--- a/apps/web/src/app/[locale]/control-panel/version-tile.tsx
+++ b/apps/web/src/app/[locale]/control-panel/version-tile.tsx
@@ -9,48 +9,92 @@ import { appVersion } from "@/lib/constants";
const RELEASES_URL = "https://github.com/lukevella/rallly/releases";
-async function UpdateStatus() {
+const versionLabel = appVersion
+ ? `v${appVersion.replace(/^v/, "")}`
+ : "unknown";
+
+// The title link is stretched over the whole tile; the new-major notice sits
+// above it (position: relative) so both stay real, non-nested anchors.
+function VersionTileFrame({
+ href,
+ children,
+}: {
+ href: string;
+ children?: React.ReactNode;
+}) {
+ return (
+ <Tile>
+ <PageIcon>
+ <DownloadIcon />
+ </PageIcon>
+ <TileTitle>
+ <a
+ href={href}
+ target="_blank"
+ rel="noreferrer noopener"
+ className="after:absolute after:inset-0"
+ >
+ {versionLabel}
+ </a>
+ </TileTitle>
+ {children}
+ </Tile>
+ );
+}
+
+async function UpdateStatusTile() {
const update = await loadUpdateStatus();
if (!update) {
- return null;
+ return <VersionTileFrame href={RELEASES_URL} />;
}
const { t } = await getTranslation();
- if (update.status === "up-to-date") {
- return (
- <span className="text-green-600 text-sm">
- {t("upToDate", { defaultValue: "Up to date" })}
- </span>
- );
- }
-
return (
- <span className="text-primary text-sm">
- {t("updateAvailable", { defaultValue: "Update available" })}
- </span>
+ <VersionTileFrame
+ href={update.status === "update-available" ? update.url : RELEASES_URL}
+ >
+ {update.newMajor ? (
+ <a
+ href={update.newMajor.migrationGuideUrl}
+ target="_blank"
+ rel="noreferrer noopener"
+ className="relative mt-1 text-amber-600 text-sm hover:underline"
+ >
+ {t("versionTileNewMajorNotice", {
+ defaultValue: "v{major} is available. Read the migration guide.",
+ major: update.newMajor.major,
+ })}
+ </a>
+ ) : null}
+ <TileDescription>
+ {update.status === "up-to-date" ? (
+ <span className="text-green-600">
+ {t("upToDate", { defaultValue: "Up to date" })}
+ </span>
+ ) : (
+ <span className="text-primary">
+ {t("updateAvailable", { defaultValue: "Update available" })}
+ </span>
+ )}
+ </TileDescription>
+ </VersionTileFrame>
);
}
export function VersionTile() {
return (
- <Tile
- render={
- <a href={RELEASES_URL} target="_blank" rel="noreferrer noopener" />
+ <Suspense
+ fallback={
+ <VersionTileFrame href={RELEASES_URL}>
+ <TileDescription>
+ <Skeleton className="h-4 w-24" />
+ </TileDescription>
+ </VersionTileFrame>
}
>
- <PageIcon>
- <DownloadIcon />
- </PageIcon>
- <TileTitle>
- {appVersion ? `v${appVersion.replace(/^v/, "")}` : "unknown"}
- </TileTitle>
- <TileDescription>
- <Suspense fallback={<Skeleton className="h-4 w-24" />}>
- <UpdateStatus />
- </Suspense>
- </TileDescription>
- </Tile>
+ <UpdateStatusTile />
+ </Suspense>
);
}
diff --git a/apps/web/src/app/api/updates/release-channels.test.ts b/apps/web/src/app/api/updates/release-channels.test.ts
new file mode 100644
index 000000000..1c62e4144
--- /dev/null
+++ b/apps/web/src/app/api/updates/release-channels.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { buildReleaseChannels } from "./release-channels";
+
+function release(tag: string, overrides: Record<string, unknown> = {}) {
+ return {
+ tag_name: tag,
+ html_url: `https://github.com/lukevella/rallly/releases/tag/${tag}`,
+ published_at: "2026-01-01T00:00:00Z",
+ draft: false,
+ prerelease: false,
+ ...overrides,
+ };
+}
+
+describe("buildReleaseChannels", () => {
+ it("keeps the newest release per major regardless of list order", () => {
+ const channels = buildReleaseChannels([
+ release("v4.2.0"),
+ release("v5.0.0"),
+ release("v4.10.0"),
+ release("v4.1.0"),
+ release("v5.1.0"),
+ ]);
+
+ expect(channels).not.toBeNull();
+ expect(channels?.latestByMajor[4]?.version).toBe("v4.10.0");
+ expect(channels?.latestByMajor[5]?.version).toBe("v5.1.0");
+ expect(channels?.latestMajor).toBe(5);
+ });
+
+ it("excludes drafts, prereleases, and non-stable tags", () => {
+ const channels = buildReleaseChannels([
+ release("v4.1.0"),
+ release("v6.0.0", { draft: true }),
+ release("v5.0.0", { prerelease: true }),
+ release("v5.0.0-beta.1"),
+ release("4-beta"),
+ ]);
+
+ expect(channels?.latestMajor).toBe(4);
+ expect(channels?.latestByMajor[5]).toBeUndefined();
+ expect(channels?.latestByMajor[6]).toBeUndefined();
+ });
+
+ it("skips releases without a published date", () => {
+ const channels = buildReleaseChannels([
+ release("v4.1.0"),
+ release("v5.0.0", { published_at: null }),
+ ]);
+
+ expect(channels?.latestMajor).toBe(4);
+ });
+
+ it("skips malformed entries instead of failing the list", () => {
+ const channels = buildReleaseChannels([
+ null,
+ {},
+ { tag_name: "v9.0.0" },
+ release("v4.1.0"),
+ ]);
+
+ expect(channels?.latestMajor).toBe(4);
+ expect(channels?.latestByMajor[4]?.version).toBe("v4.1.0");
+ });
+
+ it("returns null when nothing usable remains", () => {
+ expect(buildReleaseChannels([])).toBeNull();
+ expect(buildReleaseChannels([release("nightly")])).toBeNull();
+ expect(buildReleaseChannels({ not: "an array" })).toBeNull();
+ });
+});
diff --git a/apps/web/src/app/api/updates/release-channels.ts b/apps/web/src/app/api/updates/release-channels.ts
new file mode 100644
index 000000000..2e735bd85
--- /dev/null
+++ b/apps/web/src/app/api/updates/release-channels.ts
@@ -0,0 +1,58 @@
+import * as z from "zod";
+import {
+ getMajorVersion,
+ isOutdated,
+} from "@/features/instance-settings/utils";
+
+const releaseSchema = z.object({
+ tag_name: z.string().min(1),
+ html_url: z.string().min(1),
+ published_at: z.string().nullish(),
+ draft: z.boolean().optional(),
+ prerelease: z.boolean().optional(),
+});
+
+const STABLE_TAG_REGEX = /^v?\d+\.\d+\.\d+$/;
+
+export type ReleaseInfo = {
+ version: string;
+ url: string;
+ publishedAt: string;
+};
+
+export type ReleaseChannels = {
+ latestByMajor: Record<number, ReleaseInfo>;
+ latestMajor: number;
+};
+
+export function buildReleaseChannels(input: unknown): ReleaseChannels | null {
+ if (!Array.isArray(input)) return null;
+
+ const latestByMajor: Record<number, ReleaseInfo> = {};
+
+ for (const item of input) {
+ const parsed = releaseSchema.safeParse(item);
+ if (!parsed.success) continue;
+
+ const { tag_name, html_url, published_at, draft, prerelease } = parsed.data;
+ if (draft || prerelease || !published_at) continue;
+ if (!STABLE_TAG_REGEX.test(tag_name)) continue;
+
+ const major = getMajorVersion(tag_name);
+ if (major === null) continue;
+
+ const current = latestByMajor[major];
+ if (!current || isOutdated(current.version, tag_name)) {
+ latestByMajor[major] = {
+ version: tag_name,
+ url: html_url,
+ publishedAt: published_at,
+ };
+ }
+ }
+
+ const majors = Object.keys(latestByMajor).map(Number);
+ if (majors.length === 0) return null;
+
+ return { latestByMajor, latestMajor: Math.max(...majors) };
+}
diff --git a/apps/web/src/app/api/updates/route.ts b/apps/web/src/app/api/updates/route.ts
index dacaae7f8..35f1ebbab 100644
--- a/apps/web/src/app/api/updates/route.ts
+++ b/apps/web/src/app/api/updates/route.ts
@@ -3,29 +3,40 @@ import { createLogger } from "@rallly/logger";
import type { NextRequest } from "next/server";
import { after, NextResponse } from "next/server";
import * as z from "zod";
+import { getMajorVersion } from "@/features/instance-settings/utils";
import { createCache } from "@/lib/cache";
import { isSelfHosted } from "@/lib/constants";
import { createRatelimit } from "@/lib/rate-limit";
+import type { ReleaseChannels } from "./release-channels";
+import { buildReleaseChannels } from "./release-channels";
const logger = createLogger("api/updates");
const GITHUB_RELEASES_URL =
- "https://api.github.com/repos/lukevella/rallly/releases/latest";
-
-const upstreamSchema = z.object({
- tag_name: z.string().min(1),
- html_url: z.string().min(1),
- published_at: z.string().min(1),
-});
+ "https://api.github.com/repos/lukevella/rallly/releases";
+const RELEASES_PER_PAGE = 100;
+// Sequential unauthenticated requests count against a 60/hour IP budget, so
+// pagination is bounded; older majors beyond this window report no update.
+const MAX_RELEASE_PAGES = 3;
+
+// The fleet starts linking here the moment a new major's first release is
+// tagged — the guide must be published at this path before tagging.
+function getMigrationGuideUrl(major: number) {
+ return `https://support.rallly.co/self-hosting/migrate-to-v${major}`;
+}
type UpdatesPayload = {
- latest: string;
- url: string;
- publishedAt: string;
+ latest: string | null;
+ url: string | null;
+ publishedAt: string | null;
+ newMajor?: {
+ version: string;
+ migrationGuideUrl: string;
+ };
};
-const latestReleaseCache = createCache<UpdatesPayload>({
- namespace: "updates:latest-release",
+const releaseChannelsCache = createCache<ReleaseChannels>({
+ namespace: "updates:release-channels",
ttl: "1 h",
});
@@ -36,34 +47,87 @@ const seenInstanceCache = createCache<string>({
const ratelimit = createRatelimit(60, "1 h");
-async function fetchLatestRelease(): Promise<UpdatesPayload | null> {
- const res = await fetch(GITHUB_RELEASES_URL, {
- headers: {
- Accept: "application/vnd.github+json",
- "User-Agent": "Rallly",
- },
- });
- if (!res.ok) return null;
-
- const parsed = upstreamSchema.safeParse(await res.json());
- if (!parsed.success) return null;
+async function fetchReleaseChannels(): Promise<ReleaseChannels | null> {
+ try {
+ // One deadline for the whole pagination, just under the self-hosted
+ // client's 3s budget so a slow GitHub response still yields our
+ // controlled 502 instead of a hung slot
+ const signal = AbortSignal.timeout(2500);
+ const releases: unknown[] = [];
+
+ for (let page = 1; page <= MAX_RELEASE_PAGES; page++) {
+ const res = await fetch(
+ `${GITHUB_RELEASES_URL}?per_page=${RELEASES_PER_PAGE}&page=${page}`,
+ {
+ headers: {
+ Accept: "application/vnd.github+json",
+ "User-Agent": "Rallly",
+ },
+ signal,
+ },
+ );
+ if (!res.ok) return null;
+
+ const batch = await res.json();
+ if (!Array.isArray(batch)) return null;
+
+ releases.push(...batch);
+ if (batch.length < RELEASES_PER_PAGE) break;
+ if (page === MAX_RELEASE_PAGES) {
+ logger.warn(
+ { pages: MAX_RELEASE_PAGES },
+ "Release list truncated at the pagination bound",
+ );
+ }
+ }
- return {
- latest: parsed.data.tag_name,
- url: parsed.data.html_url,
- publishedAt: parsed.data.published_at,
- };
+ return buildReleaseChannels(releases);
+ } catch (error) {
+ logger.warn({ error }, "Failed to fetch releases from GitHub");
+ return null;
+ }
}
-async function getLatestRelease(): Promise<UpdatesPayload | null> {
- const cached = await latestReleaseCache.get("latest");
+async function getReleaseChannels(): Promise<ReleaseChannels | null> {
+ const cached = await releaseChannelsCache.get("channels");
if (cached) return cached;
- const fresh = await fetchLatestRelease();
- if (fresh) await latestReleaseCache.set("latest", fresh);
+ const fresh = await fetchReleaseChannels();
+ if (fresh) await releaseChannelsCache.set("channels", fresh);
return fresh;
}
+function buildPayload(
+ channels: ReleaseChannels,
+ requestedMajor: number | null,
+): UpdatesPayload {
+ const latestRelease = channels.latestByMajor[channels.latestMajor];
+
+ if (requestedMajor === null) {
+ return {
+ latest: latestRelease.version,
+ url: latestRelease.url,
+ publishedAt: latestRelease.publishedAt,
+ };
+ }
+
+ const ownChannel = channels.latestByMajor[requestedMajor];
+
+ return {
+ latest: ownChannel?.version ?? null,
+ url: ownChannel?.url ?? null,
+ publishedAt: ownChannel?.publishedAt ?? null,
+ ...(channels.latestMajor > requestedMajor
+ ? {
+ newMajor: {
+ version: latestRelease.version,
+ migrationGuideUrl: getMigrationGuideUrl(channels.latestMajor),
+ },
+ }
+ : {}),
+ };
+}
+
export async function GET(request: NextRequest) {
if (isSelfHosted) {
return new NextResponse(null, { status: 404 });
@@ -78,9 +142,9 @@ export async function GET(request: NextRequest) {
}
}
- const payload = await getLatestRelease();
+ const channels = await getReleaseChannels();
- if (!payload) {
+ if (!channels) {
return NextResponse.json(
{ error: "upstream_unavailable" },
{ status: 502 },
@@ -119,5 +183,9 @@ export async function GET(request: NextRequest) {
});
}
- return NextResponse.json(payload);
+ const requestedMajor = parsedVersion.success
+ ? getMajorVersion(parsedVersion.data)
+ : null;
+
+ return NextResponse.json(buildPayload(channels, requestedMajor));
}
diff --git a/apps/web/src/features/instance-settings/service.ts b/apps/web/src/features/instance-settings/service.ts
index 768b591b4..190dc1bf1 100644
--- a/apps/web/src/features/instance-settings/service.ts
+++ b/apps/web/src/features/instance-settings/service.ts
@@ -4,35 +4,22 @@ import { createLogger } from "@rallly/logger";
import * as z from "zod";
import { env } from "@/env";
import { appVersion } from "@/lib/constants";
+import { getMajorVersion, isOutdated } from "./utils";
const logger = createLogger("update-check");
const updateStatusSchema = z.object({
- latest: z.string(),
- url: z.string(),
- publishedAt: z.string(),
+ latest: z.string().nullish(),
+ url: z.string().nullish(),
+ publishedAt: z.string().nullish(),
+ newMajor: z
+ .object({
+ version: z.string(),
+ migrationGuideUrl: z.string(),
+ })
+ .nullish(),
});
-function normalizeVersion(version: string) {
- return version.replace(/^v/, "").split(/[-+]/)[0];
-}
-
-function isOutdated(current: string, latest: string) {
- const a = normalizeVersion(current)
- .split(".")
- .map((n) => Number(n) || 0);
- const b = normalizeVersion(latest)
- .split(".")
- .map((n) => Number(n) || 0);
- const len = Math.max(a.length, b.length);
- for (let i = 0; i < len; i++) {
- const ai = a[i] ?? 0;
- const bi = b[i] ?? 0;
- if (ai !== bi) return ai < bi;
- }
- return false;
-}
-
export async function getUpdateStatus({ instanceId }: { instanceId: string }) {
if (!appVersion || !env.API_BASE_URL) return null;
@@ -62,10 +49,43 @@ export async function getUpdateStatus({ instanceId }: { instanceId: string }) {
);
return null;
}
- if (!isOutdated(appVersion, parsed.data.latest)) {
- return { status: "up-to-date" as const };
- }
- return { status: "update-available" as const, ...parsed.data };
+
+ const currentMajor = getMajorVersion(appVersion);
+ const { latest, url: releaseUrl, publishedAt, newMajor } = parsed.data;
+
+ // The endpoint scopes `latest` to our own major. Guard anyway: a release
+ // from another major must never surface as a pullable update, and this
+ // code is frozen in fleet binaries.
+ const withinMajor =
+ latest &&
+ releaseUrl &&
+ publishedAt &&
+ currentMajor !== null &&
+ getMajorVersion(latest) === currentMajor &&
+ isOutdated(appVersion, latest)
+ ? {
+ status: "update-available" as const,
+ latest,
+ url: releaseUrl,
+ publishedAt,
+ }
+ : { status: "up-to-date" as const };
+
+ const newMajorVersion = newMajor ? getMajorVersion(newMajor.version) : null;
+
+ return {
+ ...withinMajor,
+ newMajor:
+ newMajor &&
+ currentMajor !== null &&
+ newMajorVersion !== null &&
+ newMajorVersion > currentMajor
+ ? {
+ major: newMajorVersion,
+ migrationGuideUrl: newMajor.migrationGuideUrl,
+ }
+ : null,
+ };
} catch (error) {
logger.warn(
{ error, instanceId, version: appVersion },
diff --git a/apps/web/src/features/instance-settings/utils.test.ts b/apps/web/src/features/instance-settings/utils.test.ts
new file mode 100644
index 000000000..7cf18cc7b
--- /dev/null
+++ b/apps/web/src/features/instance-settings/utils.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { getMajorVersion, isOutdated } from "./utils";
+
+describe("getMajorVersion", () => {
+ it("extracts the major from a tagged version", () => {
+ expect(getMajorVersion("v4.5.1")).toBe(4);
+ });
+
+ it("extracts the major from an untagged version", () => {
+ expect(getMajorVersion("4.5.1")).toBe(4);
+ });
+
+ it("ignores prerelease suffixes", () => {
+ expect(getMajorVersion("5.0.0-beta.1")).toBe(5);
+ });
+
+ it("returns null for non-version strings", () => {
+ expect(getMajorVersion("unknown")).toBeNull();
+ expect(getMajorVersion("")).toBeNull();
+ });
+
+ it("rejects malformed versions with numeric prefixes", () => {
+ expect(getMajorVersion("4foo")).toBeNull();
+ expect(getMajorVersion("4.5x")).toBeNull();
+ });
+});
+
+describe("isOutdated", () => {
+ it("detects an older patch version", () => {
+ expect(isOutdated("4.1.0", "4.1.1")).toBe(true);
+ });
+
+ it("detects an older minor version numerically", () => {
+ expect(isOutdated("4.9.0", "4.10.0")).toBe(true);
+ });
+
+ it("treats equal versions as current", () => {
+ expect(isOutdated("v4.2.0", "v4.2.0")).toBe(false);
+ });
+
+ it("treats newer versions as current", () => {
+ expect(isOutdated("4.10.0", "4.9.0")).toBe(false);
+ });
+
+ it("compares across majors without guarding", () => {
+ expect(isOutdated("4.2.0", "5.0.0")).toBe(true);
+ });
+
+ it("ignores prerelease suffixes", () => {
+ expect(isOutdated("4.2.0-beta.1", "4.2.0")).toBe(false);
+ });
+});
diff --git a/apps/web/src/features/instance-settings/utils.ts b/apps/web/src/features/instance-settings/utils.ts
index 14753c9c8..f28c00b66 100644
--- a/apps/web/src/features/instance-settings/utils.ts
+++ b/apps/web/src/features/instance-settings/utils.ts
@@ -6,3 +6,32 @@ export function isInitialAdmin(email: string) {
email.toLowerCase() === process.env.INITIAL_ADMIN_EMAIL.toLowerCase()
);
}
+
+function normalizeVersion(version: string) {
+ return version.replace(/^v/, "").split(/[-+]/)[0];
+}
+
+export function getMajorVersion(version: string) {
+ const normalized = normalizeVersion(version);
+ if (!/^\d+(\.\d+){0,2}$/.test(normalized)) return null;
+ return Number(normalized.split(".")[0]);
+}
+
+// Compares release numbers only — prerelease/build suffixes are ignored, so
+// "4.2.0-beta.1" is not outdated relative to "4.2.0". Callers that must not
+// cross majors need to guard with getMajorVersion themselves.
+export function isOutdated(current: string, latest: string) {
+ const a = normalizeVersion(current)
+ .split(".")
+ .map((n) => Number(n) || 0);
+ const b = normalizeVersion(latest)
+ .split(".")
+ .map((n) => Number(n) || 0);
+ const len = Math.max(a.length, b.length);
+ for (let i = 0; i < len; i++) {
+ const ai = a[i] ?? 0;
+ const bi = b[i] ?? 0;
+ if (ai !== bi) return ai < bi;
+ }
+ return false;
+}