refactor(api): ♻️ More OpenAPI refactoring work

api/media/:hash/:name/index.ts

@@ -1,6 +1,7 @@
-import { apiRoute, applyConfig, handleZodError } from "@/api";
-import { zValidator } from "@hono/zod-validator";
+import { apiRoute, applyConfig } from "@/api";
+import { createRoute } from "@hono/zod-openapi";
 import { z } from "zod";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET"],
@@ -24,40 +25,63 @@ export const schemas = {
     }),
 };
 
-export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        zValidator("param", schemas.param, handleZodError),
-        zValidator("header", schemas.header, handleZodError),
-        async (context) => {
-            const { hash, name } = context.req.valid("param");
-            const { range } = context.req.valid("header");
-
-            // parse `Range` header
-            const [start = 0, end = Number.POSITIVE_INFINITY] = (
-                range
-                    .split("=") // ["Range: bytes", "0-100"]
-                    .at(-1) || ""
-            ) // "0-100"
-                .split("-") // ["0", "100"]
-                .map(Number); // [0, 100]
-
-            // Serve file from filesystem
-            const file = Bun.file(`./uploads/${hash}/${name}`);
-
-            const buffer = await file.arrayBuffer();
-
-            if (!(await file.exists())) {
-                return context.json({ error: "File not found" }, 404);
-            }
-
-            // Can't directly copy file into Response because this crashes Bun for now
-            return context.newResponse(buffer, 200, {
-                "Content-Type": file.type || "application/octet-stream",
-                "Content-Length": `${file.size - start}`,
-                "Content-Range": `bytes ${start}-${end}/${file.size}`,
-            });
+const route = createRoute({
+    method: "get",
+    path: "/media/{hash}/{name}",
+    summary: "Get media file by hash and name",
+    request: {
+        params: schemas.param,
+        headers: schemas.header,
+    },
+    responses: {
+        200: {
+            description: "Media",
+            content: {
+                "*": {
+                    schema: z.any(),
+                },
+            },
         },
-    ),
+        404: {
+            description: "File not found",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
+export default apiRoute((app) =>
+    app.openapi(route, async (context) => {
+        const { hash, name } = context.req.valid("param");
+        const { range } = context.req.valid("header");
+
+        // parse `Range` header
+        const [start = 0, end = Number.POSITIVE_INFINITY] = (
+            range
+                .split("=") // ["Range: bytes", "0-100"]
+                .at(-1) || ""
+        ) // "0-100"
+            .split("-") // ["0", "100"]
+            .map(Number); // [0, 100]
+
+        // Serve file from filesystem
+        const file = Bun.file(`./uploads/${hash}/${name}`);
+
+        const buffer = await file.arrayBuffer();
+
+        if (!(await file.exists())) {
+            return context.json({ error: "File not found" }, 404);
+        }
+
+        // Can't directly copy file into Response because this crashes Bun for now
+        return context.newResponse(buffer, 200, {
+            "Content-Type": file.type || "application/octet-stream",
+            "Content-Length": `${file.size - start}`,
+            "Content-Range": `bytes ${start}-${end}/${file.size}`,
+            // biome-ignore lint/suspicious/noExplicitAny: Hono doesn't type this response so this has a TS error
+        }) as any;
+    }),
 );

api/media/proxy/:id.ts

@@ -1,8 +1,9 @@
-import { apiRoute, applyConfig, handleZodError } from "@/api";
-import { zValidator } from "@hono/zod-validator";
+import { apiRoute, applyConfig } from "@/api";
+import { createRoute } from "@hono/zod-openapi";
 import type { StatusCode } from "hono/utils/http-status";
 import { z } from "zod";
 import { config } from "~/packages/config-manager";
+import { ErrorSchema } from "~/types/api";
 
 export const meta = applyConfig({
     allowedMethods: ["GET"],
@@ -24,54 +25,76 @@ export const schemas = {
     }),
 };
 
-export default apiRoute((app) =>
-    app.on(
-        meta.allowedMethods,
-        meta.route,
-        zValidator("param", schemas.param, handleZodError),
-        async (context) => {
-            const { id } = context.req.valid("param");
-
-            // Check if URL is valid
-            if (!URL.canParse(id)) {
-                return context.json(
-                    { error: "Invalid URL (it should be encoded as base64url" },
-                    400,
-                );
-            }
-
-            const media = await fetch(id, {
-                headers: {
-                    "Accept-Encoding": "br",
+const route = createRoute({
+    method: "get",
+    path: "/media/proxy/{id}",
+    summary: "Proxy media through the server",
+    request: {
+        params: schemas.param,
+    },
+    responses: {
+        200: {
+            description: "Media",
+            content: {
+                "*": {
+                    schema: z.any(),
                 },
-                // @ts-expect-error Proxy is a Bun-specific feature
-                proxy: config.http.proxy.address,
-            });
-
-            // Check if file extension ends in svg or svg
-            // Cloudflare R2 serves those as application/xml
-            if (
-                media.headers.get("Content-Type") === "application/xml" &&
-                id.endsWith(".svg")
-            ) {
-                media.headers.set("Content-Type", "image/svg+xml");
-            }
-
-            const realFilename =
-                media.headers
-                    .get("Content-Disposition")
-                    ?.match(/filename="(.+)"/)?.[1] || id.split("/").pop();
-
-            return context.newResponse(media.body, media.status as StatusCode, {
-                "Content-Type":
-                    media.headers.get("Content-Type") ||
-                    "application/octet-stream",
-                "Content-Length": media.headers.get("Content-Length") || "0",
-                "Content-Security-Policy": "",
-                "Content-Encoding": "",
-                // Real filename
-                "Content-Disposition": `inline; filename="${realFilename}"`,
-            });
+            },
         },
-    ),
+        400: {
+            description: "Invalid URL to proxy",
+            content: {
+                "application/json": {
+                    schema: ErrorSchema,
+                },
+            },
+        },
+    },
+});
+
+export default apiRoute((app) =>
+    app.openapi(route, async (context) => {
+        const { id } = context.req.valid("param");
+
+        // Check if URL is valid
+        if (!URL.canParse(id)) {
+            return context.json(
+                { error: "Invalid URL (it should be encoded as base64url" },
+                400,
+            );
+        }
+
+        const media = await fetch(id, {
+            headers: {
+                "Accept-Encoding": "br",
+            },
+            // @ts-expect-error Proxy is a Bun-specific feature
+            proxy: config.http.proxy.address,
+        });
+
+        // Check if file extension ends in svg or svg
+        // Cloudflare R2 serves those as application/xml
+        if (
+            media.headers.get("Content-Type") === "application/xml" &&
+            id.endsWith(".svg")
+        ) {
+            media.headers.set("Content-Type", "image/svg+xml");
+        }
+
+        const realFilename =
+            media.headers
+                .get("Content-Disposition")
+                ?.match(/filename="(.+)"/)?.[1] || id.split("/").pop();
+
+        return context.newResponse(media.body, media.status as StatusCode, {
+            "Content-Type":
+                media.headers.get("Content-Type") || "application/octet-stream",
+            "Content-Length": media.headers.get("Content-Length") || "0",
+            "Content-Security-Policy": "",
+            "Content-Encoding": "",
+            // Real filename
+            "Content-Disposition": `inline; filename="${realFilename}"`,
+            // biome-ignore lint/suspicious/noExplicitAny: Hono doesn't type this response so this has a TS error
+        }) as any;
+    }),
 );