@backstage/backend-plugin-api 0.6.19-next.1 → 0.6.19-next.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @backstage/backend-plugin-api
 
+## 0.6.19-next.2
+
+### Patch Changes
+
+- 3aa3fc7: Marked the `TokenManagerService` and `IdentityService` types as deprecated
+- Updated dependencies
+  - @backstage/plugin-auth-node@0.4.14-next.2
+  - @backstage/cli-common@0.1.13
+  - @backstage/config@1.2.0
+  - @backstage/errors@1.2.4
+  - @backstage/types@1.1.1
+  - @backstage/plugin-permission-common@0.7.13
+
 ## 0.6.19-next.1
 
 ### Patch Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-plugin-api",
-  "version": "0.6.19-next.1",
+  "version": "0.6.19-next.2",
   "main": "../dist/alpha.cjs.js",
   "types": "../dist/alpha.d.ts"
 }

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":["../src/services/system/types.ts","../src/services/definitions/coreServices.ts","../src/services/definitions/SchedulerService.ts","../src/services/utilities/database.ts","../src/wiring/factories.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { BackendFeature } from '../../types';\n\n/**\n * TODO\n *\n * @public\n */\nexport type ServiceRef<\n  TService,\n  TScope extends 'root' | 'plugin' = 'root' | 'plugin',\n> = {\n  id: string;\n\n  /**\n   * This determines the scope at which this service is available.\n   *\n   * Root scoped services are available to all other services but\n   * may only depend on other root scoped services.\n   *\n   * Plugin scoped services are only available to other plugin scoped\n   * services but may depend on all other services.\n   */\n  scope: TScope;\n\n  /**\n   * Utility for getting the type of the service, using `typeof serviceRef.T`.\n   * Attempting to actually read this value will result in an exception.\n   */\n  T: TService;\n\n  $$type: '@backstage/ServiceRef';\n};\n\n/** @public */\nexport interface ServiceFactory<\n  TService = unknown,\n  TScope extends 'plugin' | 'root' = 'plugin' | 'root',\n> extends BackendFeature {\n  service: ServiceRef<TService, TScope>;\n}\n\n/** @internal */\nexport interface InternalServiceFactory<\n  TService = unknown,\n  TScope extends 'plugin' | 'root' = 'plugin' | 'root',\n> extends ServiceFactory<TService, TScope> {\n  version: 'v1';\n  initialization?: 'always' | 'lazy';\n  deps: { [key in string]: ServiceRef<unknown> };\n  createRootContext?(deps: { [key in string]: unknown }): Promise<unknown>;\n  factory(\n    deps: { [key in string]: unknown },\n    context: unknown,\n  ): Promise<TService>;\n}\n\n/**\n * Represents either a {@link ServiceFactory} or a function that returns one.\n *\n * @public\n */\nexport type ServiceFactoryOrFunction = ServiceFactory | (() => ServiceFactory);\n\n/** @public */\nexport interface ServiceRefConfig<TService, TScope extends 'root' | 'plugin'> {\n  id: string;\n  scope?: TScope;\n  defaultFactory?: (\n    service: ServiceRef<TService, TScope>,\n  ) => Promise<ServiceFactoryOrFunction>;\n}\n\n/**\n * Creates a new service definition. This overload is used to create plugin scoped services.\n *\n * @public\n */\nexport function createServiceRef<TService>(\n  config: ServiceRefConfig<TService, 'plugin'>,\n): ServiceRef<TService, 'plugin'>;\n\n/**\n * Creates a new service definition. This overload is used to create root scoped services.\n *\n * @public\n */\nexport function createServiceRef<TService>(\n  config: ServiceRefConfig<TService, 'root'>,\n): ServiceRef<TService, 'root'>;\nexport function createServiceRef<TService>(\n  config: ServiceRefConfig<TService, any>,\n): ServiceRef<TService, any> {\n  const { id, scope = 'plugin', defaultFactory } = config;\n  return {\n    id,\n    scope,\n    get T(): TService {\n      throw new Error(`tried to read ServiceRef.T of ${this}`);\n    },\n    toString() {\n      return `serviceRef{${config.id}}`;\n    },\n    $$type: '@backstage/ServiceRef',\n    __defaultFactory: defaultFactory,\n  } as ServiceRef<TService, typeof scope> & {\n    __defaultFactory?: (\n      service: ServiceRef<TService>,\n    ) => Promise<ServiceFactory<TService> | (() => ServiceFactory<TService>)>;\n  };\n}\n\n/** @ignore */\ntype ServiceRefsToInstances<\n  T extends { [key in string]: ServiceRef<unknown> },\n  TScope extends 'root' | 'plugin' = 'root' | 'plugin',\n> = {\n  [key in keyof T as T[key]['scope'] extends TScope ? key : never]: T[key]['T'];\n};\n\n/** @public */\nexport interface RootServiceFactoryConfig<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n> {\n  /**\n   * The initialization strategy for the service factory. This service is root scoped and will use `always` by default.\n   *\n   * @remarks\n   *\n   * - `always` - The service will always be initialized regardless if it is used or not.\n   * - `lazy` - The service will only be initialized if it is depended on by a different service or feature.\n   *\n   * Service factories for root scoped services use `always` as the default, while plugin scoped services use `lazy`.\n   */\n  initialization?: 'always' | 'lazy';\n  service: ServiceRef<TService, 'root'>;\n  deps: TDeps;\n  factory(deps: ServiceRefsToInstances<TDeps, 'root'>): TImpl | Promise<TImpl>;\n}\n\n/** @public */\nexport interface PluginServiceFactoryConfig<\n  TService,\n  TContext,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n> {\n  /**\n   * The initialization strategy for the service factory. This service is plugin scoped and will use `lazy` by default.\n   *\n   * @remarks\n   *\n   * - `always` - The service will always be initialized regardless if it is used or not.\n   * - `lazy` - The service will only be initialized if it is depended on by a different service or feature.\n   *\n   * Service factories for root scoped services use `always` as the default, while plugin scoped services use `lazy`.\n   */\n  initialization?: 'always' | 'lazy';\n  service: ServiceRef<TService, 'plugin'>;\n  deps: TDeps;\n  createRootContext?(\n    deps: ServiceRefsToInstances<TDeps, 'root'>,\n  ): TContext | Promise<TContext>;\n  factory(\n    deps: ServiceRefsToInstances<TDeps>,\n    context: TContext,\n  ): TImpl | Promise<TImpl>;\n}\n\n/**\n * Creates a root scoped service factory without options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown, 'root'> },\n  TOpts extends object | undefined = undefined,\n>(\n  config: RootServiceFactoryConfig<TService, TImpl, TDeps>,\n): () => ServiceFactory<TService, 'root'>;\n/**\n * Creates a root scoped service factory with optional options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown, 'root'> },\n  TOpts extends object | undefined = undefined,\n>(\n  config: (options?: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>,\n): (options?: TOpts) => ServiceFactory<TService, 'root'>;\n/**\n * Creates a plugin scoped service factory without options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext = undefined,\n  TOpts extends object | undefined = undefined,\n>(\n  config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,\n): () => ServiceFactory<TService, 'plugin'>;\n/**\n * Creates a plugin scoped service factory with optional options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext = undefined,\n  TOpts extends object | undefined = undefined,\n>(\n  config: (\n    options?: TOpts,\n  ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,\n): (options?: TOpts) => ServiceFactory<TService, 'plugin'>;\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext,\n  TOpts extends object | undefined = undefined,\n>(\n  config:\n    | RootServiceFactoryConfig<TService, TImpl, TDeps>\n    | PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>\n    | ((options: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>)\n    | ((\n        options: TOpts,\n      ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>)\n    | (() => RootServiceFactoryConfig<TService, TImpl, TDeps>)\n    | (() => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>),\n): (options: TOpts) => ServiceFactory {\n  const configCallback = typeof config === 'function' ? config : () => config;\n  const factory = (\n    options: TOpts,\n  ): InternalServiceFactory<TService, 'plugin' | 'root'> => {\n    const anyConf = configCallback(options);\n    if (anyConf.service.scope === 'root') {\n      const c = anyConf as RootServiceFactoryConfig<TService, TImpl, TDeps>;\n      return {\n        $$type: '@backstage/BackendFeature',\n        version: 'v1',\n        service: c.service,\n        initialization: c.initialization,\n        deps: c.deps,\n        factory: async (deps: TDeps) => c.factory(deps),\n      };\n    }\n    const c = anyConf as PluginServiceFactoryConfig<\n      TService,\n      TContext,\n      TImpl,\n      TDeps\n    >;\n    return {\n      $$type: '@backstage/BackendFeature',\n      version: 'v1',\n      service: c.service,\n      initialization: c.initialization,\n      ...('createRootContext' in c\n        ? {\n            createRootContext: async (deps: TDeps) =>\n              c?.createRootContext?.(deps),\n          }\n        : {}),\n      deps: c.deps,\n      factory: async (deps: TDeps, ctx: TContext) => c.factory(deps, ctx),\n    };\n  };\n\n  factory.$$type = '@backstage/BackendFeatureFactory';\n\n  return factory;\n}\n","/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createServiceRef } from '../system';\n\n/**\n * All core services references\n *\n * @public\n */\nexport namespace coreServices {\n  /**\n   * The service reference for the plugin scoped {@link AuthService}.\n   *\n   * @public\n   */\n  export const auth = createServiceRef<import('./AuthService').AuthService>({\n    id: 'core.auth',\n  });\n\n  /**\n   * The service reference for the plugin scoped {@link UserInfoService}.\n   *\n   * @public\n   */\n  export const userInfo = createServiceRef<\n    import('./UserInfoService').UserInfoService\n  >({\n    id: 'core.userInfo',\n  });\n\n  /**\n   * The service reference for the plugin scoped {@link CacheService}.\n   *\n   * @public\n   */\n  export const cache = createServiceRef<import('./CacheService').CacheService>({\n    id: 'core.cache',\n  });\n\n  /**\n   * The service reference for the root scoped {@link RootConfigService}.\n   *\n   * @public\n   */\n  export const rootConfig = createServiceRef<\n    import('./RootConfigService').RootConfigService\n  >({ id: 'core.rootConfig', scope: 'root' });\n\n  /**\n   * The service reference for the plugin scoped {@link DatabaseService}.\n   *\n   * @public\n   */\n  export const database = createServiceRef<\n    import('./DatabaseService').DatabaseService\n  >({ id: 'core.database' });\n\n  /**\n   * The service reference for the plugin scoped {@link DiscoveryService}.\n   *\n   * @public\n   */\n  export const discovery = createServiceRef<\n    import('./DiscoveryService').DiscoveryService\n  >({ id: 'core.discovery' });\n\n  /**\n   * The service reference for the plugin scoped {@link HttpAuthService}.\n   *\n   * @public\n   */\n  export const httpAuth = createServiceRef<\n    import('./HttpAuthService').HttpAuthService\n  >({ id: 'core.httpAuth' });\n\n  /**\n   * The service reference for the plugin scoped {@link HttpRouterService}.\n   *\n   * @public\n   */\n  export const httpRouter = createServiceRef<\n    import('./HttpRouterService').HttpRouterService\n  >({ id: 'core.httpRouter' });\n\n  /**\n   * The service reference for the plugin scoped {@link LifecycleService}.\n   *\n   * @public\n   */\n  export const lifecycle = createServiceRef<\n    import('./LifecycleService').LifecycleService\n  >({ id: 'core.lifecycle' });\n\n  /**\n   * The service reference for the plugin scoped {@link LoggerService}.\n   *\n   * @public\n   */\n  export const logger = createServiceRef<\n    import('./LoggerService').LoggerService\n  >({ id: 'core.logger' });\n\n  /**\n   * The service reference for the plugin scoped {@link PermissionsService}.\n   *\n   * @public\n   */\n  export const permissions = createServiceRef<\n    import('./PermissionsService').PermissionsService\n  >({ id: 'core.permissions' });\n\n  /**\n   * The service reference for the plugin scoped {@link PluginMetadataService}.\n   *\n   * @public\n   */\n  export const pluginMetadata = createServiceRef<\n    import('./PluginMetadataService').PluginMetadataService\n  >({ id: 'core.pluginMetadata' });\n\n  /**\n   * The service reference for the root scoped {@link RootHttpRouterService}.\n   *\n   * @public\n   */\n  export const rootHttpRouter = createServiceRef<\n    import('./RootHttpRouterService').RootHttpRouterService\n  >({ id: 'core.rootHttpRouter', scope: 'root' });\n\n  /**\n   * The service reference for the root scoped {@link RootLifecycleService}.\n   *\n   * @public\n   */\n  export const rootLifecycle = createServiceRef<\n    import('./RootLifecycleService').RootLifecycleService\n  >({ id: 'core.rootLifecycle', scope: 'root' });\n\n  /**\n   * The service reference for the root scoped {@link RootLoggerService}.\n   *\n   * @public\n   */\n  export const rootLogger = createServiceRef<\n    import('./RootLoggerService').RootLoggerService\n  >({ id: 'core.rootLogger', scope: 'root' });\n\n  /**\n   * The service reference for the plugin scoped {@link SchedulerService}.\n   *\n   * @public\n   */\n  export const scheduler = createServiceRef<\n    import('./SchedulerService').SchedulerService\n  >({ id: 'core.scheduler' });\n\n  /**\n   * The service reference for the plugin scoped {@link TokenManagerService}.\n   *\n   * @public\n   * @deprecated Please migrate to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead\n   */\n  export const tokenManager = createServiceRef<\n    import('./TokenManagerService').TokenManagerService\n  >({ id: 'core.tokenManager' });\n\n  /**\n   * The service reference for the plugin scoped {@link UrlReaderService}.\n   *\n   * @public\n   */\n  export const urlReader = createServiceRef<\n    import('./UrlReaderService').UrlReaderService\n  >({ id: 'core.urlReader' });\n\n  /**\n   * The service reference for the plugin scoped {@link IdentityService}.\n   *\n   * @public\n   * @deprecated Please migrate to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead\n   */\n  export const identity = createServiceRef<\n    import('./IdentityService').IdentityService\n  >({ id: 'core.identity' });\n}\n","/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config, readDurationFromConfig } from '@backstage/config';\nimport { HumanDuration, JsonObject } from '@backstage/types';\nimport { Duration } from 'luxon';\n\n/**\n * A function that can be called as a scheduled task.\n *\n * It may optionally accept an abort signal argument. When the signal triggers,\n * processing should abort and return as quickly as possible.\n *\n * @public\n */\nexport type SchedulerServiceTaskFunction =\n  | ((abortSignal: AbortSignal) => void | Promise<void>)\n  | (() => void | Promise<void>);\n\n/**\n * A semi-opaque type to describe an actively scheduled task.\n *\n * @public\n */\nexport type SchedulerServiceTaskDescriptor = {\n  /**\n   * The unique identifier of the task.\n   */\n  id: string;\n  /**\n   * The scope of the task.\n   */\n  scope: 'global' | 'local';\n  /**\n   * The settings that control the task flow. This is a semi-opaque structure\n   * that is mainly there for debugging purposes. Do not make any assumptions\n   * about the contents of this field.\n   */\n  settings: { version: number } & JsonObject;\n};\n\n/**\n * Options that control the scheduling of a task.\n *\n * @public\n */\nexport interface SchedulerServiceTaskScheduleDefinition {\n  /**\n   * How often you want the task to run. The system does its best to avoid\n   * overlapping invocations.\n   *\n   * @remarks\n   *\n   * This is the best effort value; under some circumstances there can be\n   * deviations. For example, if the task runtime is longer than the frequency\n   * and the timeout has not been given or not been exceeded yet, the next\n   * invocation of this task will be delayed until after the previous one\n   * finishes.\n   *\n   * This is a required field.\n   */\n  frequency:\n    | {\n        /**\n         * A crontab style string.\n         *\n         * @remarks\n         *\n         * Overview:\n         *\n         * ```\n         *   ┌────────────── second (optional)\n         *   │ ┌──────────── minute\n         *   │ │ ┌────────── hour\n         *   │ │ │ ┌──────── day of month\n         *   │ │ │ │ ┌────── month\n         *   │ │ │ │ │ ┌──── day of week\n         *   │ │ │ │ │ │\n         *   │ │ │ │ │ │\n         *   * * * * * *\n         * ```\n         */\n        cron: string;\n      }\n    | Duration\n    | HumanDuration;\n\n  /**\n   * The maximum amount of time that a single task invocation can take, before\n   * it's considered timed out and gets \"released\" such that a new invocation\n   * is permitted to take place (possibly, then, on a different worker).\n   */\n  timeout: Duration | HumanDuration;\n\n  /**\n   * The amount of time that should pass before the first invocation happens.\n   *\n   * @remarks\n   *\n   * This can be useful in cold start scenarios to stagger or delay some heavy\n   * compute jobs. If no value is given for this field then the first invocation\n   * will happen as soon as possible according to the cadence.\n   *\n   * NOTE: This is a per-worker delay. If you have a cluster of workers all\n   * collaborating on a task that has its `scope` field set to `'global'`, then\n   * you may still see the task being processed by other long-lived workers,\n   * while any given single worker is in its initial sleep delay time e.g. after\n   * a deployment. Therefore, this parameter is not useful for \"globally\" pausing\n   * work; its main intended use is for individual machines to get a chance to\n   * reach some equilibrium at startup before triggering heavy batch workloads.\n   */\n  initialDelay?: Duration | HumanDuration;\n\n  /**\n   * Sets the scope of concurrency control / locking to apply for invocations of\n   * this task.\n   *\n   * @remarks\n   *\n   * When the scope is set to the default value `'global'`, the scheduler will\n   * attempt to ensure that only one worker machine runs the task at a time,\n   * according to the given cadence. This means that as the number of worker\n   * hosts increases, the invocation frequency of this task will not go up.\n   * Instead, the load is spread randomly across hosts. This setting is useful\n   * for tasks that access shared resources, for example catalog ingestion tasks\n   * where you do not want many machines to repeatedly import the same data and\n   * trample over each other.\n   *\n   * When the scope is set to `'local'`, there is no concurrency control across\n   * hosts. Each host runs the task according to the given cadence similarly to\n   * `setInterval`, but the runtime ensures that there are no overlapping runs.\n   *\n   * @defaultValue 'global'\n   */\n  scope?: 'global' | 'local';\n}\n\n/**\n * Config options for {@link SchedulerServiceTaskScheduleDefinition}\n * that control the scheduling of a task.\n *\n * @public\n */\nexport interface SchedulerServiceTaskScheduleDefinitionConfig {\n  /**\n   * How often you want the task to run. The system does its best to avoid\n   * overlapping invocations.\n   *\n   * @remarks\n   *\n   * This is the best effort value; under some circumstances there can be\n   * deviations. For example, if the task runtime is longer than the frequency\n   * and the timeout has not been given or not been exceeded yet, the next\n   * invocation of this task will be delayed until after the previous one\n   * finishes.\n   *\n   * This is a required field.\n   */\n  frequency:\n    | {\n        /**\n         * A crontab style string.\n         *\n         * @remarks\n         *\n         * Overview:\n         *\n         * ```\n         *   ┌────────────── second (optional)\n         *   │ ┌──────────── minute\n         *   │ │ ┌────────── hour\n         *   │ │ │ ┌──────── day of month\n         *   │ │ │ │ ┌────── month\n         *   │ │ │ │ │ ┌──── day of week\n         *   │ │ │ │ │ │\n         *   │ │ │ │ │ │\n         *   * * * * * *\n         * ```\n         */\n        cron: string;\n      }\n    | string\n    | HumanDuration;\n\n  /**\n   * The maximum amount of time that a single task invocation can take, before\n   * it's considered timed out and gets \"released\" such that a new invocation\n   * is permitted to take place (possibly, then, on a different worker).\n   */\n  timeout: string | HumanDuration;\n\n  /**\n   * The amount of time that should pass before the first invocation happens.\n   *\n   * @remarks\n   *\n   * This can be useful in cold start scenarios to stagger or delay some heavy\n   * compute jobs. If no value is given for this field then the first invocation\n   * will happen as soon as possible according to the cadence.\n   *\n   * NOTE: This is a per-worker delay. If you have a cluster of workers all\n   * collaborating on a task that has its `scope` field set to `'global'`, then\n   * you may still see the task being processed by other long-lived workers,\n   * while any given single worker is in its initial sleep delay time e.g. after\n   * a deployment. Therefore, this parameter is not useful for \"globally\" pausing\n   * work; its main intended use is for individual machines to get a chance to\n   * reach some equilibrium at startup before triggering heavy batch workloads.\n   */\n  initialDelay?: string | HumanDuration;\n\n  /**\n   * Sets the scope of concurrency control / locking to apply for invocations of\n   * this task.\n   *\n   * @remarks\n   *\n   * When the scope is set to the default value `'global'`, the scheduler will\n   * attempt to ensure that only one worker machine runs the task at a time,\n   * according to the given cadence. This means that as the number of worker\n   * hosts increases, the invocation frequency of this task will not go up.\n   * Instead, the load is spread randomly across hosts. This setting is useful\n   * for tasks that access shared resources, for example catalog ingestion tasks\n   * where you do not want many machines to repeatedly import the same data and\n   * trample over each other.\n   *\n   * When the scope is set to `'local'`, there is no concurrency control across\n   * hosts. Each host runs the task according to the given cadence similarly to\n   * `setInterval`, but the runtime ensures that there are no overlapping runs.\n   *\n   * @defaultValue 'global'\n   */\n  scope?: 'global' | 'local';\n}\n\n/**\n * Options that apply to the invocation of a given task.\n *\n * @public\n */\nexport interface SchedulerServiceTaskInvocationDefinition {\n  /**\n   * A unique ID (within the scope of the plugin) for the task.\n   */\n  id: string;\n\n  /**\n   * The actual task function to be invoked regularly.\n   */\n  fn: SchedulerServiceTaskFunction;\n\n  /**\n   * An abort signal that, when triggered, will stop the recurring execution of\n   * the task.\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * A previously prepared task schedule, ready to be invoked.\n *\n * @public\n */\nexport interface SchedulerServiceTaskRunner {\n  /**\n   * Takes the schedule and executes an actual task using it.\n   *\n   * @param task - The actual runtime properties of the task\n   */\n  run(task: SchedulerServiceTaskInvocationDefinition): Promise<void>;\n}\n\n/**\n * Deals with the scheduling of distributed tasks, for a given plugin.\n *\n * @public\n */\nexport interface SchedulerService {\n  /**\n   * Manually triggers a task by ID.\n   *\n   * If the task doesn't exist, a NotFoundError is thrown. If the task is\n   * currently running, a ConflictError is thrown.\n   *\n   * @param id - The task ID\n   */\n  triggerTask(id: string): Promise<void>;\n\n  /**\n   * Schedules a task function for recurring runs.\n   *\n   * @remarks\n   *\n   * The `scope` task field controls whether to use coordinated exclusive\n   * invocation across workers, or to just coordinate within the current worker.\n   *\n   * This convenience method performs both the scheduling and invocation in one\n   * go.\n   *\n   * @param task - The task definition\n   */\n  scheduleTask(\n    task: SchedulerServiceTaskScheduleDefinition &\n      SchedulerServiceTaskInvocationDefinition,\n  ): Promise<void>;\n\n  /**\n   * Creates a scheduled but dormant recurring task, ready to be launched at a\n   * later time.\n   *\n   * @remarks\n   *\n   * This method is useful for pre-creating a schedule in outer code to be\n   * passed into an inner implementation, such that the outer code controls\n   * scheduling while inner code controls implementation.\n   *\n   * @param schedule - The task schedule\n   */\n  createScheduledTaskRunner(\n    schedule: SchedulerServiceTaskScheduleDefinition,\n  ): SchedulerServiceTaskRunner;\n\n  /**\n   * Returns all scheduled tasks registered to this scheduler.\n   *\n   * @remarks\n   *\n   * This method is useful for triggering tasks manually using the triggerTask\n   * functionality. Note that the returned tasks contain only tasks that have\n   * been initialized in this instance of the scheduler.\n   *\n   * @returns Scheduled tasks\n   */\n  getScheduledTasks(): Promise<SchedulerServiceTaskDescriptor[]>;\n}\n\nfunction readDuration(config: Config, key: string): Duration | HumanDuration {\n  if (typeof config.get(key) === 'string') {\n    const value = config.getString(key);\n    const duration = Duration.fromISO(value);\n    if (!duration.isValid) {\n      throw new Error(`Invalid duration: ${value}`);\n    }\n    return duration;\n  }\n\n  return readDurationFromConfig(config, { key });\n}\n\nfunction readCronOrDuration(\n  config: Config,\n  key: string,\n): { cron: string } | Duration | HumanDuration {\n  const value = config.get(key);\n  if (typeof value === 'object' && (value as { cron?: string }).cron) {\n    return value as { cron: string };\n  }\n\n  return readDuration(config, key);\n}\n\n/**\n * Reads a {@link SchedulerServiceTaskScheduleDefinition} from config. Expects\n * the config not to be the root config, but the config for the definition.\n *\n * @param config - config for a TaskScheduleDefinition.\n * @public\n */\nexport function readSchedulerServiceTaskScheduleDefinitionFromConfig(\n  config: Config,\n): SchedulerServiceTaskScheduleDefinition {\n  const frequency = readCronOrDuration(config, 'frequency');\n  const timeout = readDuration(config, 'timeout');\n\n  const initialDelay = config.has('initialDelay')\n    ? readDuration(config, 'initialDelay')\n    : undefined;\n\n  const scope = config.getOptionalString('scope');\n  if (scope && !['global', 'local'].includes(scope)) {\n    throw new Error(\n      `Only \"global\" or \"local\" are allowed for TaskScheduleDefinition.scope, but got: ${scope}`,\n    );\n  }\n\n  return {\n    frequency,\n    timeout,\n    initialDelay,\n    scope: scope as 'global' | 'local' | undefined,\n  };\n}\n","/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Tries to deduce whether a thrown error is a database conflict.\n *\n * @public\n * @param e - A thrown error\n * @returns True if the error looks like it was a conflict error thrown by a\n *          known database engine\n */\nexport function isDatabaseConflictError(e: unknown) {\n  const message = (e as any)?.message;\n\n  return (\n    typeof message === 'string' &&\n    (/SQLITE_CONSTRAINT(?:_UNIQUE)?: UNIQUE/.test(message) ||\n      /UNIQUE constraint failed:/.test(message) ||\n      /unique constraint/.test(message) ||\n      /Duplicate entry/.test(message)) // MySQL uniqueness error msg\n  );\n}\n","/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { BackendFeature, BackendFeatureFactory } from '../types';\nimport {\n  BackendModuleRegistrationPoints,\n  BackendPluginRegistrationPoints,\n  ExtensionPoint,\n  InternalBackendModuleRegistration,\n  InternalBackendPluginRegistration,\n} from './types';\n\n/**\n * The configuration options passed to {@link createExtensionPoint}.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport interface CreateExtensionPointOptions {\n  /**\n   * The ID of this extension point.\n   *\n   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n   */\n  id: string;\n}\n\n/**\n * Creates a new backend extension point.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}\n */\nexport function createExtensionPoint<T>(\n  options: CreateExtensionPointOptions,\n): ExtensionPoint<T> {\n  return {\n    id: options.id,\n    get T(): T {\n      throw new Error(`tried to read ExtensionPoint.T of ${this}`);\n    },\n    toString() {\n      return `extensionPoint{${options.id}}`;\n    },\n    $$type: '@backstage/ExtensionPoint',\n  };\n}\n\n/**\n * The configuration options passed to {@link createBackendPlugin}.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport interface CreateBackendPluginOptions {\n  /**\n   * The ID of this plugin.\n   *\n   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n   */\n  pluginId: string;\n  register(reg: BackendPluginRegistrationPoints): void;\n}\n\n/**\n * Creates a new backend plugin.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport function createBackendPlugin(\n  options: CreateBackendPluginOptions,\n): () => BackendFeature {\n  const factory: BackendFeatureFactory = () => {\n    let registrations: InternalBackendPluginRegistration[];\n\n    return {\n      $$type: '@backstage/BackendFeature',\n      version: 'v1',\n      getRegistrations() {\n        if (registrations) {\n          return registrations;\n        }\n        const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =\n          [];\n        let init: InternalBackendPluginRegistration['init'] | undefined =\n          undefined;\n\n        options.register({\n          registerExtensionPoint(ext, impl) {\n            if (init) {\n              throw new Error(\n                'registerExtensionPoint called after registerInit',\n              );\n            }\n            extensionPoints.push([ext, impl]);\n          },\n          registerInit(regInit) {\n            if (init) {\n              throw new Error('registerInit must only be called once');\n            }\n            init = {\n              deps: regInit.deps,\n              func: regInit.init,\n            };\n          },\n        });\n\n        if (!init) {\n          throw new Error(\n            `registerInit was not called by register in ${options.pluginId}`,\n          );\n        }\n\n        registrations = [\n          {\n            type: 'plugin',\n            pluginId: options.pluginId,\n            extensionPoints,\n            init,\n          },\n        ];\n        return registrations;\n      },\n    };\n  };\n  factory.$$type = '@backstage/BackendFeatureFactory';\n\n  return factory;\n}\n\n/**\n * The configuration options passed to {@link createBackendModule}.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport interface CreateBackendModuleOptions {\n  /**\n   * Should exactly match the `id` of the plugin that the module extends.\n   *\n   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n   */\n  pluginId: string;\n\n  /**\n   * The ID of this module, used to identify the module and ensure that it is not installed twice.\n   */\n  moduleId: string;\n  register(reg: BackendModuleRegistrationPoints): void;\n}\n\n/**\n * Creates a new backend module for a given plugin.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport function createBackendModule(\n  options: CreateBackendModuleOptions,\n): () => BackendFeature {\n  const factory: BackendFeatureFactory = () => {\n    let registrations: InternalBackendModuleRegistration[];\n\n    return {\n      $$type: '@backstage/BackendFeature',\n      version: 'v1',\n      getRegistrations() {\n        if (registrations) {\n          return registrations;\n        }\n        const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =\n          [];\n        let init: InternalBackendModuleRegistration['init'] | undefined =\n          undefined;\n\n        options.register({\n          registerExtensionPoint(ext, impl) {\n            if (init) {\n              throw new Error(\n                'registerExtensionPoint called after registerInit',\n              );\n            }\n            extensionPoints.push([ext, impl]);\n          },\n          registerInit(regInit) {\n            if (init) {\n              throw new Error('registerInit must only be called once');\n            }\n            init = {\n              deps: regInit.deps,\n              func: regInit.init,\n            };\n          },\n        });\n\n        if (!init) {\n          throw new Error(\n            `registerInit was not called by register in ${options.moduleId} module for ${options.pluginId}`,\n          );\n        }\n\n        registrations = [\n          {\n            type: 'module',\n            pluginId: options.pluginId,\n            moduleId: options.moduleId,\n            extensionPoints,\n            init,\n          },\n        ];\n        return registrations;\n      },\n    };\n  };\n  factory.$$type = '@backstage/BackendFeatureFactory';\n\n  return factory;\n}\n"],"names":["c","coreServices","config","Duration","readDurationFromConfig"],"mappings":"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"}
+{"version":3,"file":"index.cjs.js","sources":["../src/services/system/types.ts","../src/services/definitions/coreServices.ts","../src/services/definitions/SchedulerService.ts","../src/services/utilities/database.ts","../src/wiring/factories.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { BackendFeature } from '../../types';\n\n/**\n * TODO\n *\n * @public\n */\nexport type ServiceRef<\n  TService,\n  TScope extends 'root' | 'plugin' = 'root' | 'plugin',\n> = {\n  id: string;\n\n  /**\n   * This determines the scope at which this service is available.\n   *\n   * Root scoped services are available to all other services but\n   * may only depend on other root scoped services.\n   *\n   * Plugin scoped services are only available to other plugin scoped\n   * services but may depend on all other services.\n   */\n  scope: TScope;\n\n  /**\n   * Utility for getting the type of the service, using `typeof serviceRef.T`.\n   * Attempting to actually read this value will result in an exception.\n   */\n  T: TService;\n\n  $$type: '@backstage/ServiceRef';\n};\n\n/** @public */\nexport interface ServiceFactory<\n  TService = unknown,\n  TScope extends 'plugin' | 'root' = 'plugin' | 'root',\n> extends BackendFeature {\n  service: ServiceRef<TService, TScope>;\n}\n\n/** @internal */\nexport interface InternalServiceFactory<\n  TService = unknown,\n  TScope extends 'plugin' | 'root' = 'plugin' | 'root',\n> extends ServiceFactory<TService, TScope> {\n  version: 'v1';\n  initialization?: 'always' | 'lazy';\n  deps: { [key in string]: ServiceRef<unknown> };\n  createRootContext?(deps: { [key in string]: unknown }): Promise<unknown>;\n  factory(\n    deps: { [key in string]: unknown },\n    context: unknown,\n  ): Promise<TService>;\n}\n\n/**\n * Represents either a {@link ServiceFactory} or a function that returns one.\n *\n * @public\n */\nexport type ServiceFactoryOrFunction = ServiceFactory | (() => ServiceFactory);\n\n/** @public */\nexport interface ServiceRefConfig<TService, TScope extends 'root' | 'plugin'> {\n  id: string;\n  scope?: TScope;\n  defaultFactory?: (\n    service: ServiceRef<TService, TScope>,\n  ) => Promise<ServiceFactoryOrFunction>;\n}\n\n/**\n * Creates a new service definition. This overload is used to create plugin scoped services.\n *\n * @public\n */\nexport function createServiceRef<TService>(\n  config: ServiceRefConfig<TService, 'plugin'>,\n): ServiceRef<TService, 'plugin'>;\n\n/**\n * Creates a new service definition. This overload is used to create root scoped services.\n *\n * @public\n */\nexport function createServiceRef<TService>(\n  config: ServiceRefConfig<TService, 'root'>,\n): ServiceRef<TService, 'root'>;\nexport function createServiceRef<TService>(\n  config: ServiceRefConfig<TService, any>,\n): ServiceRef<TService, any> {\n  const { id, scope = 'plugin', defaultFactory } = config;\n  return {\n    id,\n    scope,\n    get T(): TService {\n      throw new Error(`tried to read ServiceRef.T of ${this}`);\n    },\n    toString() {\n      return `serviceRef{${config.id}}`;\n    },\n    $$type: '@backstage/ServiceRef',\n    __defaultFactory: defaultFactory,\n  } as ServiceRef<TService, typeof scope> & {\n    __defaultFactory?: (\n      service: ServiceRef<TService>,\n    ) => Promise<ServiceFactory<TService> | (() => ServiceFactory<TService>)>;\n  };\n}\n\n/** @ignore */\ntype ServiceRefsToInstances<\n  T extends { [key in string]: ServiceRef<unknown> },\n  TScope extends 'root' | 'plugin' = 'root' | 'plugin',\n> = {\n  [key in keyof T as T[key]['scope'] extends TScope ? key : never]: T[key]['T'];\n};\n\n/** @public */\nexport interface RootServiceFactoryConfig<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n> {\n  /**\n   * The initialization strategy for the service factory. This service is root scoped and will use `always` by default.\n   *\n   * @remarks\n   *\n   * - `always` - The service will always be initialized regardless if it is used or not.\n   * - `lazy` - The service will only be initialized if it is depended on by a different service or feature.\n   *\n   * Service factories for root scoped services use `always` as the default, while plugin scoped services use `lazy`.\n   */\n  initialization?: 'always' | 'lazy';\n  service: ServiceRef<TService, 'root'>;\n  deps: TDeps;\n  factory(deps: ServiceRefsToInstances<TDeps, 'root'>): TImpl | Promise<TImpl>;\n}\n\n/** @public */\nexport interface PluginServiceFactoryConfig<\n  TService,\n  TContext,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n> {\n  /**\n   * The initialization strategy for the service factory. This service is plugin scoped and will use `lazy` by default.\n   *\n   * @remarks\n   *\n   * - `always` - The service will always be initialized regardless if it is used or not.\n   * - `lazy` - The service will only be initialized if it is depended on by a different service or feature.\n   *\n   * Service factories for root scoped services use `always` as the default, while plugin scoped services use `lazy`.\n   */\n  initialization?: 'always' | 'lazy';\n  service: ServiceRef<TService, 'plugin'>;\n  deps: TDeps;\n  createRootContext?(\n    deps: ServiceRefsToInstances<TDeps, 'root'>,\n  ): TContext | Promise<TContext>;\n  factory(\n    deps: ServiceRefsToInstances<TDeps>,\n    context: TContext,\n  ): TImpl | Promise<TImpl>;\n}\n\n/**\n * Creates a root scoped service factory without options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown, 'root'> },\n  TOpts extends object | undefined = undefined,\n>(\n  config: RootServiceFactoryConfig<TService, TImpl, TDeps>,\n): () => ServiceFactory<TService, 'root'>;\n/**\n * Creates a root scoped service factory with optional options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown, 'root'> },\n  TOpts extends object | undefined = undefined,\n>(\n  config: (options?: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>,\n): (options?: TOpts) => ServiceFactory<TService, 'root'>;\n/**\n * Creates a plugin scoped service factory without options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext = undefined,\n  TOpts extends object | undefined = undefined,\n>(\n  config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,\n): () => ServiceFactory<TService, 'plugin'>;\n/**\n * Creates a plugin scoped service factory with optional options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext = undefined,\n  TOpts extends object | undefined = undefined,\n>(\n  config: (\n    options?: TOpts,\n  ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,\n): (options?: TOpts) => ServiceFactory<TService, 'plugin'>;\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext,\n  TOpts extends object | undefined = undefined,\n>(\n  config:\n    | RootServiceFactoryConfig<TService, TImpl, TDeps>\n    | PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>\n    | ((options: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>)\n    | ((\n        options: TOpts,\n      ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>)\n    | (() => RootServiceFactoryConfig<TService, TImpl, TDeps>)\n    | (() => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>),\n): (options: TOpts) => ServiceFactory {\n  const configCallback = typeof config === 'function' ? config : () => config;\n  const factory = (\n    options: TOpts,\n  ): InternalServiceFactory<TService, 'plugin' | 'root'> => {\n    const anyConf = configCallback(options);\n    if (anyConf.service.scope === 'root') {\n      const c = anyConf as RootServiceFactoryConfig<TService, TImpl, TDeps>;\n      return {\n        $$type: '@backstage/BackendFeature',\n        version: 'v1',\n        service: c.service,\n        initialization: c.initialization,\n        deps: c.deps,\n        factory: async (deps: TDeps) => c.factory(deps),\n      };\n    }\n    const c = anyConf as PluginServiceFactoryConfig<\n      TService,\n      TContext,\n      TImpl,\n      TDeps\n    >;\n    return {\n      $$type: '@backstage/BackendFeature',\n      version: 'v1',\n      service: c.service,\n      initialization: c.initialization,\n      ...('createRootContext' in c\n        ? {\n            createRootContext: async (deps: TDeps) =>\n              c?.createRootContext?.(deps),\n          }\n        : {}),\n      deps: c.deps,\n      factory: async (deps: TDeps, ctx: TContext) => c.factory(deps, ctx),\n    };\n  };\n\n  factory.$$type = '@backstage/BackendFeatureFactory';\n\n  return factory;\n}\n","/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createServiceRef } from '../system';\n\n/**\n * All core services references\n *\n * @public\n */\nexport namespace coreServices {\n  /**\n   * The service reference for the plugin scoped {@link AuthService}.\n   *\n   * @public\n   */\n  export const auth = createServiceRef<import('./AuthService').AuthService>({\n    id: 'core.auth',\n  });\n\n  /**\n   * The service reference for the plugin scoped {@link UserInfoService}.\n   *\n   * @public\n   */\n  export const userInfo = createServiceRef<\n    import('./UserInfoService').UserInfoService\n  >({\n    id: 'core.userInfo',\n  });\n\n  /**\n   * The service reference for the plugin scoped {@link CacheService}.\n   *\n   * @public\n   */\n  export const cache = createServiceRef<import('./CacheService').CacheService>({\n    id: 'core.cache',\n  });\n\n  /**\n   * The service reference for the root scoped {@link RootConfigService}.\n   *\n   * @public\n   */\n  export const rootConfig = createServiceRef<\n    import('./RootConfigService').RootConfigService\n  >({ id: 'core.rootConfig', scope: 'root' });\n\n  /**\n   * The service reference for the plugin scoped {@link DatabaseService}.\n   *\n   * @public\n   */\n  export const database = createServiceRef<\n    import('./DatabaseService').DatabaseService\n  >({ id: 'core.database' });\n\n  /**\n   * The service reference for the plugin scoped {@link DiscoveryService}.\n   *\n   * @public\n   */\n  export const discovery = createServiceRef<\n    import('./DiscoveryService').DiscoveryService\n  >({ id: 'core.discovery' });\n\n  /**\n   * The service reference for the plugin scoped {@link HttpAuthService}.\n   *\n   * @public\n   */\n  export const httpAuth = createServiceRef<\n    import('./HttpAuthService').HttpAuthService\n  >({ id: 'core.httpAuth' });\n\n  /**\n   * The service reference for the plugin scoped {@link HttpRouterService}.\n   *\n   * @public\n   */\n  export const httpRouter = createServiceRef<\n    import('./HttpRouterService').HttpRouterService\n  >({ id: 'core.httpRouter' });\n\n  /**\n   * The service reference for the plugin scoped {@link LifecycleService}.\n   *\n   * @public\n   */\n  export const lifecycle = createServiceRef<\n    import('./LifecycleService').LifecycleService\n  >({ id: 'core.lifecycle' });\n\n  /**\n   * The service reference for the plugin scoped {@link LoggerService}.\n   *\n   * @public\n   */\n  export const logger = createServiceRef<\n    import('./LoggerService').LoggerService\n  >({ id: 'core.logger' });\n\n  /**\n   * The service reference for the plugin scoped {@link PermissionsService}.\n   *\n   * @public\n   */\n  export const permissions = createServiceRef<\n    import('./PermissionsService').PermissionsService\n  >({ id: 'core.permissions' });\n\n  /**\n   * The service reference for the plugin scoped {@link PluginMetadataService}.\n   *\n   * @public\n   */\n  export const pluginMetadata = createServiceRef<\n    import('./PluginMetadataService').PluginMetadataService\n  >({ id: 'core.pluginMetadata' });\n\n  /**\n   * The service reference for the root scoped {@link RootHttpRouterService}.\n   *\n   * @public\n   */\n  export const rootHttpRouter = createServiceRef<\n    import('./RootHttpRouterService').RootHttpRouterService\n  >({ id: 'core.rootHttpRouter', scope: 'root' });\n\n  /**\n   * The service reference for the root scoped {@link RootLifecycleService}.\n   *\n   * @public\n   */\n  export const rootLifecycle = createServiceRef<\n    import('./RootLifecycleService').RootLifecycleService\n  >({ id: 'core.rootLifecycle', scope: 'root' });\n\n  /**\n   * The service reference for the root scoped {@link RootLoggerService}.\n   *\n   * @public\n   */\n  export const rootLogger = createServiceRef<\n    import('./RootLoggerService').RootLoggerService\n  >({ id: 'core.rootLogger', scope: 'root' });\n\n  /**\n   * The service reference for the plugin scoped {@link SchedulerService}.\n   *\n   * @public\n   */\n  export const scheduler = createServiceRef<\n    import('./SchedulerService').SchedulerService\n  >({ id: 'core.scheduler' });\n\n  /**\n   * The service reference for the plugin scoped {@link TokenManagerService}.\n   *\n   * @public\n   * @deprecated Please migrate to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead\n   */\n  export const tokenManager = createServiceRef<\n    import('./TokenManagerService').TokenManagerService\n  >({ id: 'core.tokenManager' });\n\n  /**\n   * The service reference for the plugin scoped {@link UrlReaderService}.\n   *\n   * @public\n   */\n  export const urlReader = createServiceRef<\n    import('./UrlReaderService').UrlReaderService\n  >({ id: 'core.urlReader' });\n\n  /**\n   * The service reference for the plugin scoped {@link IdentityService}.\n   *\n   * @public\n   * @deprecated Please migrate to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead\n   */\n  export const identity = createServiceRef<\n    import('./IdentityService').IdentityService\n  >({ id: 'core.identity' });\n}\n","/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config, readDurationFromConfig } from '@backstage/config';\nimport { HumanDuration, JsonObject } from '@backstage/types';\nimport { Duration } from 'luxon';\n\n/**\n * A function that can be called as a scheduled task.\n *\n * It may optionally accept an abort signal argument. When the signal triggers,\n * processing should abort and return as quickly as possible.\n *\n * @public\n */\nexport type SchedulerServiceTaskFunction =\n  | ((abortSignal: AbortSignal) => void | Promise<void>)\n  | (() => void | Promise<void>);\n\n/**\n * A semi-opaque type to describe an actively scheduled task.\n *\n * @public\n */\nexport type SchedulerServiceTaskDescriptor = {\n  /**\n   * The unique identifier of the task.\n   */\n  id: string;\n  /**\n   * The scope of the task.\n   */\n  scope: 'global' | 'local';\n  /**\n   * The settings that control the task flow. This is a semi-opaque structure\n   * that is mainly there for debugging purposes. Do not make any assumptions\n   * about the contents of this field.\n   */\n  settings: { version: number } & JsonObject;\n};\n\n/**\n * Options that control the scheduling of a task.\n *\n * @public\n */\nexport interface SchedulerServiceTaskScheduleDefinition {\n  /**\n   * How often you want the task to run. The system does its best to avoid\n   * overlapping invocations.\n   *\n   * @remarks\n   *\n   * This is the best effort value; under some circumstances there can be\n   * deviations. For example, if the task runtime is longer than the frequency\n   * and the timeout has not been given or not been exceeded yet, the next\n   * invocation of this task will be delayed until after the previous one\n   * finishes.\n   *\n   * This is a required field.\n   */\n  frequency:\n    | {\n        /**\n         * A crontab style string.\n         *\n         * @remarks\n         *\n         * Overview:\n         *\n         * ```\n         *   ┌────────────── second (optional)\n         *   │ ┌──────────── minute\n         *   │ │ ┌────────── hour\n         *   │ │ │ ┌──────── day of month\n         *   │ │ │ │ ┌────── month\n         *   │ │ │ │ │ ┌──── day of week\n         *   │ │ │ │ │ │\n         *   │ │ │ │ │ │\n         *   * * * * * *\n         * ```\n         */\n        cron: string;\n      }\n    | Duration\n    | HumanDuration;\n\n  /**\n   * The maximum amount of time that a single task invocation can take, before\n   * it's considered timed out and gets \"released\" such that a new invocation\n   * is permitted to take place (possibly, then, on a different worker).\n   */\n  timeout: Duration | HumanDuration;\n\n  /**\n   * The amount of time that should pass before the first invocation happens.\n   *\n   * @remarks\n   *\n   * This can be useful in cold start scenarios to stagger or delay some heavy\n   * compute jobs. If no value is given for this field then the first invocation\n   * will happen as soon as possible according to the cadence.\n   *\n   * NOTE: This is a per-worker delay. If you have a cluster of workers all\n   * collaborating on a task that has its `scope` field set to `'global'`, then\n   * you may still see the task being processed by other long-lived workers,\n   * while any given single worker is in its initial sleep delay time e.g. after\n   * a deployment. Therefore, this parameter is not useful for \"globally\" pausing\n   * work; its main intended use is for individual machines to get a chance to\n   * reach some equilibrium at startup before triggering heavy batch workloads.\n   */\n  initialDelay?: Duration | HumanDuration;\n\n  /**\n   * Sets the scope of concurrency control / locking to apply for invocations of\n   * this task.\n   *\n   * @remarks\n   *\n   * When the scope is set to the default value `'global'`, the scheduler will\n   * attempt to ensure that only one worker machine runs the task at a time,\n   * according to the given cadence. This means that as the number of worker\n   * hosts increases, the invocation frequency of this task will not go up.\n   * Instead, the load is spread randomly across hosts. This setting is useful\n   * for tasks that access shared resources, for example catalog ingestion tasks\n   * where you do not want many machines to repeatedly import the same data and\n   * trample over each other.\n   *\n   * When the scope is set to `'local'`, there is no concurrency control across\n   * hosts. Each host runs the task according to the given cadence similarly to\n   * `setInterval`, but the runtime ensures that there are no overlapping runs.\n   *\n   * @defaultValue 'global'\n   */\n  scope?: 'global' | 'local';\n}\n\n/**\n * Config options for {@link SchedulerServiceTaskScheduleDefinition}\n * that control the scheduling of a task.\n *\n * @public\n */\nexport interface SchedulerServiceTaskScheduleDefinitionConfig {\n  /**\n   * How often you want the task to run. The system does its best to avoid\n   * overlapping invocations.\n   *\n   * @remarks\n   *\n   * This is the best effort value; under some circumstances there can be\n   * deviations. For example, if the task runtime is longer than the frequency\n   * and the timeout has not been given or not been exceeded yet, the next\n   * invocation of this task will be delayed until after the previous one\n   * finishes.\n   *\n   * This is a required field.\n   */\n  frequency:\n    | {\n        /**\n         * A crontab style string.\n         *\n         * @remarks\n         *\n         * Overview:\n         *\n         * ```\n         *   ┌────────────── second (optional)\n         *   │ ┌──────────── minute\n         *   │ │ ┌────────── hour\n         *   │ │ │ ┌──────── day of month\n         *   │ │ │ │ ┌────── month\n         *   │ │ │ │ │ ┌──── day of week\n         *   │ │ │ │ │ │\n         *   │ │ │ │ │ │\n         *   * * * * * *\n         * ```\n         */\n        cron: string;\n      }\n    | string\n    | HumanDuration;\n\n  /**\n   * The maximum amount of time that a single task invocation can take, before\n   * it's considered timed out and gets \"released\" such that a new invocation\n   * is permitted to take place (possibly, then, on a different worker).\n   */\n  timeout: string | HumanDuration;\n\n  /**\n   * The amount of time that should pass before the first invocation happens.\n   *\n   * @remarks\n   *\n   * This can be useful in cold start scenarios to stagger or delay some heavy\n   * compute jobs. If no value is given for this field then the first invocation\n   * will happen as soon as possible according to the cadence.\n   *\n   * NOTE: This is a per-worker delay. If you have a cluster of workers all\n   * collaborating on a task that has its `scope` field set to `'global'`, then\n   * you may still see the task being processed by other long-lived workers,\n   * while any given single worker is in its initial sleep delay time e.g. after\n   * a deployment. Therefore, this parameter is not useful for \"globally\" pausing\n   * work; its main intended use is for individual machines to get a chance to\n   * reach some equilibrium at startup before triggering heavy batch workloads.\n   */\n  initialDelay?: string | HumanDuration;\n\n  /**\n   * Sets the scope of concurrency control / locking to apply for invocations of\n   * this task.\n   *\n   * @remarks\n   *\n   * When the scope is set to the default value `'global'`, the scheduler will\n   * attempt to ensure that only one worker machine runs the task at a time,\n   * according to the given cadence. This means that as the number of worker\n   * hosts increases, the invocation frequency of this task will not go up.\n   * Instead, the load is spread randomly across hosts. This setting is useful\n   * for tasks that access shared resources, for example catalog ingestion tasks\n   * where you do not want many machines to repeatedly import the same data and\n   * trample over each other.\n   *\n   * When the scope is set to `'local'`, there is no concurrency control across\n   * hosts. Each host runs the task according to the given cadence similarly to\n   * `setInterval`, but the runtime ensures that there are no overlapping runs.\n   *\n   * @defaultValue 'global'\n   */\n  scope?: 'global' | 'local';\n}\n\n/**\n * Options that apply to the invocation of a given task.\n *\n * @public\n */\nexport interface SchedulerServiceTaskInvocationDefinition {\n  /**\n   * A unique ID (within the scope of the plugin) for the task.\n   */\n  id: string;\n\n  /**\n   * The actual task function to be invoked regularly.\n   */\n  fn: SchedulerServiceTaskFunction;\n\n  /**\n   * An abort signal that, when triggered, will stop the recurring execution of\n   * the task.\n   */\n  signal?: AbortSignal;\n}\n\n/**\n * A previously prepared task schedule, ready to be invoked.\n *\n * @public\n */\nexport interface SchedulerServiceTaskRunner {\n  /**\n   * Takes the schedule and executes an actual task using it.\n   *\n   * @param task - The actual runtime properties of the task\n   */\n  run(task: SchedulerServiceTaskInvocationDefinition): Promise<void>;\n}\n\n/**\n * Deals with the scheduling of distributed tasks, for a given plugin.\n *\n * See the {@link https://backstage.io/docs/backend-system/core-services/scheduler | service documentation} for more details.\n *\n * @public\n */\nexport interface SchedulerService {\n  /**\n   * Manually triggers a task by ID.\n   *\n   * If the task doesn't exist, a NotFoundError is thrown. If the task is\n   * currently running, a ConflictError is thrown.\n   *\n   * @param id - The task ID\n   */\n  triggerTask(id: string): Promise<void>;\n\n  /**\n   * Schedules a task function for recurring runs.\n   *\n   * @remarks\n   *\n   * The `scope` task field controls whether to use coordinated exclusive\n   * invocation across workers, or to just coordinate within the current worker.\n   *\n   * This convenience method performs both the scheduling and invocation in one\n   * go.\n   *\n   * @param task - The task definition\n   */\n  scheduleTask(\n    task: SchedulerServiceTaskScheduleDefinition &\n      SchedulerServiceTaskInvocationDefinition,\n  ): Promise<void>;\n\n  /**\n   * Creates a scheduled but dormant recurring task, ready to be launched at a\n   * later time.\n   *\n   * @remarks\n   *\n   * This method is useful for pre-creating a schedule in outer code to be\n   * passed into an inner implementation, such that the outer code controls\n   * scheduling while inner code controls implementation.\n   *\n   * @param schedule - The task schedule\n   */\n  createScheduledTaskRunner(\n    schedule: SchedulerServiceTaskScheduleDefinition,\n  ): SchedulerServiceTaskRunner;\n\n  /**\n   * Returns all scheduled tasks registered to this scheduler.\n   *\n   * @remarks\n   *\n   * This method is useful for triggering tasks manually using the triggerTask\n   * functionality. Note that the returned tasks contain only tasks that have\n   * been initialized in this instance of the scheduler.\n   *\n   * @returns Scheduled tasks\n   */\n  getScheduledTasks(): Promise<SchedulerServiceTaskDescriptor[]>;\n}\n\nfunction readDuration(config: Config, key: string): Duration | HumanDuration {\n  if (typeof config.get(key) === 'string') {\n    const value = config.getString(key);\n    const duration = Duration.fromISO(value);\n    if (!duration.isValid) {\n      throw new Error(`Invalid duration: ${value}`);\n    }\n    return duration;\n  }\n\n  return readDurationFromConfig(config, { key });\n}\n\nfunction readCronOrDuration(\n  config: Config,\n  key: string,\n): { cron: string } | Duration | HumanDuration {\n  const value = config.get(key);\n  if (typeof value === 'object' && (value as { cron?: string }).cron) {\n    return value as { cron: string };\n  }\n\n  return readDuration(config, key);\n}\n\n/**\n * Reads a {@link SchedulerServiceTaskScheduleDefinition} from config. Expects\n * the config not to be the root config, but the config for the definition.\n *\n * @param config - config for a TaskScheduleDefinition.\n * @public\n */\nexport function readSchedulerServiceTaskScheduleDefinitionFromConfig(\n  config: Config,\n): SchedulerServiceTaskScheduleDefinition {\n  const frequency = readCronOrDuration(config, 'frequency');\n  const timeout = readDuration(config, 'timeout');\n\n  const initialDelay = config.has('initialDelay')\n    ? readDuration(config, 'initialDelay')\n    : undefined;\n\n  const scope = config.getOptionalString('scope');\n  if (scope && !['global', 'local'].includes(scope)) {\n    throw new Error(\n      `Only \"global\" or \"local\" are allowed for TaskScheduleDefinition.scope, but got: ${scope}`,\n    );\n  }\n\n  return {\n    frequency,\n    timeout,\n    initialDelay,\n    scope: scope as 'global' | 'local' | undefined,\n  };\n}\n","/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Tries to deduce whether a thrown error is a database conflict.\n *\n * @public\n * @param e - A thrown error\n * @returns True if the error looks like it was a conflict error thrown by a\n *          known database engine\n */\nexport function isDatabaseConflictError(e: unknown) {\n  const message = (e as any)?.message;\n\n  return (\n    typeof message === 'string' &&\n    (/SQLITE_CONSTRAINT(?:_UNIQUE)?: UNIQUE/.test(message) ||\n      /UNIQUE constraint failed:/.test(message) ||\n      /unique constraint/.test(message) ||\n      /Duplicate entry/.test(message)) // MySQL uniqueness error msg\n  );\n}\n","/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { BackendFeature, BackendFeatureFactory } from '../types';\nimport {\n  BackendModuleRegistrationPoints,\n  BackendPluginRegistrationPoints,\n  ExtensionPoint,\n  InternalBackendModuleRegistration,\n  InternalBackendPluginRegistration,\n} from './types';\n\n/**\n * The configuration options passed to {@link createExtensionPoint}.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport interface CreateExtensionPointOptions {\n  /**\n   * The ID of this extension point.\n   *\n   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n   */\n  id: string;\n}\n\n/**\n * Creates a new backend extension point.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}\n */\nexport function createExtensionPoint<T>(\n  options: CreateExtensionPointOptions,\n): ExtensionPoint<T> {\n  return {\n    id: options.id,\n    get T(): T {\n      throw new Error(`tried to read ExtensionPoint.T of ${this}`);\n    },\n    toString() {\n      return `extensionPoint{${options.id}}`;\n    },\n    $$type: '@backstage/ExtensionPoint',\n  };\n}\n\n/**\n * The configuration options passed to {@link createBackendPlugin}.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport interface CreateBackendPluginOptions {\n  /**\n   * The ID of this plugin.\n   *\n   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n   */\n  pluginId: string;\n  register(reg: BackendPluginRegistrationPoints): void;\n}\n\n/**\n * Creates a new backend plugin.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport function createBackendPlugin(\n  options: CreateBackendPluginOptions,\n): () => BackendFeature {\n  const factory: BackendFeatureFactory = () => {\n    let registrations: InternalBackendPluginRegistration[];\n\n    return {\n      $$type: '@backstage/BackendFeature',\n      version: 'v1',\n      getRegistrations() {\n        if (registrations) {\n          return registrations;\n        }\n        const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =\n          [];\n        let init: InternalBackendPluginRegistration['init'] | undefined =\n          undefined;\n\n        options.register({\n          registerExtensionPoint(ext, impl) {\n            if (init) {\n              throw new Error(\n                'registerExtensionPoint called after registerInit',\n              );\n            }\n            extensionPoints.push([ext, impl]);\n          },\n          registerInit(regInit) {\n            if (init) {\n              throw new Error('registerInit must only be called once');\n            }\n            init = {\n              deps: regInit.deps,\n              func: regInit.init,\n            };\n          },\n        });\n\n        if (!init) {\n          throw new Error(\n            `registerInit was not called by register in ${options.pluginId}`,\n          );\n        }\n\n        registrations = [\n          {\n            type: 'plugin',\n            pluginId: options.pluginId,\n            extensionPoints,\n            init,\n          },\n        ];\n        return registrations;\n      },\n    };\n  };\n  factory.$$type = '@backstage/BackendFeatureFactory';\n\n  return factory;\n}\n\n/**\n * The configuration options passed to {@link createBackendModule}.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport interface CreateBackendModuleOptions {\n  /**\n   * Should exactly match the `id` of the plugin that the module extends.\n   *\n   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n   */\n  pluginId: string;\n\n  /**\n   * The ID of this module, used to identify the module and ensure that it is not installed twice.\n   */\n  moduleId: string;\n  register(reg: BackendModuleRegistrationPoints): void;\n}\n\n/**\n * Creates a new backend module for a given plugin.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport function createBackendModule(\n  options: CreateBackendModuleOptions,\n): () => BackendFeature {\n  const factory: BackendFeatureFactory = () => {\n    let registrations: InternalBackendModuleRegistration[];\n\n    return {\n      $$type: '@backstage/BackendFeature',\n      version: 'v1',\n      getRegistrations() {\n        if (registrations) {\n          return registrations;\n        }\n        const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =\n          [];\n        let init: InternalBackendModuleRegistration['init'] | undefined =\n          undefined;\n\n        options.register({\n          registerExtensionPoint(ext, impl) {\n            if (init) {\n              throw new Error(\n                'registerExtensionPoint called after registerInit',\n              );\n            }\n            extensionPoints.push([ext, impl]);\n          },\n          registerInit(regInit) {\n            if (init) {\n              throw new Error('registerInit must only be called once');\n            }\n            init = {\n              deps: regInit.deps,\n              func: regInit.init,\n            };\n          },\n        });\n\n        if (!init) {\n          throw new Error(\n            `registerInit was not called by register in ${options.moduleId} module for ${options.pluginId}`,\n          );\n        }\n\n        registrations = [\n          {\n            type: 'module',\n            pluginId: options.pluginId,\n            moduleId: options.moduleId,\n            extensionPoints,\n            init,\n          },\n        ];\n        return registrations;\n      },\n    };\n  };\n  factory.$$type = '@backstage/BackendFeatureFactory';\n\n  return factory;\n}\n"],"names":["c","coreServices","config","Duration","readDurationFromConfig"],"mappings":"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"}

package/dist/index.d.ts

@@ -9,13 +9,22 @@ import { PermissionAttributes, PermissionEvaluator, AuthorizePermissionRequest,
 import { Knex } from 'knex';
 export { isChildPath } from '@backstage/cli-common';
 
-/** @public */
+/**
+ * This is the legacy service for identity handling in Backstage. Please migrate to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/identity | service documentation} for more details.
+ *
+ * @public
+ * @deprecated Please {@link https://backstage.io/docs/tutorials/auth-service-migration | migrate} to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead.
+ */
 interface IdentityService extends IdentityApi {
 }
 
 /**
  * A generic interface for fetching plain data from URLs.
  *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/url-reader | service documentation} for more details.
+ *
  * @public
  */
 interface UrlReaderService {
@@ -328,9 +337,12 @@ type SearchResponseFile = {
 };
 
 /**
- * Interface for creating and validating tokens.
+ * This is the legacy service for creating and validating tokens. Please migrate to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/token-manager | service documentation} for more details.
  *
  * @public
+ * @deprecated Please {@link https://backstage.io/docs/tutorials/auth-service-migration | migrate} to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead.
  */
 interface TokenManagerService {
     /**
@@ -599,6 +611,8 @@ interface SchedulerServiceTaskRunner {
 /**
  * Deals with the scheduling of distributed tasks, for a given plugin.
  *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/scheduler | service documentation} for more details.
+ *
  * @public
  */
 interface SchedulerService {
@@ -663,6 +677,8 @@ declare function readSchedulerServiceTaskScheduleDefinitionFromConfig(config: Co
 /**
  * A service that provides a logging facility.
  *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/logger | service documentation} for more details.
+ *
  * @public
  */
 interface LoggerService {
@@ -673,7 +689,13 @@ interface LoggerService {
     child(meta: JsonObject): LoggerService;
 }
 
-/** @public */
+/**
+ * Root-level logging.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/root-logger | service documentation} for more details.
+ *
+ * @public
+ */
 interface RootLoggerService extends LoggerService {
 }
 
@@ -704,6 +726,10 @@ interface LifecycleServiceShutdownOptions {
     logger?: LoggerService;
 }
 /**
+ * Provides registration of plugin startup and shutdown lifecycle hooks.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/lifecycle | service documentation} for more details.
+ *
  * @public
  */
 interface LifecycleService {
@@ -723,11 +749,21 @@ interface LifecycleService {
     addShutdownHook(hook: LifecycleServiceShutdownHook, options?: LifecycleServiceShutdownOptions): void;
 }
 
-/** @public */
+/**
+ * Registration of backend startup and shutdown lifecycle hooks.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/root-lifecycle | service documentation} for more details.
+ *
+ * @public
+ */
 interface RootLifecycleService extends LifecycleService {
 }
 
 /**
+ * HTTP route registration for root services.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/root-http-router | service documentation} for more details.
+ *
  * @public
  */
 interface RootHttpRouterService {
@@ -739,30 +775,61 @@ interface RootHttpRouterService {
 }
 
 /**
+ * Access metadata about the current plugin.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/plugin-metadata | service documentation} for more details.
+ *
  * @public
  */
 interface PluginMetadataService {
+    /**
+     * The ID of the current plugin.
+     */
     getId(): string;
 }
 
 /**
+ * Represents a user principal (for example when a user Backstage token issued
+ * by the auth backend was given to a request).
+ *
+ * @remarks
+ *
+ * Additional information about the user can be fetched using the
+ * {@link UserInfoService}.
+ *
  * @public
  */
 type BackstageUserPrincipal = {
     type: 'user';
+    /**
+     * The entity ref of the user entity that this principal represents.
+     */
     userEntityRef: string;
 };
 /**
+ * Represents a principal that is not authenticated (for example when no token
+ * at all was given to a request).
+ *
  * @public
  */
 type BackstageNonePrincipal = {
     type: 'none';
 };
 /**
+ * Represents a service principal (for example when an external access method
+ * token was given to a request, or the caller was a Backstage backend plugin).
  * @public
  */
 type BackstageServicePrincipal = {
     type: 'service';
+    /**
+     * A string that represents the service.
+     *
+     * @remarks
+     *
+     * This string is only informational, has no well defined semantics, and
+     * should never be used to drive actual logic in code.
+     */
     subject: string;
     /**
      * The access restrictions that apply to this principal.
@@ -812,14 +879,35 @@ type BackstagePrincipalAccessRestrictions = {
     };
 };
 /**
+ * An opaque representation of credentials, for example as passed in a
+ * request-response flow.
+ *
  * @public
  */
 type BackstageCredentials<TPrincipal = unknown> = {
     $$type: '@backstage/BackstageCredentials';
+    /**
+     * If the credentials have a limited lifetime, this is the time at which they
+     * expire and may no longer be accepted by a receiver.
+     */
     expiresAt?: Date;
+    /**
+     * The principal (originator) of the request.
+     *
+     * @remarks
+     *
+     * This is semantically the originator of a request chain, and may or may not
+     * represent the immediate caller of your service. For example, in
+     * on-behalf-of scenarios, the immediate caller may be an intermediary backend
+     * service, but the principal may still be a user that was the original
+     * caller.
+     */
     principal: TPrincipal;
 };
 /**
+ * The types of principal that can be represented in a
+ * {@link BackstageCredentials} object.
+ *
  * @public
  */
 type BackstagePrincipalTypes = {
@@ -829,25 +917,85 @@ type BackstagePrincipalTypes = {
     unknown: unknown;
 };
 /**
+ * Provides token authentication and credentials management.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/auth | service documentation} for more details.
+ *
  * @public
  */
 interface AuthService {
+    /**
+     * Verifies a token and returns the associated credentials.
+     */
     authenticate(token: string, options?: {
+        /**
+         * If set to true, allow limited access tokens (such as cookies).
+         *
+         * If this flag is not set, or is set to false, calls with limited access
+         * tokens will lead to a {@link @backstage/errors#NotAllowedError} being
+         * thrown.
+         */
         allowLimitedAccess?: boolean;
     }): Promise<BackstageCredentials>;
+    /**
+     * Checks if the given credentials are of the given type, and narrows the
+     * TypeScript type accordingly if there's a match.
+     */
     isPrincipal<TType extends keyof BackstagePrincipalTypes>(credentials: BackstageCredentials, type: TType): credentials is BackstageCredentials<BackstagePrincipalTypes[TType]>;
+    /**
+     * Create a credentials object that represents an unauthenticated caller.
+     */
     getNoneCredentials(): Promise<BackstageCredentials<BackstageNonePrincipal>>;
+    /**
+     * Create a credentials object that represents the current service itself.
+     */
     getOwnServiceCredentials(): Promise<BackstageCredentials<BackstageServicePrincipal>>;
+    /**
+     * Issue a token that can be used for authenticating calls towards other
+     * backend plugins.
+     *
+     * @remarks
+     *
+     * This method should be called before each request. Do not cold on to the
+     * issued token and reuse it for future calls.
+     */
     getPluginRequestToken(options: {
+        /**
+         * The credentials of the originator of the request.
+         *
+         * @remarks
+         *
+         * This is most commonly the result of
+         * {@link AuthService.getOwnServiceCredentials} when the current service is
+         * the originator, or the output of {@link HttpAuthService.credentials} when
+         * performing requests on behalf of an incoming request identity.
+         */
         onBehalfOf: BackstageCredentials;
+        /**
+         * The ID of the plugin that the request is being made to.
+         */
         targetPluginId: string;
     }): Promise<{
         token: string;
     }>;
-    getLimitedUserToken(credentials: BackstageCredentials<BackstageUserPrincipal>): Promise<{
+    /**
+     * Issue a limited user token that can be used e.g. in cookie flows.
+     */
+    getLimitedUserToken(
+    /**
+     * The credentials that this token should represent. Must be a user
+     * principal. Commonly the output of {@link HttpAuthService.credentials} is
+     * used as the input.
+     */
+    credentials: BackstageCredentials<BackstageUserPrincipal>): Promise<{
         token: string;
         expiresAt: Date;
     }>;
+    /**
+     * Retrieve the public keys that have been used to sign tokens that were
+     * issued by this service. This list is periodically pruned from keys that are
+     * significantly past their expiry.
+     */
     listPublicServiceKeys(): Promise<{
         keys: JsonObject[];
     }>;
@@ -864,32 +1012,168 @@ type PermissionsServiceRequestOptions = {
 } | {
     credentials: BackstageCredentials;
 };
-/** @public */
+/**
+ * Permission system integration for authorization of user/service actions.
+ *
+ * See the {@link https://backstage.io/docs/permissions/overview | permissions documentation}
+ * and the {@link https://backstage.io/docs/backend-system/core-services/permissions | service documentation}
+ * for more details.
+ *
+ * @public
+ */
 interface PermissionsService extends PermissionEvaluator {
+    /**
+     * Evaluates
+     * {@link @backstage/plugin-permission-common#Permission | Permissions} and
+     * returns definitive decisions.
+     *
+     * @remarks
+     *
+     * The returned array has the same number of items, in the same order, as the
+     * given requests.
+     */
     authorize(requests: AuthorizePermissionRequest[], options?: PermissionsServiceRequestOptions): Promise<AuthorizePermissionResponse[]>;
+    /**
+     * Evaluates {@link @backstage/plugin-permission-common#ResourcePermission | ResourcePermissions} and returns both definitive and
+     * conditional decisions, depending on the configured
+     * {@link @backstage/plugin-permission-node#PermissionPolicy}.
+     *
+     * @remarks
+     *
+     * This method is useful when the
+     * caller needs more control over the processing of conditional decisions. For example, a plugin
+     * backend may want to use {@link @backstage/plugin-permission-common#PermissionCriteria | conditions} in a database query instead of
+     * evaluating each resource in memory.
+     *
+     * The returned array has the same number of items, in the same order, as the
+     * given requests.
+     */
     authorizeConditional(requests: QueryPermissionRequest[], options?: PermissionsServiceRequestOptions): Promise<QueryPermissionResponse[]>;
 }
 
-/** @public */
+/**
+ * Options for {@link HttpRouterService.addAuthPolicy}.
+ *
+ * @public
+ */
 interface HttpRouterServiceAuthPolicy {
     path: string;
     allow: 'unauthenticated' | 'user-cookie';
 }
 /**
+ * Allows plugins to register HTTP routes.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/http-router | service documentation} for more details.
+ *
  * @public
  */
 interface HttpRouterService {
+    /**
+     * Registers an Express request handler under the plugin's base router. This
+     * typically makes its base path `/api/<plugin-id>`.
+     */
     use(handler: Handler): void;
+    /**
+     * Adds an auth policy to the router. This is used to allow unauthenticated or
+     * cookie based access to parts of a plugin's API.
+     *
+     * @remarks
+     *
+     * The paths given follow the same pattern as the routers given to the `use`
+     * method, that is, they are relative to the plugin's base URL, and can
+     * contain placeholders.
+     *
+     * @example
+     *
+     * ```ts
+     * http.addAuthPolicy({
+     *   path: '/static/:id',
+     *   allow: 'user-cookie',
+     * });
+     * ```
+     *
+     * This allows limited access tokens via cookies on the
+     * `/api/<plugin-id>/static/*` paths, but not unauthenticated access.
+     */
     addAuthPolicy(policy: HttpRouterServiceAuthPolicy): void;
 }
 
-/** @public */
+/**
+ * Provides handling of credentials in an ongoing request.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/http-auth | service documentation} for more details.
+ *
+ * @public
+ */
 interface HttpAuthService {
-    credentials<TAllowed extends keyof BackstagePrincipalTypes = 'unknown'>(req: Request<any, any, any, any, any>, options?: {
+    /**
+     * Extracts the caller's credentials from a request.
+     *
+     * @remarks
+     *
+     * The credentials have been validated before returning, and are guaranteed to
+     * adhere to whatever policies have been added to this route using
+     * {@link HttpRouterService.addAuthPolicy}, if any.
+     *
+     * Further restrictions can be imposed by passing in options that control the
+     * allowed types of credential.
+     *
+     * You can narrow the returned credentials object to specific principal types
+     * using {@link AuthService.isPrincipal}.
+     */
+    credentials<TAllowed extends keyof BackstagePrincipalTypes = 'unknown'>(
+    /**
+     * An Express request object.
+     */
+    req: Request<any, any, any, any, any>, 
+    /**
+     * Optional further restrictions.
+     */
+    options?: {
+        /**
+         * If specified, allow only principals of the given type(s).
+         *
+         * If the incoming credentials were not of a type that matched this
+         * restriction, a {@link @backstage/errors#NotAllowedError} is thrown.
+         *
+         * The default is to allow user and service principals.
+         */
         allow?: Array<TAllowed>;
+        /**
+         * If set to true, allow limited access tokens (such as cookies).
+         *
+         * If this flag is not set, or is set to false, calls with limited access
+         * tokens will lead to a {@link @backstage/errors#NotAllowedError} being
+         * thrown.
+         */
         allowLimitedAccess?: boolean;
     }): Promise<BackstageCredentials<BackstagePrincipalTypes[TAllowed]>>;
-    issueUserCookie(res: Response, options?: {
+    /**
+     * Issues a limited access token as a cookie on the given response object.
+     * This is only possible for requests that were originally made with user
+     * credentials (such as a Backstage token).
+     *
+     * This must be called before sending any payload data.
+     */
+    issueUserCookie(
+    /**
+     * An Express response object.
+     */
+    res: Response, 
+    /**
+     * Optional further settings.
+     */
+    options?: {
+        /**
+         * Issue the cookie for this specific credential. Must be a "user" type
+         * principal, or a "none" type (which leads to deleting the cookie).
+         *
+         * @remarks
+         *
+         * Normally you do not have to specify this option, because the default
+         * behavior is to extract the credentials from the request that
+         * corresponded to the given respnse.
+         */
         credentials?: BackstageCredentials;
     }): Promise<{
         expiresAt: Date;
@@ -900,6 +1184,10 @@ interface HttpAuthService {
  * The DiscoveryService is used to provide a mechanism for backend
  * plugins to discover the endpoints for itself or other backend plugins.
  *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/discovery | service documentation} for more details.
+ *
+ * @remarks
+ *
  * The purpose of the discovery API is to allow for many different deployment
  * setups and routing methods through a central configuration, instead
  * of letting each individual plugin manage that configuration.
@@ -914,13 +1202,15 @@ interface DiscoveryService {
     /**
      * Returns the internal HTTP base URL for a given plugin, without a trailing slash.
      *
+     * @remarks
+     *
      * The returned URL should point to an internal endpoint for the plugin, with
      * the shortest route possible. The URL should be used for service-to-service
      * communication within a Backstage backend deployment.
      *
-     * This method must always be called just before making a request, as opposed to
-     * fetching the URL when constructing an API client. That is to ensure that more
-     * flexible routing patterns can be supported.
+     * This method must always be called just before making each request, as opposed to
+     * fetching the URL once when constructing an API client. That is to ensure that more
+     * flexible routing patterns can be supported where a different result might be returned each time.
      *
      * For example, asking for the URL for `catalog` may return something
      * like `http://10.1.2.3/api/catalog`
@@ -929,6 +1219,8 @@ interface DiscoveryService {
     /**
      * Returns the external HTTP base backend URL for a given plugin, without a trailing slash.
      *
+     * @remarks
+     *
      * The returned URL should point to an external endpoint for the plugin, such that
      * it is reachable from the Backstage frontend and other external services. The returned
      * URL should be usable for example as a callback / webhook URL.
@@ -944,7 +1236,9 @@ interface DiscoveryService {
 }
 
 /**
- * The DatabaseService manages access to databases that Plugins get.
+ * Manages access to databases that plugins get.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/database | service documentation} for more details.
  *
  * @public
  */
@@ -970,6 +1264,12 @@ interface DatabaseService {
 }
 
 /**
+ * Provides access to static configuration.
+ *
+ * See the {@link https://backstage.io/docs/conf/ | configuration documentation}
+ * and the {@link https://backstage.io/docs/backend-system/core-services/root-config | service documentation}
+ * for more details.
+ *
  * @public
  */
 interface RootConfigService extends Config {
@@ -1004,6 +1304,8 @@ type CacheServiceOptions = {
  * A pre-configured, storage agnostic cache service suitable for use by
  * Backstage plugins.
  *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/cache | service documentation} for more details.
+ *
  * @public
  */
 interface CacheService {
@@ -1028,13 +1330,27 @@ interface CacheService {
     withOptions(options: CacheServiceOptions): CacheService;
 }
 
-/** @public */
+/**
+ * Represents user information that is available to the backend, based on some
+ * user credentials.
+ *
+ * @public
+ */
 interface BackstageUserInfo {
     userEntityRef: string;
     ownershipEntityRefs: string[];
 }
-/** @public */
+/**
+ * Authenticated user information retrieval.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/user-info | service documentation} for more details.
+ *
+ * @public
+ */
 interface UserInfoService {
+    /**
+     * Retrieve user information based on the provided credentials.
+     */
     getUserInfo(credentials: BackstageCredentials): Promise<BackstageUserInfo>;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-plugin-api",
-  "version": "0.6.19-next.1",
+  "version": "0.6.19-next.2",
   "description": "Core API used by Backstage backend plugins",
   "backstage": {
     "role": "node-library"
@@ -56,7 +56,7 @@
     "@backstage/cli-common": "^0.1.13",
     "@backstage/config": "^1.2.0",
     "@backstage/errors": "^1.2.4",
-    "@backstage/plugin-auth-node": "^0.4.14-next.1",
+    "@backstage/plugin-auth-node": "^0.4.14-next.2",
     "@backstage/plugin-permission-common": "^0.7.13",
     "@backstage/types": "^1.1.1",
     "@types/express": "^4.17.6",
@@ -66,7 +66,7 @@
     "luxon": "^3.0.0"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "^0.4.0-next.1",
-    "@backstage/cli": "^0.26.7-next.1"
+    "@backstage/backend-test-utils": "^0.4.0-next.2",
+    "@backstage/cli": "^0.26.7-next.2"
   }
 }

package/testUtils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-plugin-api",
-  "version": "0.6.19-next.1",
+  "version": "0.6.19-next.2",
   "main": "../dist/testUtils.cjs.js",
   "types": "../dist/testUtils.d.ts"
 }