@qelos/plugin-netlify-api 1.0.4 → 1.1.0

package/README.md

@@ -4,7 +4,7 @@ Netlify build plugin for Qelos frontend apps: proxies `/api/*` to your Qelos API
 
 ## Setup
 
-In your site’s `netlify.toml`, add the plugin next to your existing `[build]` / `[build.environment]` (same idea as a manual `[functions]` + `[[redirects]]` + `api-proxy.ts`, but without checking in the function or redirect yourself):
+In your site’s `netlify.toml`, add the plugin next to your existing `[build]` / `[build.environment]`:
 
 ```toml
 [build]
@@ -12,21 +12,36 @@ In your site’s `netlify.toml`, add the plugin next to your existing `[build]`
   publish = "dist"
 
 [build.environment]
-  # Used by the injected proxy at runtime (and by your build if you read it in app config)
   QELOS_API_IP = "http://159.203.152.168"
 
 [[plugins]]
   package = "@qelos/plugin-netlify-api"
 ```
 
-Minimal variant (defaults API URL inside the plugin if you omit env):
+**Nuxt / static frameworks (required):** Netlify evaluates `dist/_redirects` **before** `netlify.toml`. Nitro’s `netlify-static` preset emits a catch‑all `/*` rule, so the API rule must be **first** in `_redirects`. Add an npm **`postbuild`** script (runs after `nuxt build` when Netlify runs `npm run build`):
 
