Merge pull request #27257 from mbenson/proxy-extension

Add proxyEndpointsExtensionPoint

.changeset/four-bananas-sneeze.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-proxy-backend': patch
+'@backstage/plugin-proxy-node': minor
+---
+
+Added `proxyEndpointsExtensionPoint` to allow addition of proxy configuration through an extension point in the new backend system.

docs/plugins/proxying.md

@@ -120,3 +120,42 @@ third-parties.
 
 The same logic applies to headers that are sent from the target back to the
 frontend.
+
+### Proxy Extension Endpoint
+
+The proxy plugin additionally supports a `proxyExtensionEndpoint` which a proxy
+plugin module can utilize in order to programmatically register additional
+endpoints, whose payloads are specified exactly as in app-config (described
+above). Note that endpoints configured in app-config will always override those
+registered in this manner.
+
+Example:
+
+```ts
+backend.add(
+  createBackendModule({
+    pluginId: 'proxy',
+    moduleId: 'demo-additional-endpoints',
+    register: reg => {
+      reg.registerInit({
+        deps: {
+          proxyEndpoints: proxyEndpointsExtensionPoint,
+        },
+        init: async ({ proxyEndpoints }) => {
+          let largerExampleAuth: string = /* exercise for the reader */;
+          proxyEndpoints.addProxyEndpoints({
+            "/simple-example": "http://simple.example.com:8080",
+            "/larger-example/v1": {
+              target: "http://larger.example.com:8080/svc.v1",
+              credentials: "require",
+              headers: {
+                Authorization: largerExampleAuth
+              },
+            },
+          });
+        },
+      });
+    },
+  }),
+);
+```

plugins/proxy-backend/dev/index.ts

@@ -15,7 +15,35 @@
  */
 
 import { createBackend } from '@backstage/backend-defaults';
+import { createBackendModule } from '@backstage/backend-plugin-api';
+import { proxyEndpointsExtensionPoint } from '@backstage/plugin-proxy-node/alpha';
 
 const backend = createBackend();
 backend.add(import('../src/alpha'));
+
+backend.add(
+  createBackendModule({
+    pluginId: 'proxy',
+    moduleId: 'demo-additional-endpoints',
+    register: reg => {
+      reg.registerInit({
+        deps: {
+          proxyEndpoints: proxyEndpointsExtensionPoint,
+        },
+        init: async ({ proxyEndpoints }) => {
+          proxyEndpoints.addProxyEndpoints({
+            ...Object.fromEntries(
+              ['foo', 'bar', 'baz'].map(msv => [
+                `/${msv}`,
+                { target: `http://${msv}.org` },
+              ]),
+            ),
+            '/gocd': 'http://cannot-override-config.no',
+          });
+        },
+      });
+    },
+  }),
+);
+
 backend.start();

plugins/proxy-backend/package.json

@@ -56,6 +56,7 @@
     "@backstage/backend-common": "^0.25.0",
     "@backstage/backend-plugin-api": "workspace:^",
     "@backstage/config": "workspace:^",
+    "@backstage/plugin-proxy-node": "workspace:^",
     "@backstage/types": "workspace:^",
     "@types/express": "^4.17.6",
     "express": "^4.17.1",

plugins/proxy-backend/report.api.md

@@ -7,6 +7,7 @@ import { BackendFeature } from '@backstage/backend-plugin-api';
 import { DiscoveryService } from '@backstage/backend-plugin-api';
 import express from 'express';
 import { Logger } from 'winston';
+import { ProxyConfig } from '@backstage/plugin-proxy-node/alpha';
 import { RootConfigService } from '@backstage/backend-plugin-api';
 
 // @public @deprecated
