cli: update backend plugin template

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/mighty-terms-peel.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+The backend plugin template for the `new` command has been updated to provide more guidance and use a more modern structure.

packages/cli/templates/default-backend-plugin/dev/index.ts

@@ -1,9 +0,0 @@
-import { createBackend } from '@backstage/backend-defaults';
-
-const backend = createBackend();
-
-backend.add(import('@backstage/plugin-auth-backend'));
-backend.add(import('@backstage/plugin-auth-backend-module-guest-provider'));
-backend.add(import('../src'));
-
-backend.start();

packages/cli/templates/default-backend-plugin/dev/index.ts.hbs

@@ -0,0 +1,60 @@
+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, standalone or for the sample component:
+//
+//   curl http://localhost:7007/api/{{id}}/todos -H 'Content-Type: application/json' -d '{"title": "My Todo"}'
+//   curl http://localhost:7007/api/{{id}}/todos -H 'Content-Type: application/json' -d '{"title": "My Todo", "entityRef": "component:default/sample"}'
+//
+// List TODOs:
+//
+//   curl http://localhost:7007/api/{{id}}/todos
+//
+// Explicitly make an unauthenticated request, or with service auth:
+//
+//   curl http://localhost:7007/api/{{id}}/todos -H 'Authorization: Bearer mock-none-token'
+//   curl http://localhost:7007/api/{{id}}/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();

packages/cli/templates/default-backend-plugin/package.json.hbs

@@ -30,19 +30,19 @@
   "dependencies": {
     "@backstage/backend-defaults": "{{versionQuery '@backstage/backend-defaults'}}",
     "@backstage/backend-plugin-api": "{{versionQuery '@backstage/backend-plugin-api'}}",
+    "@backstage/catalog-client": "{{versionQuery '@backstage/catalog-client'}}",
+    "@backstage/errors": "{{versionQuery '@backstage/errors'}}",
+    "@backstage/plugin-catalog-node": "{{versionQuery '@backstage/plugin-catalog-node'}}",
     "express": "{{versionQuery 'express' '4.17.1'}}",
     "express-promise-router": "{{versionQuery 'express-promise-router' '4.1.0'}}",
-    "node-fetch": "{{versionQuery 'node-fetch' '2.6.7'}}"
+    "zod": "{{versionQuery 'zod' '3.22.4'}}"
   },
   "devDependencies": {
     "@backstage/backend-test-utils": "{{versionQuery '@backstage/backend-test-utils'}}",
     "@backstage/cli": "{{versionQuery '@backstage/cli'}}",
-    "@backstage/plugin-auth-backend": "{{versionQuery '@backstage/plugin-auth-backend'}}",
-    "@backstage/plugin-auth-backend-module-guest-provider": "{{versionQuery '@backstage/plugin-auth-backend-module-guest-provider'}}",
     "@types/express": "{{versionQuery '@types/express' '4.17.6'}}",
     "@types/supertest": "{{versionQuery '@types/supertest' '2.0.12'}}",
-    "supertest": "{{versionQuery 'supertest' '6.2.4'}}",
-    "msw": "{{versionQuery 'msw' '2.3.1'}}"
+    "supertest": "{{versionQuery 'supertest' '6.2.4'}}"
   },
   "files": [
     "dist"

packages/cli/templates/default-backend-plugin/src/index.ts.hbs

@@ -1,2 +1 @@
-export * from './service/router';
 export { {{pluginVar}} as default } from './plugin';

packages/cli/templates/default-backend-plugin/src/plugin.test.ts.hbs

@@ -0,0 +1,85 @@
+import {
+  mockCredentials,
+  startTestBackend,
+} from '@backstage/backend-test-utils';
+import { {{pluginVar}} } 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: [{{pluginVar}}],
+    });
+
+    await request(server).get('/api/{{id}}/todos').expect(200, {
+      items: [],
+    });
+
+    const createRes = await request(server)
+      .post('/api/{{id}}/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/{{id}}/todos')
+      .expect(200, {
+        items: [createdTodoItem],
+      });
+
+    await request(server)
+      .get(`/api/{{id}}/todos/${createdTodoItem.id}`)
+      .expect(200, createdTodoItem);
+  });
+
+  it('should create TODO item with catalog information', async () => {
+    const { server } = await startTestBackend({
+      features: [
+        {{pluginVar}},
+        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/{{id}}/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),
+    });
+  });
+});

