Merge pull request #13078 from backstage/jhaals/backend-defaults

Introduce backend-defaults package

.changeset/lazy-students-fetch.md

@@ -0,0 +1,7 @@
+---
+'@backstage/backend-app-api': minor
+'@backstage/backend-defaults': minor
+---
+
+Introduced a new `backend-defaults` package carrying `createBackend` which was previously exported from `backend-app-api`.
+The `backend-app-api` package now exports the `createSpecializedBacked` that does not add any service factories by default.

packages/backend-app-api/api-report.md

@@ -5,6 +5,18 @@
 ```ts
 import { AnyServiceFactory } from '@backstage/backend-plugin-api';
 import { BackendRegistrable } from '@backstage/backend-plugin-api';
+import { Config } from '@backstage/config';
+import { HttpRouterService } from '@backstage/backend-plugin-api';
+import { Logger } from '@backstage/backend-plugin-api';
+import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
+import { PermissionEvaluator } from '@backstage/plugin-permission-common';
+import { PluginCacheManager } from '@backstage/backend-common';
+import { PluginDatabaseManager } from '@backstage/backend-common';
+import { PluginEndpointDiscovery } from '@backstage/backend-common';
+import { PluginTaskScheduler } from '@backstage/backend-tasks';
+import { ServiceFactory } from '@backstage/backend-plugin-api';
+import { TokenManager } from '@backstage/backend-common';
+import { UrlReader } from '@backstage/backend-common';
 
 // @public (undocumented)
 export interface Backend {
@@ -15,11 +27,71 @@ export interface Backend {
 }
 
 // @public (undocumented)
-export function createBackend(options?: CreateBackendOptions): Backend;
+export const cacheFactory: ServiceFactory<
+  PluginCacheManager,
+  PluginCacheManager,
+  {}
+>;
 
 // @public (undocumented)
-export interface CreateBackendOptions {
+export const configFactory: ServiceFactory<Config, Config, {}>;
+
+// @public (undocumented)
+export function createSpecializedBackend(
+  options: CreateSpecializedBackendOptions,
+): Backend;
+
+// @public (undocumented)
+export interface CreateSpecializedBackendOptions {
   // (undocumented)
-  apis: AnyServiceFactory[];
+  services: AnyServiceFactory[];
 }
+
+// @public (undocumented)
+export const databaseFactory: ServiceFactory<
+  PluginDatabaseManager,
+  PluginDatabaseManager,
+  {}
+>;
+
+// @public (undocumented)
+export const discoveryFactory: ServiceFactory<
+  PluginEndpointDiscovery,
+  PluginEndpointDiscovery,
+  {}
+>;
+
+// @public (undocumented)
+export const httpRouterFactory: ServiceFactory<
+  HttpRouterService,
+  HttpRouterService,
+  {}
+>;
+
+// @public (undocumented)
+export const loggerFactory: ServiceFactory<Logger, Logger, {}>;
+
+// @public (undocumented)
+export const permissionsFactory: ServiceFactory<
+  PermissionAuthorizer | PermissionEvaluator,
+  PermissionAuthorizer | PermissionEvaluator,
+  {}
+>;
+
+// @public (undocumented)
+export const schedulerFactory: ServiceFactory<
+  PluginTaskScheduler,
+  PluginTaskScheduler,
+  {}
+>;
+
+// @public (undocumented)
+export const tokenManagerFactory: ServiceFactory<
+  TokenManager,
+  TokenManager,
+  {}
+>;
+
+// @public (undocumented)
+export const urlReaderFactory: ServiceFactory<UrlReader, UrlReader, {}>;
 ```

packages/backend-app-api/src/index.ts

@@ -21,3 +21,4 @@
  */
 
 export * from './wiring';
+export * from './services/implementations';

packages/backend-app-api/src/services/implementations/cacheService.ts

@@ -21,7 +21,7 @@ import {
   cacheServiceRef,
 } from '@backstage/backend-plugin-api';
 
