@everysk/apps-devkit 0.2.0 → 0.3.0-beta-20261019175049

package/src/vite/plugins/serveDevFiles.ts

@@ -0,0 +1,216 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { Plugin } from "vite";
+
+import { createApiTokenSource, type ApiTokenSource } from "../apiToken.js";
+
+/** Every path under the platform's file route, claimed whole so none falls through to `index.html`. */
+const FILE_ROUTE = /^\/file\//;
+
+/**
+ * A file's url as the platform serves it: the hex of a version-4 UUID, as everysk/client's
+ * `FileRequestHandler` matches it (`RE_FILE_URL`).
+ */
+const FILE_URL = /^\/file\/([0-9a-f]{12}4[0-9a-f]{3}[89ab][0-9a-f]{15})\/?(?:\?.*)?$/;
+
+/** What `createDevFileRoute` needs: the API and its token, a `fetch` and a log to replace in tests. */
+type DevFileRouteParams = ApiTokenSource & {
+    fetch?: typeof fetch;
+    log?: (message: string) => void;
+};
+
+type ListedFile = { name: string; content_type: string | null; data: string | null };
+
+type RouteRequest = Pick<IncomingMessage, "url" | "method">;
+type RouteResponse = Pick<ServerResponse, "statusCode" | "setHeader" | "end">;
+
+/** Why a file could not be served, with the status to answer it with. */
+class FileRouteError extends Error {
+    readonly status: number;
+
+    constructor(status: number, message: string) {
+        super(message);
+        this.status = status;
+    }
+}
+
+/** The error and, when Node gives one, its cause, which is where fetch keeps ECONNREFUSED or DNS. */
+const describeError = (error: unknown): string => {
+    if (!(error instanceof Error)) return String(error);
+    return error.cause instanceof Error
+        ? `${error.message}: ${error.cause.message}`
+        : error.message;
+};
+
+/** The API's own `message` from a refusal, or the start of whatever came back instead. */
+const refusalOf = async (response: Response): Promise<string> => {
+    const text = await response.text();
+    try {
+        return (JSON.parse(text) as { message?: string }).message ?? text.slice(0, 200);
+    } catch {
+        return text.slice(0, 200);
+    }
+};
+
+/**
+ * The file whose stored url is `/<hash>`, read with its content. A file stores its url as
+ * `/<hash>` and the API adds `/file` only when it returns it, and the file list accepts a `url`
+ * filter without a workspace (everysk-lib 1.13.4 `sdk/entities/file`, everysk/client
+ * `File.validate_query`).
+ */
+const findFile = async (
+    fetchApi: typeof fetch,
+    apiUrl: string,
+    accessToken: string,
+    hash: string,
+) => {
+    const query = JSON.stringify({ filters: [["url", `/${hash}`]], page_size: 1 });
+    let response: Response;
+    try {
+        response = await fetchApi(`${apiUrl}/files?query=${encodeURIComponent(query)}`, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+    } catch (error) {
+        throw new FileRouteError(502, `The API could not be reached: ${describeError(error)}`);
+    }
+
+    if (!response.ok) {
+        const refusal = await refusalOf(response);
+        throw new FileRouteError(
+            502,
+            `The API refused the file: ${response.status} ${response.statusText}: ${refusal}`,
+        );
+    }
+
+    let body: { files?: ListedFile[] };
+    try {
+        body = (await response.json()) as { files?: ListedFile[] };
+    } catch {
+        throw new FileRouteError(
+            502,
+            `The API answered with ${response.headers.get("content-type")}, not JSON.`,
+        );
+    }
+    if (!Array.isArray(body.files)) {
+        throw new FileRouteError(
+            502,
+            `The file list came back without files: ${JSON.stringify(body).slice(0, 200)}`,
+        );
+    }
+
+    return body.files[0];
+};
+
+/** The content of a found file, refusing what would be served as an empty or corrupt file. */
+const contentOf = (file: ListedFile, hash: string): Buffer => {
+    if (typeof file.data !== "string") {
+        throw new FileRouteError(
+            502,
+            `The API returned ${file.name} (/file/${hash}) without its content.`,
+        );
+    }
+    if (file.data.startsWith("data:")) {
+        throw new FileRouteError(
+            422,
+            `${file.name} was stored as a data URL, so its bytes are not the file: upload it again, read with fileToBase64.`,
+        );
+    }
+    return Buffer.from(file.data, "base64");
+};
+
+/**
+ * createDevFileRoute
+ *
+ * The dev server's stand-in for the platform's `/file/<hash>` route. On the platform a file's
+ * `url` is that route, served with the user's session and shown inline; the dev server has no
+ * session, so the file is found through the API with the dev proxy's OAuth2 token instead, by
+ * its stored `url`, and its base64 content is decoded here and sent with its own type. So an app
+ * shows a file through its `url` wherever it runs.
+ *
+ * Read with the OAuth2 client's permissions, not a user's, as everything through the dev proxy is.
+ * Every path under `/file/` is answered here, never handed on: Vite would answer it with the
+ * app's `index.html` and a 200. A file that cannot be served gets a status that says why, and a
+ * line in the terminal, since an `<img>` or `<iframe>` never shows the body. Nothing escapes the
+ * middleware: Connect ignores its promise, and a rejection would end the dev server.
+ *
+ * @param params - The API, its token and last failure, and a `fetch` and a log to replace in tests.
+ * @returns A Connect middleware that answers `/file/` and passes everything else on.
+ */
+export const createDevFileRoute =
+    ({
+        apiUrl,
+        token,
+        lastError,
+        fetch: fetchApi = fetch,
+        log = console.warn,
+    }: DevFileRouteParams) =>
+    async (req: RouteRequest, res: RouteResponse, next: () => void) => {
+        const url = req.url ?? "";
+        if (!FILE_ROUTE.test(url)) return next();
+
+        const fail = (status: number, message: string) => {
+            log(`[dev server] ${url}: ${message}`);
+            res.statusCode = status;
+            res.setHeader("Content-Type", "text/plain; charset=utf-8");
+            res.end(message);
+        };
+
+        if (req.method !== "GET" && req.method !== "HEAD")
+            return fail(405, "A file is only read here.");
+
+        const hash = FILE_URL.exec(url)?.[1];
+        if (!hash)
+            return fail(400, "Not a file url: /file/ and the 32-character hex hash of a file.");
+
+        const accessToken = token();
+        if (!accessToken) {
+            return fail(
+                503,
+                `No OAuth2 token for EVERYSK_API_URL: ${lastError()?.message ?? "not there yet"}`,
+            );
+        }
+
+        try {
+            const file = await findFile(fetchApi, apiUrl, accessToken, hash);
+            if (!file) {
+                return fail(
+                    404,
+                    `No file has the url /file/${hash}, as the OAuth2 client EVERYSK_API_CLIENT_ID sees.`,
+                );
+            }
+
+            const content = contentOf(file, hash);
+            const disposition = `inline; filename*=UTF-8''${encodeURIComponent(file.name)}`;
+            res.setHeader("Content-Type", file.content_type || "application/octet-stream");
+            res.setHeader("Content-Length", content.length);
+            res.setHeader("Content-Disposition", disposition);
+            res.statusCode = 200;
+            res.end(req.method === "HEAD" ? undefined : content);
+        } catch (error) {
+            fail(error instanceof FileRouteError ? error.status : 502, describeError(error));
+        }
+    };
+
+/**
+ * serveDevFilesPlugin
+ *
+ * Mounts `createDevFileRoute` on the dev server and on `vite preview`, neither of which has the
+ * platform's `/file/` route, logging through Vite's own logger.
+ *
+ * @param {ApiTokenSource} [tokens] - The token to send; created when the server starts if
+ *   omitted. `defineAppConfig` passes the one it shares with the `/api` proxy.
+ */
+export function serveDevFilesPlugin(tokens?: ApiTokenSource): Plugin {
+    const route = (log: (message: string) => void) =>
+        createDevFileRoute({ ...(tokens ?? createApiTokenSource()), log });
+
+    return {
+        name: "serve-dev-files",
+        configureServer(server) {
+            server.middlewares.use(route((message) => server.config.logger.warn(message)));
+        },
+        configurePreviewServer(server) {
+            server.middlewares.use(route((message) => server.config.logger.warn(message)));
+        },
+    };
+}

package/src/vite/serverProxy.ts

@@ -1,88 +1,40 @@
 import type { ProxyOptions } from "vite";
 
-// Refresh the OAuth2 token this many ms before it actually expires, so an in-flight
-// request never races a just-expired token.
-const REFRESH_SKEW_MS = 60_000;
+import { createApiTokenSource, type ApiTokenSource } from "./apiToken.js";
 
 /**
  * createDevServerProxy — Vite dev proxy for `/api`, authenticated with OAuth2 client credentials.
  *
  * Forwards `/api/*` to `EVERYSK_API_URL` (stripping the `/api` prefix) and injects an
- * `Authorization: Bearer <access_token>` header. The token is obtained from
- * `${EVERYSK_API_URL}/oauth2/token` with the `client_credentials` grant, cached in memory, and
- * refreshed in the background shortly before it expires. It is fetched eagerly at startup so a
- * token is ready before the first API call.
+ * `Authorization: Bearer <access_token>` header, from `createApiTokenSource`.
  *
+ * @param {ApiTokenSource} [tokens] - The token to send; a new source when omitted. The preset
+ *   passes the one it shares with the `/file/` route.
  * @returns {Record<string, string | ProxyOptions>} The Vite `server.proxy` config for `/api`.
- * @throws {Error} If `EVERYSK_API_URL`, `EVERYSK_API_CLIENT_ID`, or `EVERYSK_API_CLIENT_SECRET`
- *   is missing.
+ * @throws {Error} If `tokens` is omitted and `EVERYSK_API_URL`, `EVERYSK_API_CLIENT_ID`, or
+ *   `EVERYSK_API_CLIENT_SECRET` is missing.
  */
-export function createDevServerProxy(): Record<string, string | ProxyOptions> {
-  const EVERYSK_API_URL = process.env.EVERYSK_API_URL;
-  if (!EVERYSK_API_URL) throw new Error("EVERYSK_API_URL must be set.");
-
-  const clientId = process.env.EVERYSK_API_CLIENT_ID;
-  const clientSecret = process.env.EVERYSK_API_CLIENT_SECRET;
-  if (!clientId || !clientSecret) {
-    throw new Error("EVERYSK_API_CLIENT_ID and EVERYSK_API_CLIENT_SECRET must be set (OAuth2 client credentials).");
-  }
-  // Captured into an object so the narrowed `string` type survives inside the async closure below.
-  const credentials = { clientId, clientSecret };
-
-  const tokenUrl = `${EVERYSK_API_URL.replace(/\/$/, "")}/oauth2/token`;
-  let accessToken: string | null = null;
-  let refreshTimer: ReturnType<typeof setTimeout> | null = null;
-
-  /**
-   * refreshToken — fetch a fresh access token and schedule the next refresh before it expires.
-   *
-   * @returns {Promise<void>} Resolves once `accessToken` is updated.
-   * @throws {Error} If the token request fails or returns no `access_token`.
-   */
-  async function refreshToken(): Promise<void> {
-    const res = await fetch(tokenUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/x-www-form-urlencoded" },
-      body: new URLSearchParams({
-        grant_type: "client_credentials",
-        client_id: credentials.clientId,
-        client_secret: credentials.clientSecret,
-      }),
-    });
-    if (!res.ok) throw new Error(`OAuth2 token request failed: ${res.status} ${res.statusText}`);
-
-    const data = (await res.json()) as { access_token?: string; expires_in?: number };
-    if (!data.access_token) throw new Error("OAuth2 token response had no access_token.");
-    accessToken = data.access_token;
-
-    const ttlMs = (data.expires_in ?? 3600) * 1000;
-    if (refreshTimer) clearTimeout(refreshTimer);
-    refreshTimer = setTimeout(() => {
-      void refreshToken().catch((error) => console.error("[dev proxy] OAuth2 token refresh failed:", error));
-    }, Math.max(ttlMs - REFRESH_SKEW_MS, 30_000));
-    refreshTimer.unref?.();
-  }
-
-  // Warm the token before the first request; a failure is logged, not fatal (the request will 401).
-  void refreshToken().catch((error) => console.error("[dev proxy] initial OAuth2 token fetch failed:", error));
-
-  return {
-    "/api": {
-      target: EVERYSK_API_URL,
-      changeOrigin: true,
-      xfwd: true,
-      rewrite: (p) => p.replace(/^\/api(?=\/|$)/, ""),
-
-      configure: (proxy) => {
-        proxy.on("proxyReq", (proxyReq) => {
-          proxyReq.removeHeader("origin");
-          proxyReq.removeHeader("referer");
-
-          if (accessToken) {
-            proxyReq.setHeader("Authorization", `Bearer ${accessToken}`);
-          }
-        });
-      },
-    },
-  };
+export function createDevServerProxy(
+    tokens: ApiTokenSource = createApiTokenSource(),
+): Record<string, string | ProxyOptions> {
+    return {
+        "/api": {
+            target: tokens.apiUrl,
+            changeOrigin: true,
+            xfwd: true,
+            rewrite: (p) => p.replace(/^\/api(?=\/|$)/, ""),
+
+            configure: (proxy) => {
+                proxy.on("proxyReq", (proxyReq) => {
+                    proxyReq.removeHeader("origin");
+                    proxyReq.removeHeader("referer");
+
+                    const accessToken = tokens.token();
+                    if (accessToken) {
+                        proxyReq.setHeader("Authorization", `Bearer ${accessToken}`);
+                    }
+                });
+            },
+        },
+    };
 }

package/tsconfig/vitest.json

@@ -5,6 +5,6 @@
   ],
   "extends": "./app.json",
   "compilerOptions": {
-    "types": ["vitest/globals", "@testing-library/jest-dom", "node", "vite/client"]
+    "types": ["vitest/globals", "@testing-library/jest-dom/vitest", "node", "vite/client"]
   }
 }