packages/cli/templates/default-backend-plugin/src/plugin.ts.hbs

@@ -2,7 +2,9 @@ import {
   coreServices,
   createBackendPlugin,
 } from '@backstage/backend-plugin-api';
-import { createRouter } from './service/router';
+import { createRouter } from './router';
+import { catalogServiceRef } from '@backstage/plugin-catalog-node/alpha';
+import { createTodoListService } from './services/TodoListService';
 
 /**
  * {{pluginVar}} backend plugin
@@ -14,25 +16,25 @@ export const {{pluginVar}} = createBackendPlugin({
   register(env) {
     env.registerInit({
       deps: {
-        httpRouter: coreServices.httpRouter,
         logger: coreServices.logger,
-        config: coreServices.rootConfig,
+        auth: coreServices.auth,
+        httpAuth: coreServices.httpAuth,
+        httpRouter: coreServices.httpRouter,
+        catalog: catalogServiceRef,
       },
-      async init({
-        httpRouter,
-        logger,
-        config,
-      }) {
+      async init({ logger, auth, httpAuth, httpRouter, catalog }) {
+        const todoListService = await createTodoListService({
+          logger,
+          auth,
+          catalog,
+        });
+
         httpRouter.use(
           await createRouter({
-            logger,
-            config,
+            httpAuth,
+            todoListService,
           }),
         );
-        httpRouter.addAuthPolicy({
-          path: '/health',
-          allow: 'unauthenticated',
-        });
       },
     });
   },

packages/cli/templates/default-backend-plugin/src/router.test.ts

@@ -0,0 +1,67 @@
+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<TodoListService>;
+
+  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(201);
+    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);
+  });
+});

packages/cli/templates/default-backend-plugin/src/router.ts

@@ -0,0 +1,51 @@
+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<express.Router> {
+  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;
+}

packages/cli/templates/default-backend-plugin/src/service/router.test.ts

@@ -1,30 +0,0 @@
-import { mockServices } from '@backstage/backend-test-utils';
-import express from 'express';
-import request from 'supertest';
-
-import { createRouter } from './router';
-
-describe('createRouter', () => {
-  let app: express.Express;
-
-  beforeAll(async () => {
-    const router = await createRouter({
-      logger: mockServices.logger.mock(),
-      config: mockServices.rootConfig(),
-    });
-    app = express().use(router);
-  });
-
-  beforeEach(() => {
-    jest.resetAllMocks();
-  });
-
-  describe('GET /health', () => {
-    it('returns ok', async () => {
-      const response = await request(app).get('/health');
-
-      expect(response.status).toEqual(200);
-      expect(response.body).toEqual({ status: 'ok' });
-    });
-  });
-});

packages/cli/templates/default-backend-plugin/src/service/router.ts

@@ -1,28 +0,0 @@
-import { MiddlewareFactory } from '@backstage/backend-defaults/rootHttpRouter';
-import { LoggerService, RootConfigService } from '@backstage/backend-plugin-api';
-import express from 'express';
-import Router from 'express-promise-router';
-
-export interface RouterOptions {
-  logger: LoggerService;
-  config: RootConfigService;
-}
-
-export async function createRouter(
-  options: RouterOptions,
-): Promise<express.Router> {
-  const { logger, config } = options;
-
-  const router = Router();
-  router.use(express.json());
-
-  router.get('/health', (_, response) => {
-    logger.info('PONG!');
-    response.json({ status: 'ok' });
-  });
-
-  const middleware = MiddlewareFactory.create({ logger, config });
-
-  router.use(middleware.error());
-  return router;
-}

packages/cli/templates/default-backend-plugin/src/services/TodoListService/createTodoListService.ts

@@ -0,0 +1,98 @@
+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<TodoListService> {
+  logger.info('Initializing TodoListService');
+
+  const storedTodos = new Array<TodoItem>();
+
+  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;
+    },
+  };
+}

packages/cli/templates/default-backend-plugin/src/services/TodoListService/index.ts

@@ -0,0 +1 @@
+export { createTodoListService } from './createTodoListService';

packages/cli/templates/default-backend-plugin/src/services/TodoListService/types.ts

@@ -0,0 +1,27 @@
+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<BackstageUserPrincipal>;
+    },
+  ): Promise<TodoItem>;
+
+  listTodos(): Promise<{ items: TodoItem[] }>;
+
+  getTodo(request: { id: string }): Promise<TodoItem>;
+}