@@ -18,6 +19,8 @@ export default proxyPlugin;
 
 // @public @deprecated (undocumented)
 export interface RouterOptions {
+  // (undocumented)
+  additionalEndpoints?: ProxyConfig;
   // (undocumented)
   config: RootConfigService;
   // (undocumented)

plugins/proxy-backend/src/plugin.ts

@@ -20,6 +20,7 @@ import {
   coreServices,
 } from '@backstage/backend-plugin-api';
 import { createRouterInternal } from './service/router';
+import { proxyEndpointsExtensionPoint } from '@backstage/plugin-proxy-node/alpha';
 
 /**
  * The proxy backend plugin.
@@ -29,6 +30,13 @@ import { createRouterInternal } from './service/router';
 export const proxyPlugin = createBackendPlugin({
   pluginId: 'proxy',
   register(env) {
+    const additionalEndpoints = {};
+
+    env.registerExtensionPoint(proxyEndpointsExtensionPoint, {
+      addProxyEndpoints(endpoints) {
+        Object.assign(additionalEndpoints, endpoints);
+      },
+    });
     env.registerInit({
       deps: {
         config: coreServices.rootConfig,
@@ -42,6 +50,7 @@ export const proxyPlugin = createBackendPlugin({
           discovery,
           logger: loggerToWinstonLogger(logger),
           httpRouterService: httpRouter,
+          additionalEndpoints,
         });
       },
     });

plugins/proxy-backend/src/service/router.ts

@@ -20,7 +20,6 @@ import Router from 'express-promise-router';
 import {
   createProxyMiddleware,
   fixRequestBody,
-  Options,
   RequestHandler,
 } from 'http-proxy-middleware';
 import { Logger } from 'winston';
@@ -31,6 +30,7 @@ import {
   HttpRouterService,
   RootConfigService,
 } from '@backstage/backend-plugin-api';
+import { ProxyConfig } from '@backstage/plugin-proxy-node/alpha';
 
 // A list of headers that are always forwarded to the proxy targets.
 const safeForwardHeaders = [
@@ -63,12 +63,7 @@ export interface RouterOptions {
   discovery: DiscoveryService;
   skipInvalidProxies?: boolean;
   reviveConsumedRequestBodies?: boolean;
-}
-
-export interface ProxyConfig extends Options {
-  allowedMethods?: string[];
-  allowedHeaders?: string[];
-  reviveRequestBody?: boolean;
+  additionalEndpoints?: ProxyConfig;
 }
 
 // Creates a proxy middleware, possibly with defaults added on top of the
@@ -87,7 +82,7 @@ export function buildMiddleware(
     fullConfig = { target: config };
     credentialsPolicy = 'require';
   } else {
-    const { credentials, ...rest } = config as any;
+    const { credentials, ...rest } = config;
     fullConfig = rest;
     credentialsPolicy = credentials ?? 'require';
   }
@@ -315,7 +310,11 @@ export async function createRouterInternal(
   const externalUrl = await options.discovery.getExternalBaseUrl('proxy');
   const { pathname: pathPrefix } = new URL(externalUrl);
 
-  const proxyConfig = readProxyConfig(options.config, options.logger);
+  const proxyConfig: ProxyConfig = {
+    ...(options.additionalEndpoints ?? {}),
+    ...readProxyConfig(options.config, options.logger),
+  };
+
   configureMiddlewares(
     proxyOptions,
     currentRouter,
@@ -358,10 +357,10 @@ function configureMiddlewares(
   },
   router: express.Router,
   pathPrefix: string,
-  proxyConfig: any,
+  proxyConfig: ProxyConfig,
   httpRouterService?: HttpRouterService,
 ) {
-  Object.entries<any>(proxyConfig).forEach(([route, proxyRouteConfig]) => {
+  Object.entries(proxyConfig).forEach(([route, proxyRouteConfig]) => {
     try {
       router.use(
         route,

plugins/proxy-node/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/proxy-node/README.md

@@ -0,0 +1,5 @@
+# backstage-plugin-proxy-node-node
+
+Welcome to the Node.js library package for the proxy-node plugin!
+
+_This plugin was created through the Backstage CLI_

plugins/proxy-node/catalog-info.yaml

@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backstage-plugin-proxy-node
+  title: '@backstage/plugin-proxy-node'
+  description: The plugin-proxy-node module for @backstage/plugin-proxy-backend
+spec:
+  lifecycle: experimental
+  type: backstage-node-library
+  owner: maintainers

plugins/proxy-node/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@backstage/plugin-proxy-node",
+  "version": "0.0.0",
+  "description": "The plugin-proxy-node module for @backstage/plugin-proxy-backend",
+  "backstage": {
+    "role": "node-library",
+    "pluginId": "proxy-backend",
+    "pluginPackages": [
+      "@backstage/plugin-proxy-node"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "plugins/proxy-node"
+  },
+  "license": "Apache-2.0",
+  "exports": {
+    "./alpha": "./src/alpha/index.ts",
+    "./package.json": "./package.json"
+  },
+  "main": "src/alpha/index.ts",
+  "types": "src/alpha/index.ts",
+  "typesVersions": {
+    "*": {
+      "alpha": [
+        "src/alpha/index.ts"
+      ],
+      "package.json": [
+        "package.json"
+      ]
+    }
+  },
+  "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": "workspace:^",
+    "http-proxy-middleware": "^2.0.0"
+  },
+  "devDependencies": {
+    "@backstage/backend-test-utils": "workspace:^",
+    "@backstage/cli": "workspace:^",
+    "@backstage/config": "workspace:^",
+    "@types/http-proxy-middleware": "^1.0.0"
+  }
+}

plugins/proxy-node/report-alpha.api.md

@@ -0,0 +1,31 @@
+## API Report File for "@backstage/plugin-proxy-node"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { ExtensionPoint } from '@backstage/backend-plugin-api';
+import { Options } from 'http-proxy-middleware';
+
+// @alpha
+export interface ProxyConfig extends Options {
+  // (undocumented)
+  allowedHeaders?: string[];
+  // (undocumented)
+  allowedMethods?: string[];
+  // (undocumented)
+  credentials?: 'require' | 'forward' | 'dangerously-allow-unauthenticated';
+  // (undocumented)
+  reviveRequestBody?: boolean;
+}
+
+// @alpha
+export interface ProxyEndpointsExtensionPoint {
+  // (undocumented)
+  addProxyEndpoints(endpoints: Record<string, string | ProxyConfig>): void;
+}
+
+// @alpha
+export const proxyEndpointsExtensionPoint: ExtensionPoint<ProxyEndpointsExtensionPoint>;
+
+// (No @packageDocumentation comment for this package)
+```

plugins/proxy-node/src/alpha/index.ts

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { createExtensionPoint } from '@backstage/backend-plugin-api';
+import { Options } from 'http-proxy-middleware';
+
+/**
+ * http-proxy-middleware proxy config interface.
+ *
+ * @alpha
+ */
+export interface ProxyConfig extends Options {
+  allowedMethods?: string[];
+  allowedHeaders?: string[];
+  reviveRequestBody?: boolean;
+  credentials?: 'require' | 'forward' | 'dangerously-allow-unauthenticated';
+}
+
+/**
+ * Extension point interface for managing proxy endpoints.
+ *
+ * @alpha
+ */
+export interface ProxyEndpointsExtensionPoint {
+  addProxyEndpoints(endpoints: Record<string, string | ProxyConfig>): void;
+}
+
+/**
+ * Extension point for managing proxy endpoints.
+ *
+ * @alpha
+ */
+export const proxyEndpointsExtensionPoint =
+  createExtensionPoint<ProxyEndpointsExtensionPoint>({
+    id: 'proxy.endpoints',
+  });

yarn.lock

@@ -7510,6 +7510,7 @@ __metadata:
     "@backstage/config": "workspace:^"
     "@backstage/config-loader": "workspace:^"
     "@backstage/errors": "workspace:^"
+    "@backstage/plugin-proxy-node": "workspace:^"
     "@backstage/types": "workspace:^"
     "@types/express": ^4.17.6
     "@types/http-proxy-middleware": ^1.0.0
@@ -7527,6 +7528,19 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@backstage/plugin-proxy-node@workspace:^, @backstage/plugin-proxy-node@workspace:plugins/proxy-node":
+  version: 0.0.0-use.local
+  resolution: "@backstage/plugin-proxy-node@workspace:plugins/proxy-node"
+  dependencies:
+    "@backstage/backend-plugin-api": "workspace:^"
+    "@backstage/backend-test-utils": "workspace:^"
+    "@backstage/cli": "workspace:^"
+    "@backstage/config": "workspace:^"
+    "@types/http-proxy-middleware": ^1.0.0
+    http-proxy-middleware: ^2.0.0
+  languageName: unknown
+  linkType: soft
+
 "@backstage/plugin-scaffolder-backend-module-azure@workspace:^, @backstage/plugin-scaffolder-backend-module-azure@workspace:plugins/scaffolder-backend-module-azure":
   version: 0.0.0-use.local
   resolution: "@backstage/plugin-scaffolder-backend-module-azure@workspace:plugins/scaffolder-backend-module-azure"