@backstage/backend-plugin-api 0.0.0-nightly-20220709024234

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @backstage/backend-plugin-api
+
+## 0.0.0-nightly-20220709024234
+
+### Minor Changes
+
+- 91c1d12123: Introduced new package for creating backend plugins using the new alpha backend plugin framework.
+  This package is still considered **EXPERIMENTAL** and things will change without warning. Do not use this for production.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-common@0.0.0-nightly-20220709024234
+  - @backstage/plugin-permission-common@0.0.0-nightly-20220709024234
+  - @backstage/backend-tasks@0.0.0-nightly-20220709024234

package/README.md

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

package/alpha/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@backstage/backend-plugin-api",
+  "version": "0.0.0-nightly-20220709024234",
+  "main": "../dist/index.cjs.js",
+  "types": "../dist/index.alpha.d.ts"
+}

package/dist/index.alpha.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Core API used by Backstage backend plugins.
+ *
+ * @packageDocumentation
+ */
+
+import { Config } from '@backstage/config';
+import { Handler } from 'express';
+import { Logger as Logger_2 } from 'winston';
+import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
+import { PermissionEvaluator } from '@backstage/plugin-permission-common';
+import { PluginCacheManager } from '@backstage/backend-common';
+import { PluginDatabaseManager } from '@backstage/backend-common';
+import { PluginEndpointDiscovery } from '@backstage/backend-common';
+import { PluginTaskScheduler } from '@backstage/backend-tasks';
+import { TokenManager } from '@backstage/backend-common';
+import { TransportStreamOptions } from 'winston-transport';
+import { UrlReader } from '@backstage/backend-common';
+
+/** @public */
+export declare type AnyServiceFactory = ServiceFactory<unknown, unknown, {
+    [key in string]: unknown;
+}>;
+
+/** @public */
+export declare interface BackendInitRegistry {
+    registerExtensionPoint<TExtensionPoint>(ref: ServiceRef<TExtensionPoint>, impl: TExtensionPoint): void;
+    registerInit<Deps extends {
+        [name in string]: unknown;
+    }>(options: {
+        deps: {
+            [name in keyof Deps]: ServiceRef<Deps[name]>;
+        };
+        init: (deps: Deps) => Promise<void>;
+    }): void;
+}
+
+/** @public */
+export declare interface BackendModuleConfig<TOptions> {
+    pluginId: string;
+    moduleId: string;
+    register(reg: Omit<BackendInitRegistry, 'registerExtensionPoint'>, options: TOptions): void;
+}
+
+/** @public */
+export declare interface BackendPluginConfig<TOptions> {
+    id: string;
+    register(reg: BackendInitRegistry, options: TOptions): void;
+}
+
+/** @public */
+export declare interface BackendRegistrable {
+    id: string;
+    register(reg: BackendInitRegistry): void;
+}
+
+/**
+ * @public
+ */
+export declare const cacheServiceRef: ServiceRef<PluginCacheManager>;
+
+/**
+ * @public
+ */
+export declare const configServiceRef: ServiceRef<Config>;
+
+/** @public */
+export declare function createBackendModule<TOptions>(config: BackendModuleConfig<TOptions>): (option: TOptions) => BackendRegistrable;
+
+/** @public */
+export declare function createBackendPlugin<TOptions>(config: BackendPluginConfig<TOptions>): (option: TOptions) => BackendRegistrable;
+
+/** @public */
+export declare function createExtensionPoint<T>(options: {
+    id: string;
+}): ExtensionPoint<T>;
+
+/**
+ * @public
+ */
+export declare function createServiceFactory<Api, Impl extends Api, Deps extends {
+    [name in string]: unknown;
+}>(factory: ServiceFactory<Api, Impl, Deps>): ServiceFactory<Api, Api, {}>;
+
+/**
+ * @public
+ */
+export declare function createServiceRef<T>(options: {
+    id: string;
+}): ServiceRef<T>;
+
+/**
+ * @public
+ */
+export declare const databaseServiceRef: ServiceRef<PluginDatabaseManager>;
+
+/** @public */
+export declare type DepsToDepFactories<T> = {
+    [key in keyof T]: (pluginId: string) => Promise<T[key]>;
+};
+
+/**
+ * @public
+ */
+export declare const discoveryServiceRef: ServiceRef<PluginEndpointDiscovery>;
+
+/**
+ * TODO
+ *
+ * @public
+ */
+export declare type ExtensionPoint<T> = {
+    id: string;
+    /**
+     * Utility for getting the type of the extension point, using `typeof extensionPoint.T`.
+     * Attempting to actually read this value will result in an exception.
+     */
+    T: T;
+    toString(): string;
+    $$ref: 'extension-point';
+};
+
+/** @public */
+export declare type FactoryFunc<Impl> = (pluginId: string) => Promise<Impl>;
+
+/**
+ * @public
+ */
+export declare interface HttpRouterService {
+    use(handler: Handler): void;
+}
+
+/**
+ * @public
+ */
+export declare const httpRouterServiceRef: ServiceRef<HttpRouterService>;
+
+/**
+ * @public
+ */
+export declare interface Logger {
+    info(message: string): void;
+    child(fields: {
+        [name: string]: string;
+    }): Logger;
+}
+
+/**
+ * @public
+ */
+export declare const loggerServiceRef: ServiceRef<Logger>;
+
+/** @public */
+export declare function loggerToWinstonLogger(logger: Logger, opts?: TransportStreamOptions): Logger_2;
+
+/**
+ * @public
+ */
+export declare const permissionsServiceRef: ServiceRef<PermissionAuthorizer | PermissionEvaluator>;
+
+/**
+ * @public
+ */
+export declare const schedulerServiceRef: ServiceRef<PluginTaskScheduler>;
+
+/** @public */
+export declare type ServiceFactory<TApi, TImpl extends TApi, TDeps extends {
+    [name in string]: unknown;
+}> = {
+    service: ServiceRef<TApi>;
+    deps: TypesToServiceRef<TDeps>;
+    factory(deps: DepsToDepFactories<TDeps>): Promise<FactoryFunc<TImpl>>;
+};
+
+/**
+ * TODO
+ *
+ * @public
+ */
+export declare type ServiceRef<T> = {
+    id: string;
+    /**
+     * Utility for getting the type of the service, using `typeof serviceRef.T`.
+     * Attempting to actually read this value will result in an exception.
+     */
+    T: T;
+    toString(): string;
+    $$ref: 'service';
+};
+
+/**
+ * @public
+ */
+export declare const tokenManagerServiceRef: ServiceRef<TokenManager>;
+
+/** @public */
+export declare type TypesToServiceRef<T> = {
+    [key in keyof T]: ServiceRef<T[key]>;
+};
+
+/**
+ * @public
+ */
+export declare const urlReaderServiceRef: ServiceRef<UrlReader>;
+
+export { }

