@backstage/backend-common
Home > @backstage/backend-common
Common functionality library for Backstage backends
Classes
| Class | Description |
|---|---|
| AwsS3UrlReader | Implements a UrlReaderService for AWS S3 buckets. |
| AzureUrlReader | Implements a UrlReaderService for Azure repos. |
| BitbucketCloudUrlReader | Implements a UrlReaderService for files from Bitbucket Cloud. |
| BitbucketServerUrlReader | Implements a UrlReaderService for files from Bitbucket Server APIs. |
| BitbucketUrlReader | Implements a UrlReaderService for files from Bitbucket v1 and v2 APIs, such as the one exposed by Bitbucket Cloud itself. |
| CacheManager | Implements a Cache Manager which will automatically create new cache clients for plugins when requested. All requested cache clients are created with the connection details provided. |
| DatabaseManager | Manages database connections for Backstage backend plugins. |
| DockerContainerRunner | A ContainerRunner for Docker containers. |
| FetchUrlReader | A UrlReaderService that does a plain fetch of the URL. |
| GerritUrlReader | Implements a UrlReaderService for files in Gerrit. |
| Git | A convenience wrapper around the isomorphic-git library. |
| GiteaUrlReader | Implements a UrlReaderService for the Gitea v1 api. |
| GithubUrlReader | Implements a UrlReaderService for files through the GitHub v3 APIs, such as the one exposed by GitHub itself. |
| GitlabUrlReader | Implements a UrlReaderService for files on GitLab. |
| KubernetesContainerRunner | A ContainerRunner for Kubernetes. Runs containers leveraging Jobs on a Kubernetes cluster |
| ReadUrlResponseFactory | Utility class for UrlReader implementations to create valid ReadUrlResponse instances from common response primitives. |
| ServerTokenManager | Creates and validates tokens for use during service-to-service authentication. |
| UrlReaders | Helps construct UrlReaderServices. |
Functions
| Function | Description |
|---|---|
| cacheToPluginCacheManager(cache) | |
| createDatabaseClient(dbConfig, overrides, deps) | Creates a knex database connection |
| createLegacyAuthAdapters(options) | An adapter that ensures presence of the auth and/or httpAuth services. |
| createRootLogger(options, env) | Creates a default "root" logger. This also calls setRootLogger() under the hood. |
| createServiceBuilder(_module) | Creates a new service builder. |
| createStatusCheckRouter(options) | Creates a default status checking router, that you can add to your express app. |
| dropDatabase(dbConfig, databases) | Drops the given databases. |
| ensureDatabaseExists(dbConfig, databases) | Ensures that the given databases all exist, creating them if they do not. |
| errorHandler(options) | Express middleware to handle errors during request processing. This is commonly the very last middleware in the chain. Its primary purpose is not to do translation of business logic exceptions, but rather to be a global catch-all for uncaught "fatal" errors that are expected to result in a 500 error. However, it also does handle some common error types (such as http-error exceptions) and returns the enclosed status code accordingly. |
| getRootLogger() | Gets the current root logger. |
| getVoidLogger() | A logger that just throws away all messages. |
| isDatabaseConflictError(e) | Tries to deduce whether a thrown error is a database conflict. |
| loadBackendConfig(options) | Load configuration for a Backend. This function should only be called once, during the initialization of the backend. |
| loggerToWinstonLogger(logger, opts) | |
| makeLegacyPlugin(envMapping, envTransforms) | Creates a new custom plugin compatibility wrapper. |
| notFoundHandler() | Express middleware to handle requests for missing routes. Should be used as the very last handler in the chain, as it unconditionally returns a 404 status. |
| redactWinstonLogLine(info) | A winston formatting function that finds occurrences of filteredKeys and replaces them with the corresponding identifier. |
| requestLoggingHandler(logger) | Logs incoming requests. |
| resolvePackagePath(name, paths) | Resolve a path relative to the root of a package directory. Additional path arguments are resolved relative to the package dir. This is particularly useful when you want to access assets shipped with your backend plugin package. When doing so, do not forget to include the assets in your published package by adding them to |
| resolveSafeChildPath(base, path) | Resolves a target path from a base path while guaranteeing that the result is a path that point to or within the base path. This is useful for resolving paths from user input, as it otherwise opens up for vulnerabilities. |
| setRootLogger(newLogger) | Sets a completely custom default "root" logger. |
| statusCheckHandler(options) | Express middleware for status checks. This is commonly used to implement healthcheck and readiness routes. |
| useHotCleanup(_module, cancelEffect) | useHotCleanup allows cleanup of ongoing effects when a module is hot-reloaded during development. The cleanup function will be called whenever the module itself or any of its parent modules is hot-reloaded. Useful for cleaning intervals, timers, requests etc |
| useHotMemoize(_module, valueFactory) | Memoizes a generated value across hot-module reloads. This is useful for stateful parts of the backend, e.g. to retain a database. |
Interfaces
| Interface | Description |
|---|---|
| ContainerRunner | Handles the running of containers, on behalf of others. |
| PluginCacheManager | |
| PullOptions | Allows defining access credentials for a registry Follows dockerode auth configuration: https://github.com/apocas/dockerode?tab=readme-ov-file#pull-from-private-repos |
| ReadTreeResponseFactory | A factory for response factories that handle the unpacking and inspection of complex responses such as archive data. |
| ServerTokenManagerOptions | Options for ServerTokenManager. |
| StatusCheckHandlerOptions | Options passed to statusCheckHandler(). |
Variables
| Variable | Description |
|---|---|
| coloredFormat | Creates a pretty printed winston log formatter. |
| HostDiscovery | HostDiscovery is a basic PluginEndpointDiscovery implementation that can handle plugins that are hosted in a single or multiple deployments. The deployment may be scaled horizontally, as long as the external URL is the same for all instances. However, internal URLs will always be resolved to the same host, so there won't be any balancing of internal traffic. |
| legacyPlugin | Helper function to create a plugin from a legacy createRouter function and register it with the http router based on the plugin id. |
| SingleHostDiscovery | SingleHostDiscovery is a basic PluginEndpointDiscovery implementation that assumes that all plugins are hosted in a single deployment. The deployment may be scaled horizontally, as long as the external URL is the same for all instances. However, internal URLs will always be resolved to the same host, so there won't be any balancing of internal traffic. |
Type Aliases
| Type Alias | Description |
|---|---|
| AuthCallbackOptions | Configure an authentication callback that can provide credentials on demand |
| CacheManagerOptions | Options given when constructing a CacheManager. |
| DatabaseManagerOptions | Creation options for DatabaseManager. |
| ErrorHandlerOptions | Options passed to the errorHandler() middleware. |
| FromReadableArrayOptions | Options that control ReadTreeResponseFactory.fromReadableArray() execution. |
| KubernetesContainerRunnerMountBase | An existing Kubernetes volume that will be used as base for mounts. Every mount must start with the 'basePath'. |
| KubernetesContainerRunnerOptions | Options to create a KubernetesContainerRunner Kubernetes Jobs will be created on the provided 'namespace' and their names will be prefixed with the provided 'name'. 'podTemplate' defines a Pod template for the Jobs. It has to include a volume definition named as the KubernetesContainerRunnerMountBase 'volumeName'. |
| LegacyCreateRouter | |
| LegacyRootDatabaseService | An interface that represents the legacy global DatabaseManager implementation. |
| ReaderFactory | A factory function that can read config to construct zero or more UrlReaderServices along with a predicate for when it should be used. |
| ReadTreeResponseFactoryOptions | Options that control execution of ReadTreeResponseFactory methods. |
| ReadUrlResponseFactoryFromStreamOptions | An options object for ReadUrlResponseFactory factory methods. |
| RequestLoggingHandlerFactory | A factory for request loggers. |
| RunContainerOptions | Options passed to the ContainerRunner.runContainer() method. |
| ServiceBuilder | A helper for building backend service instances. |
| StaticAuthOptions | Configure static credential for authentication |
| StatusCheck | A custom status checking function, passed to statusCheckHandler() and createStatusCheckRouter(). |
| UrlReaderPredicateTuple | A predicate that decides whether a specific UrlReaderService can handle a given URL. |
| UrlReadersOptions | Creation options for UrlReaderService. |