paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 15 Packages Projects Releases Wiki Activity

Merge pull request #18913 from backstage/rugvip/app-backend-refactor

Browse Source 
app-backend: refactored to use static config and extension points
This commit is contained in:
Patrik Oldsberg
2023-08-07 11:40:47 +02:00
committed by GitHub
parent cf03c2ab78 da06d93e24
commit 1ee2b8972b
19 changed files with 264 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/lazy-pugs-wash.md
+5
View File
@@ -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.
.changeset/sharp-months-think.md
+5
View File
@@ -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.
app-config.yaml
+2
View File
@@ -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
packages/backend-next/src/index.ts
+1 -1
View File
@@ -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());
plugins/app-backend/alpha-api-report.md
+1 -10
View File
@@ -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)
```
plugins/app-backend/config.d.ts
Vendored
+46
View File
@@ -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;
};
}
plugins/app-backend/package.json
+3
View File
@@ -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"
]
plugins/app-backend/src/alpha.ts
-1
View File
@@ -15,4 +15,3 @@
*/
export { appPlugin } from './service/appPlugin';
export type { AppPluginOptions } from './service/appPlugin';
plugins/app-backend/src/service/appPlugin.test.ts
+9 -5
View File
@@ -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,
},
},
}),
],
});
plugins/app-backend/src/service/appPlugin.ts
+20 -55
View File
@@ -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);
},
});
},
}));
});
plugins/app-backend/src/service/router.ts
+9 -2
View File
@@ -92,6 +92,13 @@ export async function createRouter(
): Promise<express.Router> {
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,
plugins/app-node/.eslintrc.js
+1
View File
@@ -0,0 +1 @@
module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);
plugins/app-node/README.md
+5
View File
@@ -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_
plugins/app-node/api-report.md
+16
View File
@@ -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<StaticFallbackHandlerExtensionPoint>;
```
plugins/app-node/package.json
+35
View File
@@ -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"
}
}
plugins/app-node/src/extensions.ts
+52
View File
@@ -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<StaticFallbackHandlerExtensionPoint>({
id: 'app.staticFallbackHandler',
});
plugins/app-node/src/index.ts
+26
View File
@@ -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';
plugins/app-node/src/setupTests.ts
+16
View File
@@ -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 {};
yarn.lock
+12
View File
@@ -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"