package/dist/index.beta.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Core API used by Backstage backend plugins.
+ *
+ * @packageDocumentation
+ */
+
+import { Config } from '@backstage/config';
+import { Handler } from 'express';
+import { Logger as Logger_2 } from 'winston';
+import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
+import { PermissionEvaluator } from '@backstage/plugin-permission-common';
+import { PluginCacheManager } from '@backstage/backend-common';
+import { PluginDatabaseManager } from '@backstage/backend-common';
+import { PluginEndpointDiscovery } from '@backstage/backend-common';
+import { PluginTaskScheduler } from '@backstage/backend-tasks';
+import { TokenManager } from '@backstage/backend-common';
+import { TransportStreamOptions } from 'winston-transport';
+import { UrlReader } from '@backstage/backend-common';
+
+/** @public */
+export declare type AnyServiceFactory = ServiceFactory<unknown, unknown, {
+    [key in string]: unknown;
+}>;
+
+/** @public */
+export declare interface BackendInitRegistry {
+    registerExtensionPoint<TExtensionPoint>(ref: ServiceRef<TExtensionPoint>, impl: TExtensionPoint): void;
+    registerInit<Deps extends {
+        [name in string]: unknown;
+    }>(options: {
+        deps: {
+            [name in keyof Deps]: ServiceRef<Deps[name]>;
+        };
+        init: (deps: Deps) => Promise<void>;
+    }): void;
+}
+
+/** @public */
+export declare interface BackendModuleConfig<TOptions> {
+    pluginId: string;
+    moduleId: string;
+    register(reg: Omit<BackendInitRegistry, 'registerExtensionPoint'>, options: TOptions): void;
+}
+
+/** @public */
+export declare interface BackendPluginConfig<TOptions> {
+    id: string;
+    register(reg: BackendInitRegistry, options: TOptions): void;
+}
+
+/** @public */
+export declare interface BackendRegistrable {
+    id: string;
+    register(reg: BackendInitRegistry): void;
+}
+
+/**
+ * @public
+ */
+export declare const cacheServiceRef: ServiceRef<PluginCacheManager>;
+
+/**
+ * @public
+ */
+export declare const configServiceRef: ServiceRef<Config>;
+
+/** @public */
+export declare function createBackendModule<TOptions>(config: BackendModuleConfig<TOptions>): (option: TOptions) => BackendRegistrable;
+
+/** @public */
+export declare function createBackendPlugin<TOptions>(config: BackendPluginConfig<TOptions>): (option: TOptions) => BackendRegistrable;
+
+/** @public */
+export declare function createExtensionPoint<T>(options: {
+    id: string;
+}): ExtensionPoint<T>;
+
+/**
+ * @public
+ */
+export declare function createServiceFactory<Api, Impl extends Api, Deps extends {
+    [name in string]: unknown;
+}>(factory: ServiceFactory<Api, Impl, Deps>): ServiceFactory<Api, Api, {}>;
+
+/**
+ * @public
+ */
+export declare function createServiceRef<T>(options: {
+    id: string;
+}): ServiceRef<T>;
+
+/**
+ * @public
+ */
+export declare const databaseServiceRef: ServiceRef<PluginDatabaseManager>;
+
+/** @public */
+export declare type DepsToDepFactories<T> = {
+    [key in keyof T]: (pluginId: string) => Promise<T[key]>;
+};
+
+/**
+ * @public
+ */
+export declare const discoveryServiceRef: ServiceRef<PluginEndpointDiscovery>;
+
+/**
+ * TODO
+ *
+ * @public
+ */
+export declare type ExtensionPoint<T> = {
+    id: string;
+    /**
+     * Utility for getting the type of the extension point, using `typeof extensionPoint.T`.
+     * Attempting to actually read this value will result in an exception.
+     */
+    T: T;
+    toString(): string;
+    $$ref: 'extension-point';
+};
+
+/** @public */
+export declare type FactoryFunc<Impl> = (pluginId: string) => Promise<Impl>;
+
+/**
+ * @public
+ */
+export declare interface HttpRouterService {
+    use(handler: Handler): void;
+}
+
+/**
+ * @public
+ */
+export declare const httpRouterServiceRef: ServiceRef<HttpRouterService>;
+
+/**
+ * @public
+ */
+export declare interface Logger {
+    info(message: string): void;
+    child(fields: {
+        [name: string]: string;
+    }): Logger;
+}
+
+/**
+ * @public
+ */
+export declare const loggerServiceRef: ServiceRef<Logger>;
+
+/** @public */
+export declare function loggerToWinstonLogger(logger: Logger, opts?: TransportStreamOptions): Logger_2;
+
+/**
+ * @public
+ */
+export declare const permissionsServiceRef: ServiceRef<PermissionAuthorizer | PermissionEvaluator>;
+
+/**
+ * @public
+ */
+export declare const schedulerServiceRef: ServiceRef<PluginTaskScheduler>;
+
+/** @public */
+export declare type ServiceFactory<TApi, TImpl extends TApi, TDeps extends {
+    [name in string]: unknown;
+}> = {
+    service: ServiceRef<TApi>;
+    deps: TypesToServiceRef<TDeps>;
+    factory(deps: DepsToDepFactories<TDeps>): Promise<FactoryFunc<TImpl>>;
+};
+
+/**
+ * TODO
+ *
+ * @public
+ */
+export declare type ServiceRef<T> = {
+    id: string;
+    /**
+     * Utility for getting the type of the service, using `typeof serviceRef.T`.
+     * Attempting to actually read this value will result in an exception.
+     */
+    T: T;
+    toString(): string;
+    $$ref: 'service';
+};
+
+/**
+ * @public
+ */
+export declare const tokenManagerServiceRef: ServiceRef<TokenManager>;
+
+/** @public */
+export declare type TypesToServiceRef<T> = {
+    [key in keyof T]: ServiceRef<T[key]>;
+};
+
+/**
+ * @public
+ */
+export declare const urlReaderServiceRef: ServiceRef<UrlReader>;
+
+export { }

