From 6f1f2e94510c38cdb1b74d61928e78b781bb5b9b Mon Sep 17 00:00:00 2001 From: blam Date: Tue, 7 Feb 2023 13:28:02 +0100 Subject: [PATCH] chore: updating docs Signed-off-by: blam --- docs/backend-system/architecture/03-services.md | 16 ++++++++-------- .../architecture/07-naming-patterns.md | 14 +++++++------- .../backend-system/building-backends/01-index.md | 8 ++++---- docs/backend-system/core-services/01-index.md | 16 ++++++++-------- 4 files changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/backend-system/architecture/03-services.md b/docs/backend-system/architecture/03-services.md index d202c21740..875cb3aaea 100644 --- a/docs/backend-system/architecture/03-services.md +++ b/docs/backend-system/architecture/03-services.md @@ -61,7 +61,7 @@ class DefaultFooService implements FooService { } } -export const fooFactory = createServiceFactory({ +export const fooServiceFactory = createServiceFactory({ service: fooServiceRef, deps: { bar: barServiceRef }, factory({ bar }) { @@ -75,7 +75,7 @@ To create a service factory we need to provide a reference to the `service` for If you need the creation of the service instance to be asynchronous, you can make the `factory` function async. For example: ```ts -export const fooFactory = createServiceFactory({ +export const fooServiceFactory = createServiceFactory({ service: fooServiceRef, deps: {}, async factory() { @@ -94,18 +94,18 @@ To install a service factory in a backend instance, we pass it in through the `s ```ts const backend = createBackend({ - services: [fooFactory()], + services: [fooServiceFactory()], }); ``` -Note that we call `fooFactory` to create the service factory instance. This is because `createServiceFactory` always returns a factory function that creates the actual service factory. This is done to always allow for options to be added to the service factory in the future, without breaking existing code. To add options to your service factory, you wrap the object passed to `createServiceFactory` in a callback that accepts the desired options. For example: +Note that we call `fooServiceFactory` to create the service factory instance. This is because `createServiceFactory` always returns a factory function that creates the actual service factory. This is done to always allow for options to be added to the service factory in the future, without breaking existing code. To add options to your service factory, you wrap the object passed to `createServiceFactory` in a callback that accepts the desired options. For example: ```ts export interface FooFactoryOptions { mode: 'eager' | 'lazy'; } -export const fooFactory = createServiceFactory( +export const fooServiceFactory = createServiceFactory( (options?: FooFactoryOptions) => ({ service: fooServiceRef, deps: { bar: barServiceRef }, @@ -120,7 +120,7 @@ This lets us use the options to customize the factory implementation in any way ```ts const backend = createBackend({ - services: [fooFactory({ mode: 'eager' })], + services: [fooServiceFactory({ mode: 'eager' })], }); ``` @@ -164,7 +164,7 @@ Plugin scoped services have access to a plugin metadata service, which is a spec The plugin metadata service is the base for all plugin specific customizations for services. For example, the default implementation of the plugin scoped logger service uses the plugin metadata service to attach the plugin ID as a field in all log messages: ```ts -export const loggerFactory = createServiceFactory({ +export const loggerServiceFactory = createServiceFactory({ service: coreServices.logger, deps: { rootLogger: coreServices.rootLogger, @@ -183,7 +183,7 @@ Some services may benefit from having a context that is shared across all instan The root context is defined as part of the service factory by passing the `createRootContext` option: ```ts -export const fooFactory = createServiceFactory({ +export const fooServiceFactory = createServiceFactory({ service: fooServiceRef, deps: { rootLogger: coreServices.rootLogger, bar: barServiceRef }, createRootContext({ rootLogger }) { diff --git a/docs/backend-system/architecture/07-naming-patterns.md b/docs/backend-system/architecture/07-naming-patterns.md index b4b4c6c70f..b62e049f08 100644 --- a/docs/backend-system/architecture/07-naming-patterns.md +++ b/docs/backend-system/architecture/07-naming-patterns.md @@ -66,12 +66,12 @@ export const catalogProcessingExtensionPoint = createExtensionPointService` | `LoggerService`, `DatabaseService` | -| Reference | `ServiceRef` | `loggerServiceRef`, `databaseServiceRef` | -| ID | `.` | `'core.rootHttpRouter'`, `'catalog.catalogClient'` | -| Factory | `Factory` | `loggerFactory`, `databaseFactory` | +| Description | Pattern | Examples | +| ----------- | ---------------------- | -------------------------------------------------- | +| Interface | `Service` | `LoggerService`, `DatabaseService` | +| Reference | `ServiceRef` | `loggerServiceRef`, `databaseServiceRef` | +| ID | `.` | `'core.rootHttpRouter'`, `'catalog.catalogClient'` | +| Factory | `ServiceFactory` | `loggerServiceFactory`, `databaseServiceFactory` | Example: @@ -85,7 +85,7 @@ export const catalogClientServiceRef = createServiceRef({ ... }) -export const catalogClientFactory = createServiceFactory({ +export const catalogClientServiceFactory = createServiceFactory({ service: catalogClientServiceRef, ... }) diff --git a/docs/backend-system/building-backends/01-index.md b/docs/backend-system/building-backends/01-index.md index de01c6d39c..bda2aa7eaa 100644 --- a/docs/backend-system/building-backends/01-index.md +++ b/docs/backend-system/building-backends/01-index.md @@ -61,11 +61,11 @@ All of these services can be replaced with your own implementations if you need For example, let's say we want to customize the core configuration service to enable remote configuration loading. That would look something like this: ```ts -import { configFactory } from '@backstage/backend-app-api'; +import { configServiceFactory } from '@backstage/backend-app-api'; const backend = createBackend({ services: [ - configFactory({ + configServiceFactory({ remote: { reloadIntervalSeconds: 60 }, }), ], @@ -160,11 +160,11 @@ A shared environment is defined using `createSharedEnvironment`. In this example ```ts // packages/backend-env/src/index.ts import { createSharedEnvironment } from '@backstage/backend-plugin-api'; -import { customDiscoveryFactory } from './customDiscoveryFactory'; +import { customDiscoveryServiceFactory } from './customDiscoveryServiceFactory'; export const env = createSharedEnvironment({ services: [ - customDiscoveryFactory(), // custom DiscoveryService implementation + customDiscoveryServiceFactory(), // custom DiscoveryService implementation ], }); ``` diff --git a/docs/backend-system/core-services/01-index.md b/docs/backend-system/core-services/01-index.md index 5128a95cb3..b6682c2708 100644 --- a/docs/backend-system/core-services/01-index.md +++ b/docs/backend-system/core-services/01-index.md @@ -59,11 +59,11 @@ There's additional configuration that you can optionally pass to setup the `http You can configure these additional options by adding an override for the core service when calling `createBackend` like follows: ```ts -import { httpRouterFactory } from '@backstage/backend-app-api'; +import { httpRouterServiceFactory } from '@backstage/backend-app-api'; const backend = createBackend({ services: [ - httpRouterFactory({ + httpRouterServiceFactory({ getPath: (pluginId: string) => `/plugins/${pluginId}`, }), ], @@ -116,11 +116,11 @@ There's additional options that you can pass to configure the root HTTP Router s You can configure the root HTTP Router service by passing the options to the `createBackend` function. ```ts -import { rootHttpRouterFactory } from '@backstage/backend-app-api'; +import { rootHttpRouterServiceFactory } from '@backstage/backend-app-api'; const backend = createBackend({ services: [ - rootHttpRouterFactory({ + rootHttpRouterServiceFactory({ configure: ({ app, middleware, routes, config, logger, lifecycle }) => { // the built in middleware is provided through an option in the configure function app.use(middleware.helmet()); @@ -183,11 +183,11 @@ There's additional configuration that you can optionally pass to setup the `conf You can configure these additional options by adding an override for the core service when calling `createBackend` like follows: ```ts -import { configFactory } from '@backstage/backend-app-api'; +import { configServiceFactory } from '@backstage/backend-app-api'; const backend = createBackend({ services: [ - configFactory({ + configServiceFactory({ argv: [ '--config', '/backstage/app-config.development.yaml', @@ -438,11 +438,11 @@ There's additional configuration that you can optionally pass to setup the `iden You can configure these additional options by adding an override for the core service when calling `createBackend` like follows: ```ts -import { identityFactory } from '@backstage/backend-app-api'; +import { identityServiceFactory } from '@backstage/backend-app-api'; const backend = createBackend({ services: [ - identityFactory({ + identityServiceFactory({ issuer: 'backstage', algorithms: ['ES256', 'RS256'], }),