mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-17 07:42:23 +00:00
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:
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)`);
|
||||
},
|
||||
);
|
||||
});
|
||||
@@ -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;
|
||||
}
|
||||
Reference in new issue
Block a user