package/dist/index.cjs.js

@@ -0,0 +1,129 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var winston = require('winston');
+var Transport = require('winston-transport');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var Transport__default = /*#__PURE__*/_interopDefaultLegacy(Transport);
+
+function createServiceRef(options) {
+  return {
+    id: options.id,
+    get T() {
+      throw new Error(`tried to read ServiceRef.T of ${this}`);
+    },
+    toString() {
+      return `serviceRef{${options.id}}`;
+    },
+    $$ref: "service"
+  };
+}
+function createServiceFactory(factory) {
+  return factory;
+}
+
+const configServiceRef = createServiceRef({
+  id: "core.config"
+});
+
+const httpRouterServiceRef = createServiceRef({
+  id: "core.httpRouter"
+});
+
+const loggerServiceRef = createServiceRef({
+  id: "core.logger"
+});
+
+const urlReaderServiceRef = createServiceRef({
+  id: "core.urlReader"
+});
+
+const cacheServiceRef = createServiceRef({
+  id: "core.cache"
+});
+
+const databaseServiceRef = createServiceRef({
+  id: "core.database"
+});
+
+const discoveryServiceRef = createServiceRef({
+  id: "core.discovery"
+});
+
+const tokenManagerServiceRef = createServiceRef({
+  id: "core.tokenManager"
+});
+
+const permissionsServiceRef = createServiceRef({
+  id: "core.permissions"
+});
+
+const schedulerServiceRef = createServiceRef({
+  id: "core.scheduler"
+});
+
+class BackstageLoggerTransport extends Transport__default["default"] {
+  constructor(backstageLogger, opts) {
+    super(opts);
+    this.backstageLogger = backstageLogger;
+  }
+  log(info, callback) {
+    this.backstageLogger.info(info.message);
+    callback();
+  }
+}
+function loggerToWinstonLogger(logger, opts) {
+  return winston.createLogger({
+    transports: [new BackstageLoggerTransport(logger, opts)]
+  });
+}
+
+function createExtensionPoint(options) {
+  return {
+    id: options.id,
+    get T() {
+      throw new Error(`tried to read ExtensionPoint.T of ${this}`);
+    },
+    toString() {
+      return `extensionPoint{${options.id}}`;
+    },
+    $$ref: "extension-point"
+  };
+}
+function createBackendPlugin(config) {
+  return (options) => ({
+    id: config.id,
+    register(register) {
+      return config.register(register, options);
+    }
+  });
+}
+function createBackendModule(config) {
+  return (options) => ({
+    id: `${config.pluginId}.${config.moduleId}`,
+    register(register) {
+      return config.register(register, options);
+    }
+  });
+}
+
+exports.cacheServiceRef = cacheServiceRef;
+exports.configServiceRef = configServiceRef;
+exports.createBackendModule = createBackendModule;
+exports.createBackendPlugin = createBackendPlugin;
+exports.createExtensionPoint = createExtensionPoint;
+exports.createServiceFactory = createServiceFactory;
+exports.createServiceRef = createServiceRef;
+exports.databaseServiceRef = databaseServiceRef;
+exports.discoveryServiceRef = discoveryServiceRef;
+exports.httpRouterServiceRef = httpRouterServiceRef;
+exports.loggerServiceRef = loggerServiceRef;
+exports.loggerToWinstonLogger = loggerToWinstonLogger;
+exports.permissionsServiceRef = permissionsServiceRef;
+exports.schedulerServiceRef = schedulerServiceRef;
+exports.tokenManagerServiceRef = tokenManagerServiceRef;
+exports.urlReaderServiceRef = urlReaderServiceRef;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/services/system/types.ts","../src/services/definitions/configServiceRef.ts","../src/services/definitions/httpRouterServiceRef.ts","../src/services/definitions/loggerServiceRef.ts","../src/services/definitions/urlReaderServiceRef.ts","../src/services/definitions/cacheServiceRef.ts","../src/services/definitions/databaseServiceRef.ts","../src/services/definitions/discoveryServiceRef.ts","../src/services/definitions/tokenManagerServiceRef.ts","../src/services/definitions/permissionsServiceRef.ts","../src/services/definitions/schedulerServiceRef.ts","../src/services/helpers/loggerToWinstonLogger.ts","../src/wiring/types.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\n/**\n * TODO\n *\n * @public\n */\nexport type ServiceRef<T> = {\n  id: string;\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: T;\n\n  toString(): string;\n\n  $$ref: 'service';\n};\n\n/** @public */\nexport type TypesToServiceRef<T> = { [key in keyof T]: ServiceRef<T[key]> };\n\n/** @public */\nexport type DepsToDepFactories<T> = {\n  [key in keyof T]: (pluginId: string) => Promise<T[key]>;\n};\n\n/** @public */\nexport type FactoryFunc<Impl> = (pluginId: string) => Promise<Impl>;\n\n/** @public */\nexport type ServiceFactory<\n  TApi,\n  TImpl extends TApi,\n  TDeps extends { [name in string]: unknown },\n> = {\n  service: ServiceRef<TApi>;\n  deps: TypesToServiceRef<TDeps>;\n  factory(deps: DepsToDepFactories<TDeps>): Promise<FactoryFunc<TImpl>>;\n};\n\n/** @public */\nexport type AnyServiceFactory = ServiceFactory<\n  unknown,\n  unknown,\n  { [key in string]: unknown }\n>;\n\n/**\n * @public\n */\nexport function createServiceRef<T>(options: { id: string }): ServiceRef<T> {\n  return {\n    id: options.id,\n    get T(): T {\n      throw new Error(`tried to read ServiceRef.T of ${this}`);\n    },\n    toString() {\n      return `serviceRef{${options.id}}`;\n    },\n    $$ref: 'service', // TODO: declare\n  };\n}\n\n/**\n * @public\n */\nexport function createServiceFactory<\n  Api,\n  Impl extends Api,\n  Deps extends { [name in string]: unknown },\n>(factory: ServiceFactory<Api, Impl, Deps>): ServiceFactory<Api, Api, {}> {\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 { Config } from '@backstage/config';\nimport { createServiceRef } from '../system/types';\n\n/**\n * @public\n */\nexport const configServiceRef = createServiceRef<Config>({\n  id: 'core.config',\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/types';\nimport { Handler } from 'express';\n\n/**\n * @public\n */\nexport interface HttpRouterService {\n  use(handler: Handler): void;\n}\n\n/**\n * @public\n */\nexport const httpRouterServiceRef = createServiceRef<HttpRouterService>({\n  id: 'core.httpRouter',\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/types';\n\n/**\n * @public\n */\nexport interface Logger {\n  info(message: string): void;\n  child(fields: { [name: string]: string }): Logger;\n}\n\n/**\n * @public\n */\nexport const loggerServiceRef = createServiceRef<Logger>({\n  id: 'core.logger',\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/types';\nimport { UrlReader } from '@backstage/backend-common';\n\n/**\n * @public\n */\nexport const urlReaderServiceRef = createServiceRef<UrlReader>({\n  id: 'core.urlReader',\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/types';\nimport { PluginCacheManager } from '@backstage/backend-common';\n\n/**\n * @public\n */\nexport const cacheServiceRef = createServiceRef<PluginCacheManager>({\n  id: 'core.cache',\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 { PluginDatabaseManager } from '@backstage/backend-common';\nimport { createServiceRef } from '../system/types';\n\n/**\n * @public\n */\nexport const databaseServiceRef = createServiceRef<PluginDatabaseManager>({\n  id: 'core.database',\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/types';\nimport { PluginEndpointDiscovery } from '@backstage/backend-common';\n\n/**\n * @public\n */\nexport const discoveryServiceRef = createServiceRef<PluginEndpointDiscovery>({\n  id: 'core.discovery',\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/types';\nimport { TokenManager } from '@backstage/backend-common';\n\n/**\n * @public\n */\nexport const tokenManagerServiceRef = createServiceRef<TokenManager>({\n  id: 'core.tokenManager',\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/types';\nimport {\n  PermissionAuthorizer,\n  PermissionEvaluator,\n} from '@backstage/plugin-permission-common';\n\n/**\n * @public\n */\nexport const permissionsServiceRef = createServiceRef<\n  PermissionEvaluator | PermissionAuthorizer\n>({\n  id: 'core.permissions',\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/types';\nimport { PluginTaskScheduler } from '@backstage/backend-tasks';\n\n/**\n * @public\n */\nexport const schedulerServiceRef = createServiceRef<PluginTaskScheduler>({\n  id: 'core.scheduler',\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 { Logger as BackstageLogger } from '../definitions';\nimport { Logger as WinstonLogger, createLogger } from 'winston';\nimport Transport, { TransportStreamOptions } from 'winston-transport';\n\nclass BackstageLoggerTransport extends Transport {\n  constructor(\n    private readonly backstageLogger: BackstageLogger,\n    opts?: TransportStreamOptions,\n  ) {\n    super(opts);\n  }\n\n  log(info: { message: string }, callback: VoidFunction) {\n    // TODO: add support for levels and fields\n    this.backstageLogger.info(info.message);\n    callback();\n  }\n}\n\n/** @public */\nexport function loggerToWinstonLogger(\n  logger: BackstageLogger,\n  opts?: TransportStreamOptions,\n): WinstonLogger {\n  return createLogger({\n    transports: [new BackstageLoggerTransport(logger, opts)],\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 { ServiceRef } from '../services/system/types';\n\n/**\n * TODO\n *\n * @public\n */\nexport type ExtensionPoint<T> = {\n  id: string;\n\n  /**\n   * Utility for getting the type of the extension point, using `typeof extensionPoint.T`.\n   * Attempting to actually read this value will result in an exception.\n   */\n  T: T;\n\n  toString(): string;\n\n  $$ref: 'extension-point';\n};\n\n/** @public */\nexport function createExtensionPoint<T>(options: {\n  id: string;\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    $$ref: 'extension-point', // TODO: declare\n  };\n}\n\n/** @public */\nexport interface BackendInitRegistry {\n  registerExtensionPoint<TExtensionPoint>(\n    ref: ServiceRef<TExtensionPoint>,\n    impl: TExtensionPoint,\n  ): void;\n  registerInit<Deps extends { [name in string]: unknown }>(options: {\n    deps: { [name in keyof Deps]: ServiceRef<Deps[name]> };\n    init: (deps: Deps) => Promise<void>;\n  }): void;\n}\n\n/** @public */\nexport interface BackendRegistrable {\n  id: string;\n  register(reg: BackendInitRegistry): void;\n}\n\n/** @public */\nexport interface BackendPluginConfig<TOptions> {\n  id: string;\n  register(reg: BackendInitRegistry, options: TOptions): void;\n}\n\n// TODO: Make option optional in the returned factory if they are indeed optional\n/** @public */\nexport function createBackendPlugin<TOptions>(\n  config: BackendPluginConfig<TOptions>,\n): (option: TOptions) => BackendRegistrable {\n  return options => ({\n    id: config.id,\n    register(register) {\n      return config.register(register, options);\n    },\n  });\n}\n\n/** @public */\nexport interface BackendModuleConfig<TOptions> {\n  pluginId: string;\n  moduleId: string;\n  register(\n    reg: Omit<BackendInitRegistry, 'registerExtensionPoint'>,\n    options: TOptions,\n  ): void;\n}\n\n// TODO: Make option optional in the returned factory if they are indeed optional\n/** @public */\nexport function createBackendModule<TOptions>(\n  config: BackendModuleConfig<TOptions>,\n): (option: TOptions) => BackendRegistrable {\n  return options => ({\n    id: `${config.pluginId}.${config.moduleId}`,\n    register(register) {\n      // TODO: Hide registerExtensionPoint\n      return config.register(register, options);\n    },\n  });\n}\n"],"names":["Transport","createLogger"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Core API used by Backstage backend plugins.
+ *
+ * @packageDocumentation
+ */
+
+import { Config } from '@backstage/config';
+import { Handler } from 'express';
+import { Logger as Logger_2 } from 'winston';
+import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
+import { PermissionEvaluator } from '@backstage/plugin-permission-common';
+import { PluginCacheManager } from '@backstage/backend-common';
+import { PluginDatabaseManager } from '@backstage/backend-common';
+import { PluginEndpointDiscovery } from '@backstage/backend-common';
+import { PluginTaskScheduler } from '@backstage/backend-tasks';
+import { TokenManager } from '@backstage/backend-common';
+import { TransportStreamOptions } from 'winston-transport';
+import { UrlReader } from '@backstage/backend-common';
+
+/** @public */
+export declare type AnyServiceFactory = ServiceFactory<unknown, unknown, {
+    [key in string]: unknown;
+}>;
+
+/** @public */
+export declare interface BackendInitRegistry {
+    registerExtensionPoint<TExtensionPoint>(ref: ServiceRef<TExtensionPoint>, impl: TExtensionPoint): void;
+    registerInit<Deps extends {
+        [name in string]: unknown;
+    }>(options: {
+        deps: {
+            [name in keyof Deps]: ServiceRef<Deps[name]>;
+        };
+        init: (deps: Deps) => Promise<void>;
+    }): void;
+}
+
+/** @public */
+export declare interface BackendModuleConfig<TOptions> {
+    pluginId: string;
+    moduleId: string;
+    register(reg: Omit<BackendInitRegistry, 'registerExtensionPoint'>, options: TOptions): void;
+}
+
+/** @public */
+export declare interface BackendPluginConfig<TOptions> {
+    id: string;
+    register(reg: BackendInitRegistry, options: TOptions): void;
+}
+
+/** @public */
+export declare interface BackendRegistrable {
+    id: string;
+    register(reg: BackendInitRegistry): void;
+}
+
+/**
+ * @public
+ */
+export declare const cacheServiceRef: ServiceRef<PluginCacheManager>;
+
+/**
+ * @public
+ */
+export declare const configServiceRef: ServiceRef<Config>;
+
+/** @public */
+export declare function createBackendModule<TOptions>(config: BackendModuleConfig<TOptions>): (option: TOptions) => BackendRegistrable;
+
+/** @public */
+export declare function createBackendPlugin<TOptions>(config: BackendPluginConfig<TOptions>): (option: TOptions) => BackendRegistrable;
+
+/** @public */
+export declare function createExtensionPoint<T>(options: {
+    id: string;
+}): ExtensionPoint<T>;
+
+/**
+ * @public
+ */
+export declare function createServiceFactory<Api, Impl extends Api, Deps extends {
+    [name in string]: unknown;
+}>(factory: ServiceFactory<Api, Impl, Deps>): ServiceFactory<Api, Api, {}>;
+
+/**
+ * @public
+ */
+export declare function createServiceRef<T>(options: {
+    id: string;
+}): ServiceRef<T>;
+
+/**
+ * @public
+ */
+export declare const databaseServiceRef: ServiceRef<PluginDatabaseManager>;
+
+/** @public */
+export declare type DepsToDepFactories<T> = {
+    [key in keyof T]: (pluginId: string) => Promise<T[key]>;
+};
+
+/**
+ * @public
+ */
+export declare const discoveryServiceRef: ServiceRef<PluginEndpointDiscovery>;
+
+/**
+ * TODO
+ *
+ * @public
+ */
+export declare type ExtensionPoint<T> = {
+    id: string;
+    /**
+     * Utility for getting the type of the extension point, using `typeof extensionPoint.T`.
+     * Attempting to actually read this value will result in an exception.
+     */
+    T: T;
+    toString(): string;
+    $$ref: 'extension-point';
+};
+
+/** @public */
+export declare type FactoryFunc<Impl> = (pluginId: string) => Promise<Impl>;
+
+/**
+ * @public
+ */
+export declare interface HttpRouterService {
+    use(handler: Handler): void;
+}
+
+/**
+ * @public
+ */
+export declare const httpRouterServiceRef: ServiceRef<HttpRouterService>;
+
+/**
+ * @public
+ */
+export declare interface Logger {
+    info(message: string): void;
+    child(fields: {
+        [name: string]: string;
+    }): Logger;
+}
+
+/**
+ * @public
+ */
+export declare const loggerServiceRef: ServiceRef<Logger>;
+
+/** @public */
+export declare function loggerToWinstonLogger(logger: Logger, opts?: TransportStreamOptions): Logger_2;
+
+/**
+ * @public
+ */
+export declare const permissionsServiceRef: ServiceRef<PermissionAuthorizer | PermissionEvaluator>;
+
+/**
+ * @public
+ */
+export declare const schedulerServiceRef: ServiceRef<PluginTaskScheduler>;
+
+/** @public */
+export declare type ServiceFactory<TApi, TImpl extends TApi, TDeps extends {
+    [name in string]: unknown;
+}> = {
+    service: ServiceRef<TApi>;
+    deps: TypesToServiceRef<TDeps>;
+    factory(deps: DepsToDepFactories<TDeps>): Promise<FactoryFunc<TImpl>>;
+};
+
+/**
+ * TODO
+ *
+ * @public
+ */
+export declare type ServiceRef<T> = {
+    id: string;
+    /**
+     * Utility for getting the type of the service, using `typeof serviceRef.T`.
+     * Attempting to actually read this value will result in an exception.
+     */
+    T: T;
+    toString(): string;
+    $$ref: 'service';
+};
+
+/**
+ * @public
+ */
+export declare const tokenManagerServiceRef: ServiceRef<TokenManager>;
+
+/** @public */
+export declare type TypesToServiceRef<T> = {
+    [key in keyof T]: ServiceRef<T[key]>;
+};
+
+/**
+ * @public
+ */
+export declare const urlReaderServiceRef: ServiceRef<UrlReader>;
+
+export { }

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@backstage/backend-plugin-api",
+  "description": "Core API used by Backstage backend plugins",
+  "version": "0.0.0-nightly-20220709024234",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts",
+    "alphaTypes": "dist/index.alpha.d.ts"
+  },
+  "backstage": {
+    "role": "node-library"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "packages/backend-plugin-api"
+  },
+  "keywords": [
+    "backstage"
+  ],
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "backstage-cli package build --experimental-type-build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack",
+    "clean": "backstage-cli package clean",
+    "start": "backstage-cli package start"
+  },
+  "dependencies": {
+    "@backstage/config": "^1.0.1",
+    "@backstage/backend-common": "0.0.0-nightly-20220709024234",
+    "@backstage/plugin-permission-common": "0.0.0-nightly-20220709024234",
+    "@backstage/backend-tasks": "0.0.0-nightly-20220709024234",
+    "@types/express": "^4.17.6",
+    "express": "^4.17.1",
+    "winston": "^3.2.1",
+    "winston-transport": "^4.5.0"
+  },
+  "devDependencies": {
+    "@backstage/cli": "0.0.0-nightly-20220709024234"
+  },
+  "files": [
+    "dist",
+    "alpha"
+  ]
+}