@qelos/plugin-netlify-api 1.0.5 → 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,14 +12,13 @@ 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"
 ```
 
-**Nuxt / static frameworks (required):** Netlify evaluates `dist/_redirects` **before** `netlify.toml`. Nitro’s `netlify-static` preset emits a catch‑all `/*` rule first, so you must prepend the API rewrite **after** `nuxt build`. Add an npm **`postbuild`** script (runs automatically when Netlify runs `npm run build`):
+**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`):
 
 ```json
 {
@@ -30,16 +29,19 @@ In your site’s `netlify.toml`, add the plugin next to your existing `[build]`
 }
 ```
 
-If your publish directory is not `dist`, set `QELOS_NETLIFY_PUBLISH` to that folder name (relative to the app root) for the patch script.
+If your publish directory is not `dist`, set `QELOS_NETLIFY_PUBLISH` to that folder name (relative to the app root).
 
-Minimal variant (defaults API URL inside the plugin if you omit env):
+## How it proxies (default)
 
-```toml
-[[plugins]]
-  package = "@qelos/plugin-netlify-api"
-```
+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)):
 
-Optional: set the API URL (default `http://159.203.152.168`) and/or enable bypass-admin header:
+- `/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]]
@@ -48,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 ships **`qelos-netlify-patch-redirects`** to prepend the same line to **`publish/_redirects`** (use the **`postbuild`** script above — do not rely on the build plugin alone for Nuxt).
-- **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

@@ -21,55 +21,91 @@ function resolvePublishDir(constants, netlifyConfig) {
   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,
-    });
   },
 
-  /**
-   * Best-effort: some Netlify builds omit logging or skip this hook; the supported fix
-   * for Nuxt is `postbuild` → `qelos-netlify-patch-redirects` (see README).
-   */
-  async onPostBuild({ constants, netlifyConfig }) {
+  async onPostBuild({ constants, netlifyConfig, inputs }) {
     const publishDir = resolvePublishDir(constants, netlifyConfig);
-    const changed = patchRedirects(publishDir);
+    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' : 'skipped'} ${path.join(publishDir, '_redirects')}`,
+      `[@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,6 +1,6 @@
 {
   "name": "@qelos/plugin-netlify-api",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Netlify build plugin: proxy /api/* to Qelos API and inject config",
   "main": "index.js",
   "bin": {

package/scripts/patch-redirects.cjs

@@ -2,24 +2,66 @@
 'use strict';
 
 /**
- * Prepend `/api/*` → qelos-api-proxy to publish/_redirects *before* Netlify deploy.
- * Netlify evaluates `_redirects` before netlify.toml; Nuxt `netlify-static` emits
- * `/* → /404.html` first — without this line, `/api/*` never reaches the function.
+ * 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/*`.
  *
- * Run via npm lifecycle: "postbuild": "qelos-netlify-patch-redirects"
- * (postbuild runs automatically after `nuxt build` when Netlify runs `npm run build`).
+ * 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 REDIRECT_LINE = '/api/* /.netlify/functions/qelos-api-proxy 200!\n';
+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} publishDir absolute path to the directory Netlify deploys (e.g. …/dist)
+ * @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) {
+function patchRedirects(publishDir, apiUrl, mode) {
   if (!publishDir) return false;
   const redirectsPath = path.join(publishDir, '_redirects');
   let existing = '';
@@ -28,10 +70,13 @@ function patchRedirects(publishDir) {
   } catch (e) {
     if (e.code !== 'ENOENT') throw e;
   }
-  if (existing.includes('qelos-api-proxy')) {
+  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, REDIRECT_LINE + existing, 'utf8');
+  fs.writeFileSync(redirectsPath, next, 'utf8');
   return true;
 }
 
@@ -42,15 +87,24 @@ function resolvePublishDirFromEnv() {
 
 if (require.main === module) {
   const abs = resolvePublishDirFromEnv();
-  const changed = patchRedirects(abs);
+  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/* rewrite → ${target}`);
-  } else {
     console.log(
-      `[qelos-netlify-patch-redirects] skipped (already has qelos-api-proxy) → ${target}`,
+      `[qelos-netlify-patch-redirects] prepended /api/* (${kind}) → ${target}`,
     );
+  } else {
+    console.log(`[qelos-netlify-patch-redirects] up to date → ${target}`);
   }
 }
 
-module.exports = { patchRedirects, REDIRECT_LINE };
+module.exports = {
+  patchRedirects,
+  buildRedirectLine,
+  upstreamOrigin,
+  stripApiRedirectLines,
+};