diff --git a/.changeset/lazy-pugs-wash.md b/.changeset/lazy-pugs-wash.md new file mode 100644 index 0000000000..923ef5b116 --- /dev/null +++ b/.changeset/lazy-pugs-wash.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-app-node': minor +--- + +Added the `app` plugin node library, initially providing an extension point that can be used to configure a static fallback handler. diff --git a/.changeset/sharp-months-think.md b/.changeset/sharp-months-think.md new file mode 100644 index 0000000000..04ffbb8d1b --- /dev/null +++ b/.changeset/sharp-months-think.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-app-backend': patch +--- + +Migrated the alpha `appBackend` export to use static configuration and extension points rather than accepting options. diff --git a/app-config.yaml b/app-config.yaml index 8dcd052e61..7988d6ebbe 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -20,6 +20,8 @@ app: - url: https://discord.gg/backstage-687207715902193673 title: '#backstage' + packageName: example-app + backend: # Used for enabling authentication, secret is shared by all backend plugins # See https://backstage.io/docs/auth/service-to-service-auth for diff --git a/packages/backend-next/src/index.ts b/packages/backend-next/src/index.ts index fa7561e211..c44da4ae8c 100644 --- a/packages/backend-next/src/index.ts +++ b/packages/backend-next/src/index.ts @@ -42,7 +42,7 @@ import { lighthousePlugin } from '@backstage/plugin-lighthouse-backend'; const backend = createBackend(); -backend.add(appPlugin({ appPackageName: 'example-app' })); +backend.add(appPlugin()); // Badges backend.add(badgesPlugin()); diff --git a/plugins/app-backend/alpha-api-report.md b/plugins/app-backend/alpha-api-report.md index 20a2902557..5fb0546a79 100644 --- a/plugins/app-backend/alpha-api-report.md +++ b/plugins/app-backend/alpha-api-report.md @@ -4,18 +4,9 @@ ```ts import { BackendFeature } from '@backstage/backend-plugin-api'; -import express from 'express'; // @alpha -export const appPlugin: (options: AppPluginOptions) => BackendFeature; - -// @alpha (undocumented) -export type AppPluginOptions = { - appPackageName?: string; - staticFallbackHandler?: express.Handler; - disableConfigInjection?: boolean; - disableStaticFallbackCache?: boolean; -}; +export const appPlugin: () => BackendFeature; // (No @packageDocumentation comment for this package) ``` diff --git a/plugins/app-backend/config.d.ts b/plugins/app-backend/config.d.ts new file mode 100644 index 0000000000..dc11bc4e0a --- /dev/null +++ b/plugins/app-backend/config.d.ts @@ -0,0 +1,46 @@ +/* + * Copyright 2023 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. + */ + +export interface Config { + app?: { + /** + * 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 will default to 'app'. + */ + packageName?: string; + + /** + * 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; + }; +} diff --git a/plugins/app-backend/package.json b/plugins/app-backend/package.json index c9b25508c0..be1b6b3a80 100644 --- a/plugins/app-backend/package.json +++ b/plugins/app-backend/package.json @@ -49,6 +49,7 @@ "@backstage/backend-plugin-api": "workspace:^", "@backstage/config": "workspace:^", "@backstage/config-loader": "workspace:^", + "@backstage/plugin-app-node": "workspace:^", "@backstage/types": "workspace:^", "@types/express": "^4.17.6", "express": "^4.17.1", @@ -73,8 +74,10 @@ "node-fetch": "^2.6.7", "supertest": "^6.1.3" }, + "configSchema": "config.d.ts", "files": [ "dist", + "config.d.ts", "migrations/**/*.{js,d.ts}", "static" ] diff --git a/plugins/app-backend/src/alpha.ts b/plugins/app-backend/src/alpha.ts index cc8276b853..edb5c8caf5 100644 --- a/plugins/app-backend/src/alpha.ts +++ b/plugins/app-backend/src/alpha.ts @@ -15,4 +15,3 @@ */ export { appPlugin } from './service/appPlugin'; -export type { AppPluginOptions } from './service/appPlugin'; diff --git a/plugins/app-backend/src/service/appPlugin.test.ts b/plugins/app-backend/src/service/appPlugin.test.ts index 518f56b7f9..37d38663ef 100644 --- a/plugins/app-backend/src/service/appPlugin.test.ts +++ b/plugins/app-backend/src/service/appPlugin.test.ts @@ -17,7 +17,7 @@ import mockFs from 'mock-fs'; import { resolve as resolvePath } from 'path'; import fetch from 'node-fetch'; -import { startTestBackend } from '@backstage/backend-test-utils'; +import { mockServices, startTestBackend } from '@backstage/backend-test-utils'; import { appPlugin } from './appPlugin'; describe('appPlugin', () => { @@ -39,10 +39,14 @@ describe('appPlugin', () => { it('boots', async () => { const { server } = await startTestBackend({ - features: [ - appPlugin({ - appPackageName: 'app', - disableStaticFallbackCache: true, + features: [appPlugin()], + services: [ + mockServices.rootConfig.factory({ + data: { + app: { + disableStaticFallbackCache: true, + }, + }, }), ], }); diff --git a/plugins/app-backend/src/service/appPlugin.ts b/plugins/app-backend/src/service/appPlugin.ts index a223d3ffb5..9ba2ea6d6c 100644 --- a/plugins/app-backend/src/service/appPlugin.ts +++ b/plugins/app-backend/src/service/appPlugin.ts @@ -21,58 +21,28 @@ import { } from '@backstage/backend-plugin-api'; import { createRouter } from './router'; import { loggerToWinstonLogger } from '@backstage/backend-common'; - -/** @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 will default 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; -}; +import { staticFallbackHandlerExtensionPoint } from '@backstage/plugin-app-node'; /** * The App plugin is responsible for serving the frontend app bundle and static assets. * @alpha */ -export const appPlugin = createBackendPlugin((options: AppPluginOptions) => ({ +export const appPlugin = createBackendPlugin({ pluginId: 'app', register(env) { + let staticFallbackHandler: express.Handler | undefined; + + env.registerExtensionPoint(staticFallbackHandlerExtensionPoint, { + setStaticFallbackHandler(handler) { + if (staticFallbackHandler) { + throw new Error( + 'Attempted to install a static fallback handler for the app-backend twice', + ); + } + staticFallbackHandler = handler; + }, + }); + env.registerInit({ deps: { logger: coreServices.logger, @@ -81,24 +51,19 @@ export const appPlugin = createBackendPlugin((options: AppPluginOptions) => ({ httpRouter: coreServices.httpRouter, }, async init({ logger, config, database, httpRouter }) { - const { - appPackageName, - staticFallbackHandler, - disableConfigInjection, - disableStaticFallbackCache, - } = options; + const appPackageName = + config.getOptionalString('app.packageName') ?? 'app'; const winstonLogger = loggerToWinstonLogger(logger); const router = await createRouter({ logger: winstonLogger, config, - database: disableStaticFallbackCache ? undefined : database, - appPackageName: appPackageName ?? 'app', + database, + appPackageName, staticFallbackHandler, - disableConfigInjection, }); httpRouter.use(router); }, }); }, -})); +}); diff --git a/plugins/app-backend/src/service/router.ts b/plugins/app-backend/src/service/router.ts index 4e94138439..40e291c19d 100644 --- a/plugins/app-backend/src/service/router.ts +++ b/plugins/app-backend/src/service/router.ts @@ -92,6 +92,13 @@ export async function createRouter( ): Promise { const { config, logger, appPackageName, staticFallbackHandler } = options; + const disableConfigInjection = + options.disableConfigInjection ?? + config.getOptionalBoolean('app.disableConfigInjection'); + const disableStaticFallbackCache = config.getOptionalBoolean( + 'app.disableStaticFallbackCache', + ); + const appDistDir = resolvePackagePath(appPackageName, 'dist'); const staticDir = resolvePath(appDistDir, 'static'); @@ -107,7 +114,7 @@ export async function createRouter( logger.info(`Serving static app content from ${appDistDir}`); - if (!options.disableConfigInjection) { + if (!disableConfigInjection) { const appConfigs = await readConfigs({ config, appDistDir, @@ -131,7 +138,7 @@ export async function createRouter( }), ); - if (options.database) { + if (options.database && !disableStaticFallbackCache) { const store = await StaticAssetsStore.create({ logger, database: options.database, diff --git a/plugins/app-node/.eslintrc.js b/plugins/app-node/.eslintrc.js new file mode 100644 index 0000000000..e2a53a6ad2 --- /dev/null +++ b/plugins/app-node/.eslintrc.js @@ -0,0 +1 @@ +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); diff --git a/plugins/app-node/README.md b/plugins/app-node/README.md new file mode 100644 index 0000000000..5c606540c0 --- /dev/null +++ b/plugins/app-node/README.md @@ -0,0 +1,5 @@ +# @backstage/plugin-app-node + +Welcome to the Node.js library package for the app plugin! + +_This plugin was created through the Backstage CLI_ diff --git a/plugins/app-node/api-report.md b/plugins/app-node/api-report.md new file mode 100644 index 0000000000..504c9d48c1 --- /dev/null +++ b/plugins/app-node/api-report.md @@ -0,0 +1,16 @@ +## API Report File for "@backstage/plugin-app-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 { Handler } from 'express'; + +// @public +export interface StaticFallbackHandlerExtensionPoint { + setStaticFallbackHandler(handler: Handler): void; +} + +// @public +export const staticFallbackHandlerExtensionPoint: ExtensionPoint; +``` diff --git a/plugins/app-node/package.json b/plugins/app-node/package.json new file mode 100644 index 0000000000..c971bdb628 --- /dev/null +++ b/plugins/app-node/package.json @@ -0,0 +1,35 @@ +{ + "name": "@backstage/plugin-app-node", + "description": "Node.js library for the app plugin", + "version": "0.0.0", + "main": "src/index.ts", + "types": "src/index.ts", + "license": "Apache-2.0", + "publishConfig": { + "access": "public", + "main": "dist/index.cjs.js", + "types": "dist/index.d.ts" + }, + "backstage": { + "role": "node-library" + }, + "scripts": { + "build": "backstage-cli package build", + "lint": "backstage-cli package lint", + "test": "backstage-cli package test", + "clean": "backstage-cli package clean", + "prepack": "backstage-cli package prepack", + "postpack": "backstage-cli package postpack" + }, + "devDependencies": { + "@backstage/cli": "workspace:^" + }, + "files": [ + "dist" + ], + "dependencies": { + "@backstage/backend-plugin-api": "workspace:^", + "@types/express": "^4.17.6", + "express": "^4.17.1" + } +} diff --git a/plugins/app-node/src/extensions.ts b/plugins/app-node/src/extensions.ts new file mode 100644 index 0000000000..6a75a5b791 --- /dev/null +++ b/plugins/app-node/src/extensions.ts @@ -0,0 +1,52 @@ +/* + * Copyright 2023 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 { Handler } from 'express'; + +/** + * The interface for {@link staticFallbackHandlerExtensionPoint}. + * + * @public + */ +export interface StaticFallbackHandlerExtensionPoint { + /** + * Sets the static fallback handler. This can only be done once. + */ + setStaticFallbackHandler(handler: Handler): void; +} + +/** + * An extension point the exposes the ability to configure a static fallback handler for the app backend. + * + * The static fallback handler is a request handler to handle requests for static content that is 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. + * + * @public + */ +export const staticFallbackHandlerExtensionPoint = + createExtensionPoint({ + id: 'app.staticFallbackHandler', + }); diff --git a/plugins/app-node/src/index.ts b/plugins/app-node/src/index.ts new file mode 100644 index 0000000000..c5189fa8b9 --- /dev/null +++ b/plugins/app-node/src/index.ts @@ -0,0 +1,26 @@ +/* + * Copyright 2023 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. + */ + +/** + * Node.js library for the app plugin. + * + * @packageDocumentation + */ + +export { + staticFallbackHandlerExtensionPoint, + type StaticFallbackHandlerExtensionPoint, +} from './extensions'; diff --git a/plugins/app-node/src/setupTests.ts b/plugins/app-node/src/setupTests.ts new file mode 100644 index 0000000000..4b9026cde5 --- /dev/null +++ b/plugins/app-node/src/setupTests.ts @@ -0,0 +1,16 @@ +/* + * Copyright 2023 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. + */ +export {}; diff --git a/yarn.lock b/yarn.lock index 8b41dfe9f9..8172e59412 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4584,6 +4584,7 @@ __metadata: "@backstage/cli": "workspace:^" "@backstage/config": "workspace:^" "@backstage/config-loader": "workspace:^" + "@backstage/plugin-app-node": "workspace:^" "@backstage/types": "workspace:^" "@types/express": ^4.17.6 "@types/supertest": ^2.0.8 @@ -4604,6 +4605,17 @@ __metadata: languageName: unknown linkType: soft +"@backstage/plugin-app-node@workspace:^, @backstage/plugin-app-node@workspace:plugins/app-node": + version: 0.0.0-use.local + resolution: "@backstage/plugin-app-node@workspace:plugins/app-node" + dependencies: + "@backstage/backend-plugin-api": "workspace:^" + "@backstage/cli": "workspace:^" + "@types/express": ^4.17.6 + express: ^4.17.1 + languageName: unknown + linkType: soft + "@backstage/plugin-auth-backend@workspace:^, @backstage/plugin-auth-backend@workspace:plugins/auth-backend": version: 0.0.0-use.local resolution: "@backstage/plugin-auth-backend@workspace:plugins/auth-backend"