api-report.md

API Report File for "@backstage/backend-plugin-api"

Do not edit this file. It is a report generated by API Extractor.

/// <reference types="node" />

import { Config } from '@backstage/config';
import { Handler } from 'express';
import { IdentityApi } from '@backstage/plugin-auth-node';
import { JsonObject } from '@backstage/types';
import { JsonValue } from '@backstage/types';
import { Knex } from 'knex';
import { PermissionEvaluator } from '@backstage/plugin-permission-common';
import { PluginTaskScheduler } from '@backstage/backend-tasks';
import { Readable } from 'stream';

// @public (undocumented)
export interface BackendFeature {
  // (undocumented)
  $$type: '@backstage/BackendFeature';
}

// @public
export interface BackendModuleConfig {
  moduleId: string;
  pluginId: string;
  // (undocumented)
  register(reg: BackendModuleRegistrationPoints): void;
}

// @public
export interface BackendModuleRegistrationPoints {
  // (undocumented)
  registerInit<
    Deps extends {
      [name in string]: unknown;
    },
  >(options: {
    deps: {
      [name in keyof Deps]: ServiceRef<Deps[name]> | ExtensionPoint<Deps[name]>;
    };
    init(deps: Deps): Promise<void>;
  }): void;
}

// @public
export interface BackendPluginConfig {
  pluginId: string;
  // (undocumented)
  register(reg: BackendPluginRegistrationPoints): void;
}

// @public
export interface BackendPluginRegistrationPoints {
  // (undocumented)
  registerExtensionPoint<TExtensionPoint>(
    ref: ExtensionPoint<TExtensionPoint>,
    impl: TExtensionPoint,
  ): void;
  // (undocumented)
  registerInit<
    Deps extends {
      [name in string]: unknown;
    },
  >(options: {
    deps: {
      [name in keyof Deps]: ServiceRef<Deps[name]>;
    };
    init(deps: Deps): Promise<void>;
  }): void;
}

// @public
export interface CacheService {
  delete(key: string): Promise<void>;
  get<TValue extends JsonValue>(key: string): Promise<TValue | undefined>;
  set(
    key: string,
    value: JsonValue,
    options?: CacheServiceSetOptions,
  ): Promise<void>;
  withOptions(options: CacheServiceOptions): CacheService;
}

// @public
export type CacheServiceOptions = {
  defaultTtl?: number;
};

// @public
export type CacheServiceSetOptions = {
  ttl?: number;
};

// @public (undocumented)
export interface ConfigService extends Config {}

// @public
export namespace coreServices {
  const cache: ServiceRef<CacheService, 'plugin'>;
  const config: ServiceRef<ConfigService, 'root'>;
  const database: ServiceRef<DatabaseService, 'plugin'>;
  const discovery: ServiceRef<DiscoveryService, 'plugin'>;
  const httpRouter: ServiceRef<HttpRouterService, 'plugin'>;
  const lifecycle: ServiceRef<LifecycleService, 'plugin'>;
  const logger: ServiceRef<LoggerService, 'plugin'>;
  const permissions: ServiceRef<PermissionsService, 'plugin'>;
  const pluginMetadata: ServiceRef<PluginMetadataService, 'plugin'>;
  const rootHttpRouter: ServiceRef<RootHttpRouterService, 'root'>;
  const rootLifecycle: ServiceRef<RootLifecycleService, 'root'>;
  const rootLogger: ServiceRef<RootLoggerService, 'root'>;
  const scheduler: ServiceRef<SchedulerService, 'plugin'>;
  const tokenManager: ServiceRef<TokenManagerService, 'plugin'>;
  const urlReader: ServiceRef<UrlReaderService, 'plugin'>;
  const identity: ServiceRef<IdentityService, 'plugin'>;
}

// @public
export function createBackendModule<TOptions extends [options?: object] = []>(
  config: BackendModuleConfig | ((...params: TOptions) => BackendModuleConfig),
): (...params: TOptions) => BackendFeature;

// @public
export function createBackendPlugin<TOptions extends [options?: object] = []>(
  config: BackendPluginConfig | ((...params: TOptions) => BackendPluginConfig),
): (...params: TOptions) => BackendFeature;

// @public
export function createExtensionPoint<T>(
  config: ExtensionPointConfig,
): ExtensionPoint<T>;

// @public
export function createServiceFactory<
  TService,
  TImpl extends TService,
  TDeps extends {
    [name in string]: ServiceRef<unknown>;
  },
  TOpts extends object | undefined = undefined,