-// TODO: Work out some naming and implementation patterns for these
+/** @public */
 export const cacheFactory = createServiceFactory({
   service: cacheServiceRef,
   deps: {

packages/backend-app-api/src/services/implementations/configService.ts

@@ -22,6 +22,7 @@ import {
   loggerServiceRef,
 } from '@backstage/backend-plugin-api';
 
+/** @public */
 export const configFactory = createServiceFactory({
   service: configServiceRef,
   deps: {

packages/backend-app-api/src/services/implementations/databaseService.ts

@@ -21,6 +21,7 @@ import {
   databaseServiceRef,
 } from '@backstage/backend-plugin-api';
 
+/** @public */
 export const databaseFactory = createServiceFactory({
   service: databaseServiceRef,
   deps: {

packages/backend-app-api/src/services/implementations/discoveryService.ts

@@ -21,6 +21,7 @@ import {
   discoveryServiceRef,
 } from '@backstage/backend-plugin-api';
 
+/** @public */
 export const discoveryFactory = createServiceFactory({
   service: discoveryServiceRef,
   deps: {

packages/backend-app-api/src/services/implementations/httpRouterService.ts

@@ -23,6 +23,7 @@ import Router from 'express-promise-router';
 import { Handler } from 'express';
 import { createServiceBuilder } from '@backstage/backend-common';
 
+/** @public */
 export const httpRouterFactory = createServiceFactory({
   service: httpRouterServiceRef,
   deps: {

packages/backend-app-api/src/services/implementations/index.ts

@@ -14,26 +14,13 @@
  * limitations under the License.
  */
 
-import { cacheFactory } from './cacheService';
-import { configFactory } from './configService';
-import { databaseFactory } from './databaseService';
-import { discoveryFactory } from './discoveryService';
-import { loggerFactory } from './loggerService';
-import { permissionsFactory } from './permissionsService';
-import { schedulerFactory } from './schedulerService';
-import { tokenManagerFactory } from './tokenManagerService';
-import { urlReaderFactory } from './urlReaderService';
-import { httpRouterFactory } from './httpRouterService';
-
-export const defaultServiceFactories = [
-  cacheFactory,
-  configFactory,
-  databaseFactory,
-  discoveryFactory,
-  loggerFactory,
-  permissionsFactory,
-  schedulerFactory,
-  tokenManagerFactory,
-  urlReaderFactory,
-  httpRouterFactory,
-];
+export { cacheFactory } from './cacheService';
+export { configFactory } from './configService';
+export { databaseFactory } from './databaseService';
+export { discoveryFactory } from './discoveryService';
+export { loggerFactory } from './loggerService';
+export { permissionsFactory } from './permissionsService';
+export { schedulerFactory } from './schedulerService';
+export { tokenManagerFactory } from './tokenManagerService';
+export { urlReaderFactory } from './urlReaderService';
+export { httpRouterFactory } from './httpRouterService';

packages/backend-app-api/src/services/implementations/loggerService.ts

@@ -38,6 +38,7 @@ class BackstageLogger implements Logger {
   }
 }
 
+/** @public */
 export const loggerFactory = createServiceFactory({
   service: loggerServiceRef,
   deps: {},

packages/backend-app-api/src/services/implementations/permissionsService.ts

@@ -23,6 +23,7 @@ import {
 } from '@backstage/backend-plugin-api';
 import { ServerPermissionClient } from '@backstage/plugin-permission-node';
 
+/** @public */
 export const permissionsFactory = createServiceFactory({
   service: permissionsServiceRef,
   deps: {

packages/backend-app-api/src/services/implementations/schedulerService.ts

@@ -21,6 +21,7 @@ import {
 } from '@backstage/backend-plugin-api';
 import { TaskScheduler } from '@backstage/backend-tasks';
 
+/** @public */
 export const schedulerFactory = createServiceFactory({
   service: schedulerServiceRef,
   deps: {

packages/backend-app-api/src/services/implementations/tokenManagerService.ts

@@ -23,6 +23,7 @@ import {
 } from '@backstage/backend-plugin-api';
 import { ServerTokenManager } from '@backstage/backend-common';
 
+/** @public */
 export const tokenManagerFactory = createServiceFactory({
   service: tokenManagerServiceRef,
   deps: {

packages/backend-app-api/src/services/implementations/urlReaderService.ts

@@ -23,6 +23,7 @@ import {
   urlReaderServiceRef,
 } from '@backstage/backend-plugin-api';
 
+/** @public */
 export const urlReaderFactory = createServiceFactory({
   service: urlReaderServiceRef,
   deps: {

packages/backend-app-api/src/wiring/index.ts

@@ -14,5 +14,5 @@
  * limitations under the License.
  */
 
-export type { Backend, CreateBackendOptions } from './types';
-export { createBackend } from './types';
+export type { Backend, CreateSpecializedBackendOptions } from './types';
+export { createSpecializedBackend } from './types';

packages/backend-app-api/src/wiring/types.ts

@@ -20,7 +20,6 @@ import {
   FactoryFunc,
   ServiceRef,
 } from '@backstage/backend-plugin-api';
-import { defaultServiceFactories } from '../services/implementations';
 import { BackstageBackend } from './BackstageBackend';
 
 /**
@@ -42,8 +41,8 @@ export interface BackendRegisterInit {
 /**
  * @public
  */
-export interface CreateBackendOptions {
-  apis: AnyServiceFactory[];
+export interface CreateSpecializedBackendOptions {
+  services: AnyServiceFactory[];
 }
 
 export type ServiceHolder = {
@@ -53,10 +52,8 @@ export type ServiceHolder = {
 /**
  * @public
  */
-export function createBackend(options?: CreateBackendOptions): Backend {
-  // TODO: merge with provided APIs
-  return new BackstageBackend([
-    ...defaultServiceFactories,
-    ...(options?.apis ?? []),
-  ]);
+export function createSpecializedBackend(
+  options: CreateSpecializedBackendOptions,
+): Backend {
+  return new BackstageBackend(options.services);
 }

packages/backend-defaults/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

packages/backend-defaults/README.md

@@ -0,0 +1,19 @@
+# @backstage/backend-defaults
+
+**This package is HIGHLY EXPERIMENTAL, do not use this for production**
+
+This package provides the core API used by Backstage backend apps.
+
+## Installation
+
+Add the library to your backend app package:
+
+```bash
+# From your Backstage root directory
+yarn add --cwd packages/backend @backstage/backend-defaults
+```
+
+## Documentation
+
+- [Backstage Readme](https://github.com/backstage/backstage/blob/master/README.md)
+- [Backstage Documentation](https://github.com/backstage/backstage/blob/master/docs/README.md)

packages/backend-defaults/api-report.md

@@ -0,0 +1,17 @@
+## API Report File for "@backstage/backend-defaults"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { AnyServiceFactory } from '@backstage/backend-plugin-api';
+import { Backend } from '@backstage/backend-app-api';
+
+// @public (undocumented)
+export function createBackend(options?: CreateBackendOptions): Backend;
+
+// @public (undocumented)
+export interface CreateBackendOptions {
+  // (undocumented)
+  services?: AnyServiceFactory[];
+}
+```

packages/backend-defaults/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@backstage/backend-defaults",
+  "description": "Backend defaults used by Backstage backend apps",
+  "version": "0.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "node-library"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "packages/backend-defaults"
+  },
+  "keywords": [
+    "backstage"
+  ],
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack",
+    "clean": "backstage-cli package clean",
+    "start": "backstage-cli package start"
+  },
+  "dependencies": {
+    "@backstage/backend-app-api": "^0.1.1-next.0",
+    "@backstage/backend-plugin-api": "^0.1.1-next.0"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.18.1-next.0"
+  },
+  "files": [
+    "dist"
+  ]
+}

packages/backend-defaults/src/CreateBackend.ts

@@ -0,0 +1,62 @@
+/*
+ * 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 {
+  Backend,
+  cacheFactory,
+  configFactory,
+  createSpecializedBackend,
+  databaseFactory,
+  discoveryFactory,
+  httpRouterFactory,
+  loggerFactory,
+  permissionsFactory,
+  schedulerFactory,
+  tokenManagerFactory,
+  urlReaderFactory,
+} from '@backstage/backend-app-api';
+
+export const defaultServiceFactories = [
+  cacheFactory,
+  configFactory,
+  databaseFactory,
+  discoveryFactory,
+  loggerFactory,
+  permissionsFactory,
+  schedulerFactory,
+  tokenManagerFactory,
+  urlReaderFactory,
+  httpRouterFactory,
+];
+
+import { AnyServiceFactory } from '@backstage/backend-plugin-api';
+
+/**
+ * @public
+ */
+export interface CreateBackendOptions {
+  services?: AnyServiceFactory[];
+}
+
+/**
+ * @public
+ */
+export function createBackend(options?: CreateBackendOptions): Backend {
+  // TODO: merge with provided APIs
+  return createSpecializedBackend({
+    services: [...defaultServiceFactories, ...(options?.services || [])],
+  });
+}

packages/backend-defaults/src/index.ts

@@ -0,0 +1,24 @@
+/*
+ * 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.
+ */
+
+/**
+ * Backend defaults used by Backstage backend apps
+ *
+ * @packageDocumentation
+ */
+
+export type { CreateBackendOptions } from './CreateBackend';
+export { createBackend } from './CreateBackend';

packages/backend-next/package.json

@@ -25,7 +25,7 @@
     "clean": "backstage-cli package clean"
   },
   "dependencies": {
-    "@backstage/backend-app-api": "^0.1.1-next.0",
+    "@backstage/backend-defaults": "^0.0.0",
     "@backstage/plugin-catalog-backend": "^1.3.1-next.0",
     "@backstage/plugin-scaffolder-backend": "^1.5.0-next.0"
   },

packages/backend-next/src/index.ts

@@ -14,13 +14,11 @@
  * limitations under the License.
  */
 
-import { createBackend } from '@backstage/backend-app-api';
 import { catalogPlugin } from '@backstage/plugin-catalog-backend';
 import { scaffolderCatalogModule } from '@backstage/plugin-scaffolder-backend';
+import { createBackend } from '@backstage/backend-defaults';
 
-const backend = createBackend({
-  apis: [],
-});
+const backend = createBackend();
 
 backend.add(catalogPlugin({}));
 backend.add(scaffolderCatalogModule({}));