feat(api): date deprecations and log which builds still call them

/api/feature-flags answered Deprecation: true and nothing else: a client
learned the route was going, never when, and the log could not tell which
builds still called it. deprecated() (src/lib/http/deprecation.ts) applies
one reviewed notice per route: Deprecation as an RFC 9745 date, Sunset as
an RFC 8594 HTTP-date, the successor Link, and a wide-event annotation
with the client build read from the User-Agent.

feature-flags was deprecated on 2026-09-24 (v1.39.0); its sunset is
2027-03-31. The headers are declared on the operation, and a test holds
every notice to a deprecated operation that answers through the helper.
This commit is contained in:
Marc-André Bombeck committed 2026-10-20 13:57:11 +02:00
1 parent 39d23dbb7d
commit 9fda88586c
6 files changed
+237 -10

No files matched your search

@@ -0,0 +1,95 @@
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { beforeEach, describe, expect, it, vi } from "vitest";
vi.mock("@/lib/logging/context", () => ({ annotate: vi.fn() }));
import { annotate } from "@/lib/logging/context";
import { buildOpenApiDocument } from "@/lib/openapi/registry";
import { clientBuildOf, deprecated, DEPRECATIONS } from "../deprecation";
beforeEach(() => vi.mocked(annotate).mockClear());
function request(userAgent?: string): Request {
return new Request("http://localhost/api/feature-flags", {
headers: userAgent ? { "user-agent": userAgent } : {},
});
}
describe("deprecated()", () => {
it("dates the deprecation and the sunset, and names the successor", () => {
const res = deprecated(
new Response(null, { headers: { Link: '</a>; rel="next"' } }),
"/api/feature-flags",
request(),
);
const notice = DEPRECATIONS["/api/feature-flags"];
expect(res.headers.get("Deprecation")).toBe(
`@${Date.parse(`${notice.since}T00:00:00Z`) / 1000}`,
);
expect(new Date(res.headers.get("Sunset")!).toISOString()).toBe(
`${notice.sunset}T00:00:00.000Z`,
);
// A Link the route already set survives beside the successor.
expect(res.headers.get("Link")).toBe(
'</a>; rel="next", </api/auth/me>; rel="successor-version"',
);
});
it("logs which client build still asked", () => {
deprecated(
new Response(null),
"/api/feature-flags",
request("HealthLog-iOS/1.2.0 (dev.healthlog.app)"),
);
expect(annotate).toHaveBeenCalledWith({
meta: {
deprecated_route: "/api/feature-flags",
deprecation_sunset: DEPRECATIONS["/api/feature-flags"].sunset,
client_build: "ios/1.2.0",
},
});
});
it("sunsets every notice after it was deprecated", () => {
for (const notice of Object.values(DEPRECATIONS)) {
expect(Date.parse(notice.sunset)).toBeGreaterThan(
Date.parse(notice.since),
);
}
});
});
describe("clientBuildOf", () => {
it("reads the native build, a browser, anything else, and nothing", () => {
expect(clientBuildOf("HealthLog-iOS/1.3.0 (dev.healthlog.app)")).toBe(
"ios/1.3.0",
);
expect(
clientBuildOf("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"),
).toBe("web");
expect(clientBuildOf("curl/8.4.0")).toBe("other");
expect(clientBuildOf(null)).toBeNull();
});
});
describe("each deprecation is published and applied", () => {
const doc = buildOpenApiDocument() as unknown as {
paths: Record<string, Record<string, { deprecated?: boolean }>>;
};
it.each(Object.keys(DEPRECATIONS))(
"%s is deprecated in the contract and answers through the helper",
(route) => {
const ops = Object.values(doc.paths[route] ?? {});
expect(ops.length).toBeGreaterThan(0);
expect(ops.every((op) => op.deprecated === true)).toBe(true);
const src = readFileSync(
join(process.cwd(), "src/app", route, "route.ts"),
"utf8",
);
expect(src).toContain(`deprecated(response, "${route}", request)`);
},
);
});
+96
View File
@@ -0,0 +1,96 @@
/**
* How a deprecated route says so: on the wire, and in the operator's log.
*
* `/api/feature-flags` was marked deprecated with a bare `Deprecation: true`
* and no date at all: a client could learn that the route was going, never
* when, and the operator could not tell which builds still called it, so the
* removal criterion ("the first release after the native build that reads
* `ai` ships") could not be checked against anything. A deprecation is now one
* reviewed notice per route, applied with {@link deprecated}:
*
* - `Deprecation: @<unix seconds>` — when it was deprecated (RFC 9745);
* - `Sunset: <HTTP-date>` — from when the route may stop answering
* (RFC 8594);
* - `Link: <successor>; rel="successor-version"` — where to go instead;
* - a wide-event annotation naming the route's notice and the calling
* client build, read off the `User-Agent`, so the log answers "who still
* calls this" before the sunset arrives.
*
* The notices live in {@link DEPRECATIONS}, so the dates are in one place and
* `deprecation.test.ts` holds each route that applies one to the OpenAPI
* `deprecated` flag.
*/
import { annotate } from "@/lib/logging/context";
export interface DeprecationNotice {
/** The day the route was deprecated, `YYYY-MM-DD` (UTC). */
since: string;
/** The first day the route may stop answering, `YYYY-MM-DD` (UTC). */
sunset: string;
/** The path that replaces it, when there is one. */
successor?: string;
}
/**
* Every route that answers as deprecated, with its dates.
*
* `/api/feature-flags`: deprecated in v1.39.0 (2026-09-24), when `ai` on
* `GET /api/auth/me` replaced it. The shipped native build still reads it, so
* the sunset leaves two native release cycles.
*/
export const DEPRECATIONS = {
"/api/feature-flags": {
since: "2026-09-24",
sunset: "2027-03-31",
successor: "/api/auth/me",
},
} as const satisfies Record<string, DeprecationNotice>;
export type DeprecatedRoute = keyof typeof DEPRECATIONS;
function utcDay(day: string): Date {
if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) {
throw new Error(`Deprecation date must be YYYY-MM-DD, got "${day}"`);
}
return new Date(`${day}T00:00:00.000Z`);
}
/**
* The calling client, coarsely: `ios/<version>` for the native app (its
* `User-Agent` is `HealthLog-iOS/<version> (<bundle id>)`), `web` for a
* browser, `other` for anything else, null with no header.
*/
export function clientBuildOf(userAgent: string | null): string | null {
if (!userAgent) return null;
const ios = /^HealthLog-iOS\/([0-9][0-9A-Za-z.+-]{0,31})/.exec(userAgent);
if (ios) return `ios/${ios[1]}`;
if (/^Mozilla\//.test(userAgent)) return "web";
return "other";
}
/** Mark a response as coming from a deprecated route, and log who asked. */
export function deprecated<R extends Response>(
response: R,
route: DeprecatedRoute,
request: Request,
): R {
const notice: DeprecationNotice = DEPRECATIONS[route];
const since = utcDay(notice.since);
const sunset = utcDay(notice.sunset);
response.headers.set("Deprecation", `@${Math.floor(since.getTime() / 1000)}`);
response.headers.set("Sunset", sunset.toUTCString());
if (notice.successor) {
response.headers.append(
"Link",
`<${notice.successor}>; rel="successor-version"`,
);
}
annotate({
meta: {
deprecated_route: route,
deprecation_sunset: notice.sunset,
client_build: clientBuildOf(request.headers.get("user-agent")),
},
});
return response;
}