paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 36 Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'upstream/master' into feat/placeholder-resolve

Browse Source
This commit is contained in:
Dominik Henneke
2021-09-08 09:58:07 +02:00
parent dbb9527878 96f239228a
commit 9554de545b
154 changed files with 1517 additions and 746 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/bright-birds-jog.md
+14
View File
@@ -0,0 +1,14 @@
---
'@backstage/core-components': patch
---
Fix warning produced by BottomLink component
During development, we noticed warnings such as:
```
react_devtools_backend.js:2842 Warning: validateDOMNesting(...): <div> cannot appear as a descendant of <p>.
```
The BottomLink component renders a Box component within a Typography component which leads to a div tag within a p tag.
This change inverts that ordering without changing the visual appearance.
.changeset/dull-trains-shout.md
+11
View File
@@ -0,0 +1,11 @@
---
'@backstage/backend-test-utils': patch
'@backstage/catalog-client': patch
'@backstage/catalog-model': patch
'@backstage/cli-common': patch
'@backstage/config-loader': patch
'@backstage/dev-utils': patch
'@backstage/errors': patch
---
Properly export all used types.
.changeset/forty-moons-boil.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-todo': patch
---
All types are now properly documented and exported.
.changeset/good-singers-flourish.md
+6
View File
@@ -0,0 +1,6 @@
---
'@backstage/plugin-home': minor
---
Rename RandomJokeHomePageComponent to HomePageRandomJoke to fit convention, and update example app accordingly.
**NOTE**: If you're using the RandomJoke component in your instance, it now has to be renamed to `HomePageRandomJoke`
.changeset/great-balloons-walk.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/config': patch
---
Documented `Config` interface and mark types as public.
.changeset/long-walls-tie.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-scaffolder-backend': patch
---
GitHub Webhook action in Scaffolder Backend has been improved to validate event names against Octokit Webhook event names list.
.changeset/strong-pears-wink.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-scaffolder': patch
---
Fix display error when it fails to load a template (/create) page
.changeset/twenty-ravens-fetch.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-search': patch
---
Add Home Page Search Bar Component, to be included in composable Home Page.
.changeset/wise-monkeys-enjoy.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/backend-common': patch
---
Properly export all used types.
.changeset/yellow-hats-sniff.md
+6
View File
@@ -0,0 +1,6 @@
---
'@backstage/cli': patch
---
Support importing font files in tests.
This fixes remaining issues from [#7019](https://github.com/backstage/backstage/pull/7019).
.snyk
+10
View File
@@ -0,0 +1,10 @@
# Snyk (https://snyk.io) policy file, patches or ignores known vulnerabilities.
version: v1.22.1
# ignores vulnerabilities until expiry date; change duration by modifying expiry date
ignore:
SNYK-JS-ANSIHTML-1296849:
- '@backstage/cli > webpack-dev-server > ansi-html':
reason: Developer tools are not a valid target for ReDoS attacks
expires: 2022-03-06T17:18:55.019Z
created: 2021-09-06T17:18:55.027Z
patch: {}
docs/assets/features/catalog/life-of-an-entity_processing.svg
+3
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

docs/assets/features/catalog/life-of-an-entity_stitching.svg
+3
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

docs/features/software-catalog/life-of-an-entity.md
+120 -4
View File
@@ -111,20 +111,136 @@ as possible.
Each catalog deployment has a number of processors installed. They are
responsible for receiving unprocessed entities that the catalog decided are due
for processing, and then running that data through a number of processing
stages. mutating the entity and emitting auxiliary data about it. When all of
stages, mutating the entity and emitting auxiliary data about it. When all of
that is done, the catalog takes all of that information and stores it as the
processed entity, and errors and relations to other entities separately. Then,
the catalog checks to see what entities are touched by that output, and triggers
the final assembly of those (see Stitching below).
There are several stages involved in the processing.
![Processing overview](../../assets/features/catalog/life-of-an-entity_processing.svg)
> TODO: More info here
Entities are always processed one by one, but all of your catalog service hosts
collaborate in doing so to distribute the load. Note how each processor can
contribute to one or more of the fixed steps in the processing pipeline. First
all of the processors' contributions to one step are run in the order that the
processors were registered, then all of their contributions to the next step in
the same order, and so on.
Each step has the opportunity to optionally modify the entity, and to optionally
emit other information. For example, the processor might look at information in
the `spec` field of the entity, and emit relations that correspond to those
declarations. If the processor emits an entity, then that entity gets stored
verbatim with a timestamp saying that it, too, should be processed as soon as
possible. If errors are emitted, then that signals that something is wrong with
the entity and that it should not replace whatever previously error-free version
we had among the final entities. If relations are emitted, then they are put in
a dedicated relations table to be picked up by the stitching process below.
> Optional low level detail note: When entities are emitted, the catalog keeps
> track of the edges between the emitting entity and the ones emitted. This
> happens behind the scenes, hidden from the outside, and is used to form a
> graph. This is _not_ the same thing as relations! The purpose of these edges,
> is to be able to detect when an entity becomes orphaned (see below), and to be
> able to perform eager deletions throughout the graph when a root is explicitly
> unregistered and nothing else is keeping lower nodes alive. We will talk more
> about orphaning and deletions later on in this article.
When the final step has completed, and no errors were encountered, the processed
entity and all of the relations are finally persisted in the database. Then the
catalog considers this entity, and all of the entities it had relations to,
subject for stitching.
It is worth noting here that the processing does not lead to deletion or
unregistration of entities; it can only call new entities into existence or
update entities that it has previously called into existence. More about that
later.
## Stitching
Stitching finalizes the entity, by gathering all of the output from the previous
steps and merging them into the final object which is what is visible from the
catalog API. As the final entity itself gets updated, the stitcher makes sure
that the search table gets refreshed accordingly as well.
> Note: The search table mentioned here is not related to the core Search
> feature of Backstage. It's rather the table that backs the ability to filter
> catalog API query results.
![Stitching overview](../../assets/features/catalog/life-of-an-entity_stitching.svg)
The diagram shows how the stitcher reads from several sources:
- The processed entity, as returned from the processing step
- The errors, if any, that were emitted by the processing step
- All relations that were emitted by the processing step, as well as any
relations emitted by _other_ entity processing steps that happen to point at
the current entity
The last part is noteworthy: This is how the stitcher is able to collect all of
the relation edges, both incoming and outgoing, no matter who produced them.
The stitching is currently a fixed process, that cannot be modified or extended.
This means that any modifications you want to make on the final result, has to
happen during ingestion or processing.
> TODO: More info here
## Errors
> TODO: Describe how errors are exposed through entities
## Orphaning
As mentioned earlier, entities internally form a graph. The edges go from
processed parent entities, to child entities emitted while processing the
parent.
The processing loop runs continuously, so these edges are reconsidered over
time. If processing a parent entity no longer emits a given child entity, then
that former edge is severed. If that child has no other edges pointing at it
either, it becomes _orphaned_. The end result is as follows:
- The stitching process injects a `backstage.io/orphan: 'true'` annotation on
the child entity.
- The child entity is _not_ removed from the catalog, but stays around until
explicitly deleted via the catalog API, or "reclaimed" by the original parent
or another parent starting to reference it.
- The catalog page in Backstage for the child entity detects the new annotation
and informs users about the orphan status.
Orphaning can occur in several different scenarios. One common cause is that the
end user edited a corresponding catalog catalog-info YAML file removing the
entity's entry. In the case of a `Location` parent entity, orphaning can happen
if removing the target line pointing to the file containing the child entity.
Another common cause is large batch processors such as the ones that crawl
through remote systems looking for entities, no longer finding something that it
used to find before. Maybe the data was moved, or deleted, in the remote system.
So for example when a person leaves the company an LDAP org discovery processor
might leave an orphaned `User` entity behind. Note that this only applies to
processors - ingestion that happens using entity providers work differently,
described below.
> Note that removing a file, or accidentally corrupting a file so that it cannot
> be read successfully, does _not_ lead to orphaning. Hard errors, including the
> inability to find or read a distinct remote, are marked as such on the entity
> to inform the owner that something is wrong. But processing and other
> behaviors continue as usual.
The reason that the orphaning mechanism exists instead of having an eager
deletion triggered, is safety. Scenarios like these can happen purely by
accident, due to the asynchronous nature of the system and the fallible nature
of humans. In particular when external systems start consuming and relying on
the catalog, there could be substantial consequences to suddenly dropping
entities without explicit owner consent. The catalog therefore takes the stance
that entities that often were added by direct user action should also be deleted
only by direct user action.
It is possible to use the catalog API to build automated "reaper" systems that
finally delete entities that are orphaned. This is however not something that's
provided out of the box.
## Implicit Deletion
> TODO: Describe the process of entity providers eagerly deleting entities
## Explicit Deletion
> TODO: Describe direct deletion via the catalog API
packages/app/src/components/home/HomePage.tsx
+12 -11
View File
@@ -17,27 +17,28 @@
import React from 'react';
import Grid from '@material-ui/core/Grid';
import {
RandomJokeHomePageComponent,
HomePageRandomJoke,
ComponentAccordion,
ComponentTabs,
ComponentTab,
} from '@backstage/plugin-home';
import { HomePageSearchBar } from '@backstage/plugin-search';
export const HomePage = () => (
<Grid container spacing={3}>
<Grid item xs={12} md={4}>
<RandomJokeHomePageComponent />
<Grid item xs={12}>
<HomePageSearchBar />
</Grid>
<Grid item xs={12} md={4}>
<RandomJokeHomePageComponent
defaultCategory="any"
Renderer={ComponentAccordion}
/>
<RandomJokeHomePageComponent
<HomePageRandomJoke />
</Grid>
<Grid item xs={12} md={4}>
<HomePageRandomJoke defaultCategory="any" Renderer={ComponentAccordion} />
<HomePageRandomJoke
title="Another Random Joke"
Renderer={ComponentAccordion}
/>
<RandomJokeHomePageComponent
<HomePageRandomJoke
title="One More Random Joke"
defaultCategory="programming"
Renderer={ComponentAccordion}
@@ -50,7 +51,7 @@ export const HomePage = () => (
{
label: 'Programming',
Component: () => (
<RandomJokeHomePageComponent
<HomePageRandomJoke
defaultCategory="programming"
Renderer={ComponentTab}
/>
@@ -59,7 +60,7 @@ export const HomePage = () => (
{
label: 'Any',
Component: () => (
<RandomJokeHomePageComponent
<HomePageRandomJoke
defaultCategory="any"
Renderer={ComponentTab}
/>
packages/backend-common/api-report.md
+76 -160
View File
@@ -9,7 +9,6 @@
import { AzureIntegration } from '@backstage/integration';
import { BitbucketIntegration } from '@backstage/integration';
import { Config } from '@backstage/config';
import { ConfigReader } from '@backstage/config';
import cors from 'cors';
import Docker from 'dockerode';
import { ErrorRequestHandler } from 'express';
@@ -17,7 +16,6 @@ import express from 'express';
import { GithubCredentialsProvider } from '@backstage/integration';
import { GitHubIntegration } from '@backstage/integration';
import { GitLabIntegration } from '@backstage/integration';
import * as http from 'http';
import { isChildPath } from '@backstage/cli-common';
import { JsonValue } from '@backstage/config';
import { Knex } from 'knex';
@@ -32,8 +30,6 @@ import { Server } from 'http';
import * as winston from 'winston';
import { Writable } from 'stream';
// Warning: (ae-missing-release-tag) "AzureUrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export class AzureUrlReader implements UrlReader {
constructor(
@@ -56,8 +52,6 @@ export class AzureUrlReader implements UrlReader {
toString(): string;
}
// Warning: (ae-missing-release-tag) "BitbucketUrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export class BitbucketUrlReader implements UrlReader {
constructor(
@@ -80,92 +74,82 @@ export class BitbucketUrlReader implements UrlReader {
toString(): string;
}
// Warning: (ae-missing-release-tag) "CacheClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export interface CacheClient {
delete(key: string): Promise<void>;
get(key: string): Promise<JsonValue | undefined>;
// Warning: (ae-forgotten-export) The symbol "CacheSetOptions" needs to be exported by the entry point index.d.ts
set(key: string, value: JsonValue, options?: CacheSetOptions): Promise<void>;
set(
key: string,
value: JsonValue,
options?: CacheClientSetOptions,
): Promise<void>;
}
// Warning: (ae-missing-release-tag) "CacheManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type CacheClientOptions = {
defaultTtl?: number;
};
// @public (undocumented)
export type CacheClientSetOptions = {
ttl?: number;
};
// @public
export class CacheManager {
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
forPlugin(pluginId: string): PluginCacheManager;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-forgotten-export) The symbol "CacheManagerOptions" needs to be exported by the entry point index.d.ts
static fromConfig(
config: Config,
options?: CacheManagerOptions,
): CacheManager;
}
// Warning: (ae-missing-release-tag) "coloredFormat" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type CacheManagerOptions = {
logger?: Logger_2;
onError?: (err: Error) => void;
};
// @public (undocumented)
export const coloredFormat: winston.Logform.Format;
// Warning: (ae-missing-release-tag) "ContainerRunner" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export interface ContainerRunner {
// (undocumented)
runContainer(opts: RunContainerOptions): Promise<void>;
}
// Warning: (ae-missing-release-tag) "createDatabase" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public @deprecated
export const createDatabase: typeof createDatabaseClient;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "createDatabaseClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function createDatabaseClient(
dbConfig: Config,
overrides?: Partial<Knex.Config>,
): Knex<any, unknown[]>;
// Warning: (ae-missing-release-tag) "createRootLogger" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export function createRootLogger(
options?: winston.LoggerOptions,
env?: NodeJS.ProcessEnv,
): winston.Logger;
// Warning: (ae-forgotten-export) The symbol "ServiceBuilderImpl" needs to be exported by the entry point index.d.ts
// Warning: (ae-missing-release-tag) "createServiceBuilder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function createServiceBuilder(_module: NodeModule): ServiceBuilderImpl;
export function createServiceBuilder(_module: NodeModule): ServiceBuilder;
// Warning: (ae-forgotten-export) The symbol "StatusCheckRouterOptions" needs to be exported by the entry point index.d.ts
// Warning: (ae-missing-release-tag) "createStatusCheckRouter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export function createStatusCheckRouter(
options: StatusCheckRouterOptions,
): Promise<express.Router>;
export function createStatusCheckRouter(options: {
logger: Logger_2;
path?: string;
statusCheck?: StatusCheck;
}): Promise<express.Router>;
// Warning: (ae-missing-release-tag) "DatabaseManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export class DatabaseManager {
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
forPlugin(pluginId: string): PluginDatabaseManager;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
static fromConfig(config: Config): DatabaseManager;
}
// Warning: (ae-missing-release-tag) "DockerContainerRunner" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export class DockerContainerRunner implements ContainerRunner {
constructor({ dockerClient }: { dockerClient: Docker });
@@ -182,23 +166,17 @@ export class DockerContainerRunner implements ContainerRunner {
}: RunContainerOptions): Promise<void>;
}
// Warning: (ae-missing-release-tag) "ensureDatabaseExists" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function ensureDatabaseExists(
dbConfig: Config,
...databases: Array<string>
): Promise<void>;
// Warning: (ae-missing-release-tag) "errorHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function errorHandler(
options?: ErrorHandlerOptions,
): ErrorRequestHandler;
// Warning: (ae-missing-release-tag) "ErrorHandlerOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type ErrorHandlerOptions = {
showStackTraces?: boolean;
@@ -206,18 +184,12 @@ export type ErrorHandlerOptions = {
logClientErrors?: boolean;
};
// Warning: (ae-missing-release-tag) "getRootLogger" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export function getRootLogger(): winston.Logger;
// Warning: (ae-missing-release-tag) "getVoidLogger" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function getVoidLogger(): winston.Logger;
// Warning: (ae-missing-release-tag) "Git" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export class Git {
// (undocumented)
@@ -322,8 +294,6 @@ export class Git {
resolveRef({ dir, ref }: { dir: string; ref: string }): Promise<string>;
}
// Warning: (ae-missing-release-tag) "GithubUrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export class GithubUrlReader implements UrlReader {
constructor(
@@ -347,8 +317,6 @@ export class GithubUrlReader implements UrlReader {
toString(): string;
}
// Warning: (ae-missing-release-tag) "GitlabUrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export class GitlabUrlReader implements UrlReader {
constructor(
@@ -373,41 +341,31 @@ export class GitlabUrlReader implements UrlReader {
export { isChildPath };
// Warning: (ae-forgotten-export) The symbol "Options" needs to be exported by the entry point index.d.ts
// Warning: (ae-missing-release-tag) "loadBackendConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function loadBackendConfig(options: Options): Promise<Config>;
export function loadBackendConfig(options: {
logger: Logger_2;
argv: string[];
}): Promise<Config>;
// Warning: (ae-missing-release-tag) "notFoundHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function notFoundHandler(): RequestHandler;
// Warning: (ae-missing-release-tag) "PluginCacheManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type PluginCacheManager = {
getClient: (options?: ClientOptions) => CacheClient;
getClient: (options?: CacheClientOptions) => CacheClient;
};
// Warning: (ae-missing-release-tag) "PluginDatabaseManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export interface PluginDatabaseManager {
getClient(): Promise<Knex>;
}
// Warning: (ae-missing-release-tag) "PluginEndpointDiscovery" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type PluginEndpointDiscovery = {
getBaseUrl(pluginId: string): Promise<string>;
getExternalBaseUrl(pluginId: string): Promise<string>;
};
// Warning: (ae-missing-release-tag) "ReaderFactory" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type ReaderFactory = (options: {
config: Config;
@@ -415,8 +373,6 @@ export type ReaderFactory = (options: {
treeResponseFactory: ReadTreeResponseFactory;
}) => UrlReaderPredicateTuple[];
// Warning: (ae-missing-release-tag) "ReadTreeOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type ReadTreeOptions = {
filter?(
@@ -428,8 +384,6 @@ export type ReadTreeOptions = {
etag?: string;
};
// Warning: (ae-missing-release-tag) "ReadTreeResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type ReadTreeResponse = {
files(): Promise<ReadTreeResponseFile[]>;
@@ -438,68 +392,67 @@ export type ReadTreeResponse = {
etag: string;
};
// Warning: (ae-missing-release-tag) "ReadTreeResponseFactory" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type ReadTreeResponseDirOptions = {
targetDir?: string;
};
// @public (undocumented)
export interface ReadTreeResponseFactory {
// Warning: (ae-forgotten-export) The symbol "FromArchiveOptions" needs to be exported by the entry point index.d.ts
//
// (undocumented)
fromTarArchive(options: FromArchiveOptions): Promise<ReadTreeResponse>;
fromTarArchive(
options: ReadTreeResponseFactoryOptions,
): Promise<ReadTreeResponse>;
// (undocumented)
fromZipArchive(options: FromArchiveOptions): Promise<ReadTreeResponse>;
fromZipArchive(
options: ReadTreeResponseFactoryOptions,
): Promise<ReadTreeResponse>;
}
// Warning: (ae-missing-release-tag) "ReadTreeResponseFile" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type ReadTreeResponseFactoryOptions = {
stream: Readable;
subpath?: string;
etag: string;
filter?: (
path: string,
info?: {
size: number;
},
) => boolean;
};
// @public
export type ReadTreeResponseFile = {
path: string;
content(): Promise<Buffer>;
};
// Warning: (ae-missing-release-tag) "ReadUrlOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type ReadUrlOptions = {
etag?: string;
};
// Warning: (ae-missing-release-tag) "ReadUrlResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type ReadUrlResponse = {
buffer(): Promise<Buffer>;
etag?: string;
};
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "requestLoggingHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function requestLoggingHandler(logger?: Logger_2): RequestHandler;
// Warning: (ae-missing-release-tag) "RequestLoggingHandlerFactory" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type RequestLoggingHandlerFactory = (
logger?: Logger_2,
) => RequestHandler;
// Warning: (ae-missing-release-tag) "resolvePackagePath" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function resolvePackagePath(name: string, ...paths: string[]): string;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "resolveSafeChildPath" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function resolveSafeChildPath(base: string, path: string): string;
// Warning: (ae-missing-release-tag) "RunContainerOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type RunContainerOptions = {
imageName: string;
@@ -512,39 +465,40 @@ export type RunContainerOptions = {
pullImage?: boolean;
};
// Warning: (ae-missing-release-tag) "SearchOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type SearchOptions = {
etag?: string;
};
// Warning: (ae-missing-release-tag) "SearchResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type SearchResponse = {
files: SearchResponseFile[];
etag: string;
};
// Warning: (ae-missing-release-tag) "SearchResponseFile" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type SearchResponseFile = {
url: string;
content(): Promise<Buffer>;
};
// Warning: (ae-missing-release-tag) "ServiceBuilder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type ServiceBuilder = {
loadConfig(config: ConfigReader): ServiceBuilder;
loadConfig(config: Config): ServiceBuilder;
setPort(port: number): ServiceBuilder;
setHost(host: string): ServiceBuilder;
setLogger(logger: Logger_2): ServiceBuilder;
enableCors(options: cors.CorsOptions): ServiceBuilder;
setHttpsSettings(settings: HttpsSettings): ServiceBuilder;
setHttpsSettings(settings: {
certificate:
| {
key: string;
cert: string;
}
| {
hostname: string;
};
}): ServiceBuilder;
addRouter(root: string, router: Router | RequestHandler): ServiceBuilder;
setRequestLoggingHandler(
requestLoggingHandler: RequestLoggingHandlerFactory,
@@ -552,18 +506,12 @@ export type ServiceBuilder = {
start(): Promise<Server>;
};
// Warning: (ae-missing-release-tag) "setRootLogger" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export function setRootLogger(newLogger: winston.Logger): void;
// Warning: (ae-missing-release-tag) "SingleConnectionDatabaseManager" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public @deprecated
export const SingleConnectionDatabaseManager: typeof DatabaseManager;
// Warning: (ae-missing-release-tag) "SingleHostDiscovery" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export class SingleHostDiscovery implements PluginEndpointDiscovery {
static fromConfig(
@@ -578,28 +526,19 @@ export class SingleHostDiscovery implements PluginEndpointDiscovery {
getExternalBaseUrl(pluginId: string): Promise<string>;
}
// Warning: (ae-missing-release-tag) "StatusCheck" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type StatusCheck = () => Promise<any>;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "statusCheckHandler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function statusCheckHandler(
options?: StatusCheckHandlerOptions,
): Promise<RequestHandler>;
// Warning: (ae-missing-release-tag) "StatusCheckHandlerOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export interface StatusCheckHandlerOptions {
statusCheck?: StatusCheck;
}
// Warning: (ae-missing-release-tag) "UrlReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type UrlReader = {
read(url: string): Promise<Buffer>;
@@ -608,56 +547,33 @@ export type UrlReader = {
search(url: string, options?: SearchOptions): Promise<SearchResponse>;
};
// Warning: (ae-missing-release-tag) "UrlReaderPredicateTuple" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type UrlReaderPredicateTuple = {
predicate: (url: URL) => boolean;
reader: UrlReader;
};
// Warning: (ae-missing-release-tag) "UrlReaders" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export class UrlReaders {
// Warning: (ae-forgotten-export) The symbol "CreateOptions" needs to be exported by the entry point index.d.ts
static create({ logger, config, factories }: CreateOptions): UrlReader;
static default({ logger, config, factories }: CreateOptions): UrlReader;
static create({ logger, config, factories }: UrlReadersOptions): UrlReader;
static default({ logger, config, factories }: UrlReadersOptions): UrlReader;
}
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "useHotCleanup" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type UrlReadersOptions = {
config: Config;
logger: Logger_2;
factories?: ReaderFactory[];
};
// @public
export function useHotCleanup(
_module: NodeModule,
cancelEffect: () => void,
): void;
// Warning: (tsdoc-undefined-tag) The TSDoc tag "@warning" is not defined in this configuration
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "useHotMemoize" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function useHotMemoize<T>(_module: NodeModule, valueFactory: () => T): T;
// Warnings were encountered during analysis:
//
// src/cache/types.d.ts:34:5 - (ae-forgotten-export) The symbol "ClientOptions" needs to be exported by the entry point index.d.ts
// src/middleware/errorHandler.d.ts:17:26 - (tsdoc-malformed-html-name) Invalid HTML element: A space is not allowed here
// src/reading/types.d.ts:108:5 - (ae-forgotten-export) The symbol "ReadTreeResponseDirOptions" needs to be exported by the entry point index.d.ts
// src/service/types.d.ts:12:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// src/service/types.d.ts:22:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// src/service/types.d.ts:30:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// src/service/types.d.ts:38:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// src/service/types.d.ts:47:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// src/service/types.d.ts:55:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// src/service/types.d.ts:57:5 - (ae-forgotten-export) The symbol "HttpsSettings" needs to be exported by the entry point index.d.ts
// src/service/types.d.ts:61:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// src/service/types.d.ts:62:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// src/service/types.d.ts:70:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// (No @packageDocumentation comment for this package)
```
packages/backend-common/src/cache/CacheClient.ts
Vendored
+10 -3
View File
@@ -22,7 +22,8 @@ type CacheClientArgs = {
client: Keyv;
};
type CacheSetOptions = {
/** @public */
export type CacheClientSetOptions = {
/**
* Optional TTL in milliseconds. Defaults to the TTL provided when the client
* was set up (or no TTL if none are provided).
@@ -33,6 +34,8 @@ type CacheSetOptions = {
/**
* A pre-configured, storage agnostic cache client suitable for use by
* Backstage plugins.
*
* @public
*/
export interface CacheClient {
/**
@@ -46,7 +49,11 @@ export interface CacheClient {
* optional TTL may also be provided, otherwise it defaults to the TTL that
* was provided when the client was instantiated.
*/
set(key: string, value: JsonValue, options?: CacheSetOptions): Promise<void>;
set(
key: string,
value: JsonValue,
options?: CacheClientSetOptions,
): Promise<void>;
/**
* Removes the given key from the cache store.
@@ -73,7 +80,7 @@ export class DefaultCacheClient implements CacheClient {
async set(
key: string,
value: JsonValue,
opts: CacheSetOptions = {},
opts: CacheClientSetOptions = {},
): Promise<void> {
const k = this.getNormalizedKey(key);
await this.client.set(k, value, opts.ttl);
packages/backend-common/src/cache/CacheManager.ts
Vendored
+7 -9
View File
@@ -22,16 +22,14 @@ import { Logger } from 'winston';
import { getRootLogger } from '../logging';
import { DefaultCacheClient, CacheClient } from './CacheClient';
import { NoStore } from './NoStore';
import {
CacheManagerOptions,
OptionalOnError,
PluginCacheManager,
} from './types';
import { CacheManagerOptions, PluginCacheManager } from './types';
/**
* 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.
*
* @public
*/
export class CacheManager {
/**
@@ -47,13 +45,13 @@ export class CacheManager {
private readonly logger: Logger;
private readonly store: keyof CacheManager['storeFactories'];
private readonly connection: string;
private readonly errorHandler: OptionalOnError;
private readonly errorHandler: CacheManagerOptions['onError'];
/**
* Creates a new CacheManager instance by reading from the `backend` config
* section, specifically the `.cache` key.
*
* @param config The loaded application configuration.
* @param config - The loaded application configuration.
*/
static fromConfig(
config: Config,
@@ -74,7 +72,7 @@ export class CacheManager {
store: string,
connectionString: string,
logger: Logger,
errorHandler: OptionalOnError,
errorHandler: CacheManagerOptions['onError'],
) {
if (!this.storeFactories.hasOwnProperty(store)) {
throw new Error(`Unknown cache store: ${store}`);
@@ -88,7 +86,7 @@ export class CacheManager {
/**
* Generates a PluginCacheManager for consumption by plugins.
*
* @param pluginId The plugin that the cache manager should be created for. Plugin names should be unique.
* @param pluginId - The plugin that the cache manager should be created for. Plugin names should be unique.
*/
forPlugin(pluginId: string): PluginCacheManager {
return {
packages/backend-common/src/cache/index.ts
Vendored
+6 -2
View File
@@ -14,6 +14,10 @@
* limitations under the License.
*/
export type { CacheClient } from './CacheClient';
export type { CacheClient, CacheClientSetOptions } from './CacheClient';
export { CacheManager } from './CacheManager';
export type { PluginCacheManager } from './types';
export type {
PluginCacheManager,
CacheManagerOptions,
CacheClientOptions,
} from './types';
packages/backend-common/src/cache/types.ts
Vendored
+7 -5
View File
@@ -17,7 +17,8 @@
import { Logger } from 'winston';
import { CacheClient } from './CacheClient';
type ClientOptions = {
/** @public */
export type CacheClientOptions = {
/**
* An optional default TTL (in milliseconds) to be set when getting a client
* instance. If not provided, data will persist indefinitely by default (or
@@ -26,8 +27,7 @@ type ClientOptions = {
defaultTtl?: number;
};
export type OptionalOnError = ((err: Error) => void) | undefined;
/** @public */
export type CacheManagerOptions = {
/**
* An optional logger for use by the PluginCacheManager.
@@ -38,11 +38,13 @@ export type CacheManagerOptions = {
* An optional handler for connection errors emitted from the underlying data
* store.
*/
onError?: OptionalOnError;
onError?: (err: Error) => void;
};
/**
* The PluginCacheManager manages access to cache stores that Plugins get.
*
* @public
*/
export type PluginCacheManager = {
/**
@@ -52,5 +54,5 @@ export type PluginCacheManager = {
* stores so that plugins are discouraged from cache-level integration
* and/or cache key collisions.
*/
getClient: (options?: ClientOptions) => CacheClient;
getClient: (options?: CacheClientOptions) => CacheClient;
};
packages/backend-common/src/config.ts
+7 -7
View File
@@ -101,12 +101,6 @@ class ObservableConfigProxy implements Config {
}
}
type Options = {
logger: Logger;
// process.argv or any other overrides
argv: string[];
};
// A global used to ensure that only a single file watcher is active at a time.
let currentCancelFunc: () => void;
@@ -114,8 +108,14 @@ let currentCancelFunc: () => void;
* Load configuration for a Backend.
*
* This function should only be called once, during the initialization of the backend.
*
* @public
*/
export async function loadBackendConfig(options: Options): Promise<Config> {
export async function loadBackendConfig(options: {
logger: Logger;
// process.argv or any other overrides
argv: string[];
}): Promise<Config> {
const args = parseArgs(options.argv);
const configPaths: string[] = [args.config ?? []].flat();
packages/backend-common/src/database/DatabaseManager.ts
+3 -2
View File
@@ -31,6 +31,7 @@ function pluginPath(pluginId: string): string {
return `plugin.${pluginId}`;
}
/** @public */
export class DatabaseManager {
/**
* Creates a DatabaseManager from `backend.database` config.
@@ -40,7 +41,7 @@ export class DatabaseManager {
* defaults. Optionally, a user may set `prefix` which is used to prefix generated database
* names if config is not provided.
*
* @param config The loaded application configuration.
* @param config - The loaded application configuration.
*/
static fromConfig(config: Config): DatabaseManager {
const databaseConfig = config.getConfig('backend.database');
@@ -59,7 +60,7 @@ export class DatabaseManager {
/**
* Generates a PluginDatabaseManager for consumption by plugins.
*
* @param pluginId The plugin that the database manager should be created for. Plugin names
* @param pluginId - The plugin that the database manager should be created for. Plugin names
* should be unique as they are used to look up database config overrides under
* `backend.database.plugin`.
*/
packages/backend-common/src/database/SingleConnection.ts
+1
View File
@@ -22,6 +22,7 @@ import { DatabaseManager } from './DatabaseManager';
* credentials provided; if the database already exists no attempt to create
* the database will be made.
*
* @public
* @deprecated Use `DatabaseManager` from `@backend-common` instead.
*/
export const SingleConnectionDatabaseManager = DatabaseManager;
packages/backend-common/src/database/config.ts
+1
View File
@@ -19,6 +19,7 @@ import { merge } from 'lodash';
/**
* Merges database objects together
*
* @public
* @param config The base config. The input is not modified
* @param overrides Any additional overrides
*/
packages/backend-common/src/database/connection.ts
+7 -2
View File
@@ -40,8 +40,9 @@ const ConnectorMapping: Record<DatabaseClient, DatabaseConnector> = {
/**
* Creates a knex database connection
*
* @param dbConfig The database config
* @param overrides Additional options to merge with the config
* @public
* @param dbConfig - The database config
* @param overrides - Additional options to merge with the config
*/
export function createDatabaseClient(
dbConfig: Config,
@@ -57,12 +58,16 @@ export function createDatabaseClient(
/**
* Alias for createDatabaseClient
*
* @public
* @deprecated Use createDatabaseClient instead
*/
export const createDatabase = createDatabaseClient;
/**
* Ensures that the given databases all exist, creating them if they do not.
*
* @public
*/
export async function ensureDatabaseExists(
dbConfig: Config,
packages/backend-common/src/database/types.ts
+2
View File
@@ -19,6 +19,8 @@ import { Knex } from 'knex';
/**
* The PluginDatabaseManager manages access to databases that Plugins get.
*
* @public
*/
export interface PluginDatabaseManager {
/**
packages/backend-common/src/discovery/SingleHostDiscovery.ts
+2
View File
@@ -26,6 +26,8 @@ import { DEFAULT_PORT } from '../service/lib/ServiceBuilderImpl';
* 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.
*
* @public
*/
export class SingleHostDiscovery implements PluginEndpointDiscovery {
/**
packages/backend-common/src/discovery/types.ts
+2
View File
@@ -25,6 +25,8 @@
* Implementations of the discovery API can be as simple as a URL pattern
* using the pluginId, but could also have overrides for individual plugins,
* or query a separate discovery service.
*
* @public
*/
export type PluginEndpointDiscovery = {
/**
packages/backend-common/src/hot.ts
+7 -5
View File
@@ -46,13 +46,14 @@ function findAllAncestors(_module: NodeModule): NodeModule[] {
*
* Useful for cleaning intervals, timers, requests etc
*
* @public
* @example
* ```ts
* const intervalId = setInterval(doStuff, 1000);
* useHotCleanup(module, () => clearInterval(intervalId));
* ```
* @param _module Reference to the current module where you invoke the fn
* @param cancelEffect Fn that cleans up the ongoing effects
* @param _module - Reference to the current module where you invoke the fn
* @param cancelEffect - Fn that cleans up the ongoing effects
*/
export function useHotCleanup(_module: NodeModule, cancelEffect: () => void) {
if (_module.hot) {
@@ -78,16 +79,17 @@ const CURRENT_HOT_MEMOIZE_INDEX_KEY = 'backstage.io/hmr-memoize-key';
* Memoizes a generated value across hot-module reloads. This is useful for
* stateful parts of the backend, e.g. to retain a database.
*
* @public
* @example
* ```ts
* const db = useHotMemoize(module, () => createDB(dbParams));
* ```
*
* @warning Don't use inside conditionals or loops,
* **NOTE:** Do not use inside conditionals or loops,
* same rules as for hooks apply (https://reactjs.org/docs/hooks-rules.html)
*
* @param _module Reference to the current module where you invoke the fn
* @param valueFactory Fn that returns the value you want to memoize
* @param _module - Reference to the current module where you invoke the fn
* @param valueFactory - Fn that returns the value you want to memoize
*/
export function useHotMemoize<T>(
_module: NodeModule,
packages/backend-common/src/logging/formats.ts
+1
View File
@@ -31,6 +31,7 @@ const coloredTemplate = (info: TransformableInfo) => {
return `${timestampColor} ${prefixColor} ${level} ${message} ${extraFields}`;
};
/** @public */
export const coloredFormat = winston.format.combine(
winston.format.timestamp(),
winston.format.colorize({
packages/backend-common/src/logging/rootLogger.ts
+3
View File
@@ -21,14 +21,17 @@ import { coloredFormat } from './formats';
let rootLogger: winston.Logger;
/** @public */
export function getRootLogger(): winston.Logger {
return rootLogger;
}
/** @public */
export function setRootLogger(newLogger: winston.Logger) {
rootLogger = newLogger;
}
/** @public */
export function createRootLogger(
options: winston.LoggerOptions = {},
env = process.env,
packages/backend-common/src/logging/voidLogger.ts
+2
View File
@@ -19,6 +19,8 @@ import * as winston from 'winston';
/**
* A logger that just throws away all messages.
*
* @public
*/
export function getVoidLogger(): winston.Logger {
return winston.createLogger({
packages/backend-common/src/middleware/errorHandler.ts
+4 -2
View File
@@ -28,6 +28,7 @@ import { ErrorRequestHandler, NextFunction, Request, Response } from 'express';
import { Logger } from 'winston';
import { getRootLogger } from '../logging';
/** @public */
export type ErrorHandlerOptions = {
/**
* Whether error response bodies should show error stack traces or not.
@@ -44,9 +45,9 @@ export type ErrorHandlerOptions = {
logger?: Logger;
/**
* Whether any error < 4XX should be logged or not.
* Whether any 4xx errors should be logged or not.
*
* If not specified, by default log any 5xx errors.
* If not specified, default to only logging 5xx errors.
*/
logClientErrors?: boolean;
};
@@ -62,6 +63,7 @@ export type ErrorHandlerOptions = {
* error types (such as http-error exceptions) and returns the enclosed status
* code accordingly.
*
* @public
* @returns An Express error request handler
*/
export function errorHandler(
packages/backend-common/src/middleware/notFoundHandler.ts
+1
View File
@@ -22,6 +22,7 @@ import { NextFunction, Request, RequestHandler, Response } from 'express';
* Should be used as the very last handler in the chain, as it unconditionally
* returns a 404 status.
*
* @public
* @returns An Express request handler
*/
export function notFoundHandler(): RequestHandler {
packages/backend-common/src/middleware/requestLoggingHandler.ts
+2 -1
View File
@@ -22,7 +22,8 @@ import { getRootLogger } from '../logging';
/**
* Logs incoming requests.
*
* @param logger An optional logger to use. If not specified, the root logger will be used.
* @public
* @param logger - An optional logger to use. If not specified, the root logger will be used.
* @returns An Express request handler
*/
export function requestLoggingHandler(logger?: Logger): RequestHandler {
packages/backend-common/src/middleware/statusCheckHandler.ts
+4 -1
View File
@@ -16,8 +16,10 @@
import { NextFunction, Request, Response, RequestHandler } from 'express';
/** @public */
export type StatusCheck = () => Promise<any>;
/** @public */
export interface StatusCheckHandlerOptions {
/**
* Optional status function which returns a message.
@@ -30,7 +32,8 @@ export interface StatusCheckHandlerOptions {
*
* This is commonly used to implement healthcheck and readiness routes.
*
* @param options An optional configuration object.
* @public
* @param options - An optional configuration object.
* @returns An Express error request handler
*/
export async function statusCheckHandler(
packages/backend-common/src/paths.ts
+5 -2
View File
@@ -25,6 +25,8 @@ import { resolve as resolvePath } from 'path';
* 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 `files` in your `package.json`.
*
* @public
*/
export function resolvePackagePath(name: string, ...paths: string[]) {
const req =
@@ -40,8 +42,9 @@ export function resolvePackagePath(name: string, ...paths: string[]) {
* 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.
*
* @param base The base directory to resolve the path from.
* @param path The target path, relative or absolute
* @public
* @param base - The base directory to resolve the path from.
* @param path - The target path, relative or absolute
* @returns A path that is guaranteed to point to or within the base path.
*/
export function resolveSafeChildPath(base: string, path: string): string {
packages/backend-common/src/reading/AzureUrlReader.ts
+1
View File
@@ -40,6 +40,7 @@ import {
ReadUrlResponse,
} from './types';
/** @public */
export class AzureUrlReader implements UrlReader {
static factory: ReaderFactory = ({ config, treeResponseFactory }) => {
const integrations = ScmIntegrations.fromConfig(config);
packages/backend-common/src/reading/BitbucketUrlReader.ts
+2
View File
@@ -43,6 +43,8 @@ import {
/**
* A processor that adds the ability to read files from Bitbucket v1 and v2 APIs, such as
* the one exposed by Bitbucket Cloud itself.
*
* @public
*/
export class BitbucketUrlReader implements UrlReader {
static factory: ReaderFactory = ({ config, treeResponseFactory }) => {
packages/backend-common/src/reading/FetchUrlReader.ts
+2
View File
@@ -27,6 +27,8 @@ import {
/**
* A UrlReader that does a plain fetch of the URL.
*
* @public
*/
export class FetchUrlReader implements UrlReader {
/**
packages/backend-common/src/reading/GithubUrlReader.ts
+2
View File
@@ -51,6 +51,8 @@ export type GhBlobResponse =
/**
* A processor that adds the ability to read files from GitHub v3 APIs, such as
* the one exposed by GitHub itself.
*
* @public
*/
export class GithubUrlReader implements UrlReader {
static factory: ReaderFactory = ({ config, treeResponseFactory }) => {
packages/backend-common/src/reading/GitlabUrlReader.ts
+1
View File
@@ -38,6 +38,7 @@ import {
ReadUrlOptions,
} from './types';
/** @public */
export class GitlabUrlReader implements UrlReader {
static factory: ReaderFactory = ({ config, treeResponseFactory }) => {
const integrations = ScmIntegrations.fromConfig(config);
packages/backend-common/src/reading/GoogleGcsUrlReader.ts
+1
View File
@@ -48,6 +48,7 @@ const parseURL = (
};
};
/** @public */
export class GoogleGcsUrlReader implements UrlReader {
static factory: ReaderFactory = ({ config, logger }) => {
if (!config.has('integrations.googleGcs')) {
packages/backend-common/src/reading/UrlReaders.ts
+6 -3
View File
@@ -27,7 +27,8 @@ import { FetchUrlReader } from './FetchUrlReader';
import { GoogleGcsUrlReader } from './GoogleGcsUrlReader';
import { AwsS3UrlReader } from './AwsS3UrlReader';
type CreateOptions = {
/** @public */
export type UrlReadersOptions = {
/** Root config object */
config: Config;
/** Logger used by all the readers */
@@ -38,12 +39,14 @@ type CreateOptions = {
/**
* UrlReaders provide various utilities related to the UrlReader interface.
*
* @public
*/
export class UrlReaders {
/**
* Creates a UrlReader without any known types.
*/
static create({ logger, config, factories }: CreateOptions): UrlReader {
static create({ logger, config, factories }: UrlReadersOptions): UrlReader {
const mux = new UrlReaderPredicateMux(logger);
const treeResponseFactory = DefaultReadTreeResponseFactory.create({
config,
@@ -65,7 +68,7 @@ export class UrlReaders {
*
* Any additional factories passed will be loaded before the default ones.
*/
static default({ logger, config, factories = [] }: CreateOptions) {
static default({ logger, config, factories = [] }: UrlReadersOptions) {
return UrlReaders.create({
logger,
config,
packages/backend-common/src/reading/index.ts
+3
View File
@@ -24,6 +24,8 @@ export type {
ReadTreeResponse,
ReadTreeResponseFactory,
ReadTreeResponseFile,
ReadTreeResponseDirOptions,
ReadTreeResponseFactoryOptions,
ReadUrlOptions,
ReadUrlResponse,
SearchOptions,
@@ -33,3 +35,4 @@ export type {
UrlReaderPredicateTuple,
} from './types';
export { UrlReaders } from './UrlReaders';
export type { UrlReadersOptions } from './UrlReaders';
packages/backend-common/src/reading/tree/ReadTreeResponseFactory.ts
+7 -3
View File
@@ -18,7 +18,7 @@ import os from 'os';
import { Config } from '@backstage/config';
import {
ReadTreeResponse,
FromArchiveOptions,
ReadTreeResponseFactoryOptions,
ReadTreeResponseFactory,
} from '../types';
import { TarArchiveResponse } from './TarArchiveResponse';
@@ -34,7 +34,9 @@ export class DefaultReadTreeResponseFactory implements ReadTreeResponseFactory {
constructor(private readonly workDir: string) {}
async fromTarArchive(options: FromArchiveOptions): Promise<ReadTreeResponse> {
async fromTarArchive(
options: ReadTreeResponseFactoryOptions,
): Promise<ReadTreeResponse> {
return new TarArchiveResponse(
options.stream,
options.subpath ?? '',
@@ -44,7 +46,9 @@ export class DefaultReadTreeResponseFactory implements ReadTreeResponseFactory {
);
}
async fromZipArchive(options: FromArchiveOptions): Promise<ReadTreeResponse> {
async fromZipArchive(
options: ReadTreeResponseFactoryOptions,
): Promise<ReadTreeResponse> {
return new ZipArchiveResponse(
options.stream,
options.subpath ?? '',
packages/backend-common/src/reading/types.ts
+36 -8
View File
@@ -20,6 +20,8 @@ import { Config } from '@backstage/config';
/**
* A generic interface for fetching plain data from URLs.
*
* @public
*/
export type UrlReader = {
/* Used to read a single file and return its content. */
@@ -39,6 +41,7 @@ export type UrlReader = {
search(url: string, options?: SearchOptions): Promise<SearchResponse>;
};
/** @public */
export type UrlReaderPredicateTuple = {
predicate: (url: URL) => boolean;
reader: UrlReader;
@@ -47,6 +50,8 @@ export type UrlReaderPredicateTuple = {
/**
* A factory function that can read config to construct zero or more
* UrlReaders along with a predicate for when it should be used.
*
* @public
*/
export type ReaderFactory = (options: {
config: Config;
@@ -56,6 +61,8 @@ export type ReaderFactory = (options: {
/**
* An options object for readUrl operations.
*
* @public
*/
export type ReadUrlOptions = {
/**
@@ -74,6 +81,8 @@ export type ReadUrlOptions = {
/**
* A response object for readUrl operations.
*
* @public
*/
export type ReadUrlResponse = {
/**
@@ -90,6 +99,8 @@ export type ReadUrlResponse = {
/**
* An options object for readTree operations.
*
* @public
*/
export type ReadTreeOptions = {
/**
@@ -120,8 +131,16 @@ export type ReadTreeOptions = {
etag?: string;
};
/** @public */
export type ReadTreeResponseDirOptions = {
/** The directory to write files to. Defaults to the OS tmpdir or `backend.workingDirectory` if set in config */
targetDir?: string;
};
/**
* A response object for readTree operations.
*
* @public
*/
export type ReadTreeResponse = {
/**
@@ -142,20 +161,18 @@ export type ReadTreeResponse = {
etag: string;
};
export type ReadTreeResponseDirOptions = {
/** The directory to write files to. Defaults to the OS tmpdir or `backend.workingDirectory` if set in config */
targetDir?: string;
};
/**
* Represents a single file in a readTree response.
*
* @public
*/
export type ReadTreeResponseFile = {
path: string;
content(): Promise<Buffer>;
};
export type FromArchiveOptions = {
/** @public */
export type ReadTreeResponseFactoryOptions = {
// A binary stream of a tar archive.
stream: Readable;
// If unset, the files at the root of the tree will be read.
@@ -167,13 +184,20 @@ export type FromArchiveOptions = {
filter?: (path: string, info?: { size: number }) => boolean;
};
/** @public */
export interface ReadTreeResponseFactory {
fromTarArchive(options: FromArchiveOptions): Promise<ReadTreeResponse>;
fromZipArchive(options: FromArchiveOptions): Promise<ReadTreeResponse>;
fromTarArchive(
options: ReadTreeResponseFactoryOptions,
): Promise<ReadTreeResponse>;
fromZipArchive(
options: ReadTreeResponseFactoryOptions,
): Promise<ReadTreeResponse>;
}
/**
* An options object for search operations.
*
* @public
*/
export type SearchOptions = {
/**
@@ -192,6 +216,8 @@ export type SearchOptions = {
/**
* The output of a search operation.
*
* @public
*/
export type SearchResponse = {
/**
@@ -207,6 +233,8 @@ export type SearchResponse = {
/**
* Represents a single file in a search response.
*
* @public
*/
export type SearchResponseFile = {
/**
packages/backend-common/src/scm/git.ts
+2
View File
@@ -31,6 +31,8 @@ From : https://isomorphic-git.org/docs/en/onAuth with fix for GitHub
Azure 'notempty' token
*/
/** @public */
export class Git {
private constructor(
private readonly config: {
packages/backend-common/src/service/createServiceBuilder.ts
+4 -1
View File
@@ -15,10 +15,13 @@
*/
import { ServiceBuilderImpl } from './lib/ServiceBuilderImpl';
import { ServiceBuilder } from './types';
/**
* Creates a new service builder.
*
* @public
*/
export function createServiceBuilder(_module: NodeModule) {
export function createServiceBuilder(_module: NodeModule): ServiceBuilder {
return new ServiceBuilderImpl(_module);
}
packages/backend-common/src/service/createStatusCheckRouter.ts
+3 -6
View File
@@ -19,7 +19,8 @@ import Router from 'express-promise-router';
import express from 'express';
import { errorHandler, statusCheckHandler, StatusCheck } from '../middleware';
export interface StatusCheckRouterOptions {
/** @public */
export async function createStatusCheckRouter(options: {
logger: Logger;
path?: string;
/**
@@ -27,11 +28,7 @@ export interface StatusCheckRouterOptions {
* Override this to implement your own logic for a health check.
*/
statusCheck?: StatusCheck;
}
export async function createStatusCheckRouter(
options: StatusCheckRouterOptions,
): Promise<express.Router> {
}): Promise<express.Router> {
const router = Router();
const { path = '/healthcheck', statusCheck } = options;
packages/backend-common/src/service/types.ts
+16 -13
View File
@@ -14,20 +14,20 @@
* limitations under the License.
*/
import { ConfigReader } from '@backstage/config';
import { Config } from '@backstage/config';
import cors from 'cors';
import { Router, RequestHandler } from 'express';
import { Server } from 'http';
import { Logger } from 'winston';
import { HttpsSettings } from './lib/config';
/** @public */
export type ServiceBuilder = {
/**
* Sets the service parameters based on configuration.
*
* @param config The configuration to read
* @param config - The configuration to read
*/
loadConfig(config: ConfigReader): ServiceBuilder;
loadConfig(config: Config): ServiceBuilder;
/**
* Sets the port to listen on.
@@ -36,7 +36,7 @@ export type ServiceBuilder = {
* variable named PORT and use that if present, otherwise it picks a default
* port (7000).
*
* @param port The port to listen on
* @param port - The port to listen on
*/
setPort(port: number): ServiceBuilder;
@@ -45,7 +45,7 @@ export type ServiceBuilder = {
*
* '' is express default, which listens to all interfaces.
*
* @param host The host to listen on
* @param host - The host to listen on
*/
setHost(host: string): ServiceBuilder;
@@ -54,7 +54,7 @@ export type ServiceBuilder = {
*
* If no logger is given, the default root logger is used.
*
* @param logger A winston logger
* @param logger - A winston logger
*/
setLogger(logger: Logger): ServiceBuilder;
@@ -64,7 +64,7 @@ export type ServiceBuilder = {
* If this method is not called, the resulting service will not have any
* built in CORS handling.
*
* @param options Standard CORS options
* @param options - Standard CORS options
*/
enableCors(options: cors.CorsOptions): ServiceBuilder;
@@ -73,15 +73,17 @@ export type ServiceBuilder = {
*
* If this method is not called, the resulting service will use sensible defaults
*
* @param options Standard certificate options
* @param options - Standard certificate options
*/
setHttpsSettings(settings: HttpsSettings): ServiceBuilder;
setHttpsSettings(settings: {
certificate: { key: string; cert: string } | { hostname: string };
}): ServiceBuilder;
/**
* Adds a router (similar to the express .use call) to the service.
*
* @param root The root URL to bind to (e.g. "/api/function1")
* @param router An express router
* @param root - The root URL to bind to (e.g. "/api/function1")
* @param router - An express router
*/
addRouter(root: string, router: Router | RequestHandler): ServiceBuilder;
@@ -90,7 +92,7 @@ export type ServiceBuilder = {
*
* If no handler is given the default one is used
*
* @param requestLoggingHandler a factory function that given a logger returns an handler
* @param requestLoggingHandler - a factory function that given a logger returns an handler
*/
setRequestLoggingHandler(
requestLoggingHandler: RequestLoggingHandlerFactory,
@@ -102,4 +104,5 @@ export type ServiceBuilder = {
start(): Promise<Server>;
};
/** @public */
export type RequestLoggingHandlerFactory = (logger?: Logger) => RequestHandler;
packages/backend-common/src/util/ContainerRunner.ts
+2
View File
@@ -16,6 +16,7 @@
import { Writable } from 'stream';
/** @public */
export type RunContainerOptions = {
imageName: string;
command?: string | string[];
@@ -27,6 +28,7 @@ export type RunContainerOptions = {
pullImage?: boolean;
};
/** @public */
export interface ContainerRunner {
runContainer(opts: RunContainerOptions): Promise<void>;
}
packages/backend-common/src/util/DockerContainerRunner.ts
+1
View File
@@ -23,6 +23,7 @@ export type UserOptions = {
User?: string;
};
/** @public */
export class DockerContainerRunner implements ContainerRunner {
private readonly dockerClient: Docker;
packages/backend-test-utils/api-report.md
-7
View File
@@ -5,13 +5,9 @@
```ts
import { Knex } from 'knex';
// Warning: (ae-missing-release-tag) "isDockerDisabledForTests" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export function isDockerDisabledForTests(): boolean;
// Warning: (ae-missing-release-tag) "TestDatabaseId" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type TestDatabaseId =
| 'POSTGRES_13'
@@ -19,8 +15,6 @@ export type TestDatabaseId =
| 'MYSQL_8'
| 'SQLITE_3';
// Warning: (ae-missing-release-tag) "TestDatabases" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export class TestDatabases {
static create(options?: {
@@ -29,7 +23,6 @@ export class TestDatabases {
}): TestDatabases;
// (undocumented)
eachSupportedId(): [TestDatabaseId][];
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
init(id: TestDatabaseId): Promise<Knex>;
// (undocumented)
supports(id: TestDatabaseId): boolean;
packages/backend-test-utils/src/database/TestDatabases.ts
+3 -1
View File
@@ -31,6 +31,8 @@ import {
/**
* Encapsulates the creation of ephemeral test database instances for use
* inside unit or integration tests.
*
* @public
*/
export class TestDatabases {
private readonly instanceById: Map<string, Instance>;
@@ -113,7 +115,7 @@ export class TestDatabases {
* Returns a fresh, unique, empty logical database on an instance of the
* given database ID platform.
*
* @param id The ID of the database platform to use, e.g. 'POSTGRES_13'
* @param id - The ID of the database platform to use, e.g. 'POSTGRES_13'
* @returns A `Knex` connection object
*/
async init(id: TestDatabaseId): Promise<Knex> {
packages/backend-test-utils/src/database/types.ts
+2
View File
@@ -19,6 +19,8 @@ import { Knex } from 'knex';
/**
* The possible databases to test against.
*
* @public
*/
export type TestDatabaseId =
| 'POSTGRES_13'
packages/backend-test-utils/src/util/isDockerDisabledForTests.ts
+1
View File
@@ -14,6 +14,7 @@
* limitations under the License.
*/
/** @public */
export function isDockerDisabledForTests() {
// If we are not running in continuous integration, the default is to skip
// the (relatively heavy, long running) docker based tests. If you want to
packages/catalog-client/api-report.md
+5 -22
View File
@@ -7,8 +7,6 @@ import { Entity } from '@backstage/catalog-model';
import { EntityName } from '@backstage/catalog-model';
import { Location as Location_2 } from '@backstage/catalog-model';
// Warning: (ae-missing-release-tag) "AddLocationRequest" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type AddLocationRequest = {
type?: string;
@@ -17,21 +15,15 @@ export type AddLocationRequest = {
presence?: 'optional' | 'required';
};
// Warning: (ae-missing-release-tag) "AddLocationResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type AddLocationResponse = {
location: Location_2;
entities: Entity[];
};
// Warning: (ae-missing-release-tag) "CATALOG_FILTER_EXISTS" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const CATALOG_FILTER_EXISTS: unique symbol;
// Warning: (ae-missing-release-tag) "CatalogApi" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export interface CatalogApi {
// (undocumented)
@@ -76,8 +68,6 @@ export interface CatalogApi {
): Promise<void>;
}
// Warning: (ae-missing-release-tag) "CatalogClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export class CatalogClient implements CatalogApi {
constructor(options: { discoveryApi: DiscoveryApi });
@@ -123,8 +113,6 @@ export class CatalogClient implements CatalogApi {
): Promise<void>;
}
// Warning: (ae-missing-release-tag) "CatalogEntitiesRequest" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type CatalogEntitiesRequest = {
filter?:
@@ -134,29 +122,24 @@ export type CatalogEntitiesRequest = {
fields?: string[] | undefined;
};
// Warning: (ae-missing-release-tag) "CatalogListResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type CatalogListResponse<T> = {
items: T[];
};
// Warning: (ae-missing-release-tag) "CatalogRequestOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type CatalogRequestOptions = {
token?: string;
};
// Warning: (ae-missing-release-tag) "ENTITY_STATUS_CATALOG_PROCESSING_TYPE" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type DiscoveryApi = {
getBaseUrl(pluginId: string): Promise<string>;
};
// @public
export const ENTITY_STATUS_CATALOG_PROCESSING_TYPE =
'backstage.io/catalog-processing';
// Warnings were encountered during analysis:
//
// src/CatalogClient.d.ts:7:9 - (ae-forgotten-export) The symbol "DiscoveryApi" needs to be exported by the entry point index.d.ts
// (No @packageDocumentation comment for this package)
```
packages/catalog-client/src/CatalogClient.ts
+1
View File
@@ -36,6 +36,7 @@ import {
} from './types/api';
import { DiscoveryApi } from './types/discovery';
/** @public */
export class CatalogClient implements CatalogApi {
private readonly discoveryApi: DiscoveryApi;
packages/catalog-client/src/types/api.ts
+7
View File
@@ -16,8 +16,10 @@
import { Entity, EntityName, Location } from '@backstage/catalog-model';
/** @public */
export const CATALOG_FILTER_EXISTS = Symbol('CATALOG_FILTER_EXISTS');
/** @public */
export type CatalogEntitiesRequest = {
filter?:
| Record<string, string | symbol | (string | symbol)[]>[]
@@ -26,14 +28,17 @@ export type CatalogEntitiesRequest = {
fields?: string[] | undefined;
};
/** @public */
export type CatalogListResponse<T> = {
items: T[];
};
/** @public */
export type CatalogRequestOptions = {
token?: string;
};
/** @public */
export interface CatalogApi {
// Entities
getEntities(
@@ -72,6 +77,7 @@ export interface CatalogApi {
): Promise<void>;
}
/** @public */
export type AddLocationRequest = {
type?: string;
target: string;
@@ -79,6 +85,7 @@ export type AddLocationRequest = {
presence?: 'optional' | 'required';
};
/** @public */
export type AddLocationResponse = {
location: Location;
entities: Entity[];
packages/catalog-client/src/types/discovery.ts
+2
View File
@@ -16,6 +16,8 @@
/**
* This is a copy of the core DiscoveryApi, to avoid importing core.
*
* @public
*/
export type DiscoveryApi = {
getBaseUrl(pluginId: string): Promise<string>;
packages/catalog-client/src/types/index.ts
+1
View File
@@ -22,5 +22,6 @@ export type {
CatalogListResponse,
CatalogRequestOptions,
} from './api';
export type { DiscoveryApi } from './discovery';
export { CATALOG_FILTER_EXISTS } from './api';
export { ENTITY_STATUS_CATALOG_PROCESSING_TYPE } from './status';
packages/catalog-client/src/types/status.ts
+2
View File
@@ -17,6 +17,8 @@
/**
* The entity `status.items[].type` for the status of the processing engine in
* regards to an entity.
*
* @public
*/
export const ENTITY_STATUS_CATALOG_PROCESSING_TYPE =
'backstage.io/catalog-processing';
packages/catalog-model/api-report.md
+9 -210
View File
@@ -9,9 +9,6 @@ import { JsonValue } from '@backstage/config';
import { SerializedError } from '@backstage/errors';
import * as yup from 'yup';
// Warning: (tsdoc-missing-deprecation-message) The @deprecated block must include a deprecation message, e.g. describing the recommended alternative
// Warning: (ae-missing-release-tag) "analyzeLocationSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public @deprecated (undocumented)
export const analyzeLocationSchema: yup.ObjectSchema<
{
@@ -20,8 +17,6 @@ export const analyzeLocationSchema: yup.ObjectSchema<
object
>;
// Warning: (ae-missing-release-tag) "ApiEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
interface ApiEntityV1alpha1 extends Entity {
// (undocumented)
@@ -40,43 +35,24 @@ interface ApiEntityV1alpha1 extends Entity {
export { ApiEntityV1alpha1 as ApiEntity };
export { ApiEntityV1alpha1 };
// Warning: (ae-missing-release-tag) "apiEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const apiEntityV1alpha1Validator: KindValidator;
// Warning: (ae-missing-release-tag) "CommonValidatorFunctions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export class CommonValidatorFunctions {
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
static isJsonSafe(value: unknown): boolean;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
static isValidDnsLabel(value: unknown): boolean;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
static isValidDnsSubdomain(value: unknown): boolean;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
static isValidPrefixAndOrSuffix(
value: unknown,
separator: string,
isValidPrefix: (value: string) => boolean,
isValidSuffix: (value: string) => boolean,
): boolean;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
static isValidString(value: unknown): boolean;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
static isValidUrl(value: unknown): boolean;
}
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-forgotten-export) The symbol "EntityRefContext" needs to be exported by the entry point index.d.ts
// Warning: (ae-missing-release-tag) "compareEntityToRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function compareEntityToRef(
entity: Entity,
@@ -84,8 +60,6 @@ export function compareEntityToRef(
context?: EntityRefContext,
): boolean;
// Warning: (ae-missing-release-tag) "ComponentEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
interface ComponentEntityV1alpha1 extends Entity {
// (undocumented)
@@ -107,13 +81,9 @@ interface ComponentEntityV1alpha1 extends Entity {
export { ComponentEntityV1alpha1 as ComponentEntity };
export { ComponentEntityV1alpha1 };
// Warning: (ae-missing-release-tag) "componentEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const componentEntityV1alpha1Validator: KindValidator;
// Warning: (ae-missing-release-tag) "DefaultNamespaceEntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export class DefaultNamespaceEntityPolicy implements EntityPolicy {
constructor(namespace?: string);
@@ -121,8 +91,6 @@ export class DefaultNamespaceEntityPolicy implements EntityPolicy {
enforce(entity: Entity): Promise<Entity>;
}
// Warning: (ae-missing-release-tag) "DomainEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
interface DomainEntityV1alpha1 extends Entity {
// (undocumented)
@@ -137,18 +105,12 @@ interface DomainEntityV1alpha1 extends Entity {
export { DomainEntityV1alpha1 as DomainEntity };
export { DomainEntityV1alpha1 };
// Warning: (ae-missing-release-tag) "domainEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const domainEntityV1alpha1Validator: KindValidator;
// Warning: (ae-missing-release-tag) "EDIT_URL_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const EDIT_URL_ANNOTATION = 'backstage.io/edit-url';
// Warning: (ae-missing-release-tag) "Entity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type Entity = {
apiVersion: string;
@@ -159,13 +121,9 @@ export type Entity = {
status?: UNSTABLE_EntityStatus;
};
// Warning: (ae-missing-release-tag) "ENTITY_DEFAULT_NAMESPACE" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export const ENTITY_DEFAULT_NAMESPACE = 'default';
// Warning: (ae-missing-release-tag) "ENTITY_META_GENERATED_FIELDS" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export const ENTITY_META_GENERATED_FIELDS: readonly [
'uid',
@@ -173,8 +131,6 @@ export const ENTITY_META_GENERATED_FIELDS: readonly [
'generation',
];
// Warning: (ae-missing-release-tag) "EntityEnvelope" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type EntityEnvelope = {
apiVersion: string;
@@ -185,35 +141,19 @@ export type EntityEnvelope = {
};
};
// Warning: (ae-missing-release-tag) "entityEnvelopeSchemaValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
// Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/catalog-model" does not have an export "TypeError"
//
// @public
export function entityEnvelopeSchemaValidator<
T extends EntityEnvelope = EntityEnvelope,
>(schema?: unknown): (data: unknown) => T;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "entityHasChanges" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function entityHasChanges(previous: Entity, next: Entity): boolean;
// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
// Warning: (ae-missing-release-tag) "entityKindSchemaValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
// Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/catalog-model" does not have an export "TypeError"
//
// @public
export function entityKindSchemaValidator<T extends Entity>(
schema: unknown,
): (data: unknown) => T | false;
// Warning: (ae-missing-release-tag) "EntityLink" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type EntityLink = {
url: string;
@@ -221,8 +161,6 @@ export type EntityLink = {
icon?: string;
};
// Warning: (ae-missing-release-tag) "EntityMeta" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type EntityMeta = JsonObject & {
uid?: string;
@@ -238,8 +176,6 @@ export type EntityMeta = JsonObject & {
links?: EntityLink[];
};
// Warning: (ae-missing-release-tag) "EntityName" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type EntityName = {
kind: string;
@@ -247,23 +183,17 @@ export type EntityName = {
name: string;
};
// Warning: (ae-missing-release-tag) "EntityPolicies" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const EntityPolicies: {
allOf(policies: EntityPolicy[]): AllEntityPolicies;
oneOf(policies: EntityPolicy[]): AnyEntityPolicy;
allOf(policies: EntityPolicy[]): EntityPolicy;
oneOf(policies: EntityPolicy[]): EntityPolicy;
};
// Warning: (ae-missing-release-tag) "EntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type EntityPolicy = {
enforce(entity: Entity): Promise<Entity | undefined>;
};
// Warning: (ae-missing-release-tag) "EntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type EntityRef =
| string
@@ -273,16 +203,18 @@ export type EntityRef =
name: string;
};
// Warning: (ae-missing-release-tag) "EntityRelation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type EntityRefContext = {
defaultKind?: string;
defaultNamespace?: string;
};
// @public
export type EntityRelation = {
type: string;
target: EntityName;
};
// Warning: (ae-missing-release-tag) "EntityRelationSpec" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type EntityRelationSpec = {
source: EntityName;
@@ -290,16 +222,11 @@ export type EntityRelationSpec = {
target: EntityName;
};
// Warning: (ae-missing-release-tag) "entitySchemaValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
// Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/catalog-model" does not have an export "TypeError"
//
// @public
export function entitySchemaValidator<T extends Entity = Entity>(
schema?: unknown,
): (data: unknown) => T;
// Warning: (ae-missing-release-tag) "FieldFormatEntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export class FieldFormatEntityPolicy implements EntityPolicy {
constructor(validators?: Validators);
@@ -307,40 +234,24 @@ export class FieldFormatEntityPolicy implements EntityPolicy {
enforce(entity: Entity): Promise<Entity>;
}
// Warning: (ae-missing-release-tag) "generateEntityEtag" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function generateEntityEtag(): string;
// Warning: (ae-missing-release-tag) "generateEntityUid" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function generateEntityUid(): string;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "generateUpdatedEntity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function generateUpdatedEntity(previous: Entity, next: Entity): Entity;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "getEntityName" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function getEntityName(entity: Entity): EntityName;
// Warning: (tsdoc-characters-after-block-tag) The token "@backstage" looks like a TSDoc tag but contains an invalid character "/"; if it is not a tag, use a backslash to escape the "@"
// Warning: (ae-missing-release-tag) "getEntitySourceLocation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function getEntitySourceLocation(entity: Entity): {
type: string;
target: string;
};
// Warning: (ae-missing-release-tag) "GroupEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
interface GroupEntityV1alpha1 extends Entity {
// (undocumented)
@@ -363,28 +274,20 @@ interface GroupEntityV1alpha1 extends Entity {
export { GroupEntityV1alpha1 as GroupEntity };
export { GroupEntityV1alpha1 };
// Warning: (ae-missing-release-tag) "groupEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const groupEntityV1alpha1Validator: KindValidator;
// Warning: (ae-missing-release-tag) "JSONSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type JSONSchema = JSONSchema7 &
{
[key in string]?: JsonValue;
};
// Warning: (ae-missing-release-tag) "KindValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export type KindValidator = {
check(entity: Entity): Promise<boolean>;
};
// Warning: (ae-missing-release-tag) "KubernetesValidatorFunctions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export class KubernetesValidatorFunctions {
// (undocumented)
@@ -405,21 +308,15 @@ export class KubernetesValidatorFunctions {
static isValidObjectName(value: unknown): boolean;
}
// Warning: (ae-missing-release-tag) "Location" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
type Location_2 = {
id: string;
} & LocationSpec;
export { Location_2 as Location };
// Warning: (ae-missing-release-tag) "LOCATION_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const LOCATION_ANNOTATION = 'backstage.io/managed-by-location';
// Warning: (ae-missing-release-tag) "LocationEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
interface LocationEntityV1alpha1 extends Entity {
// (undocumented)
@@ -436,19 +333,12 @@ interface LocationEntityV1alpha1 extends Entity {
export { LocationEntityV1alpha1 as LocationEntity };
export { LocationEntityV1alpha1 };
// Warning: (ae-missing-release-tag) "locationEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const locationEntityV1alpha1Validator: KindValidator;
// Warning: (tsdoc-missing-deprecation-message) The @deprecated block must include a deprecation message, e.g. describing the recommended alternative
// Warning: (ae-missing-release-tag) "locationSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public @deprecated (undocumented)
export const locationSchema: yup.ObjectSchema<Location_2, object>;
// Warning: (ae-missing-release-tag) "LocationSpec" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type LocationSpec = {
type: string;
@@ -456,19 +346,12 @@ export type LocationSpec = {
presence?: 'optional' | 'required';
};
// Warning: (tsdoc-missing-deprecation-message) The @deprecated block must include a deprecation message, e.g. describing the recommended alternative
// Warning: (ae-missing-release-tag) "locationSpecSchema" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public @deprecated (undocumented)
export const locationSpecSchema: yup.ObjectSchema<LocationSpec, object>;
// Warning: (ae-missing-release-tag) "makeValidator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export function makeValidator(overrides?: Partial<Validators>): Validators;
// Warning: (ae-missing-release-tag) "NoForeignRootFieldsEntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export class NoForeignRootFieldsEntityPolicy implements EntityPolicy {
constructor(knownFields?: string[]);
@@ -476,28 +359,16 @@ export class NoForeignRootFieldsEntityPolicy implements EntityPolicy {
enforce(entity: Entity): Promise<Entity>;
}
// Warning: (ae-missing-release-tag) "ORIGIN_LOCATION_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const ORIGIN_LOCATION_ANNOTATION =
'backstage.io/managed-by-origin-location';
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "parseEntityName" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function parseEntityName(
ref: EntityRef,
context?: EntityRefContext,
): EntityName;
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "parseEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
// Warning: (ae-missing-release-tag) "parseEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
// Warning: (ae-missing-release-tag) "parseEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function parseEntityRef(
ref: EntityRef,
@@ -535,89 +406,54 @@ export function parseEntityRef(
name: string;
};
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
// Warning: (ae-missing-release-tag) "parseLocationReference" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function parseLocationReference(ref: string): {
type: string;
target: string;
};
// Warning: (ae-missing-release-tag) "RELATION_API_CONSUMED_BY" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const RELATION_API_CONSUMED_BY = 'apiConsumedBy';
// Warning: (ae-missing-release-tag) "RELATION_API_PROVIDED_BY" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const RELATION_API_PROVIDED_BY = 'apiProvidedBy';
// Warning: (ae-missing-release-tag) "RELATION_CHILD_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const RELATION_CHILD_OF = 'childOf';
// Warning: (ae-missing-release-tag) "RELATION_CONSUMES_API" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export const RELATION_CONSUMES_API = 'consumesApi';
// Warning: (ae-missing-release-tag) "RELATION_DEPENDENCY_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const RELATION_DEPENDENCY_OF = 'dependencyOf';
// Warning: (ae-missing-release-tag) "RELATION_DEPENDS_ON" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export const RELATION_DEPENDS_ON = 'dependsOn';
// Warning: (ae-missing-release-tag) "RELATION_HAS_MEMBER" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const RELATION_HAS_MEMBER = 'hasMember';
// Warning: (ae-missing-release-tag) "RELATION_HAS_PART" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const RELATION_HAS_PART = 'hasPart';
// Warning: (ae-missing-release-tag) "RELATION_MEMBER_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export const RELATION_MEMBER_OF = 'memberOf';
// Warning: (ae-missing-release-tag) "RELATION_OWNED_BY" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export const RELATION_OWNED_BY = 'ownedBy';
// Warning: (ae-missing-release-tag) "RELATION_OWNER_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const RELATION_OWNER_OF = 'ownerOf';
// Warning: (ae-missing-release-tag) "RELATION_PARENT_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export const RELATION_PARENT_OF = 'parentOf';
// Warning: (ae-missing-release-tag) "RELATION_PART_OF" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export const RELATION_PART_OF = 'partOf';
// Warning: (ae-missing-release-tag) "RELATION_PROVIDES_API" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const RELATION_PROVIDES_API = 'providesApi';
// Warning: (ae-missing-release-tag) "ResourceEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
interface ResourceEntityV1alpha1 extends Entity {
// (undocumented)
@@ -635,22 +471,15 @@ interface ResourceEntityV1alpha1 extends Entity {
export { ResourceEntityV1alpha1 as ResourceEntity };
export { ResourceEntityV1alpha1 };
// Warning: (ae-missing-release-tag) "resourceEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const resourceEntityV1alpha1Validator: KindValidator;
// Warning: (ae-missing-release-tag) "SchemaValidEntityPolicy" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export class SchemaValidEntityPolicy implements EntityPolicy {
// (undocumented)
enforce(entity: Entity): Promise<Entity>;
}
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "serializeEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public @deprecated
export function serializeEntityRef(
ref:
@@ -662,14 +491,9 @@ export function serializeEntityRef(
},
): EntityRef;
// Warning: (ae-missing-release-tag) "SOURCE_LOCATION_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const SOURCE_LOCATION_ANNOTATION = 'backstage.io/source-location';
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "stringifyEntityRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function stringifyEntityRef(
ref:
@@ -681,19 +505,12 @@ export function stringifyEntityRef(
},
): string;
// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// Warning: (ae-missing-release-tag) "stringifyLocationReference" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export function stringifyLocationReference(ref: {
type: string;
target: string;
}): string;
// Warning: (ae-missing-release-tag) "SystemEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
interface SystemEntityV1alpha1 extends Entity {
// (undocumented)
@@ -709,13 +526,9 @@ interface SystemEntityV1alpha1 extends Entity {
export { SystemEntityV1alpha1 as SystemEntity };
export { SystemEntityV1alpha1 };
// Warning: (ae-missing-release-tag) "systemEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const systemEntityV1alpha1Validator: KindValidator;
// Warning: (ae-missing-release-tag) "TemplateEntityV1beta2" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export interface TemplateEntityV1beta2 extends Entity {
// (undocumented)
@@ -740,8 +553,6 @@ export interface TemplateEntityV1beta2 extends Entity {
};
}
// Warning: (ae-missing-release-tag) "templateEntityV1beta2Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const templateEntityV1beta2Validator: KindValidator;
@@ -761,8 +572,6 @@ export type UNSTABLE_EntityStatusItem = {
// @alpha
export type UNSTABLE_EntityStatusLevel = 'info' | 'warning' | 'error';
// Warning: (ae-missing-release-tag) "UserEntityV1alpha1" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
interface UserEntityV1alpha1 extends Entity {
// (undocumented)
@@ -782,13 +591,9 @@ interface UserEntityV1alpha1 extends Entity {
export { UserEntityV1alpha1 as UserEntity };
export { UserEntityV1alpha1 };
// Warning: (ae-missing-release-tag) "userEntityV1alpha1Validator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export const userEntityV1alpha1Validator: KindValidator;
// Warning: (ae-missing-release-tag) "Validators" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type Validators = {
isValidApiVersion(value: unknown): boolean;
@@ -802,18 +607,12 @@ export type Validators = {
isValidTag(value: unknown): boolean;
};
// Warning: (ae-missing-release-tag) "VIEW_URL_ANNOTATION" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public
export const VIEW_URL_ANNOTATION = 'backstage.io/view-url';
// Warnings were encountered during analysis:
//
// src/EntityPolicies.d.ts:13:5 - (ae-forgotten-export) The symbol "AllEntityPolicies" needs to be exported by the entry point index.d.ts
// src/EntityPolicies.d.ts:14:5 - (ae-forgotten-export) The symbol "AnyEntityPolicy" needs to be exported by the entry point index.d.ts
// src/entity/Entity.d.ts:37:5 - (ae-incompatible-release-tags) The symbol "status" is marked as @public, but its signature references "UNSTABLE_EntityStatus" which is marked as @alpha
// src/entity/policies/types.d.ts:10:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// src/kinds/types.d.ts:9:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
// src/entity/Entity.d.ts:38:5 - (ae-incompatible-release-tags) The symbol "status" is marked as @public, but its signature references "UNSTABLE_EntityStatus" which is marked as @alpha
// (No @packageDocumentation comment for this package)
```
packages/catalog-model/src/EntityPolicies.ts
+3 -2
View File
@@ -52,11 +52,12 @@ class AnyEntityPolicy implements EntityPolicy {
}
}
/** @public */
export const EntityPolicies = {
allOf(policies: EntityPolicy[]) {
allOf(policies: EntityPolicy[]): EntityPolicy {
return new AllEntityPolicies(policies);
},
oneOf(policies: EntityPolicy[]) {
oneOf(policies: EntityPolicy[]): EntityPolicy {
return new AnyEntityPolicy(policies);
},
};
packages/catalog-model/src/entity/Entity.ts
+8
View File
@@ -21,6 +21,7 @@ import { UNSTABLE_EntityStatus } from './EntityStatus';
/**
* The parts of the format that's common to all versions/kinds of entity.
*
* @public
* @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/
*/
export type Entity = {
@@ -62,6 +63,7 @@ export type Entity = {
/**
* Metadata fields common to all versions/kinds of entity.
*
* @public
* @see https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta
* @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/
*/
@@ -166,6 +168,8 @@ export type EntityMeta = JsonObject & {
/**
* A relation of a specific type to another entity in the catalog.
*
* @public
*/
export type EntityRelation = {
/**
@@ -181,6 +185,8 @@ export type EntityRelation = {
/**
* Holds the relation data for entities.
*
* @public
*/
export type EntityRelationSpec = {
/**
@@ -201,6 +207,8 @@ export type EntityRelationSpec = {
/**
* A link to external information that is related to the entity.
*
* @public
*/
export type EntityLink = {
/**
packages/catalog-model/src/entity/EntityEnvelope.ts
+1
View File
@@ -18,6 +18,7 @@
* The envelope skeleton parts of an entity - whatever is necessary to be able
* to give it a ref and pass to further validation / policy checking.
*
* @public
* @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/
*/
export type EntityEnvelope = {
packages/catalog-model/src/entity/EntityStatus.ts
+1
View File
@@ -18,6 +18,7 @@ import { SerializedError } from '@backstage/errors';
/**
* The current status of the entity, as claimed by various sources.
*
* @alpha
*/
export type UNSTABLE_EntityStatus = {
packages/catalog-model/src/entity/constants.ts
+7
View File
@@ -16,11 +16,15 @@
/**
* The namespace that entities without an explicit namespace fall into.
*
* @public
*/
export const ENTITY_DEFAULT_NAMESPACE = 'default';
/**
* The keys of EntityMeta that are auto-generated.
*
* @public
*/
export const ENTITY_META_GENERATED_FIELDS = [
'uid',
@@ -30,6 +34,9 @@ export const ENTITY_META_GENERATED_FIELDS = [
/**
* Annotations for linking to entity from catalog pages.
*
* @public
*/
export const VIEW_URL_ANNOTATION = 'backstage.io/view-url';
/** @public */
export const EDIT_URL_ANNOTATION = 'backstage.io/edit-url';
packages/catalog-model/src/entity/index.ts
+1
View File
@@ -42,6 +42,7 @@ export {
serializeEntityRef,
stringifyEntityRef,
} from './ref';
export type { EntityRefContext } from './ref';
export {
entityHasChanges,
generateEntityEtag,
packages/catalog-model/src/entity/policies/DefaultNamespaceEntityPolicy.ts
+2
View File
@@ -21,6 +21,8 @@ import { Entity } from '../Entity';
/**
* Sets a default namespace if none was set.
*
* @public
*/
export class DefaultNamespaceEntityPolicy implements EntityPolicy {
private readonly namespace: string;
packages/catalog-model/src/entity/policies/FieldFormatEntityPolicy.ts
+2
View File
@@ -29,6 +29,8 @@ import { Entity } from '../Entity';
*
* This does not take into account machine generated fields such as uid, etag
* and generation.
*
* @public
*/
export class FieldFormatEntityPolicy implements EntityPolicy {
private readonly validators: Validators;
packages/catalog-model/src/entity/policies/NoForeignRootFieldsEntityPolicy.ts
+2
View File
@@ -21,6 +21,8 @@ const defaultKnownFields = ['apiVersion', 'kind', 'metadata', 'spec'];
/**
* Ensures that there are no foreign root fields in the entity.
*
* @public
*/
export class NoForeignRootFieldsEntityPolicy implements EntityPolicy {
private readonly knownFields: string[];
packages/catalog-model/src/entity/policies/SchemaValidEntityPolicy.ts
+2
View File
@@ -27,6 +27,8 @@ import { EntityPolicy } from './types';
* This should be the first policy in the list, to ensure that other downstream
* policies can work with a structure that is at least valid in therms of the
* typescript type.
*
* @public
*/
export class SchemaValidEntityPolicy implements EntityPolicy {
private validate: ValidateFunction<Entity> | undefined;
packages/catalog-model/src/entity/policies/types.ts
+3 -1
View File
@@ -19,12 +19,14 @@ import type { Entity } from '../Entity';
/**
* A policy for validation or mutation to be applied to entities as they are
* entering the system.
*
* @public
*/
export type EntityPolicy = {
/**
* Applies validation or mutation on an entity.
*
* @param entity The entity, as validated/mutated so far in the policy tree
* @param entity - The entity, as validated/mutated so far in the policy tree
* @returns The incoming entity, or a mutated version of the same, or
* undefined if this processor could not handle the entity
* @throws An error if the entity should be rejected
packages/catalog-model/src/entity/ref.ts
+21 -11
View File
@@ -41,7 +41,8 @@ function parseRefString(ref: string): {
* Extracts the kind, namespace and name that form the name triplet of the
* given entity.
*
* @param entity An entity
* @public
* @param entity - An entity
* @returns The complete entity name
*/
export function getEntityName(entity: Entity): EntityName {
@@ -54,8 +55,10 @@ export function getEntityName(entity: Entity): EntityName {
/**
* The context of defaults that entity reference parsing happens within.
*
* @public
*/
type EntityRefContext = {
export type EntityRefContext = {
/** The default kind, if none is given in the reference */
defaultKind?: string;
/** The default namespace, if none is given in the reference */
@@ -70,8 +73,9 @@ type EntityRefContext = {
* otherwise specified as part of the options, and will throw an error if no
* kind was specified in the input reference and no default kind was given.
*
* @param ref The reference to parse
* @param context The context of defaults that the parsing happens within
* @public
* @param ref - The reference to parse
* @param context - The context of defaults that the parsing happens within
* @returns A complete entity name
*/
export function parseEntityName(
@@ -99,8 +103,9 @@ export function parseEntityName(
* The options object can contain default values for the kind and namespace,
* that will be used if the input reference did not specify any.
*
* @param ref The reference to parse
* @param context The context of defaults that the parsing happens within
* @public
* @param ref - The reference to parse
* @param context - The context of defaults that the parsing happens within
* @returns The compound form of the reference
*/
export function parseEntityRef(
@@ -111,6 +116,7 @@ export function parseEntityRef(
namespace: string;
name: string;
};
/** @public */
export function parseEntityRef(
ref: EntityRef,
context?: { defaultKind: string },
@@ -119,6 +125,7 @@ export function parseEntityRef(
namespace?: string;
name: string;
};
/** @public */
export function parseEntityRef(
ref: EntityRef,
context?: { defaultNamespace: string },
@@ -170,8 +177,9 @@ export function parseEntityRef(
* special/reserved characters, it outputs the string form, otherwise it
* outputs the compound form.
*
* @public
* @deprecated Use `stringifyEntityRef` instead
* @param ref The reference to serialize
* @param ref - The reference to serialize
* @returns The same reference on either string or compound form
*/
export function serializeEntityRef(
@@ -219,7 +227,8 @@ export function serializeEntityRef(
* all parts of the name to lowercase and inserts the default namespace if needed.
* It is typically not the best way to represent the entity reference to the user.
*
* @param ref The reference to serialize
* @public
* @param ref - The reference to serialize
* @returns The same reference on either string or compound form
*/
export function stringifyEntityRef(
@@ -248,9 +257,10 @@ export function stringifyEntityRef(
* The comparison is case insensitive, and all of kind, namespace, and name
* must match (after applying the optional context to the ref).
*
* @param entity The entity to match
* @param ref A string or compound entity ref
* @param context An optional context of default kind and namespace, that apply
* @public
* @param entity - The entity to match
* @param ref - A string or compound entity ref
* @param context - An optional context of default kind and namespace, that apply
* to the ref if given
* @returns True if matching, false otherwise
*/
packages/catalog-model/src/entity/util.ts
+8 -4
View File
@@ -21,6 +21,7 @@ import { Entity } from './Entity';
/**
* Generates a new random UID for an entity.
*
* @public
* @returns A string with enough randomness to uniquely identify an entity
*/
export function generateEntityUid(): string {
@@ -30,6 +31,7 @@ export function generateEntityUid(): string {
/**
* Generates a new random Etag for an entity.
*
* @public
* @returns A string with enough randomness to uniquely identify an entity
* revision
*/
@@ -48,8 +50,9 @@ export function generateEntityEtag(): string {
* account. It only compares the actual input entity data, i.e. metadata and
* spec.
*
* @param previous The old state of the entity
* @param next The new state of the entity
* @public
* @param previous - The old state of the entity
* @param next - The new state of the entity
*/
export function entityHasChanges(previous: Entity, next: Entity): boolean {
const e1 = lodash.cloneDeep(previous);
@@ -98,8 +101,9 @@ export function entityHasChanges(previous: Entity, next: Entity): boolean {
* The previous revision is expected to be a complete model loaded from the
* catalog, including the uid, etag and generation fields.
*
* @param previous The old state of the entity
* @param next The new state of the entity
* @public
* @param previous - The old state of the entity
* @param next - The new state of the entity
* @returns An entity with the merged state of both
*/
export function generateUpdatedEntity(previous: Entity, next: Entity): Entity {
packages/catalog-model/src/kinds/ApiEntityV1alpha1.ts
+2
View File
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
import schema from '../schema/kinds/API.v1alpha1.schema.json';
import { ajvCompiledJsonSchemaValidator } from './util';
/** @public */
export interface ApiEntityV1alpha1 extends Entity {
apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
kind: 'API';
@@ -30,5 +31,6 @@ export interface ApiEntityV1alpha1 extends Entity {
};
}
/** @public */
export const apiEntityV1alpha1Validator =
ajvCompiledJsonSchemaValidator(schema);
packages/catalog-model/src/kinds/ComponentEntityV1alpha1.ts
+2
View File
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
import schema from '../schema/kinds/Component.v1alpha1.schema.json';
import { ajvCompiledJsonSchemaValidator } from './util';
/** @public */
export interface ComponentEntityV1alpha1 extends Entity {
apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
kind: 'Component';
@@ -33,5 +34,6 @@ export interface ComponentEntityV1alpha1 extends Entity {
};
}
/** @public */
export const componentEntityV1alpha1Validator =
ajvCompiledJsonSchemaValidator(schema);
packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts
+2
View File
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
import schema from '../schema/kinds/Domain.v1alpha1.schema.json';
import { ajvCompiledJsonSchemaValidator } from './util';
/** @public */
export interface DomainEntityV1alpha1 extends Entity {
apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
kind: 'Domain';
@@ -26,5 +27,6 @@ export interface DomainEntityV1alpha1 extends Entity {
};
}
/** @public */
export const domainEntityV1alpha1Validator =
ajvCompiledJsonSchemaValidator(schema);
packages/catalog-model/src/kinds/GroupEntityV1alpha1.ts
+2
View File
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
import schema from '../schema/kinds/Group.v1alpha1.schema.json';
import { ajvCompiledJsonSchemaValidator } from './util';
/** @public */
export interface GroupEntityV1alpha1 extends Entity {
apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
kind: 'Group';
@@ -34,5 +35,6 @@ export interface GroupEntityV1alpha1 extends Entity {
};
}
/** @public */
export const groupEntityV1alpha1Validator =
ajvCompiledJsonSchemaValidator(schema);
packages/catalog-model/src/kinds/LocationEntityV1alpha1.ts
+2
View File
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
import schema from '../schema/kinds/Location.v1alpha1.schema.json';
import { ajvCompiledJsonSchemaValidator } from './util';
/** @public */
export interface LocationEntityV1alpha1 extends Entity {
apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
kind: 'Location';
@@ -28,5 +29,6 @@ export interface LocationEntityV1alpha1 extends Entity {
};
}
/** @public */
export const locationEntityV1alpha1Validator =
ajvCompiledJsonSchemaValidator(schema);
packages/catalog-model/src/kinds/ResourceEntityV1alpha1.ts
+2
View File
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
import schema from '../schema/kinds/Resource.v1alpha1.schema.json';
import { ajvCompiledJsonSchemaValidator } from './util';
/** @public */
export interface ResourceEntityV1alpha1 extends Entity {
apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
kind: 'Resource';
@@ -29,5 +30,6 @@ export interface ResourceEntityV1alpha1 extends Entity {
};
}
/** @public */
export const resourceEntityV1alpha1Validator =
ajvCompiledJsonSchemaValidator(schema);
packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts
+2
View File
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
import schema from '../schema/kinds/System.v1alpha1.schema.json';
import { ajvCompiledJsonSchemaValidator } from './util';
/** @public */
export interface SystemEntityV1alpha1 extends Entity {
apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
kind: 'System';
@@ -27,5 +28,6 @@ export interface SystemEntityV1alpha1 extends Entity {
};
}
/** @public */
export const systemEntityV1alpha1Validator =
ajvCompiledJsonSchemaValidator(schema);
packages/catalog-model/src/kinds/TemplateEntityV1beta2.ts
+2
View File
@@ -19,6 +19,7 @@ import type { Entity } from '../entity/Entity';
import schema from '../schema/kinds/Template.v1beta2.schema.json';
import { ajvCompiledJsonSchemaValidator } from './util';
/** @public */
export interface TemplateEntityV1beta2 extends Entity {
apiVersion: 'backstage.io/v1beta2';
kind: 'Template';
@@ -37,5 +38,6 @@ export interface TemplateEntityV1beta2 extends Entity {
};
}
/** @public */
export const templateEntityV1beta2Validator =
ajvCompiledJsonSchemaValidator(schema);
packages/catalog-model/src/kinds/UserEntityV1alpha1.ts
+2
View File
@@ -18,6 +18,7 @@ import type { Entity } from '../entity/Entity';
import schema from '../schema/kinds/User.v1alpha1.schema.json';
import { ajvCompiledJsonSchemaValidator } from './util';
/** @public */
export interface UserEntityV1alpha1 extends Entity {
apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1';
kind: 'User';
@@ -31,5 +32,6 @@ export interface UserEntityV1alpha1 extends Entity {
};
}
/** @public */
export const userEntityV1alpha1Validator =
ajvCompiledJsonSchemaValidator(schema);
packages/catalog-model/src/kinds/relations.ts
+20
View File
@@ -25,40 +25,60 @@ Naming rules for relations in priority order:
/**
* An ownership relation where the owner is usually an organizational
* entity (user or group), and the other entity can be anything.
*
* @public
*/
export const RELATION_OWNED_BY = 'ownedBy';
/** @public */
export const RELATION_OWNER_OF = 'ownerOf';
/**
* A relation with an API entity, typically from a component
*
* @public
*/
export const RELATION_CONSUMES_API = 'consumesApi';
/** @public */
export const RELATION_API_CONSUMED_BY = 'apiConsumedBy';
/** @public */
export const RELATION_PROVIDES_API = 'providesApi';
/** @public */
export const RELATION_API_PROVIDED_BY = 'apiProvidedBy';
/**
* A relation denoting a dependency on another entity.
*
* @public
*/
export const RELATION_DEPENDS_ON = 'dependsOn';
/** @public */
export const RELATION_DEPENDENCY_OF = 'dependencyOf';
/**
* A parent/child relation to build up a tree, used for example to describe
* the organizational structure between groups.
*
* @public
*/
export const RELATION_PARENT_OF = 'parentOf';
/** @public */
export const RELATION_CHILD_OF = 'childOf';
/**
* A membership relation, typically for users in a group.
*
* @public
*/
export const RELATION_MEMBER_OF = 'memberOf';
/** @public */
export const RELATION_HAS_MEMBER = 'hasMember';
/**
* A part/whole relation, typically for components in a system and systems
* in a domain.
*
* @public
*/
export const RELATION_PART_OF = 'partOf';
/** @public */
export const RELATION_HAS_PART = 'hasPart';
packages/catalog-model/src/kinds/types.ts
+3 -1
View File
@@ -18,12 +18,14 @@ import { Entity } from '../entity';
/**
* Validates entities of a certain kind.
*
* @public
*/
export type KindValidator = {
/**
* Validates the entity as a known entity kind.
*
* @param entity The entity to validate
* @param entity - The entity to validate
* @returns Resolves to true, if the entity was of a kind that was known and
* handled by this validator, and was found to be valid. Resolves to false,
* if the entity was not of a kind that was known by this validator.
packages/catalog-model/src/location/annotation.ts
+3
View File
@@ -14,8 +14,11 @@
* limitations under the License.
*/
/** @public */
export const LOCATION_ANNOTATION = 'backstage.io/managed-by-location';
/** @public */
export const ORIGIN_LOCATION_ANNOTATION =
'backstage.io/managed-by-origin-location';
/** @public */
export const SOURCE_LOCATION_ANNOTATION = 'backstage.io/source-location';
packages/catalog-model/src/location/helpers.ts
+9 -5
View File
@@ -23,8 +23,9 @@ import { LOCATION_ANNOTATION, SOURCE_LOCATION_ANNOTATION } from './annotation';
* Note that the return type is not `LocationSpec`, because we do not want to
* conflate the string form with the additional properties of that type.
*
* @param ref A string-form location reference, e.g. 'url:https://host'
* @returns A location reference, e.g. { type: 'url', target: 'https://host' }
* @public
* @param ref - A string-form location reference, e.g. `'url:https://host'`
* @returns A location reference, e.g. `{ type: 'url', target: 'https://host' }`
*/
export function parseLocationReference(ref: string): {
type: string;
@@ -67,8 +68,9 @@ export function parseLocationReference(ref: string): {
* Note that the input type is not `LocationSpec`, because we do not want to
* conflate the string form with the additional properties of that type.
*
* @param ref A location reference, e.g. { type: 'url', target: 'https://host' }
* @returns A string-form location reference, e.g. 'url:https://host'
* @public
* @param ref - A location reference, e.g. `{ type: 'url', target: 'https://host' }`
* @returns A string-form location reference, e.g. `'url:https://host'`
*/
export function stringifyLocationReference(ref: {
type: string;
@@ -89,8 +91,10 @@ export function stringifyLocationReference(ref: {
* Returns the source code location of the Entity, to the extent that one exists.
*
* If the returned location type is of type 'url', the target should be readable at least
* using the UrlReader from @backstage/backend-common. If it is not of type 'url', the caller
* using the UrlReader from `@backstage/backend-common`. If it is not of type 'url', the caller
* needs to have explicit handling of each location type or signal that it is not supported.
*
* @public
*/
export function getEntitySourceLocation(entity: Entity): {
type: string;
packages/catalog-model/src/location/types.ts
+2
View File
@@ -14,6 +14,7 @@
* limitations under the License.
*/
/** @public */
export type LocationSpec = {
type: string;
target: string;
@@ -23,6 +24,7 @@ export type LocationSpec = {
presence?: 'optional' | 'required';
};
/** @public */
export type Location = {
id: string;
} & LocationSpec;
packages/catalog-model/src/location/validation.ts
+12 -3
View File
@@ -17,7 +17,10 @@
import * as yup from 'yup';
import { LocationSpec, Location } from './types';
/** @deprecated */
/**
* @public
* @deprecated Use JSONSchema or validators instead.
*/
export const locationSpecSchema = yup
.object<LocationSpec>({
type: yup.string().required(),
@@ -27,7 +30,10 @@ export const locationSpecSchema = yup
.noUnknown()
.required();
/** @deprecated */
/**
* @public
* @deprecated Use JSONSchema or validators instead.
*/
export const locationSchema = yup
.object<Location>({
id: yup.string().required(),
@@ -37,7 +43,10 @@ export const locationSchema = yup
.noUnknown()
.required();
/** @deprecated */
/**
* @public
* @deprecated Use JSONSchema or validators instead.
*/
export const analyzeLocationSchema = yup
.object<{ location: LocationSpec }>({
location: locationSpecSchema,
packages/catalog-model/src/types.ts
+5
View File
@@ -17,10 +17,13 @@
import { JsonValue } from '@backstage/config';
import { JSONSchema7 } from 'json-schema';
/** @public */
export type JSONSchema = JSONSchema7 & { [key in string]?: JsonValue };
/**
* A complete entity name, with the full kind-namespace-name triplet.
*
* @public
*/
export type EntityName = {
kind: string;
@@ -36,6 +39,8 @@ export type EntityName = {
*
* Left-out parts of the reference need to be handled by the application,
* either by rejecting the reference or by falling back to default values.
*
* @public
*/
export type EntityRef =
| string
packages/catalog-model/src/validation/CommonValidatorFunctions.ts
+11 -9
View File
@@ -19,16 +19,18 @@ import lodash from 'lodash';
/**
* Contains various helper validation and normalization functions that can be
* composed to form a Validator.
*
* @public
*/
export class CommonValidatorFunctions {
/**
* Checks that the value is on the form <suffix> or <prefix><separator><suffix>, and validates
* those parts separately.
*
* @param value The value to check
* @param separator The separator between parts
* @param isValidPrefix Checks that the part before the separator is valid, if present
* @param isValidSuffix Checks that the part after the separator (or the entire value if there is no separator) is valid
* @param value - The value to check
* @param separator - The separator between parts
* @param isValidPrefix - Checks that the part before the separator is valid, if present
* @param isValidSuffix - Checks that the part after the separator (or the entire value if there is no separator) is valid
*/
static isValidPrefixAndOrSuffix(
value: unknown,
@@ -53,7 +55,7 @@ export class CommonValidatorFunctions {
/**
* Checks that the value can be safely transferred as JSON.
*
* @param value The value to check
* @param value - The value to check
*/
static isJsonSafe(value: unknown): boolean {
try {
@@ -66,7 +68,7 @@ export class CommonValidatorFunctions {
/**
* Checks that the value is a valid DNS subdomain name.
*
* @param value The value to check
* @param value - The value to check
* @see https://tools.ietf.org/html/rfc1123
*/
static isValidDnsSubdomain(value: unknown): boolean {
@@ -81,7 +83,7 @@ export class CommonValidatorFunctions {
/**
* Checks that the value is a valid DNS label.
*
* @param value The value to check
* @param value - The value to check
* @see https://tools.ietf.org/html/rfc1123
*/
static isValidDnsLabel(value: unknown): boolean {
@@ -96,7 +98,7 @@ export class CommonValidatorFunctions {
/**
* Checks that the value is a valid URL.
*
* @param value The value to check
* @param value - The value to check
*/
static isValidUrl(value: unknown): boolean {
if (typeof value !== 'string') {
@@ -115,7 +117,7 @@ export class CommonValidatorFunctions {
/**
* Checks that the value is a non empty string value.
*
* @param value The value to check
* @param value - The value to check
*/
static isValidString(value: unknown): boolean {
return typeof value === 'string' && value?.trim()?.length >= 1;
packages/catalog-model/src/validation/KubernetesValidatorFunctions.ts
+1
View File
@@ -20,6 +20,7 @@ import { CommonValidatorFunctions } from './CommonValidatorFunctions';
* Contains validation functions that match the Kubernetes spec, usable to
* build a catalog that is compatible with those rule sets.
*
* @public
* @see https://kubernetes.io/docs/concepts/overview/working-with-objects/names/
* @see https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set
* @see https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set
packages/catalog-model/src/validation/entityEnvelopeSchemaValidator.ts
+2 -1
View File
@@ -22,7 +22,7 @@ import { compileAjvSchema, throwAjvError } from './ajv';
/**
* Creates a validation function that takes some arbitrary data, and either
* returns that data cast to an {@link EntityEnvelope} (or the given subtype)
* if it matches that schema, or throws a {@link TypeError} describing the
* if it matches that schema, or throws a {@link globals#TypeError} describing the
* errors.
*
* Note that this validator is only meant for applying the base schema checks;
@@ -38,6 +38,7 @@ import { compileAjvSchema, throwAjvError } from './ajv';
* - EntityMeta
* - common#<id>
*
* @public
* @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema
*/
export function entityEnvelopeSchemaValidator<
packages/catalog-model/src/validation/entityKindSchemaValidator.ts
+10 -9
View File
@@ -22,20 +22,20 @@ import { compileAjvSchema, throwAjvError } from './ajv';
* Creates a validation function that takes some arbitrary data, and either
* returns that data cast to a `T` if it matches that schema, or `false` if the
* schema apiVersion/kind didn't apply to that data, or throws a
* {@link TypeError} describing actual errors.
* {@link globals#TypeError} describing actual errors.
*
* This validator is highly specialized, in that it has special treatment of
* the `kind` and `apiVersion` root keys. This only works if your schema has
* their rule set to `"enum"`:
*
* <pre>
* "apiVersion": {
* "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"]
* },
* "kind": {
* "enum": ["Group"]
* },
* </pre>
* ```
* "apiVersion": {
* "enum": ["backstage.io/v1alpha1", "backstage.io/v1beta1"]
* },
* "kind": {
* "enum": ["Group"]
* },
* ```
*
* In the above example, the created validator will return `false` if and only
* if the kind and/or apiVersion mismatch.
@@ -52,6 +52,7 @@ import { compileAjvSchema, throwAjvError } from './ajv';
* - EntityMeta
* - common#<id>
*
* @public
* @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema
*/
export function entityKindSchemaValidator<T extends Entity>(
packages/catalog-model/src/validation/entitySchemaValidator.ts
+2 -1
View File
@@ -22,7 +22,7 @@ import { compileAjvSchema, throwAjvError } from './ajv';
/**
* Creates a validation function that takes some arbitrary data, and either
* returns that data cast to an {@link Entity} (or the given subtype) if it
* matches that schema, or throws a {@link TypeError} describing the errors.
* matches that schema, or throws a {@link globals#TypeError} describing the errors.
*
* Note that this validator is only meant for applying the base schema checks;
* it does not take custom policies or additional processor based validation
@@ -37,6 +37,7 @@ import { compileAjvSchema, throwAjvError } from './ajv';
* - EntityMeta
* - common#<id>
*
* @public
* @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema
*/
export function entitySchemaValidator<T extends Entity = Entity>(
packages/catalog-model/src/validation/makeValidator.ts
+1
View File
@@ -30,6 +30,7 @@ const defaultValidators: Validators = {
isValidTag: CommonValidatorFunctions.isValidDnsLabel,
};
/** @public */
export function makeValidator(overrides: Partial<Validators> = {}): Validators {
return {
...defaultValidators,
packages/catalog-model/src/validation/types.ts
+1
View File
@@ -14,6 +14,7 @@
* limitations under the License.
*/
/** @public */
export type Validators = {
isValidApiVersion(value: unknown): boolean;
isValidKind(value: unknown): boolean;

Some files were not shown because too many files have changed in this diff Show More