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

Merge pull request #10169 from backstage/blam/scaffolder/tidy-up-api-reports

Browse Source 
Tidying up some api-reports
This commit is contained in:
Ben Lambert
2022-03-15 13:14:10 +01:00
committed by GitHub
parent 4e3e34e120 169e00c426
commit 401c122840
9 changed files with 136 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/lucky-kangaroos-sneeze.md
+6
View File
@@ -0,0 +1,6 @@
---
'@backstage/plugin-scaffolder-backend': patch
'@backstage/plugin-scaffolder-common': patch
---
Adding some documentation for exported things
plugins/scaffolder-backend/api-report.md
+3 -14
View File
@@ -49,15 +49,10 @@ export const createBuiltinActions: (
// @public
export interface CreateBuiltInActionsOptions {
// (undocumented)
additionalTemplateFilters?: Record<string, TemplateFilter>;
// (undocumented)
catalogClient: CatalogApi;
// (undocumented)
config: Config;
// (undocumented)
integrations: ScmIntegrations;
// (undocumented)
reader: UrlReader;
}
@@ -142,19 +137,16 @@ export function createGithubActionsDispatchAction(options: {
token?: string | undefined;
}>;
// @public (undocumented)
// @public
export interface CreateGithubPullRequestActionOptions {
// (undocumented)
clientFactory?: (
input: CreateGithubPullRequestClientFactoryInput,
) => Promise<OctokitWithPullRequestPluginClient>;
// (undocumented)
githubCredentialsProvider?: GithubCredentialsProvider;
// (undocumented)
integrations: ScmIntegrationRegistry;
}
// @public (undocumented)
// @public
export type CreateGithubPullRequestClientFactoryInput = {
integrations: ScmIntegrationRegistry;
githubCredentialsProvider?: GithubCredentialsProvider;
@@ -278,7 +270,7 @@ export const createPublishGitlabMergeRequestAction: (options: {
token?: string | undefined;
}>;
// @public (undocumented)
// @public
export function createRouter(options: RouterOptions): Promise<express.Router>;
// @public
@@ -298,11 +290,8 @@ export type CreateWorkerOptions = {
// @public
export interface CurrentClaimedTask {
// (undocumented)
secrets?: TaskSecrets;
// (undocumented)
spec: TaskSpec;
// (undocumented)
taskId: string;
}
plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts
+16
View File
@@ -54,10 +54,26 @@ import { TemplateAction } from '../types';
* @public
*/
export interface CreateBuiltInActionsOptions {
/**
* The {@link @backstage/backend-common#UrlReader} interface that will be used in the default actions.
*/
reader: UrlReader;
/**
* The {@link @backstage/integrations#ScmIntegrations} that will be used in the default actions.
*/
integrations: ScmIntegrations;
/**
* The {@link @backstage/catalog-client#CatalogApi} that will be used in the default actions.
*/
catalogClient: CatalogApi;
/**
* The {@link @backstage/config#Config} that will be used in the default actions.
*/
config: Config;
/**
* Additional custom filters that will be passed to the nunjucks template engine for use in
* Template Manifests and also template skeleton files when using `fetch:template`.
*/
additionalTemplateFilters?: Record<string, TemplateFilter>;
}
plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts
+17 -2
View File
@@ -41,7 +41,10 @@ export interface OctokitWithPullRequestPluginClient {
} | null>;
}
/** @public */
/**
* The options passed to the client factory function.
* @public
*/
export type CreateGithubPullRequestClientFactoryInput = {
integrations: ScmIntegrationRegistry;
githubCredentialsProvider?: GithubCredentialsProvider;
@@ -74,10 +77,22 @@ export const defaultClientFactory = async ({
return new OctokitPR(octokitOptions);
};
/** @public */
/**
* The options passed to {@link createPublishGithubPullRequestAction} method
* @public
*/
export interface CreateGithubPullRequestActionOptions {
/**
* An instance of {@link @backstage/integration#ScmIntegrationRegistry} that will be used in the action.
*/
integrations: ScmIntegrationRegistry;
/**
* An instance of {@link @backstage/integration#GithubCredentialsProvider} that will be used to get credentials for the action.
*/
githubCredentialsProvider?: GithubCredentialsProvider;
/**
* A method to return the Octokit client with the Pull Request Plugin.
*/
clientFactory?: (
input: CreateGithubPullRequestClientFactoryInput,
) => Promise<OctokitWithPullRequestPluginClient>;
plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts
+24
View File
@@ -115,8 +115,17 @@ export class TaskManager implements TaskContext {
* @public
*/
export interface CurrentClaimedTask {
/**
* The TaskSpec of the current claimed task.
*/
spec: TaskSpec;
/**
* The uuid of the current claimed task.
*/
taskId: string;
/**
* The secrets that are stored with the task.
*/
secrets?: TaskSecrets;
}
@@ -135,6 +144,9 @@ export class StorageTaskBroker implements TaskBroker {
) {}
private deferredDispatch = defer();
/**
* {@inheritdoc TaskBroker.claim}
*/
async claim(): Promise<TaskContext> {
for (;;) {
const pendingTask = await this.storage.claimTask();
@@ -154,6 +166,9 @@ export class StorageTaskBroker implements TaskBroker {
}
}
/**
* {@inheritdoc TaskBroker.dispatch}
*/
async dispatch(
options: TaskBrokerDispatchOptions,
): Promise<{ taskId: string }> {
@@ -164,10 +179,16 @@ export class StorageTaskBroker implements TaskBroker {
};
}
/**
* {@inheritdoc TaskBroker.get}
*/
async get(taskId: string): Promise<SerializedTask> {
return this.storage.getTask(taskId);
}
/**
* {@inheritdoc TaskBroker.event$}
*/
event$(options: {
taskId: string;
after?: number;
@@ -197,6 +218,9 @@ export class StorageTaskBroker implements TaskBroker {
});
}
/**
* {@inheritdoc TaskBroker.vacuumTasks}
*/
async vacuumTasks(options: { timeoutS: number }): Promise<void> {
const { tasks } = await this.storage.listStaleTasks(options);
await Promise.all(
plugins/scaffolder-backend/src/service/router.ts
+4 -1
View File
@@ -62,7 +62,10 @@ function isSupportedTemplate(entity: TemplateEntityV1beta3) {
return entity.apiVersion === 'scaffolder.backstage.io/v1beta3';
}
/** @public */
/**
* A method to create a router for the scaffolder backend plugin.
* @public
*/
export async function createRouter(
options: RouterOptions,
): Promise<express.Router> {
plugins/scaffolder-common/api-report.md
-13
View File
@@ -13,41 +13,28 @@ export type TaskSpec = TaskSpecV1beta3;
// @public
export interface TaskSpecV1beta3 {
// (undocumented)
apiVersion: 'scaffolder.backstage.io/v1beta3';
// (undocumented)
output: {
[name: string]: JsonValue;
};
// (undocumented)
parameters: JsonObject;
// (undocumented)
steps: TaskStep[];
// (undocumented)
templateInfo?: TemplateInfo;
}
// @public
export interface TaskStep {
// (undocumented)
action: string;
// (undocumented)
id: string;
// (undocumented)
if?: string | boolean;
// (undocumented)
input?: JsonObject;
// (undocumented)
name: string;
}
// @public
export interface TemplateEntityV1beta3 extends Entity {
// (undocumented)
apiVersion: 'scaffolder.backstage.io/v1beta3';
// (undocumented)
kind: 'Template';
// (undocumented)
spec: {
type: string;
parameters?: JsonObject | JsonObject[];
plugins/scaffolder-common/src/TaskSpec.ts
+39
View File
@@ -23,7 +23,13 @@ import { JsonValue, JsonObject } from '@backstage/types';
* @public
*/
export type TemplateInfo = {
/**
* The entityRef of the template
*/
entityRef: string;
/**
* Where the template is stored, so we can resolve relative paths for things like `fetch:template` paths.
*/
baseUrl?: string;
};
@@ -33,10 +39,25 @@ export type TemplateInfo = {
* @public
*/
export interface TaskStep {
/**
* A unqiue identifier for this step.
*/
id: string;
/**
* A display name to show the user.
*/
name: string;
/**
* The underlying action ID that will be called as part of running this step.
*/
action: string;
/**
* Additional data that will be passed to the action.
*/
input?: JsonObject;
/**
* When this is false, or if the templated value string evaluates to something that is falsy the step will be skipped.
*/
if?: string | boolean;
}
@@ -47,10 +68,28 @@ export interface TaskStep {
* @public
*/
export interface TaskSpecV1beta3 {
/**
* The apiVersion string of the TaskSpec.
*/
apiVersion: 'scaffolder.backstage.io/v1beta3';
/**
* This is a JSONSchema which is used to render a form in the frontend
* to collect user input and validate it against that schema. This can then be used in the `steps` part below to template
* variables passed from the user into each action in the template.
*/
parameters: JsonObject;
/**
* A list of steps to be executed in sequence which are defined by the template. These steps are a list of the underlying
* javascript action and some optional input parameters that may or may not have been collected from the end user.
*/
steps: TaskStep[];
/**
* The output is an object where template authors can pull out information from template actions and return them in a known standard way.
*/
output: { [name: string]: JsonValue };
/**
* Some information about the template that is stored on the task spec.
*/
templateInfo?: TemplateInfo;
}
plugins/scaffolder-common/src/TemplateEntityV1beta3.ts
+27
View File
@@ -29,11 +29,32 @@ import schema from './Template.v1beta3.schema.json';
* @public
*/
export interface TemplateEntityV1beta3 extends Entity {
/**
* The apiVersion string of the TaskSpec.
*/
apiVersion: 'scaffolder.backstage.io/v1beta3';
/**
* The kind of the entity
*/
kind: 'Template';
/**
* The specification of the Template Entity
*/
spec: {
/**
* The type that the Template will create. For example service, website or library.
*/
type: string;
/**
* This is a JSONSchema or an array of JSONSchema's which is used to render a form in the frontend
* to collect user input and validate it against that schema. This can then be used in the `steps` part below to template
* variables passed from the user into each action in the template.
*/
parameters?: JsonObject | JsonObject[];
/**
* A list of steps to be executed in sequence which are defined by the template. These steps are a list of the underlying
* javascript action and some optional input parameters that may or may not have been collected from the end user.
*/
steps: Array<{
id?: string;
name?: string;
@@ -41,7 +62,13 @@ export interface TemplateEntityV1beta3 extends Entity {
input?: JsonObject;
if?: string | boolean;
}>;
/**
* The output is an object where template authors can pull out information from template actions and return them in a known standard way.
*/
output?: { [name: string]: string };
/**
* The owner entityRef of the TemplateEntity
*/
owner?: string;
};
}