-```toml
-[[plugins]]
-  package = "@qelos/plugin-netlify-api"
+```json
+{
+  "scripts": {
+    "build": "nuxt build",
+    "postbuild": "qelos-netlify-patch-redirects"
+  }
+}
 ```
 
-Optional: set the API URL (default `http://159.203.152.168`) and/or enable bypass-admin header:
+If your publish directory is not `dist`, set `QELOS_NETLIFY_PUBLISH` to that folder name (relative to the app root).
+
+## How it proxies (default)
+
+By default the plugin uses **Netlify’s CDN rewrite** to your Qelos API (same pattern as [Netlify’s proxy docs](https://docs.netlify.com/manage/routing/redirects/rewrites-proxies/#proxy-to-another-service)):
+
+- `/api/*` → `${QELOS_API_IP origin}/api/:splat` with status `200` and `force`
+
+So `/api/me` is proxied to `http://your-api-host/api/me` **at the edge**, without a serverless function. That avoids fragile `/.netlify/functions/...` rewrites and matches Nuxt’s `_redirects` behavior.
+
+Optional: **`use_function_proxy = true`** — uses the bundled `qelos-api-proxy` serverless function instead (for cases where you must run Node logic on each request).
+
+Optional plugin inputs:
 
 ```toml
 [[plugins]]
@@ -35,17 +50,17 @@ Optional: set the API URL (default `http://159.203.152.168`) and/or enable bypas
   [plugins.inputs]
     api_url = "http://159.203.152.168"
     bypass_admin = true
+    use_function_proxy = false
 ```
 
-- **api_url** — Target for the `/api/*` proxy. You can also set **`QELOS_API_IP`** or **`API_HOST`** in `[build.environment]` or in the Netlify UI (same role as `API_HOST` in a hand-written `netlify/functions/api-proxy.ts`).
-- **bypass_admin** — If `true`, the proxy adds the header `x-bypass-admin: true` to every request so that admin users are scoped as regular users. See root docs: `documentation/docs/plugins/api-proxy.md` and `documentation/docs/sdk/token_refresh.md`.
+- **api_url** — Qelos API base URL (same as `QELOS_API_IP` / `API_HOST`).
+- **bypass_admin** — If `true`, adds header `x-bypass-admin: true` on proxied requests (CDN and function modes).
+- **use_function_proxy** — If `true`, deploy the bundled `qelos-api-proxy` function and rewrite to it instead of the CDN proxy.
 
 ## What it does
 
-- **Environment:** Sets `QELOS_API_IP` for the build (and for the proxy function at runtime).
-- **Redirect:** Adds a rewrite in `netlify.toml` and, **after the site build**, prepends the same rule to **`publish/_redirects`** when that file exists. Netlify applies `_redirects` **before** `netlify.toml`; frameworks (e.g. Nuxt `netlify-static`) often emit `/* → /404.html` first, which would otherwise match `/api/*` and never reach the proxy.
-- **Function:** Copies `qelos-api-proxy.ts` from the package into your Netlify **functions directory** (default `netlify/functions`, or `[functions] directory` in `netlify.toml`) during `onPreBuild`, so the bundler sees a normal function file. Forwards requests using `QELOS_API_IP` / `API_HOST` (full URL or hostname).
-
-No need to add redirects or commit the proxy yourself; the plugin writes it each build. Optional: add `netlify/functions/qelos-api-proxy.ts` to `.gitignore` if you run local Netlify builds and do not want the copy tracked.
+- **Environment:** Sets `QELOS_API_IP`, `QELOS_NETLIFY_PROXY_MODE` (`cdn` or `function`).
+- **Redirects:** Injects the `/api/*` rewrite into `netlify.toml` (and **`postbuild`** rewrites `publish/_redirects` so Nuxt’s catch‑all does not win).
+- **Function mode only:** Copies `qelos-api-proxy.ts` into your Netlify functions directory.
 
-**Parity with a manual Netlify function** (e.g. `[[redirects]]` → `/.netlify/functions/api-proxy` and a function using `process.env.API_HOST`): use this plugin instead of those entries; set `QELOS_API_IP` or `API_HOST` to the same value you used for `API_HOST`, and set `bypass_admin = true` under `[plugins.inputs]` if your old proxy always sent `x-bypass-admin: true`.
+No need to commit redirects yourself; the plugin and `postbuild` maintain them each build.

package/index.js

@@ -1,73 +1,111 @@
 const fs = require('node:fs/promises');
 const path = require('node:path');
 
-const DEFAULT_API_URL = 'http://159.203.152.168';
+const { patchRedirects } = require('./scripts/patch-redirects.cjs');
 
-/** Must appear before any `/*` rule in publish/_redirects — Netlify evaluates that file before netlify.toml. */
-const REDIRECTS_FILE_LINE =
-  '/api/* /.netlify/functions/qelos-api-proxy 200!\n';
+const DEFAULT_API_URL = 'http://159.203.152.168';
 
 function resolveFunctionsDirectory(netlifyConfig) {
   const dir = netlifyConfig.functions?.directory ?? 'netlify/functions';
   return path.isAbsolute(dir) ? dir : path.join(process.cwd(), dir);
 }
 
+function resolvePublishDir(constants, netlifyConfig) {
+  if (constants?.PUBLISH_DIR) {
+    return constants.PUBLISH_DIR;
+  }
+  const p = netlifyConfig?.build?.publish;
+  if (!p) {
+    return path.join(process.cwd(), 'dist');
+  }
+  return path.isAbsolute(p) ? p : path.join(process.cwd(), p);
+}
+
+function upstreamOrigin(apiUrl) {
+  const s = String(apiUrl ?? '').trim().replace(/\/$/, '');
+  if (!s) {
+    return new URL(DEFAULT_API_URL).origin;
+  }
+  if (/^https?:\/\//i.test(s)) {
+    return new URL(s).origin;
+  }
+  return `http://${s}`;
+}
+
+function stripApiRedirects(redirects) {
+  return (redirects || []).filter((r) => r && r.from !== '/api/*');
+}
+
 module.exports = {
   async onPreBuild({ netlifyConfig, inputs }) {
     const apiUrl =
       inputs.api_url ?? process.env.QELOS_API_IP ?? DEFAULT_API_URL;
     const bypassAdmin =
       inputs.bypass_admin === true || inputs.bypass_admin === 'true';
+    const useFunctionProxy =
+      inputs.use_function_proxy === true || inputs.use_function_proxy === 'true';
 
-    // Ensure build.environment exists
     if (!netlifyConfig.build.environment) {
       netlifyConfig.build.environment = {};
     }
     netlifyConfig.build.environment.QELOS_API_IP = apiUrl;
+    netlifyConfig.build.environment.QELOS_NETLIFY_PROXY_MODE = useFunctionProxy
+      ? 'function'
+      : 'cdn';
     if (bypassAdmin) {
       netlifyConfig.build.environment.QELOS_BYPASS_ADMIN_HEADER = 'true';
     }
 
-    if (!netlifyConfig.functions) {
-      netlifyConfig.functions = { directory: 'netlify/functions' };
+    if (!netlifyConfig.redirects) {
+      netlifyConfig.redirects = [];
     }
+    netlifyConfig.redirects = stripApiRedirects(netlifyConfig.redirects);
 
-    // Copy the proxy into the site's functions dir so Netlify bundles it like any
-    // checked-in function (utils.functions.add from node_modules is unreliable for .ts).
-    const destDir = resolveFunctionsDirectory(netlifyConfig);
-    const destFile = path.join(destDir, 'qelos-api-proxy.ts');
-    const srcFile = path.join(__dirname, 'functions', 'qelos-api-proxy.ts');
-    await fs.mkdir(destDir, { recursive: true });
-    await fs.copyFile(srcFile, destFile);
+    if (useFunctionProxy) {
+      if (!netlifyConfig.functions) {
+        netlifyConfig.functions = { directory: 'netlify/functions' };
+      }
+      const destDir = resolveFunctionsDirectory(netlifyConfig);
+      const destFile = path.join(destDir, 'qelos-api-proxy.ts');
+      const srcFile = path.join(__dirname, 'functions', 'qelos-api-proxy.ts');
+      await fs.mkdir(destDir, { recursive: true });
+      await fs.copyFile(srcFile, destFile);
 
-    // Add redirect: /api/* -> Netlify function (proxy)
-    if (!netlifyConfig.redirects) {
-      netlifyConfig.redirects = [];
+      netlifyConfig.redirects.unshift({
+        from: '/api/*',
+        to: '/.netlify/functions/qelos-api-proxy',
+        status: 200,
+        force: true,
+      });
+    } else {
+      const origin = upstreamOrigin(apiUrl);
+      const redirect = {
+        from: '/api/*',
+        to: `${origin}/api/:splat`,
+        status: 200,
+        force: true,
+      };
+      if (bypassAdmin) {
+        redirect.headers = { 'X-Bypass-Admin': 'true' };
+      }
+      netlifyConfig.redirects.unshift(redirect);
     }
-    netlifyConfig.redirects.push({
-      from: '/api/*',
-      to: '/.netlify/functions/qelos-api-proxy',
-      status: 200,
-      force: true,
-    });
   },
 
-  /**
-   * Nuxt/static generators emit `dist/_redirects` with `/* → 404` first. Netlify runs
-   * `_redirects` rules before `netlify.toml`, so that catch-all wins unless `/api/*` is
-   * prepended here (after the framework build).
-   */
-  async onPostBuild({ constants }) {
-    const publishDir = constants.PUBLISH_DIR;
-    if (!publishDir) return;
-    const redirectsPath = path.join(publishDir, '_redirects');
-    let existing = '';
-    try {
-      existing = await fs.readFile(redirectsPath, 'utf8');
-    } catch (e) {
-      if (e.code !== 'ENOENT') throw e;
-    }
-    if (existing.includes('qelos-api-proxy')) return;
-    await fs.writeFile(redirectsPath, REDIRECTS_FILE_LINE + existing, 'utf8');
+  async onPostBuild({ constants, netlifyConfig, inputs }) {
+    const publishDir = resolvePublishDir(constants, netlifyConfig);
+    const apiUrl =
+      inputs?.api_url ??
+      netlifyConfig?.build?.environment?.QELOS_API_IP ??
+      process.env.QELOS_API_IP ??
+      DEFAULT_API_URL;
+    const mode =
+      netlifyConfig?.build?.environment?.QELOS_NETLIFY_PROXY_MODE === 'function'
+        ? 'function'
+        : 'cdn';
+    const changed = patchRedirects(publishDir, apiUrl, mode);
+    console.log(
+      `[@qelos/plugin-netlify-api] onPostBuild: ${changed ? 'patched' : 'unchanged'} ${path.join(publishDir, '_redirects')} (${mode})`,
+    );
   },
 };

package/manifest.yml

@@ -8,3 +8,7 @@ inputs:
     required: false
     description: "If true, the proxy adds header x-bypass-admin: true to every request (so admins are scoped as regular users)."
     default: false
+  - name: use_function_proxy
+    required: false
+    description: "If true, use the bundled serverless function instead of Netlify CDN proxy to api_url (default is CDN rewrite to origin/api/:splat)."
+    default: false

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@qelos/plugin-netlify-api",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Netlify build plugin: proxy /api/* to Qelos API and inject config",
   "main": "index.js",
+  "bin": {
+    "qelos-netlify-patch-redirects": "./scripts/patch-redirects.cjs"
+  },
   "files": [
     "index.js",
     "manifest.yml",
-    "functions"
+    "functions",
+    "scripts"
   ],
   "author": "David Meir-Levy <davidmeirlevy@gmail.com>",
   "license": "MIT",

package/scripts/patch-redirects.cjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Prepend a forced `/api/*` rewrite as the first line of publish/_redirects.
+ * Netlify evaluates this file before netlify.toml; Nuxt `netlify-static` adds
+ * `/* → /404.html` — that must come after `/api/*`.
+ *
+ * Default: CDN proxy to `${QELOS_API_IP}/api/:splat` (Netlify’s documented pattern).
+ * Set QELOS_NETLIFY_PROXY_MODE=function to use the serverless function instead.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_API = 'http://159.203.152.168';
+
+function upstreamOrigin(apiUrl) {
+  const s = String(apiUrl ?? '').trim().replace(/\/$/, '');
+  if (!s) {
+    return new URL(DEFAULT_API).origin;
+  }
+  if (/^https?:\/\//i.test(s)) {
+    return new URL(s).origin;
+  }
+  return `http://${s}`;
+}
+
+/**
+ * @param {string} [apiUrl]
+ * @param {'cdn'|'function'} [mode]
+ */
+function buildRedirectLine(apiUrl, mode) {
+  const m = mode === 'function' ? 'function' : 'cdn';
+  if (m === 'function') {
+    return '/api/* /.netlify/functions/qelos-api-proxy 200!\n';
+  }
+  const origin = upstreamOrigin(apiUrl ?? process.env.QELOS_API_IP);
+  return `/api/* ${origin}/api/:splat 200!\n`;
+}
+
+/**
+ * Drop existing /api/* lines so we don’t stack stale rules when the target URL changes.
+ * @param {string} content
+ */
+function stripApiRedirectLines(content) {
+  return content
+    .split('\n')
+    .filter((line) => {
+      const t = line.trim();
+      if (!t || t.startsWith('#')) return true;
+      if (t.startsWith('/api/*')) return false;
+      return true;
+    })
+    .join('\n');
+}
+
+/**
+ * @param {string} publishDir absolute path to deploy root (e.g. …/dist)
+ * @param {string} [apiUrl] same as QELOS_API_IP
+ * @param {'cdn'|'function'} [mode]
+ * @returns {boolean} true if the file was written
+ */
+function patchRedirects(publishDir, apiUrl, mode) {
+  if (!publishDir) return false;
+  const redirectsPath = path.join(publishDir, '_redirects');
+  let existing = '';
+  try {
+    existing = fs.readFileSync(redirectsPath, 'utf8');
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  const line = buildRedirectLine(apiUrl, mode);
+  const rest = stripApiRedirectLines(existing);
+  const next = line + (rest ? rest + (rest.endsWith('\n') ? '' : '\n') : '');
+  if (next === existing) {
+    return false;
+  }
+  fs.writeFileSync(redirectsPath, next, 'utf8');
+  return true;
+}
+
+function resolvePublishDirFromEnv() {
+  const rel = process.env.QELOS_NETLIFY_PUBLISH || 'dist';
+  return path.isAbsolute(rel) ? rel : path.join(process.cwd(), rel);
+}
+
+if (require.main === module) {
+  const abs = resolvePublishDirFromEnv();
+  const mode =
+    process.env.QELOS_NETLIFY_PROXY_MODE === 'function' ? 'function' : 'cdn';
+  const apiUrl = process.env.QELOS_API_IP;
+  const changed = patchRedirects(abs, apiUrl, mode);
+  const target = path.join(abs, '_redirects');
+  const kind = mode === 'function' ? 'function' : 'CDN';
+  if (changed) {
+    console.log(
+      `[qelos-netlify-patch-redirects] prepended /api/* (${kind}) → ${target}`,
+    );
+  } else {
+    console.log(`[qelos-netlify-patch-redirects] up to date → ${target}`);
+  }
+}
+
+module.exports = {
+  patchRedirects,
+  buildRedirectLine,
+  upstreamOrigin,
+  stripApiRedirectLines,
+};