app-backend: initial port to new backend system

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
Co-authored-by: Johan Haals <johan.haals@gmail.com>
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

plugins/app-backend/api-report.md

@@ -3,11 +3,23 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
+import { BackendFeature } from '@backstage/backend-plugin-api';
 import { Config } from '@backstage/config';
 import express from 'express';
 import { Logger } from 'winston';
 import { PluginDatabaseManager } from '@backstage/backend-common';
 
+// @alpha
+export const appPlugin: (options: AppPluginOptions) => BackendFeature;
+
+// @alpha (undocumented)
+export type AppPluginOptions = {
+  appPackageName: string;
+  staticFallbackHandler?: express.Handler;
+  disableConfigInjection?: boolean;
+  disableStaticFallbackCache?: boolean;
+};
+
 // @public (undocumented)
 export function createRouter(options: RouterOptions): Promise<express.Router>;
 

plugins/app-backend/package.json

@@ -8,7 +8,8 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts"
+    "types": "dist/index.d.ts",
+    "alphaTypes": "dist/index.alpha.d.ts"
   },
   "backstage": {
     "role": "backend-plugin"
@@ -24,7 +25,7 @@
   ],
   "scripts": {
     "start": "backstage-cli package start",
-    "build": "backstage-cli package build",
+    "build": "backstage-cli package build --experimental-type-build",
     "lint": "backstage-cli package lint",
     "test": "backstage-cli package test",
     "prepack": "backstage-cli package prepack",
@@ -33,6 +34,7 @@
   },
   "dependencies": {
     "@backstage/backend-common": "workspace:^",
+    "@backstage/backend-plugin-api": "workspace:^",
     "@backstage/config": "workspace:^",
     "@backstage/config-loader": "workspace:^",
     "@backstage/types": "workspace:^",
@@ -49,16 +51,20 @@
     "yn": "^4.0.0"
   },
   "devDependencies": {
+    "@backstage/backend-app-api": "workspace:^",
     "@backstage/backend-test-utils": "workspace:^",
     "@backstage/cli": "workspace:^",
     "@backstage/types": "workspace:^",
     "@types/supertest": "^2.0.8",
+    "get-port": "^6.1.2",
     "mock-fs": "^5.1.0",
     "msw": "^0.47.0",
+    "node-fetch": "^2.6.7",
     "supertest": "^6.1.3"
   },
   "files": [
     "dist",
+    "alpha",
     "migrations/**/*.{js,d.ts}",
     "static"
   ]

plugins/app-backend/src/index.ts

@@ -21,3 +21,5 @@
  */
 
 export * from './service/router';
+export { appPlugin } from './service/appPlugin';
+export type { AppPluginOptions } from './service/appPlugin';

plugins/app-backend/src/service/appPlugin.test.ts

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2022 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 mockFs from 'mock-fs';
+import { resolve as resolvePath } from 'path';
+import fetch from 'node-fetch';
+import { configServiceRef } from '@backstage/backend-plugin-api';
+import { startTestBackend } from '@backstage/backend-test-utils';
+import { appPlugin } from './appPlugin';
+import {
+  databaseFactory,
+  httpRouterFactory,
+  loggerFactory,
+  rootLoggerFactory,
+} from '@backstage/backend-app-api';
+import { ConfigReader } from '@backstage/config';
+import getPort from 'get-port';
+
+describe('appPlugin', () => {
+  beforeAll(() => {
+    mockFs({
+      [resolvePath(process.cwd(), 'node_modules/app')]: {
+        'package.json': '{}',
+        dist: {
+          static: {},
+          'index.html': 'winning',
+        },
+      },
+    });
+  });
+
+  afterAll(() => {
+    mockFs.restore();
+  });
+
+  it('boots', async () => {
+    const port = await getPort();
+    await startTestBackend({
+      services: [
+        [
+          configServiceRef,
+          new ConfigReader({
+            backend: {
+              listen: { port },
+              database: { client: 'better-sqlite3', connection: ':memory:' },
+            },
+          }),
+        ],
+        loggerFactory(),
+        rootLoggerFactory(),
+        databaseFactory(),
+        httpRouterFactory(),
+      ],
+      features: [
+        appPlugin({
+          appPackageName: 'app',
+          disableStaticFallbackCache: true,
+        }),
+      ],
+    });
+
+    await expect(
+      fetch(`http://localhost:${port}/api/app/derp.html`).then(res =>
+        res.text(),
+      ),
+    ).resolves.toBe('winning');
+  });
+});

plugins/app-backend/src/service/appPlugin.ts

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2022 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 express from 'express';
+import {
+  configServiceRef,
+  createBackendPlugin,
+  databaseServiceRef,
+  loggerServiceRef,
+  loggerToWinstonLogger,
+  httpRouterServiceRef,
+} from '@backstage/backend-plugin-api';
+import { createRouter } from './router';
+
+/** @alpha */
+export type AppPluginOptions = {
+  /**
+   * The name of the app package (in most Backstage repositories, this is the
+   * "name" field in `packages/app/package.json`) that content should be served
+   * from. The same app package should be added as a dependency to the backend
+   * package in order for it to be accessible at runtime.
+   *
+   * In a typical setup with a single app package, this would be set to 'app'.
+   */
+  appPackageName: string;
+
+  /**
+   * A request handler to handle requests for static content that are not present in the app bundle.
+   *
+   * This can be used to avoid issues with clients on older deployment versions trying to access lazy
+   * loaded content that is no longer present. Typically the requests would fall back to a long-term
+   * object store where all recently deployed versions of the app are present.
+   *
+   * Another option is to provide a `database` that will take care of storing the static assets instead.
+   *
+   * If both `database` and `staticFallbackHandler` are provided, the `database` will attempt to serve
+   * static assets first, and if they are not found, the `staticFallbackHandler` will be called.
+   */
+  staticFallbackHandler?: express.Handler;
+
+  /**
+   * Disables the configuration injection. This can be useful if you're running in an environment
+   * with a read-only filesystem, or for some other reason don't want configuration to be injected.
+   *
+   * Note that this will cause the configuration used when building the app bundle to be used, unless
+   * a separate configuration loading strategy is set up.
+   *
+   * This also disables configuration injection though `APP_CONFIG_` environment variables.
+   */
+  disableConfigInjection?: boolean;
+
+  /**
+   * By default the app backend plugin will cache previously deployed static assets in the database.
+   * If you disable this, it is recommended to set a `staticFallbackHandler` instead.
+   */
+  disableStaticFallbackCache?: boolean;
+};
+
+/**
+ * The App plugin is responsible for serving the frontend app bundle and static assets.
+ * @alpha
+ */
+export const appPlugin = createBackendPlugin({
+  id: 'app',
+  register(env, options: AppPluginOptions) {
+    env.registerInit({
+      deps: {
+        logger: loggerServiceRef,
+        config: configServiceRef,
+        database: databaseServiceRef,
+        httpRouter: httpRouterServiceRef,
+      },
+      async init({ logger, config, database, httpRouter }) {
+        const {
+          appPackageName,
+          staticFallbackHandler,
+          disableConfigInjection,
+          disableStaticFallbackCache,
+        } = options;
+        const winstonLogger = loggerToWinstonLogger(logger);
+
+        const router = await createRouter({
+          logger: winstonLogger,
+          config,
+          database: disableStaticFallbackCache ? undefined : database,
+          appPackageName,
+          staticFallbackHandler,
+          disableConfigInjection,
+        });
+        httpRouter.use(router);
+      },
+    });
+  },
+});