>(
  config: RootServiceFactoryConfig<TService, TImpl, TDeps>,
): () => ServiceFactory<TService, 'root'>;

// @public
export function createServiceFactory<
  TService,
  TImpl extends TService,
  TDeps extends {
    [name in string]: ServiceRef<unknown>;
  },
  TOpts extends object | undefined = undefined,
>(
  config: (options?: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>,
): (options?: TOpts) => ServiceFactory<TService, 'root'>;

// @public
export function createServiceFactory<
  TService,
  TImpl extends TService,
  TDeps extends {
    [name in string]: ServiceRef<unknown>;
  },
  TOpts extends object | undefined = undefined,
>(
  config: (options: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>,
): (options: TOpts) => ServiceFactory<TService, 'root'>;

// @public
export function createServiceFactory<
  TService,
  TImpl extends TService,
  TDeps extends {
    [name in string]: ServiceRef<unknown>;
  },
  TContext = undefined,
  TOpts extends object | undefined = undefined,
>(
  config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,
): () => ServiceFactory<TService, 'plugin'>;

// @public
export function createServiceFactory<
  TService,
  TImpl extends TService,
  TDeps extends {
    [name in string]: ServiceRef<unknown>;
  },
  TContext = undefined,
  TOpts extends object | undefined = undefined,
>(
  config: (
    options?: TOpts,
  ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,
): (options?: TOpts) => ServiceFactory<TService, 'plugin'>;

// @public
export function createServiceFactory<
  TService,
  TImpl extends TService,
  TDeps extends {
    [name in string]: ServiceRef<unknown>;
  },
  TContext = undefined,
  TOpts extends object | undefined = undefined,
>(
  config:
    | PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>
    | ((
        options: TOpts,
      ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>),
): (options: TOpts) => ServiceFactory<TService, 'plugin'>;

// @public
export function createServiceRef<TService>(
  config: ServiceRefConfig<TService, 'plugin'>,
): ServiceRef<TService, 'plugin'>;

// @public
export function createServiceRef<TService>(
  config: ServiceRefConfig<TService, 'root'>,
): ServiceRef<TService, 'root'>;

// @public
export function createSharedEnvironment<
  TOptions extends [options?: object] = [],
>(
  config:
    | SharedBackendEnvironmentConfig
    | ((...params: TOptions) => SharedBackendEnvironmentConfig),
): (...options: TOptions) => SharedBackendEnvironment;

// @public
export interface DatabaseService {
  getClient(): Promise<Knex>;
  migrations?: {
    skip?: boolean;
  };
}

// @public
export interface DiscoveryService {
  getBaseUrl(pluginId: string): Promise<string>;
  getExternalBaseUrl(pluginId: string): Promise<string>;
}

// @public
export type ExtensionPoint<T> = {
  id: string;
  T: T;
  toString(): string;
  $$type: '@backstage/ExtensionPoint';
};

// @public
export interface ExtensionPointConfig {
  id: string;
}

// @public (undocumented)
export interface HttpRouterService {
  // (undocumented)
  use(handler: Handler): void;
}

// @public (undocumented)
export interface IdentityService extends IdentityApi {}

// @public (undocumented)
export interface LifecycleService {
  addShutdownHook(
    hook: LifecycleServiceShutdownHook,
    options?: LifecycleServiceShutdownOptions,
  ): void;
  addStartupHook(
    hook: LifecycleServiceStartupHook,
    options?: LifecycleServiceStartupOptions,
  ): void;
}

// @public (undocumented)
export type LifecycleServiceShutdownHook = () => void | Promise<void>;

// @public (undocumented)
export interface LifecycleServiceShutdownOptions {
  logger?: LoggerService;
}

// @public (undocumented)
export type LifecycleServiceStartupHook = () => void | Promise<void>;

// @public (undocumented)
export interface LifecycleServiceStartupOptions {
  logger?: LoggerService;
}

// @public
export interface LoggerService {
  // (undocumented)
  child(meta: JsonObject): LoggerService;
  // (undocumented)
  debug(message: string, meta?: Error | JsonObject): void;
  // (undocumented)
  error(message: string, meta?: Error | JsonObject): void;
  // (undocumented)
  info(message: string, meta?: Error | JsonObject): void;
  // (undocumented)
  warn(message: string, meta?: Error | JsonObject): void;
}

// @public (undocumented)
export interface PermissionsService extends PermissionEvaluator {}

// @public (undocumented)
export interface PluginMetadataService {
  // (undocumented)
  getId(): string;
}

// @public (undocumented)
export interface PluginServiceFactoryConfig<
  TService,
  TContext,
  TImpl extends TService,
  TDeps extends {
    [name in string]: ServiceRef<unknown>;
  },
> {
  // (undocumented)
  createRootContext?(
    deps: ServiceRefsToInstances<TDeps, 'root'>,
  ): TContext | Promise<TContext>;
  // (undocumented)
  deps: TDeps;
  // (undocumented)
  factory(
    deps: ServiceRefsToInstances<TDeps>,
    context: TContext,
  ): TImpl | Promise<TImpl>;
  // (undocumented)
  service: ServiceRef<TService, 'plugin'>;
}

// @public
export type ReadTreeOptions = {
  filter?(
    path: string,
    info?: {
      size: number;
    },
  ): boolean;
  etag?: string;
  signal?: AbortSignal;
};

// @public
export type ReadTreeResponse = {
  files(): Promise<ReadTreeResponseFile[]>;
  archive(): Promise<NodeJS.ReadableStream>;
  dir(options?: ReadTreeResponseDirOptions): Promise<string>;
  etag: string;
};

// @public
export type ReadTreeResponseDirOptions = {
  targetDir?: string;
};

// @public
export type ReadTreeResponseFile = {
  path: string;
  content(): Promise<Buffer>;
  lastModifiedAt?: Date;
};

// @public
export type ReadUrlOptions = {
  etag?: string;
  lastModifiedAfter?: Date;
  signal?: AbortSignal;
};

// @public
export type ReadUrlResponse = {
  buffer(): Promise<Buffer>;
  stream?(): Readable;
  etag?: string;
  lastModifiedAt?: Date;
};

// @public (undocumented)
export interface RootHttpRouterService {
  use(path: string, handler: Handler): void;
}

// @public (undocumented)
export interface RootLifecycleService extends LifecycleService {}

// @public (undocumented)
export interface RootLoggerService extends LoggerService {}

// @public (undocumented)
export interface RootServiceFactoryConfig<
  TService,
  TImpl extends TService,
  TDeps extends {
    [name in string]: ServiceRef<unknown>;
  },
> {
  // (undocumented)
  deps: TDeps;
  // (undocumented)
  factory(deps: ServiceRefsToInstances<TDeps, 'root'>): TImpl | Promise<TImpl>;
  // (undocumented)
  service: ServiceRef<TService, 'root'>;
}

// @public (undocumented)
export interface SchedulerService extends PluginTaskScheduler {}

// @public
export type SearchOptions = {
  etag?: string;
  signal?: AbortSignal;
};

// @public
export type SearchResponse = {
  files: SearchResponseFile[];
  etag: string;
};

// @public
export type SearchResponseFile = {
  url: string;
  content(): Promise<Buffer>;
  lastModifiedAt?: Date;
};

// @public (undocumented)
export interface ServiceFactory<
  TService = unknown,
  TScope extends 'plugin' | 'root' = 'plugin' | 'root',
> {
  // (undocumented)
  $$type: '@backstage/ServiceFactory';
  // (undocumented)
  service: ServiceRef<TService, TScope>;
}

// @public
export type ServiceFactoryOrFunction = ServiceFactory | (() => ServiceFactory);

// @public
export type ServiceRef<
  TService,
  TScope extends 'root' | 'plugin' = 'root' | 'plugin',
> = {
  id: string;
  scope: TScope;
  T: TService;
  toString(): string;
  $$type: '@backstage/ServiceRef';
};

// @public (undocumented)
export interface ServiceRefConfig<TService, TScope extends 'root' | 'plugin'> {
  // (undocumented)
  defaultFactory?: (
    service: ServiceRef<TService, TScope>,
  ) => Promise<ServiceFactoryOrFunction>;
  // (undocumented)
  id: string;
  // (undocumented)
  scope?: TScope;
}

// @public
export interface SharedBackendEnvironment {
  // (undocumented)
  $$type: '@backstage/SharedBackendEnvironment';
}

// @public
export interface SharedBackendEnvironmentConfig {
  // (undocumented)
  services?: ServiceFactoryOrFunction[];
}

// @public
export interface TokenManagerService {
  authenticate(token: string): Promise<void>;
  getToken(): Promise<{
    token: string;
  }>;
}

// @public
export interface UrlReaderService {
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  search(url: string, options?: SearchOptions): Promise<SearchResponse>;
}