@backstage/backend-plugin-api 1.3.0 → 1.3.1-next.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/dist/index.d.ts +16 -18
  3. package/dist/services/definitions/SchedulerService.cjs.js.map +1 -1
  4. package/package.json +10 -10
package/CHANGELOG.md CHANGED
@@ -1,5 +1,34 @@
1
1
  # @backstage/backend-plugin-api
2
2
 
3
+ ## 1.3.1-next.1
4
+
5
+ ### Patch Changes
6
+
7
+ - acea1d4: update documentation
8
+ - 72d019d: Removed various typos
9
+ - d385854: Minor doc comment update
10
+ - Updated dependencies
11
+ - @backstage/plugin-auth-node@0.6.3-next.1
12
+ - @backstage/plugin-permission-common@0.9.0-next.0
13
+ - @backstage/plugin-permission-node@0.10.0-next.1
14
+ - @backstage/cli-common@0.1.15
15
+ - @backstage/config@1.3.2
16
+ - @backstage/errors@1.2.7
17
+ - @backstage/types@1.2.1
18
+
19
+ ## 1.3.1-next.0
20
+
21
+ ### Patch Changes
22
+
23
+ - Updated dependencies
24
+ - @backstage/plugin-auth-node@0.6.3-next.0
25
+ - @backstage/plugin-permission-node@0.9.2-next.0
26
+ - @backstage/cli-common@0.1.15
27
+ - @backstage/config@1.3.2
28
+ - @backstage/errors@1.2.7
29
+ - @backstage/types@1.2.1
30
+ - @backstage/plugin-permission-common@0.8.4
31
+
3
32
  ## 1.3.0
4
33
 
5
34
  ### Minor Changes
