From c8475ab3bbc94b16068e7b95d3729204db522357 Mon Sep 17 00:00:00 2001 From: blam Date: Mon, 14 Mar 2022 13:09:24 +0100 Subject: [PATCH] chore: working through the api-report of `scaffolder-backend` Signed-off-by: blam --- .changeset/lucky-kangaroos-sneeze.md | 6 +++++ plugins/scaffolder-backend/api-report.md | 17 +++---------- .../actions/builtin/createBuiltinActions.ts | 16 +++++++++++++ .../builtin/publish/githubPullRequest.ts | 19 +++++++++++++-- .../src/scaffolder/tasks/StorageTaskBroker.ts | 24 +++++++++++++++++++ .../scaffolder-backend/src/service/router.ts | 5 +++- 6 files changed, 70 insertions(+), 17 deletions(-) create mode 100644 .changeset/lucky-kangaroos-sneeze.md diff --git a/.changeset/lucky-kangaroos-sneeze.md b/.changeset/lucky-kangaroos-sneeze.md new file mode 100644 index 0000000000..badcd8a5cf --- /dev/null +++ b/.changeset/lucky-kangaroos-sneeze.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-scaffolder-backend': patch +'@backstage/plugin-scaffolder-common': patch +--- + +Adding some documentation for exported things diff --git a/plugins/scaffolder-backend/api-report.md b/plugins/scaffolder-backend/api-report.md index 6934f2ef83..c0d3595503 100644 --- a/plugins/scaffolder-backend/api-report.md +++ b/plugins/scaffolder-backend/api-report.md @@ -49,15 +49,10 @@ export const createBuiltinActions: ( // @public export interface CreateBuiltInActionsOptions { - // (undocumented) additionalTemplateFilters?: Record; - // (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; - // (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; // @public @@ -298,11 +290,8 @@ export type CreateWorkerOptions = { // @public export interface CurrentClaimedTask { - // (undocumented) secrets?: TaskSecrets; - // (undocumented) spec: TaskSpec; - // (undocumented) taskId: string; } diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts index d7f15cdf13..250a2b4b9e 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts @@ -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; } diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts index 2ce8e1d81e..d46457ee1b 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts @@ -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; diff --git a/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts b/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts index 1399c25118..a4ec429121 100644 --- a/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts +++ b/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts @@ -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 + */ async claim(): Promise { for (;;) { const pendingTask = await this.storage.claimTask(); @@ -154,6 +166,9 @@ export class StorageTaskBroker implements TaskBroker { } } + /** + * @inheritdoc + */ async dispatch( options: TaskBrokerDispatchOptions, ): Promise<{ taskId: string }> { @@ -164,10 +179,16 @@ export class StorageTaskBroker implements TaskBroker { }; } + /** + * @inheritdoc + */ async get(taskId: string): Promise { return this.storage.getTask(taskId); } + /** + * @inheritdoc + */ event$(options: { taskId: string; after?: number; @@ -197,6 +218,9 @@ export class StorageTaskBroker implements TaskBroker { }); } + /** + * @inheritdoc + */ async vacuumTasks(options: { timeoutS: number }): Promise { const { tasks } = await this.storage.listStaleTasks(options); await Promise.all( diff --git a/plugins/scaffolder-backend/src/service/router.ts b/plugins/scaffolder-backend/src/service/router.ts index cf073b551b..e7413b3a87 100644 --- a/plugins/scaffolder-backend/src/service/router.ts +++ b/plugins/scaffolder-backend/src/service/router.ts @@ -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 {