@backstage/plugin-gateway-backend 0.0.0-nightly-20250422023845

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @backstage/plugin-gateway-backend
+
+## 0.0.0-nightly-20250422023845
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-plugin-api@0.0.0-nightly-20250422023845
+
+## 1.0.0
+
+### Major Changes
+
+- 6b5681c: Initial release of `@backstage/plugin-gateway-backend`
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-plugin-api@1.3.0

package/README.md

@@ -0,0 +1,39 @@
+# Gateway Backend Plugin
+
+A plugin for managing request routing in distributed Backstage deployments.
+
+## Overview
+
+This plugin is designed for organizations that have [split their backend plugins across multiple Backstage deployments](https://backstage.io/docs/backend-system/building-backends/index#split-into-multiple-backends) and implemented a custom Discovery service to resolve backend plugin URLs.
+
+While a custom discovery service handles routing between backend plugins, it doesn't address frontend-to-backend routing without either:
+
+- Hardcoding URLs in the frontend
+- Implementing a custom reverse proxy
+
+The Gateway Backend Plugin solves this by providing a centralized routing solution in a dedicated "gateway" Backstage deployment. It routes frontend requests to the appropriate backend plugins using the Discovery service, while prioritizing local plugins when available.
+
+## Installation
+
+1. Install the plugin package:
+
+```bash
+# From your root directory
+yarn --cwd packages/backend add @backstage/plugin-gateway-backend
+```
+
+2. Add the plugin to your backend in `packages/backend/src/index.ts`:
+
+```diff
+  const backend = createBackend();
+  // ...
++ backend.add(import('@backstage/plugin-gateway-backend'));
+```
+
+3. Configure the `baseUrl` in your `app-config.yaml` to point to your gateway deployment:
+
+```yaml
+backend:
+  # The baseUrl of your gateway Backstage deployment
+  baseUrl: http://gateway-backstage-backend.example.com
+```

package/dist/index.cjs.js

@@ -0,0 +1,10 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var plugin = require('./plugin.cjs.js');
+
+
+
+exports.default = plugin.gatewayPlugin;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
+
+/**
+ * gateway backend plugin
+ *
+ * @public
+ */
+declare const gatewayPlugin: _backstage_backend_plugin_api.BackendFeature;
+
+export { gatewayPlugin as default };

package/dist/plugin.cjs.js

@@ -0,0 +1,32 @@
+'use strict';
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+var router = require('./router.cjs.js');
+var alpha = require('@backstage/backend-plugin-api/alpha');
+
+const gatewayPlugin = backendPluginApi.createBackendPlugin({
+  pluginId: "gateway",
+  register(env) {
+    env.registerInit({
+      deps: {
+        logger: backendPluginApi.coreServices.logger,
+        rootHttpRouter: backendPluginApi.coreServices.rootHttpRouter,
+        instanceMeta: alpha.instanceMetadataServiceRef,
+        discovery: backendPluginApi.coreServices.discovery
+      },
+      async init({ logger, discovery, instanceMeta, rootHttpRouter }) {
+        rootHttpRouter.use(
+          "/api/:pluginId",
+          router.createRouter({
+            discovery,
+            instanceMeta,
+            logger
+          })
+        );
+      }
+    });
+  }
+});
+
+exports.gatewayPlugin = gatewayPlugin;
+//# sourceMappingURL=plugin.cjs.js.map

package/dist/plugin.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.cjs.js","sources":["../src/plugin.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport {\n  coreServices,\n  createBackendPlugin,\n} from '@backstage/backend-plugin-api';\nimport { createRouter } from './router';\nimport { instanceMetadataServiceRef } from '@backstage/backend-plugin-api/alpha';\nimport { Handler } from 'express';\n\n/**\n * gateway backend plugin\n *\n * @public\n */\nexport const gatewayPlugin = createBackendPlugin({\n  pluginId: 'gateway',\n  register(env) {\n    env.registerInit({\n      deps: {\n        logger: coreServices.logger,\n        rootHttpRouter: coreServices.rootHttpRouter,\n        instanceMeta: instanceMetadataServiceRef,\n        discovery: coreServices.discovery,\n      },\n      async init({ logger, discovery, instanceMeta, rootHttpRouter }) {\n        rootHttpRouter.use(\n          '/api/:pluginId',\n          createRouter({\n            discovery,\n            instanceMeta,\n            logger,\n          }) as Handler,\n        );\n      },\n    });\n  },\n});\n"],"names":["createBackendPlugin","coreServices","instanceMetadataServiceRef","createRouter"],"mappings":";;;;;;AA4BO,MAAM,gBAAgBA,oCAAoB,CAAA;AAAA,EAC/C,QAAU,EAAA,SAAA;AAAA,EACV,SAAS,GAAK,EAAA;AACZ,IAAA,GAAA,CAAI,YAAa,CAAA;AAAA,MACf,IAAM,EAAA;AAAA,QACJ,QAAQC,6BAAa,CAAA,MAAA;AAAA,QACrB,gBAAgBA,6BAAa,CAAA,cAAA;AAAA,QAC7B,YAAc,EAAAC,gCAAA;AAAA,QACd,WAAWD,6BAAa,CAAA;AAAA,OAC1B;AAAA,MACA,MAAM,IAAK,CAAA,EAAE,QAAQ,SAAW,EAAA,YAAA,EAAc,gBAAkB,EAAA;AAC9D,QAAe,cAAA,CAAA,GAAA;AAAA,UACb,gBAAA;AAAA,UACAE,mBAAa,CAAA;AAAA,YACX,SAAA;AAAA,YACA,YAAA;AAAA,YACA;AAAA,WACD;AAAA,SACH;AAAA;AACF,KACD,CAAA;AAAA;AAEL,CAAC;;;;"}

package/dist/router.cjs.js

@@ -0,0 +1,44 @@
+'use strict';
+
+var httpProxyMiddleware = require('http-proxy-middleware');
+var api = require('@opentelemetry/api');
+var core = require('@opentelemetry/core');
+
+function createRouter({
+  discovery,
+  instanceMeta
+}) {
+  const localPluginIds = new Set(
+    instanceMeta.getInstalledFeatures().filter((f) => f.type === "plugin").map((f) => f.pluginId)
+  );
+  const proxy = httpProxyMiddleware.createProxyMiddleware({
+    changeOrigin: true,
+    router: async (req) => {
+      const pluginId = req.params.pluginId;
+      return discovery.getBaseUrl(pluginId);
+    },
+    on: {
+      proxyRes(proxyRes, _req, res) {
+        proxyRes.on("close", () => {
+          if (!res.writableEnded) {
+            res.end();
+          }
+        });
+      }
+    }
+  });
+  return function proxyMiddleware(req, res, next) {
+    if (localPluginIds.has(req.params.pluginId)) {
+      next();
+      return;
+    }
+    const rpcMetadata = core.getRPCMetadata(api.context.active());
+    if (rpcMetadata) {
+      rpcMetadata.route = req.baseUrl;
+    }
+    proxy(req, res, next);
+  };
+}
+
+exports.createRouter = createRouter;
+//# sourceMappingURL=router.cjs.js.map

package/dist/router.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.cjs.js","sources":["../src/router.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { DiscoveryService, LoggerService } from '@backstage/backend-plugin-api';\nimport { InstanceMetadataService } from '@backstage/backend-plugin-api/alpha';\nimport { Request, Response, NextFunction } from 'express';\nimport { createProxyMiddleware } from 'http-proxy-middleware';\nimport { context } from '@opentelemetry/api';\nimport { getRPCMetadata } from '@opentelemetry/core';\n\nexport function createRouter({\n  discovery,\n  instanceMeta,\n}: {\n  discovery: DiscoveryService;\n  instanceMeta: InstanceMetadataService;\n  logger: LoggerService;\n}) {\n  const localPluginIds = new Set(\n    instanceMeta\n      .getInstalledFeatures()\n      .filter(f => f.type === 'plugin')\n      .map(f => f.pluginId),\n  );\n\n  const proxy = createProxyMiddleware({\n    changeOrigin: true,\n    router: async (req: Request<{ pluginId: string }>) => {\n      const pluginId = req.params.pluginId;\n      return discovery.getBaseUrl(pluginId);\n    },\n    on: {\n      proxyRes(proxyRes, _req, res) {\n        // https://github.com/chimurai/http-proxy-middleware/discussions/765\n        proxyRes.on('close', () => {\n          if (!res.writableEnded) {\n            res.end();\n          }\n        });\n      },\n    },\n  });\n\n  return function proxyMiddleware(\n    req: Request<{ pluginId: string }>,\n    res: Response,\n    next: NextFunction,\n  ) {\n    if (localPluginIds.has(req.params.pluginId)) {\n      next();\n      return;\n    }\n\n    const rpcMetadata = getRPCMetadata(context.active());\n    if (rpcMetadata) {\n      rpcMetadata.route = req.baseUrl;\n    }\n\n    proxy(req, res, next);\n  };\n}\n"],"names":["createProxyMiddleware","getRPCMetadata","context"],"mappings":";;;;;;AAsBO,SAAS,YAAa,CAAA;AAAA,EAC3B,SAAA;AAAA,EACA;AACF,CAIG,EAAA;AACD,EAAA,MAAM,iBAAiB,IAAI,GAAA;AAAA,IACzB,YACG,CAAA,oBAAA,EACA,CAAA,MAAA,CAAO,CAAK,CAAA,KAAA,CAAA,CAAE,IAAS,KAAA,QAAQ,CAC/B,CAAA,GAAA,CAAI,CAAK,CAAA,KAAA,CAAA,CAAE,QAAQ;AAAA,GACxB;AAEA,EAAA,MAAM,QAAQA,yCAAsB,CAAA;AAAA,IAClC,YAAc,EAAA,IAAA;AAAA,IACd,MAAA,EAAQ,OAAO,GAAuC,KAAA;AACpD,MAAM,MAAA,QAAA,GAAW,IAAI,MAAO,CAAA,QAAA;AAC5B,MAAO,OAAA,SAAA,CAAU,WAAW,QAAQ,CAAA;AAAA,KACtC;AAAA,IACA,EAAI,EAAA;AAAA,MACF,QAAA,CAAS,QAAU,EAAA,IAAA,EAAM,GAAK,EAAA;AAE5B,QAAS,QAAA,CAAA,EAAA,CAAG,SAAS,MAAM;AACzB,UAAI,IAAA,CAAC,IAAI,aAAe,EAAA;AACtB,YAAA,GAAA,CAAI,GAAI,EAAA;AAAA;AACV,SACD,CAAA;AAAA;AACH;AACF,GACD,CAAA;AAED,EAAA,OAAO,SAAS,eAAA,CACd,GACA,EAAA,GAAA,EACA,IACA,EAAA;AACA,IAAA,IAAI,cAAe,CAAA,GAAA,CAAI,GAAI,CAAA,MAAA,CAAO,QAAQ,CAAG,EAAA;AAC3C,MAAK,IAAA,EAAA;AACL,MAAA;AAAA;AAGF,IAAA,MAAM,WAAc,GAAAC,mBAAA,CAAeC,WAAQ,CAAA,MAAA,EAAQ,CAAA;AACnD,IAAA,IAAI,WAAa,EAAA;AACf,MAAA,WAAA,CAAY,QAAQ,GAAI,CAAA,OAAA;AAAA;AAG1B,IAAM,KAAA,CAAA,GAAA,EAAK,KAAK,IAAI,CAAA;AAAA,GACtB;AACF;;;;"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@backstage/plugin-gateway-backend",
+  "version": "0.0.0-nightly-20250422023845",
+  "backstage": {
+    "role": "backend-plugin",
+    "pluginId": "gateway",
+    "pluginPackages": [
+      "@backstage/plugin-gateway-backend"
+    ],
+    "features": {
+      ".": "@backstage/BackendFeature"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "plugins/gateway-backend"
+  },
+  "license": "Apache-2.0",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "backstage-cli package build",
+    "clean": "backstage-cli package clean",
+    "lint": "backstage-cli package lint",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack",
+    "start": "backstage-cli package start",
+    "test": "backstage-cli package test"
+  },
+  "dependencies": {
+    "@backstage/backend-plugin-api": "0.0.0-nightly-20250422023845",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^1.29.0",
+    "express": "^4.17.1",
+    "http-proxy-middleware": "^3.0.3"
+  },
+  "devDependencies": {
+    "@backstage/backend-app-api": "0.0.0-nightly-20250422023845",
+    "@backstage/backend-defaults": "0.0.0-nightly-20250422023845",
+    "@backstage/backend-test-utils": "0.0.0-nightly-20250422023845",
+    "@backstage/cli": "0.0.0-nightly-20250422023845",
+    "@types/express": "^4.17.6",
+    "eventsource": "^3.0.6",
+    "wait-for-expect": "^3.0.2"
+  },
+  "typesVersions": {
+    "*": {
+      "package.json": [
+        "package.json"
+      ]
+    }
+  }
+}