package/dist/index.d.ts CHANGED
@@ -491,7 +491,7 @@ interface HttpAuthService {
491
491
  *
492
492
  * Normally you do not have to specify this option, because the default
493
493
  * behavior is to extract the credentials from the request that
494
- * corresponded to the given respnse.
494
+ * corresponded to the given response.
495
495
  */
496
496
  credentials?: BackstageCredentials;
497
497
  }): Promise<{
@@ -907,13 +907,12 @@ interface SchedulerServiceTaskScheduleDefinition {
907
907
  * Overview:
908
908
  *
909
909
  * ```
910
- * ┌────────────── second (optional)
911
- * │ ┌──────────── minute
912
- * │ │ ┌────────── hour
913
- * │ │ │ ┌──────── day of month
914
- * │ │ │ │ ┌────── month
915
- * │ │ │ │ │ ┌──── day of week
916
- * │ │ │ │ │ │
910
+ * ┌────────────── second (0-60, optional)
911
+ * │ ┌──────────── minute (0-59)
912
+ * │ │ ┌────────── hour (0-23)
913
+ * │ │ │ ┌──────── day of month (1-31)
914
+ * │ │ │ │ ┌────── month (1-12)
915
+ * │ │ │ │ │ ┌──── day of week (0-6, 0 is Sunday)
917
916
  * │ │ │ │ │ │
918
917
  * * * * * * *
919
918
  * ```
@@ -999,13 +998,12 @@ interface SchedulerServiceTaskScheduleDefinitionConfig {
999
998
  * Overview:
1000
999
  *
1001
1000
  * ```
1002
- * ┌────────────── second (optional)
1003
- * │ ┌──────────── minute
1004
- * │ │ ┌────────── hour
1005
- * │ │ │ ┌──────── day of month
1006
- * │ │ │ │ ┌────── month
1007
- * │ │ │ │ │ ┌──── day of week
1008
- * │ │ │ │ │ │
1001
+ * ┌────────────── second (0-60, optional)
1002
+ * │ ┌──────────── minute (0-59)
1003
+ * │ │ ┌────────── hour (0-23)
1004
+ * │ │ │ ┌──────── day of month (1-31)
1005
+ * │ │ │ │ ┌────── month (1-12)
1006
+ * │ │ │ │ │ ┌──── day of week (0-6, 0 is Sunday)
1009
1007
  * │ │ │ │ │ │
1010
1008
  * * * * * * *
1011
1009
  * ```
@@ -1244,7 +1242,7 @@ type UrlReaderServiceReadUrlOptions = {
1244
1242
  * @remarks
1245
1243
  *
1246
1244
  * By default all URL Readers will use the integrations config which is supplied
1247
- * when creating the Readers. Sometimes it might be desireable to use the already
1245
+ * when creating the Readers. Sometimes it might be desirable to use the already
1248
1246
  * created URLReaders but with a different token, maybe that's supplied by the user
1249
1247
  * at runtime.
1250
1248
  */
@@ -1337,7 +1335,7 @@ type UrlReaderServiceReadTreeOptions = {
1337
1335
  * @remarks
1338
1336
  *
1339
1337
  * By default all URL Readers will use the integrations config which is supplied
1340
- * when creating the Readers. Sometimes it might be desireable to use the already
1338
+ * when creating the Readers. Sometimes it might be desirable to use the already
1341
1339
  * created URLReaders but with a different token, maybe that's supplied by the user
1342
1340
  * at runtime.
1343
1341
  */
@@ -1440,7 +1438,7 @@ type UrlReaderServiceSearchOptions = {
1440
1438
  * @remarks
1441
1439
  *
1442
1440
  * By default all URL Readers will use the integrations config which is supplied
1443
- * when creating the Readers. Sometimes it might be desireable to use the already
1441
+ * when creating the Readers. Sometimes it might be desirable to use the already
1444
1442
  * created URLReaders but with a different token, maybe that's supplied by the user
1445
1443
  * at runtime.
1446
1444
  */
package/dist/services/definitions/SchedulerService.cjs.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"SchedulerService.cjs.js","sources":["../../../src/services/definitions/SchedulerService.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config, readDurationFromConfig } from '@backstage/config';\nimport { HumanDuration, JsonObject } from '@backstage/types';\nimport { Duration } from 'luxon';\n\n/**\n * A function that can be called as a scheduled task.\n *\n * It may optionally accept an abort signal argument. When the signal triggers,\n * processing should abort and return as quickly as possible.\n *\n * @public\n */\nexport type SchedulerServiceTaskFunction =\n | ((abortSignal: AbortSignal) => void | Promise<void>)\n | (() => void | Promise<void>);\n\n/**\n * A semi-opaque type to describe an actively scheduled task.\n *\n * @public\n */\nexport type SchedulerServiceTaskDescriptor = {\n /**\n * The unique identifier of the task.\n */\n id: string;\n /**\n * The scope of the task.\n */\n scope: 'global' | 'local';\n /**\n * The settings that control the task flow. This is a semi-opaque structure\n * that is mainly there for debugging purposes. Do not make any assumptions\n * about the contents of this field.\n */\n settings: { version: number } & JsonObject;\n};\n\n/**\n * Options that control the scheduling of a task.\n *\n * @public\n */\nexport interface SchedulerServiceTaskScheduleDefinition {\n /**\n * How often you want the task to run. The system does its best to avoid\n * overlapping invocations.\n *\n * @remarks\n *\n * This is the best effort value; under some circumstances there can be\n * deviations. For example, if the task runtime is longer than the frequency\n * and the timeout has not been given or not been exceeded yet, the next\n * invocation of this task will be delayed until after the previous one\n * finishes.\n *\n * This is a required field.\n */\n frequency:\n | {\n /**\n * A crontab style string.\n *\n * @remarks\n *\n * Overview:\n *\n * ```\n * ┌────────────── second (optional)\n * │ ┌──────────── minute\n * │ │ ┌────────── hour\n * │ │ │ ┌──────── day of month\n * │ │ │ │ ┌────── month\n * │ │ │ │ │ ┌──── day of week\n * │ │ │ │ │ │\n * │ │ │ │ │ │\n * * * * * * *\n * ```\n */\n cron: string;\n }\n | Duration\n | HumanDuration\n | { trigger: 'manual' };\n\n /**\n * The maximum amount of time that a single task invocation can take, before\n * it's considered timed out and gets \"released\" such that a new invocation\n * is permitted to take place (possibly, then, on a different worker).\n */\n timeout: Duration | HumanDuration;\n\n /**\n * The amount of time that should pass before the first invocation happens.\n *\n * @remarks\n *\n * This can be useful in cold start scenarios to stagger or delay some heavy\n * compute jobs. If no value is given for this field then the first invocation\n * will happen as soon as possible according to the cadence.\n *\n * NOTE: This is a per-worker delay. If you have a cluster of workers all\n * collaborating on a task that has its `scope` field set to `'global'`, then\n * you may still see the task being processed by other long-lived workers,\n * while any given single worker is in its initial sleep delay time e.g. after\n * a deployment. Therefore, this parameter is not useful for \"globally\" pausing\n * work; its main intended use is for individual machines to get a chance to\n * reach some equilibrium at startup before triggering heavy batch workloads.\n */\n initialDelay?: Duration | HumanDuration;\n\n /**\n * Sets the scope of concurrency control / locking to apply for invocations of\n * this task.\n *\n * @remarks\n *\n * When the scope is set to the default value `'global'`, the scheduler will\n * attempt to ensure that only one worker machine runs the task at a time,\n * according to the given cadence. This means that as the number of worker\n * hosts increases, the invocation frequency of this task will not go up.\n * Instead, the load is spread randomly across hosts. This setting is useful\n * for tasks that access shared resources, for example catalog ingestion tasks\n * where you do not want many machines to repeatedly import the same data and\n * trample over each other.\n *\n * When the scope is set to `'local'`, there is no concurrency control across\n * hosts. Each host runs the task according to the given cadence similarly to\n * `setInterval`, but the runtime ensures that there are no overlapping runs.\n *\n * @defaultValue 'global'\n */\n scope?: 'global' | 'local';\n}\n\n/**\n * Config options for {@link SchedulerServiceTaskScheduleDefinition}\n * that control the scheduling of a task.\n *\n * @public\n */\nexport interface SchedulerServiceTaskScheduleDefinitionConfig {\n /**\n * How often you want the task to run. The system does its best to avoid\n * overlapping invocations.\n *\n * @remarks\n *\n * This is the best effort value; under some circumstances there can be\n * deviations. For example, if the task runtime is longer than the frequency\n * and the timeout has not been given or not been exceeded yet, the next\n * invocation of this task will be delayed until after the previous one\n * finishes.\n *\n * This is a required field.\n */\n frequency:\n | {\n /**\n * A crontab style string.\n *\n * @remarks\n *\n * Overview:\n *\n * ```\n * ┌────────────── second (optional)\n * │ ┌──────────── minute\n * │ │ ┌────────── hour\n * │ │ │ ┌──────── day of month\n * │ │ │ │ ┌────── month\n * │ │ │ │ │ ┌──── day of week\n * │ │ │ │ │ │\n * │ │ │ │ │ │\n * * * * * * *\n * ```\n */\n cron: string;\n }\n | string\n | HumanDuration\n /**\n * This task will only run when manually triggered with the `triggerTask` method; no automatic\n * scheduling. This is useful for locking of global tasks that should not be run concurrently.\n */\n | { trigger: 'manual' };\n\n /**\n * The maximum amount of time that a single task invocation can take, before\n * it's considered timed out and gets \"released\" such that a new invocation\n * is permitted to take place (possibly, then, on a different worker).\n */\n timeout: string | HumanDuration;\n\n /**\n * The amount of time that should pass before the first invocation happens.\n *\n * @remarks\n *\n * This can be useful in cold start scenarios to stagger or delay some heavy\n * compute jobs. If no value is given for this field then the first invocation\n * will happen as soon as possible according to the cadence.\n *\n * NOTE: This is a per-worker delay. If you have a cluster of workers all\n * collaborating on a task that has its `scope` field set to `'global'`, then\n * you may still see the task being processed by other long-lived workers,\n * while any given single worker is in its initial sleep delay time e.g. after\n * a deployment. Therefore, this parameter is not useful for \"globally\" pausing\n * work; its main intended use is for individual machines to get a chance to\n * reach some equilibrium at startup before triggering heavy batch workloads.\n */\n initialDelay?: string | HumanDuration;\n\n /**\n * Sets the scope of concurrency control / locking to apply for invocations of\n * this task.\n *\n * @remarks\n *\n * When the scope is set to the default value `'global'`, the scheduler will\n * attempt to ensure that only one worker machine runs the task at a time,\n * according to the given cadence. This means that as the number of worker\n * hosts increases, the invocation frequency of this task will not go up.\n * Instead, the load is spread randomly across hosts. This setting is useful\n * for tasks that access shared resources, for example catalog ingestion tasks\n * where you do not want many machines to repeatedly import the same data and\n * trample over each other.\n *\n * When the scope is set to `'local'`, there is no concurrency control across\n * hosts. Each host runs the task according to the given cadence similarly to\n * `setInterval`, but the runtime ensures that there are no overlapping runs.\n *\n * @defaultValue 'global'\n */\n scope?: 'global' | 'local';\n}\n\n/**\n * Options that apply to the invocation of a given task.\n *\n * @public\n */\nexport interface SchedulerServiceTaskInvocationDefinition {\n /**\n * A unique ID (within the scope of the plugin) for the task.\n */\n id: string;\n\n /**\n * The actual task function to be invoked regularly.\n */\n fn: SchedulerServiceTaskFunction;\n\n /**\n * An abort signal that, when triggered, will stop the recurring execution of\n * the task.\n */\n signal?: AbortSignal;\n}\n\n/**\n * A previously prepared task schedule, ready to be invoked.\n *\n * @public\n */\nexport interface SchedulerServiceTaskRunner {\n /**\n * Takes the schedule and executes an actual task using it.\n *\n * @param task - The actual runtime properties of the task\n */\n run(task: SchedulerServiceTaskInvocationDefinition): Promise<void>;\n}\n\n/**\n * Deals with the scheduling of distributed tasks, for a given plugin.\n *\n * See the {@link https://backstage.io/docs/backend-system/core-services/scheduler | service documentation} for more details.\n *\n * @public\n */\nexport interface SchedulerService {\n /**\n * Manually triggers a task by ID.\n *\n * If the task doesn't exist, a NotFoundError is thrown. If the task is\n * currently running, a ConflictError is thrown.\n *\n * @param id - The task ID\n */\n triggerTask(id: string): Promise<void>;\n\n /**\n * Schedules a task function for recurring runs.\n *\n * @remarks\n *\n * The `scope` task field controls whether to use coordinated exclusive\n * invocation across workers, or to just coordinate within the current worker.\n *\n * This convenience method performs both the scheduling and invocation in one\n * go.\n *\n * @param task - The task definition\n */\n scheduleTask(\n task: SchedulerServiceTaskScheduleDefinition &\n SchedulerServiceTaskInvocationDefinition,\n ): Promise<void>;\n\n /**\n * Creates a scheduled but dormant recurring task, ready to be launched at a\n * later time.\n *\n * @remarks\n *\n * This method is useful for pre-creating a schedule in outer code to be\n * passed into an inner implementation, such that the outer code controls\n * scheduling while inner code controls implementation.\n *\n * @param schedule - The task schedule\n */\n createScheduledTaskRunner(\n schedule: SchedulerServiceTaskScheduleDefinition,\n ): SchedulerServiceTaskRunner;\n\n /**\n * Returns all scheduled tasks registered to this scheduler.\n *\n * @remarks\n *\n * This method is useful for triggering tasks manually using the triggerTask\n * functionality. Note that the returned tasks contain only tasks that have\n * been initialized in this instance of the scheduler.\n *\n * @returns Scheduled tasks\n */\n getScheduledTasks(): Promise<SchedulerServiceTaskDescriptor[]>;\n}\n\nfunction readFrequency(\n config: Config,\n key: string,\n): { cron: string } | HumanDuration | { trigger: 'manual' } {\n const value = config.get(key);\n if (typeof value === 'object' && (value as { cron?: string }).cron) {\n return value as { cron: string };\n }\n if (\n typeof value === 'object' &&\n (value as { trigger?: string }).trigger === 'manual'\n ) {\n return { trigger: 'manual' };\n }\n\n return readDurationFromConfig(config, { key });\n}\n\n/**\n * Reads a {@link SchedulerServiceTaskScheduleDefinition} from config. Expects\n * the config not to be the root config, but the config for the definition.\n *\n * @param config - config for a TaskScheduleDefinition.\n * @public\n */\nexport function readSchedulerServiceTaskScheduleDefinitionFromConfig(\n config: Config,\n): SchedulerServiceTaskScheduleDefinition {\n const frequency = readFrequency(config, 'frequency');\n const timeout = readDurationFromConfig(config, { key: 'timeout' });\n\n const initialDelay = config.has('initialDelay')\n ? readDurationFromConfig(config, { key: 'initialDelay' })\n : undefined;\n\n const scope = config.getOptionalString('scope');\n if (scope && !['global', 'local'].includes(scope)) {\n throw new Error(\n `Only \"global\" or \"local\" are allowed for TaskScheduleDefinition.scope, but got: ${scope}`,\n );\n }\n\n return {\n frequency,\n timeout,\n initialDelay,\n scope: scope as 'global' | 'local' | undefined,\n };\n}\n"],"names":["config","readDurationFromConfig"],"mappings":";;;;AAoWA,SAAS,aAAA,CACPA,UACA,GAC0D,EAAA;AAC1D,EAAM,MAAA,KAAA,GAAQA,QAAO,CAAA,GAAA,CAAI,GAAG,CAAA;AAC5B,EAAA,IAAI,OAAO,KAAA,KAAU,QAAa,IAAA,KAAA,CAA4B,IAAM,EAAA;AAClE,IAAO,OAAA,KAAA;AAAA;AAET,EAAA,IACE,OAAO,KAAA,KAAU,QAChB,IAAA,KAAA,CAA+B,YAAY,QAC5C,EAAA;AACA,IAAO,OAAA,EAAE,SAAS,QAAS,EAAA;AAAA;AAG7B,EAAA,OAAOC,6BAAuB,CAAAD,QAAA,EAAQ,EAAE,GAAA,EAAK,CAAA;AAC/C;AASO,SAAS,qDACdA,QACwC,EAAA;AACxC,EAAM,MAAA,SAAA,GAAY,aAAc,CAAAA,QAAA,EAAQ,WAAW,CAAA;AACnD,EAAA,MAAM,UAAUC,6BAAuB,CAAAD,QAAA,EAAQ,EAAE,GAAA,EAAK,WAAW,CAAA;AAEjE,EAAM,MAAA,YAAA,GAAeA,QAAO,CAAA,GAAA,CAAI,cAAc,CAAA,GAC1CC,6BAAuB,CAAAD,QAAA,EAAQ,EAAE,GAAA,EAAK,cAAe,EAAC,CACtD,GAAA,KAAA,CAAA;AAEJ,EAAM,MAAA,KAAA,GAAQA,QAAO,CAAA,iBAAA,CAAkB,OAAO,CAAA;AAC9C,EAAI,IAAA,KAAA,IAAS,CAAC,CAAC,QAAA,EAAU,OAAO,CAAE,CAAA,QAAA,CAAS,KAAK,CAAG,EAAA;AACjD,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,mFAAmF,KAAK,CAAA;AAAA,KAC1F;AAAA;AAGF,EAAO,OAAA;AAAA,IACL,SAAA;AAAA,IACA,OAAA;AAAA,IACA,YAAA;AAAA,IACA;AAAA,GACF;AACF;;;;"}
1
+ {"version":3,"file":"SchedulerService.cjs.js","sources":["../../../src/services/definitions/SchedulerService.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config, readDurationFromConfig } from '@backstage/config';\nimport { HumanDuration, JsonObject } from '@backstage/types';\nimport { Duration } from 'luxon';\n\n/**\n * A function that can be called as a scheduled task.\n *\n * It may optionally accept an abort signal argument. When the signal triggers,\n * processing should abort and return as quickly as possible.\n *\n * @public\n */\nexport type SchedulerServiceTaskFunction =\n | ((abortSignal: AbortSignal) => void | Promise<void>)\n | (() => void | Promise<void>);\n\n/**\n * A semi-opaque type to describe an actively scheduled task.\n *\n * @public\n */\nexport type SchedulerServiceTaskDescriptor = {\n /**\n * The unique identifier of the task.\n */\n id: string;\n /**\n * The scope of the task.\n */\n scope: 'global' | 'local';\n /**\n * The settings that control the task flow. This is a semi-opaque structure\n * that is mainly there for debugging purposes. Do not make any assumptions\n * about the contents of this field.\n */\n settings: { version: number } & JsonObject;\n};\n\n/**\n * Options that control the scheduling of a task.\n *\n * @public\n */\nexport interface SchedulerServiceTaskScheduleDefinition {\n /**\n * How often you want the task to run. The system does its best to avoid\n * overlapping invocations.\n *\n * @remarks\n *\n * This is the best effort value; under some circumstances there can be\n * deviations. For example, if the task runtime is longer than the frequency\n * and the timeout has not been given or not been exceeded yet, the next\n * invocation of this task will be delayed until after the previous one\n * finishes.\n *\n * This is a required field.\n */\n frequency:\n | {\n /**\n * A crontab style string.\n *\n * @remarks\n *\n * Overview:\n *\n * ```\n * ┌────────────── second (0-60, optional)\n * │ ┌──────────── minute (0-59)\n * │ │ ┌────────── hour (0-23)\n * │ │ │ ┌──────── day of month (1-31)\n * │ │ │ │ ┌────── month (1-12)\n * │ │ │ │ │ ┌──── day of week (0-6, 0 is Sunday)\n * │ │ │ │ │ │\n * * * * * * *\n * ```\n */\n cron: string;\n }\n | Duration\n | HumanDuration\n | { trigger: 'manual' };\n\n /**\n * The maximum amount of time that a single task invocation can take, before\n * it's considered timed out and gets \"released\" such that a new invocation\n * is permitted to take place (possibly, then, on a different worker).\n */\n timeout: Duration | HumanDuration;\n\n /**\n * The amount of time that should pass before the first invocation happens.\n *\n * @remarks\n *\n * This can be useful in cold start scenarios to stagger or delay some heavy\n * compute jobs. If no value is given for this field then the first invocation\n * will happen as soon as possible according to the cadence.\n *\n * NOTE: This is a per-worker delay. If you have a cluster of workers all\n * collaborating on a task that has its `scope` field set to `'global'`, then\n * you may still see the task being processed by other long-lived workers,\n * while any given single worker is in its initial sleep delay time e.g. after\n * a deployment. Therefore, this parameter is not useful for \"globally\" pausing\n * work; its main intended use is for individual machines to get a chance to\n * reach some equilibrium at startup before triggering heavy batch workloads.\n */\n initialDelay?: Duration | HumanDuration;\n\n /**\n * Sets the scope of concurrency control / locking to apply for invocations of\n * this task.\n *\n * @remarks\n *\n * When the scope is set to the default value `'global'`, the scheduler will\n * attempt to ensure that only one worker machine runs the task at a time,\n * according to the given cadence. This means that as the number of worker\n * hosts increases, the invocation frequency of this task will not go up.\n * Instead, the load is spread randomly across hosts. This setting is useful\n * for tasks that access shared resources, for example catalog ingestion tasks\n * where you do not want many machines to repeatedly import the same data and\n * trample over each other.\n *\n * When the scope is set to `'local'`, there is no concurrency control across\n * hosts. Each host runs the task according to the given cadence similarly to\n * `setInterval`, but the runtime ensures that there are no overlapping runs.\n *\n * @defaultValue 'global'\n */\n scope?: 'global' | 'local';\n}\n\n/**\n * Config options for {@link SchedulerServiceTaskScheduleDefinition}\n * that control the scheduling of a task.\n *\n * @public\n */\nexport interface SchedulerServiceTaskScheduleDefinitionConfig {\n /**\n * How often you want the task to run. The system does its best to avoid\n * overlapping invocations.\n *\n * @remarks\n *\n * This is the best effort value; under some circumstances there can be\n * deviations. For example, if the task runtime is longer than the frequency\n * and the timeout has not been given or not been exceeded yet, the next\n * invocation of this task will be delayed until after the previous one\n * finishes.\n *\n * This is a required field.\n */\n frequency:\n | {\n /**\n * A crontab style string.\n *\n * @remarks\n *\n * Overview:\n *\n * ```\n * ┌────────────── second (0-60, optional)\n * │ ┌──────────── minute (0-59)\n * │ │ ┌────────── hour (0-23)\n * │ │ │ ┌──────── day of month (1-31)\n * │ │ │ │ ┌────── month (1-12)\n * │ │ │ │ │ ┌──── day of week (0-6, 0 is Sunday)\n * │ │ │ │ │ │\n * * * * * * *\n * ```\n */\n cron: string;\n }\n | string\n | HumanDuration\n /**\n * This task will only run when manually triggered with the `triggerTask` method; no automatic\n * scheduling. This is useful for locking of global tasks that should not be run concurrently.\n */\n | { trigger: 'manual' };\n\n /**\n * The maximum amount of time that a single task invocation can take, before\n * it's considered timed out and gets \"released\" such that a new invocation\n * is permitted to take place (possibly, then, on a different worker).\n */\n timeout: string | HumanDuration;\n\n /**\n * The amount of time that should pass before the first invocation happens.\n *\n * @remarks\n *\n * This can be useful in cold start scenarios to stagger or delay some heavy\n * compute jobs. If no value is given for this field then the first invocation\n * will happen as soon as possible according to the cadence.\n *\n * NOTE: This is a per-worker delay. If you have a cluster of workers all\n * collaborating on a task that has its `scope` field set to `'global'`, then\n * you may still see the task being processed by other long-lived workers,\n * while any given single worker is in its initial sleep delay time e.g. after\n * a deployment. Therefore, this parameter is not useful for \"globally\" pausing\n * work; its main intended use is for individual machines to get a chance to\n * reach some equilibrium at startup before triggering heavy batch workloads.\n */\n initialDelay?: string | HumanDuration;\n\n /**\n * Sets the scope of concurrency control / locking to apply for invocations of\n * this task.\n *\n * @remarks\n *\n * When the scope is set to the default value `'global'`, the scheduler will\n * attempt to ensure that only one worker machine runs the task at a time,\n * according to the given cadence. This means that as the number of worker\n * hosts increases, the invocation frequency of this task will not go up.\n * Instead, the load is spread randomly across hosts. This setting is useful\n * for tasks that access shared resources, for example catalog ingestion tasks\n * where you do not want many machines to repeatedly import the same data and\n * trample over each other.\n *\n * When the scope is set to `'local'`, there is no concurrency control across\n * hosts. Each host runs the task according to the given cadence similarly to\n * `setInterval`, but the runtime ensures that there are no overlapping runs.\n *\n * @defaultValue 'global'\n */\n scope?: 'global' | 'local';\n}\n\n/**\n * Options that apply to the invocation of a given task.\n *\n * @public\n */\nexport interface SchedulerServiceTaskInvocationDefinition {\n /**\n * A unique ID (within the scope of the plugin) for the task.\n */\n id: string;\n\n /**\n * The actual task function to be invoked regularly.\n */\n fn: SchedulerServiceTaskFunction;\n\n /**\n * An abort signal that, when triggered, will stop the recurring execution of\n * the task.\n */\n signal?: AbortSignal;\n}\n\n/**\n * A previously prepared task schedule, ready to be invoked.\n *\n * @public\n */\nexport interface SchedulerServiceTaskRunner {\n /**\n * Takes the schedule and executes an actual task using it.\n *\n * @param task - The actual runtime properties of the task\n */\n run(task: SchedulerServiceTaskInvocationDefinition): Promise<void>;\n}\n\n/**\n * Deals with the scheduling of distributed tasks, for a given plugin.\n *\n * See the {@link https://backstage.io/docs/backend-system/core-services/scheduler | service documentation} for more details.\n *\n * @public\n */\nexport interface SchedulerService {\n /**\n * Manually triggers a task by ID.\n *\n * If the task doesn't exist, a NotFoundError is thrown. If the task is\n * currently running, a ConflictError is thrown.\n *\n * @param id - The task ID\n */\n triggerTask(id: string): Promise<void>;\n\n /**\n * Schedules a task function for recurring runs.\n *\n * @remarks\n *\n * The `scope` task field controls whether to use coordinated exclusive\n * invocation across workers, or to just coordinate within the current worker.\n *\n * This convenience method performs both the scheduling and invocation in one\n * go.\n *\n * @param task - The task definition\n */\n scheduleTask(\n task: SchedulerServiceTaskScheduleDefinition &\n SchedulerServiceTaskInvocationDefinition,\n ): Promise<void>;\n\n /**\n * Creates a scheduled but dormant recurring task, ready to be launched at a\n * later time.\n *\n * @remarks\n *\n * This method is useful for pre-creating a schedule in outer code to be\n * passed into an inner implementation, such that the outer code controls\n * scheduling while inner code controls implementation.\n *\n * @param schedule - The task schedule\n */\n createScheduledTaskRunner(\n schedule: SchedulerServiceTaskScheduleDefinition,\n ): SchedulerServiceTaskRunner;\n\n /**\n * Returns all scheduled tasks registered to this scheduler.\n *\n * @remarks\n *\n * This method is useful for triggering tasks manually using the triggerTask\n * functionality. Note that the returned tasks contain only tasks that have\n * been initialized in this instance of the scheduler.\n *\n * @returns Scheduled tasks\n */\n getScheduledTasks(): Promise<SchedulerServiceTaskDescriptor[]>;\n}\n\nfunction readFrequency(\n config: Config,\n key: string,\n): { cron: string } | HumanDuration | { trigger: 'manual' } {\n const value = config.get(key);\n if (typeof value === 'object' && (value as { cron?: string }).cron) {\n return value as { cron: string };\n }\n if (\n typeof value === 'object' &&\n (value as { trigger?: string }).trigger === 'manual'\n ) {\n return { trigger: 'manual' };\n }\n\n return readDurationFromConfig(config, { key });\n}\n\n/**\n * Reads a {@link SchedulerServiceTaskScheduleDefinition} from config. Expects\n * the config not to be the root config, but the config for the definition.\n *\n * @param config - config for a TaskScheduleDefinition.\n * @public\n */\nexport function readSchedulerServiceTaskScheduleDefinitionFromConfig(\n config: Config,\n): SchedulerServiceTaskScheduleDefinition {\n const frequency = readFrequency(config, 'frequency');\n const timeout = readDurationFromConfig(config, { key: 'timeout' });\n\n const initialDelay = config.has('initialDelay')\n ? readDurationFromConfig(config, { key: 'initialDelay' })\n : undefined;\n\n const scope = config.getOptionalString('scope');\n if (scope && !['global', 'local'].includes(scope)) {\n throw new Error(\n `Only \"global\" or \"local\" are allowed for TaskScheduleDefinition.scope, but got: ${scope}`,\n );\n }\n\n return {\n frequency,\n timeout,\n initialDelay,\n scope: scope as 'global' | 'local' | undefined,\n };\n}\n"],"names":["config","readDurationFromConfig"],"mappings":";;;;AAkWA,SAAS,aAAA,CACPA,UACA,GAC0D,EAAA;AAC1D,EAAM,MAAA,KAAA,GAAQA,QAAO,CAAA,GAAA,CAAI,GAAG,CAAA;AAC5B,EAAA,IAAI,OAAO,KAAA,KAAU,QAAa,IAAA,KAAA,CAA4B,IAAM,EAAA;AAClE,IAAO,OAAA,KAAA;AAAA;AAET,EAAA,IACE,OAAO,KAAA,KAAU,QAChB,IAAA,KAAA,CAA+B,YAAY,QAC5C,EAAA;AACA,IAAO,OAAA,EAAE,SAAS,QAAS,EAAA;AAAA;AAG7B,EAAA,OAAOC,6BAAuB,CAAAD,QAAA,EAAQ,EAAE,GAAA,EAAK,CAAA;AAC/C;AASO,SAAS,qDACdA,QACwC,EAAA;AACxC,EAAM,MAAA,SAAA,GAAY,aAAc,CAAAA,QAAA,EAAQ,WAAW,CAAA;AACnD,EAAA,MAAM,UAAUC,6BAAuB,CAAAD,QAAA,EAAQ,EAAE,GAAA,EAAK,WAAW,CAAA;AAEjE,EAAM,MAAA,YAAA,GAAeA,QAAO,CAAA,GAAA,CAAI,cAAc,CAAA,GAC1CC,6BAAuB,CAAAD,QAAA,EAAQ,EAAE,GAAA,EAAK,cAAe,EAAC,CACtD,GAAA,KAAA,CAAA;AAEJ,EAAM,MAAA,KAAA,GAAQA,QAAO,CAAA,iBAAA,CAAkB,OAAO,CAAA;AAC9C,EAAI,IAAA,KAAA,IAAS,CAAC,CAAC,QAAA,EAAU,OAAO,CAAE,CAAA,QAAA,CAAS,KAAK,CAAG,EAAA;AACjD,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,mFAAmF,KAAK,CAAA;AAAA,KAC1F;AAAA;AAGF,EAAO,OAAA;AAAA,IACL,SAAA;AAAA,IACA,OAAA;AAAA,IACA,YAAA;AAAA,IACA;AAAA,GACF;AACF;;;;"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@backstage/backend-plugin-api",
3
- "version": "1.3.0",
3
+ "version": "1.3.1-next.1",
4
4
  "description": "Core API used by Backstage backend plugins",
5
5
  "backstage": {
6
6
  "role": "node-library"
@@ -65,21 +65,21 @@
65
65
  "test": "backstage-cli package test"
66
66
  },
67
67
  "dependencies": {
68
- "@backstage/cli-common": "^0.1.15",
69
- "@backstage/config": "^1.3.2",
70
- "@backstage/errors": "^1.2.7",
71
- "@backstage/plugin-auth-node": "^0.6.2",
72
- "@backstage/plugin-permission-common": "^0.8.4",
73
- "@backstage/plugin-permission-node": "^0.9.1",
74
- "@backstage/types": "^1.2.1",
68
+ "@backstage/cli-common": "0.1.15",
69
+ "@backstage/config": "1.3.2",
70
+ "@backstage/errors": "1.2.7",
71
+ "@backstage/plugin-auth-node": "0.6.3-next.1",
72
+ "@backstage/plugin-permission-common": "0.9.0-next.0",
73
+ "@backstage/plugin-permission-node": "0.10.0-next.1",
74
+ "@backstage/types": "1.2.1",
75
75
  "@types/express": "^4.17.6",
76
76
  "@types/luxon": "^3.0.0",
77
77
  "knex": "^3.0.0",
78
78
  "luxon": "^3.0.0"
79
79
  },
80
80
  "devDependencies": {
81
- "@backstage/backend-test-utils": "^1.4.0",
82
- "@backstage/cli": "^0.32.0"
81
+ "@backstage/backend-test-utils": "1.5.0-next.1",
82
+ "@backstage/cli": "0.32.1-next.1"
83
83
  },
84
84
  "configSchema": "config.d.ts"
85
85
  }