Merge pull request #3462 from SDA-SE/feat/proxy-schema

Add a configuration schema for the proxy plugin

.changeset/weak-roses-search.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-proxy-backend': patch
+---
+
+Add configuration schema for the commonly used properties

app-config.yaml

@@ -38,7 +38,7 @@ proxy:
     headers:
       Authorization:
         $env: TRAVISCI_AUTH_TOKEN
-      travis-api-version: 3
+      travis-api-version: '3'
 
   '/newrelic/apm/api':
     target: https://api.newrelic.com/v2

docs/plugins/proxying.md

@@ -52,19 +52,7 @@ configuration will lead to the proxy acting on backend requests to
 
 The value inside each route is either a simple URL string, or an object on the
 format accepted by
-[http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware). It
-is also possible to limit the forwarded HTTP methods with the configuration
-`allowedMethods`, for example `allowedMethods: ['GET']` to enforce read-only
-access.
-
-By default, the proxy will only forward safe HTTP request headers to the target.
-Those are based on the headers that are considered safe for CORS and includes
-headers like `content-type` or `last-modified`, as well as all headers that are
-set by the proxy. If the proxy should forward other headers like
-`authorization`, this must be enabled by the `allowedHeaders` config, for
-example `allowedHeaders: ['Authorization']`. This should help to not
-accidentally forward confidential headers (`cookie`, `X-Auth-Request-User`) to
-third-parties.
+[http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware).
 
 If the value is a string, it is assumed to correspond to:
 
@@ -85,3 +73,18 @@ except with the following caveats for convenience:
   `'^/api/proxy/larger-example/v1/': '/'` is added. That means that a request to
   `/api/proxy/larger-example/v1/some/path` will be translated to a request to
   `http://larger.example.com:8080/svc.v1/some/path`.
+
+There are also additional settings:
+
+- `allowedMethods`: Limit the forwarded HTTP methods. For example
+  `allowedMethods: ['GET']` enforces read-only access.
+- `allowedHeaders`: A list of headers that should be forwarded to the target.
+
+By default, the proxy will only forward safe HTTP request headers to the target.
+Those are based on the headers that are considered safe for CORS and includes
+headers like `content-type` or `last-modified`, as well as all headers that are
+set by the proxy. If the proxy should forward other headers like
+`authorization`, this must be enabled by the `allowedHeaders` config, for
+example `allowedHeaders: ['Authorization']`. This should help to not
+accidentally forward confidential headers (`cookie`, `X-Auth-Request-User`) to
+third-parties.

plugins/proxy-backend/config.d.ts

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * 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.
+ */
+
+export interface Config {
+  /**
+   * A list of forwarding-proxies. Each key is a route to match,
+   * below the prefix that the proxy plugin is mounted on. It must
+   * start with a '/'.
+   */
+  proxy?: {
+    [key: string]:
+      | string
+      | {
+          /**
+           * Target of the proxy. Url string to be parsed with the url module.
+           */
+          target: string;
+          /**
+           * Object with extra headers to be added to target requests.
+           */
+          headers?: { [key: string]: string };
+          /**
+           * Changes the origin of the host header to the target URL. Default: true.
+           */
+          changeOrigin?: boolean;
+          /**
+           * Rewrite target's url path. Object-keys will be used as RegExp to match paths.
+           * If pathRewrite is not specified, it is set to a single rewrite that removes the entire prefix and route.
+           */
+          pathRewrite?: { [regexp: string]: string };
+          /**
+           * Limit the forwarded HTTP methods, for example allowedMethods: ['GET'] to enforce read-only access.
+           */
+          allowedMethods?: string[];
+          /**
+           * Limit the forwarded HTTP methods. By default, only the headers that are considered safe for CORS
+           * and headers that are set by the proxy will be forwarded.
+           */
+          allowedHeaders?: string[];
+        };
+  };
+}

plugins/proxy-backend/package.json

@@ -41,6 +41,8 @@
     "supertest": "^4.0.2"
   },
   "files": [
-    "dist"
-  ]
+    "dist",
+    "config.d.ts"
+  ],
+  "configSchema": "config.d.ts"
 }