diff --git a/plugins/modern-backend/.eslintrc.js b/plugins/modern-backend/.eslintrc.js new file mode 100644 index 0000000000..e2a53a6ad2 --- /dev/null +++ b/plugins/modern-backend/.eslintrc.js @@ -0,0 +1 @@ +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); diff --git a/plugins/modern-backend/README.md b/plugins/modern-backend/README.md new file mode 100644 index 0000000000..929b0a189f --- /dev/null +++ b/plugins/modern-backend/README.md @@ -0,0 +1,14 @@ +# modern + +Welcome to the modern backend plugin! + +_This plugin was created through the Backstage CLI_ + +## Getting started + +Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn +start` in the root directory, and then navigating to [/modern/health](http://localhost:7007/api/modern/health). + +You can also serve the plugin in isolation by running `yarn start` in the plugin directory. +This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads. +It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory. diff --git a/plugins/modern-backend/catalog-info.yaml b/plugins/modern-backend/catalog-info.yaml new file mode 100644 index 0000000000..fd4b9dc0ba --- /dev/null +++ b/plugins/modern-backend/catalog-info.yaml @@ -0,0 +1,9 @@ +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: backstage-plugin-modern-backend + title: '@backstage/plugin-modern-backend' +spec: + lifecycle: experimental + type: backstage-backend-plugin + owner: maintainers diff --git a/plugins/modern-backend/dev/index.ts b/plugins/modern-backend/dev/index.ts new file mode 100644 index 0000000000..393f979bed --- /dev/null +++ b/plugins/modern-backend/dev/index.ts @@ -0,0 +1,74 @@ +/* + * 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 { createBackend } from '@backstage/backend-defaults'; +import { mockServices } from '@backstage/backend-test-utils'; +import { catalogServiceMock } from '@backstage/plugin-catalog-node/testUtils'; + +// TEMPLATE NOTE: +// This is the development setup for your plugin that wires up a +// minimal backend that can use both real and mocked plugins and services. +// +// Start up the backend by running `yarn start` in the package directory. +// It's it's up and running, try out the following requests: +// +// Create a new todo item: +// +// curl http://localhost:7007/api/modern/todos -H 'Content-Type: application/json' -d '{"title": "My Todo"}' +// +// List TODOs: +// +// curl http://localhost:7007/api/modern/todos +// +// Explicitly make an unauthenticated request, or with service auth: +// +// curl http://localhost:7007/api/modern/todos -H 'Authorization: Bearer mock-none-token' +// curl http://localhost:7007/api/modern/todos -H 'Authorization: Bearer mock-service-token' + +const backend = createBackend(); + +// TEMPLATE NOTE: +// Mocking the auth and httpAuth service allows you to call your plugin API without +// having to authenticate. +// +// If you want to use real auth, you can install the following instead: +// backend.add(import('@backstage/plugin-auth-backend')); +// backend.add(import('@backstage/plugin-auth-backend-module-guest-provider')); +backend.add(mockServices.auth.factory()); +backend.add(mockServices.httpAuth.factory()); + +// TEMPLATE NOTE: +// Rather than using a real catalog you can use a mock with a fixed set of entities. +backend.add( + catalogServiceMock.factory({ + entities: [ + { + apiVersion: 'backstage.io/v1alpha1', + kind: 'Component', + metadata: { + name: 'sample', + title: 'Sample Component', + }, + spec: { + type: 'service', + }, + }, + ], + }), +); + +backend.add(import('../src')); + +backend.start(); diff --git a/plugins/modern-backend/package.json b/plugins/modern-backend/package.json new file mode 100644 index 0000000000..def56e6ce3 --- /dev/null +++ b/plugins/modern-backend/package.json @@ -0,0 +1,48 @@ +{ + "name": "@backstage/plugin-modern-backend", + "version": "0.0.0", + "backstage": { + "role": "backend-plugin" + }, + "publishConfig": { + "access": "public", + "main": "dist/index.cjs.js", + "types": "dist/index.d.ts" + }, + "license": "Apache-2.0", + "main": "src/index.ts", + "types": "src/index.ts", + "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-defaults": "workspace:^", + "@backstage/backend-plugin-api": "workspace:^", + "@backstage/catalog-client": "workspace:^", + "@backstage/errors": "workspace:^", + "@backstage/plugin-catalog-node": "workspace:^", + "express": "^4.17.1", + "express-promise-router": "^4.1.0", + "node-fetch": "^2.6.7", + "zod": "^3.22.4" + }, + "devDependencies": { + "@backstage/backend-test-utils": "workspace:^", + "@backstage/cli": "workspace:^", + "@backstage/plugin-auth-backend": "workspace:^", + "@backstage/plugin-auth-backend-module-guest-provider": "workspace:^", + "@types/express": "*", + "@types/supertest": "^2.0.8", + "msw": "^2.0.8", + "supertest": "^6.2.4" + } +} diff --git a/plugins/modern-backend/src/index.ts b/plugins/modern-backend/src/index.ts new file mode 100644 index 0000000000..33e742ca76 --- /dev/null +++ b/plugins/modern-backend/src/index.ts @@ -0,0 +1,17 @@ +/* + * 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. + */ + +export { modernPlugin as default } from './plugin'; diff --git a/plugins/modern-backend/src/plugin.test.ts b/plugins/modern-backend/src/plugin.test.ts new file mode 100644 index 0000000000..975fb1ae70 --- /dev/null +++ b/plugins/modern-backend/src/plugin.test.ts @@ -0,0 +1,101 @@ +/* + * 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 { + mockCredentials, + startTestBackend, +} from '@backstage/backend-test-utils'; +import { modernPlugin } from './plugin'; +import request from 'supertest'; +import { catalogServiceMock } from '@backstage/plugin-catalog-node/testUtils'; + +// TEMPLATE NOTE: +// Plugin tests are integration tests for your plugin, ensuring that all pieces +// work together end-to-end. You can still mock injected backend services +// however, just like anyway that installs your plugin might replace the +// services with their own implementations. +describe('plugin', () => { + it('should create and read TODO items', async () => { + const { server } = await startTestBackend({ + features: [modernPlugin], + }); + + await request(server).get('/api/modern/todos').expect(200, { + items: [], + }); + + const createRes = await request(server) + .post('/api/modern/todos') + .send({ title: 'My Todo' }); + + expect(createRes.status).toBe(201); + expect(createRes.body).toEqual({ + id: expect.any(String), + title: 'My Todo', + createdBy: mockCredentials.user().principal.userEntityRef, + createdAt: expect.any(String), + }); + + const createdTodoItem = createRes.body; + + await request(server) + .get('/api/modern/todos') + .expect(200, { + items: [createdTodoItem], + }); + + await request(server) + .get(`/api/modern/todos/${createdTodoItem.id}`) + .expect(200, createdTodoItem); + }); + + it('should create TODO item with catalog information', async () => { + const { server } = await startTestBackend({ + features: [ + modernPlugin, + catalogServiceMock.factory({ + entities: [ + { + apiVersion: 'backstage.io/v1alpha1', + kind: 'Component', + metadata: { + name: 'my-component', + namespace: 'default', + title: 'My Component', + }, + spec: { + type: 'service', + owner: 'me', + }, + }, + ], + }), + ], + }); + + const createRes = await request(server) + .post('/api/modern/todos') + .send({ title: 'My Todo', entityRef: 'component:default/my-component' }); + + expect(createRes.status).toBe(201); + expect(createRes.body).toEqual({ + id: expect.any(String), + title: '[My Component] My Todo', + createdBy: mockCredentials.user().principal.userEntityRef, + createdAt: expect.any(String), + }); + }); +}); diff --git a/plugins/modern-backend/src/plugin.ts b/plugins/modern-backend/src/plugin.ts new file mode 100644 index 0000000000..6db9427f2d --- /dev/null +++ b/plugins/modern-backend/src/plugin.ts @@ -0,0 +1,57 @@ +/* + * 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 { + coreServices, + createBackendPlugin, +} from '@backstage/backend-plugin-api'; +import { createRouter } from './router'; +import { catalogServiceRef } from '@backstage/plugin-catalog-node/alpha'; +import { createTodoListService } from './services/TodoListService'; + +/** + * modernPlugin backend plugin + * + * @public + */ +export const modernPlugin = createBackendPlugin({ + pluginId: 'modern', + register(env) { + env.registerInit({ + deps: { + logger: coreServices.logger, + auth: coreServices.auth, + httpAuth: coreServices.httpAuth, + httpRouter: coreServices.httpRouter, + catalog: catalogServiceRef, + }, + async init({ logger, auth, httpAuth, httpRouter, catalog }) { + const todoListService = await createTodoListService({ + logger, + auth, + catalog, + }); + + httpRouter.use( + await createRouter({ + httpAuth, + todoListService, + }), + ); + }, + }); + }, +}); diff --git a/plugins/modern-backend/src/router.test.ts b/plugins/modern-backend/src/router.test.ts new file mode 100644 index 0000000000..70534703b4 --- /dev/null +++ b/plugins/modern-backend/src/router.test.ts @@ -0,0 +1,83 @@ +/* + * 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 { + mockCredentials, + mockErrorHandler, + mockServices, +} from '@backstage/backend-test-utils'; +import express from 'express'; +import request from 'supertest'; + +import { createRouter } from './router'; +import { TodoListService } from './services/TodoListService/types'; + +const mockTodoItem = { + title: 'Do the thing', + id: '123', + createdBy: mockCredentials.user().principal.userEntityRef, + createdAt: new Date().toISOString(), +}; + +// TEMPLATE NOTE: +// Testing the router directly allows you to write a unit test that mocks the provided options. +describe('createRouter', () => { + let app: express.Express; + let todoListService: jest.Mocked; + + beforeEach(async () => { + todoListService = { + createTodo: jest.fn(), + listTodos: jest.fn(), + getTodo: jest.fn(), + }; + const router = await createRouter({ + httpAuth: mockServices.httpAuth(), + todoListService, + }); + app = express(); + app.use(router); + app.use(mockErrorHandler()); + }); + + it('should create a TODO', async () => { + todoListService.createTodo.mockResolvedValue(mockTodoItem); + + const response = await request(app).post('/todos').send({ + title: 'Do the thing', + }); + + expect(response.status).toBe(200); + expect(response.body).toEqual(mockTodoItem); + }); + + it('should not allow unauthenticated requests to create a TODO', async () => { + todoListService.createTodo.mockResolvedValue(mockTodoItem); + + // TEMPLATE NOTE: + // The HttpAuth mock service considers all requests to be authenticated as a + // mock user by default. In order to test other cases we need to explicitly + // pass an authorization header with mock credentials. + const response = await request(app) + .post('/todos') + .set('Authorization', mockCredentials.none.header()) + .send({ + title: 'Do the thing', + }); + + expect(response.status).toBe(401); + }); +}); diff --git a/plugins/modern-backend/src/router.ts b/plugins/modern-backend/src/router.ts new file mode 100644 index 0000000000..f4abbe7383 --- /dev/null +++ b/plugins/modern-backend/src/router.ts @@ -0,0 +1,67 @@ +/* + * 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 { HttpAuthService } from '@backstage/backend-plugin-api'; +import { InputError } from '@backstage/errors'; +import { z } from 'zod'; +import express from 'express'; +import Router from 'express-promise-router'; +import { TodoListService } from './services/TodoListService/types'; + +export async function createRouter({ + httpAuth, + todoListService, +}: { + httpAuth: HttpAuthService; + todoListService: TodoListService; +}): Promise { + const router = Router(); + router.use(express.json()); + + // TEMPLATE NOTE: + // Zod is a powerful library for data validation and recommended in particular + // for user-defined schemas. In this case we use it for input validation too. + // + // If you want to define a schema for your API we recommend using Backstage's + // OpenAPI tooling: https://backstage.io/docs/next/openapi/01-getting-started + const todoSchema = z.object({ + title: z.string(), + entityRef: z.string().optional(), + }); + + router.post('/todos', async (req, res) => { + const parsed = todoSchema.safeParse(req.body); + if (!parsed.success) { + throw new InputError(parsed.error.toString()); + } + + const result = await todoListService.createTodo(parsed.data, { + credentials: await httpAuth.credentials(req, { allow: ['user'] }), + }); + + res.status(201).json(result); + }); + + router.get('/todos', async (_req, res) => { + res.json(await todoListService.listTodos()); + }); + + router.get('/todos/:id', async (req, res) => { + res.json(await todoListService.getTodo({ id: req.params.id })); + }); + + return router; +} diff --git a/plugins/modern-backend/src/services/TodoListService/createTodoListService.ts b/plugins/modern-backend/src/services/TodoListService/createTodoListService.ts new file mode 100644 index 0000000000..a1b25b027f --- /dev/null +++ b/plugins/modern-backend/src/services/TodoListService/createTodoListService.ts @@ -0,0 +1,114 @@ +/* + * 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 { AuthService, LoggerService } from '@backstage/backend-plugin-api'; +import { NotFoundError } from '@backstage/errors'; +import { catalogServiceRef } from '@backstage/plugin-catalog-node/alpha'; +import crypto from 'node:crypto'; +import { TodoItem, TodoListService } from './types'; + +// TEMPLATE NOTE: +// This is a simple in-memory todo list store. It is recommended to use a +// database to store data in a real application. See the database service +// documentation for more information on how to do this: +// https://backstage.io/docs/backend-system/core-services/database +export async function createTodoListService({ + auth, + logger, + catalog, +}: { + auth: AuthService; + logger: LoggerService; + catalog: typeof catalogServiceRef.T; +}): Promise { + logger.info('Initializing TodoListService'); + + const storedTodos = new Array(); + + return { + async createTodo(input, options) { + let title = input.title; + + // TEMPLATE NOTE: + // A common pattern for Backstage plugins is to pass an entity reference + // from the frontend to then fetch the entire entity from the catalog in the + // backend plugin. + if (input.entityRef) { + // TEMPLATE NOTE: + // Cross-plugin communication uses service-to-service authentication. The + // `AuthService` lets you generate a token that is valid for communication + // with the target plugin only. You must also provide credentials for the + // identity that you are making the request on behalf of. + // + // If you want to make a request using the plugin backend's own identity, + // you can access it via the `auth.getOwnServiceCredentials()` method. + // Beware that this bypasses any user permission checks. + const { token } = await auth.getPluginRequestToken({ + onBehalfOf: options.credentials, + targetPluginId: 'catalog', + }); + const entity = await catalog.getEntityByRef(input.entityRef, { + token, + }); + if (!entity) { + throw new NotFoundError( + `No entity found for ref '${input.entityRef}'`, + ); + } + + // TEMPLATE NOTE: + // Here you could read any form of data from the entity. A common use case + // is to read the value of a custom annotation for your plugin. You can + // read more about how to add custom annotations here: + // https://backstage.io/docs/features/software-catalog/extending-the-model#adding-a-new-annotation + // + // In this example we just use the entity title to decorate the todo item. + + const entityDisplay = entity.metadata.title ?? input.entityRef; + title = `[${entityDisplay}] ${input.title}`; + } + + const id = crypto.randomUUID(); + const createdBy = options.credentials.principal.userEntityRef; + const newTodo = { + title, + id, + createdBy, + createdAt: new Date().toISOString(), + }; + + storedTodos.push(newTodo); + + // TEMPLATE NOTE: + // The second argument of the logger methods can be used to pass structured metadata + logger.info('Created new todo item', { id, title, createdBy }); + + return newTodo; + }, + + async listTodos() { + return { items: Array.from(storedTodos) }; + }, + + async getTodo(request: { id: string }) { + const todo = storedTodos.find(item => item.id === request.id); + if (!todo) { + throw new NotFoundError(`No todo found with id '${request.id}'`); + } + return todo; + }, + }; +} diff --git a/plugins/modern-backend/src/services/TodoListService/index.ts b/plugins/modern-backend/src/services/TodoListService/index.ts new file mode 100644 index 0000000000..8f2547209b --- /dev/null +++ b/plugins/modern-backend/src/services/TodoListService/index.ts @@ -0,0 +1,17 @@ +/* + * 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. + */ + +export { createTodoListService } from './createTodoListService'; diff --git a/plugins/modern-backend/src/services/TodoListService/types.ts b/plugins/modern-backend/src/services/TodoListService/types.ts new file mode 100644 index 0000000000..07ff7cdc48 --- /dev/null +++ b/plugins/modern-backend/src/services/TodoListService/types.ts @@ -0,0 +1,43 @@ +/* + * 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 { + BackstageCredentials, + BackstageUserPrincipal, +} from '@backstage/backend-plugin-api'; + +export interface TodoItem { + title: string; + id: string; + createdBy: string; + createdAt: string; +} + +export interface TodoListService { + createTodo( + input: { + title: string; + entityRef?: string; + }, + options: { + credentials: BackstageCredentials; + }, + ): Promise; + + listTodos(): Promise<{ items: TodoItem[] }>; + + getTodo(request: { id: string }): Promise; +} diff --git a/plugins/modern-backend/src/setupTests.ts b/plugins/modern-backend/src/setupTests.ts new file mode 100644 index 0000000000..b0f602d2d8 --- /dev/null +++ b/plugins/modern-backend/src/setupTests.ts @@ -0,0 +1,17 @@ +/* + * 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. + */ + +export {};