@backstage/backend-plugin-api 1.7.0 → 1.8.0-next.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @backstage/backend-plugin-api
 
+## 1.8.0-next.1
+
+### Minor Changes
+
+- 015668c: Added `cancelTask` method to the `SchedulerService` interface and implementation, allowing cancellation of currently running scheduled tasks. For global tasks, the database lock is released and a periodic liveness check aborts the running task function. For local tasks, the task's abort signal is triggered directly. A new `POST /.backstage/scheduler/v1/tasks/:id/cancel` endpoint is also available.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/cli-common@0.2.0-next.2
+  - @backstage/plugin-auth-node@0.6.14-next.2
+  - @backstage/plugin-permission-node@0.10.11-next.1
+
+## 1.7.1-next.0
+
+### Patch Changes
+
+- 1ee5b28: Adds an alpha `MetricsService` to provide a unified interface for metrics instrumentation across Backstage plugins.
+- Updated dependencies
+  - @backstage/cli-common@0.2.0-next.0
+  - @backstage/config@1.3.6
+  - @backstage/errors@1.2.7
+  - @backstage/types@1.2.2
+  - @backstage/plugin-auth-node@0.6.14-next.0
+  - @backstage/plugin-permission-common@0.9.6
+  - @backstage/plugin-permission-node@0.10.11-next.0
+
 ## 1.7.0
 
 ### Minor Changes

package/dist/alpha/refs.cjs.js

@@ -12,8 +12,12 @@ const rootSystemMetadataServiceRef = backendPluginApi.createServiceRef({
   id: "alpha.core.rootSystemMetadata",
   scope: "root"
 });
+const metricsServiceRef = backendPluginApi.createServiceRef({
+  id: "alpha.core.metrics"
+});
 
 exports.actionsRegistryServiceRef = actionsRegistryServiceRef;
 exports.actionsServiceRef = actionsServiceRef;
+exports.metricsServiceRef = metricsServiceRef;
 exports.rootSystemMetadataServiceRef = rootSystemMetadataServiceRef;
 //# sourceMappingURL=refs.cjs.js.map

package/dist/alpha/refs.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"refs.cjs.js","sources":["../../src/alpha/refs.ts"],"sourcesContent":["/*\n * Copyright 2025 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 { createServiceRef } from '@backstage/backend-plugin-api';\n\n/**\n * Service for calling distributed actions\n *\n * See {@link ActionsService}\n * and {@link https://backstage.io/docs/backend-system/core-services/actions | the service docs}\n * for more information.\n *\n * @alpha\n */\nexport const actionsServiceRef = createServiceRef<\n  import('./ActionsService').ActionsService\n>({\n  id: 'alpha.core.actions',\n});\n\n/**\n * Service for registering and managing distributed actions.\n *\n * See {@link ActionsRegistryService}\n * and {@link https://backstage.io/docs/backend-system/core-services/actions-registry | the service docs}\n * for more information.\n *\n * @alpha\n */\nexport const actionsRegistryServiceRef = createServiceRef<\n  import('./ActionsRegistryService').ActionsRegistryService\n>({\n  id: 'alpha.core.actionsRegistry',\n});\n\n/**\n * Read information about your current Backstage deployment.\n * @alpha\n */\nexport const rootSystemMetadataServiceRef = createServiceRef<\n  import('./RootSystemMetadataService').RootSystemMetadataService\n>({\n  id: 'alpha.core.rootSystemMetadata',\n  scope: 'root',\n});\n"],"names":["createServiceRef"],"mappings":";;;;AA2BO,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AAWM,MAAM,4BAA4BA,iCAAA,CAEvC;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AAMM,MAAM,+BAA+BA,iCAAA,CAE1C;AAAA,EACA,EAAA,EAAI,+BAAA;AAAA,EACJ,KAAA,EAAO;AACT,CAAC;;;;;;"}
+{"version":3,"file":"refs.cjs.js","sources":["../../src/alpha/refs.ts"],"sourcesContent":["/*\n * Copyright 2025 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 { createServiceRef } from '@backstage/backend-plugin-api';\n\n/**\n * Service for calling distributed actions\n *\n * See {@link ActionsService}\n * and {@link https://backstage.io/docs/backend-system/core-services/actions | the service docs}\n * for more information.\n *\n * @alpha\n */\nexport const actionsServiceRef = createServiceRef<\n  import('./ActionsService').ActionsService\n>({\n  id: 'alpha.core.actions',\n});\n\n/**\n * Service for registering and managing distributed actions.\n *\n * See {@link ActionsRegistryService}\n * and {@link https://backstage.io/docs/backend-system/core-services/actions-registry | the service docs}\n * for more information.\n *\n * @alpha\n */\nexport const actionsRegistryServiceRef = createServiceRef<\n  import('./ActionsRegistryService').ActionsRegistryService\n>({\n  id: 'alpha.core.actionsRegistry',\n});\n\n/**\n * Read information about your current Backstage deployment.\n * @alpha\n */\nexport const rootSystemMetadataServiceRef = createServiceRef<\n  import('./RootSystemMetadataService').RootSystemMetadataService\n>({\n  id: 'alpha.core.rootSystemMetadata',\n  scope: 'root',\n});\n\n/**\n * Service for managing metrics.\n *\n * @alpha\n */\nexport const metricsServiceRef = createServiceRef<\n  import('./MetricsService').MetricsService\n>({\n  id: 'alpha.core.metrics',\n});\n"],"names":["createServiceRef"],"mappings":";;;;AA2BO,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AAWM,MAAM,4BAA4BA,iCAAA,CAEvC;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AAMM,MAAM,+BAA+BA,iCAAA,CAE1C;AAAA,EACA,EAAA,EAAI,+BAAA;AAAA,EACJ,KAAA,EAAO;AACT,CAAC;AAOM,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;;;;;;;"}

package/dist/alpha.cjs.js

@@ -6,5 +6,6 @@ var refs = require('./alpha/refs.cjs.js');
 
 exports.actionsRegistryServiceRef = refs.actionsRegistryServiceRef;
 exports.actionsServiceRef = refs.actionsServiceRef;
+exports.metricsServiceRef = refs.metricsServiceRef;
 exports.rootSystemMetadataServiceRef = refs.rootSystemMetadataServiceRef;
 //# sourceMappingURL=alpha.cjs.js.map

package/dist/alpha.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"alpha.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}
+{"version":3,"file":"alpha.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;"}

package/dist/alpha.d.ts

@@ -84,6 +84,189 @@ interface ActionsService {
     }>;
 }
 
+/**
+ * Attribute values that can be attached to metric measurements.
+ *
+ * @alpha
+ */
+type MetricAttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
+/**
+ * A set of key-value pairs that can be attached to metric measurements.
+ *
+ * @alpha
+ */
+interface MetricAttributes {
+    [attributeKey: string]: MetricAttributeValue | undefined;
+}
+/**
+ * Advisory options that influence aggregation configuration.
+ *
+ * @alpha
+ */
+interface MetricAdvice {
+    /**
+     * Hint the explicit bucket boundaries for histogram aggregation.
+     */
+    explicitBucketBoundaries?: number[];
+}
+/**
+ * Options for creating a metric instrument.
+ *
+ * @alpha
+ */
+interface MetricOptions {
+    /**
+     * The description of the Metric.
+     */
+    description?: string;
+    /**
+     * The unit of the Metric values.
+     */
+    unit?: string;
+    /**
+     * Advisory options that influence aggregation configuration.
+     */
+    advice?: MetricAdvice;
+}
+/**
+ * A counter metric that only supports non-negative increments.
+ *
+ * @alpha
+ */
+interface MetricsServiceCounter<TAttributes extends MetricAttributes = MetricAttributes> {
+    add(value: number, attributes?: TAttributes): void;
+}
+/**
+ * A counter metric that supports both positive and negative increments.
+ *
+ * @alpha
+ */
+interface MetricsServiceUpDownCounter<TAttributes extends MetricAttributes = MetricAttributes> {
+    add(value: number, attributes?: TAttributes): void;
+}
+/**
+ * A histogram metric for recording distributions of values.
+ *
+ * @alpha
+ */
+interface MetricsServiceHistogram<TAttributes extends MetricAttributes = MetricAttributes> {
+    record(value: number, attributes?: TAttributes): void;
+}
+/**
+ * A gauge metric for recording instantaneous values.
+ *
+ * @alpha
+ */
+interface MetricsServiceGauge<TAttributes extends MetricAttributes = MetricAttributes> {
+    record(value: number, attributes?: TAttributes): void;
+}
+/**
+ * The result object passed to observable metric callbacks.
+ *
+ * @alpha
+ */
+interface MetricsServiceObservableResult<TAttributes extends MetricAttributes = MetricAttributes> {
+    observe(value: number, attributes?: TAttributes): void;
+}
+/**
+ * A callback function for observable metrics. Called whenever a metric
+ * collection is initiated.
+ *
+ * @alpha
+ */
+type MetricsServiceObservableCallback<TAttributes extends MetricAttributes = MetricAttributes> = (observableResult: MetricsServiceObservableResult<TAttributes>) => void | Promise<void>;
+/**
+ * An observable metric instrument that reports values via callbacks.
+ *
+ * @alpha
+ */
+interface MetricsServiceObservable<TAttributes extends MetricAttributes = MetricAttributes> {
+    addCallback(callback: MetricsServiceObservableCallback<TAttributes>): void;
+    removeCallback(callback: MetricsServiceObservableCallback<TAttributes>): void;
+}
+/**
+ * An observable counter metric that reports non-negative sums via callbacks.
+ *
+ * @alpha
+ */
+type MetricsServiceObservableCounter<TAttributes extends MetricAttributes = MetricAttributes> = MetricsServiceObservable<TAttributes>;
+/**
+ * An observable counter metric that reports sums that can go up or down
+ * via callbacks.
+ *
+ * @alpha
+ */
+type MetricsServiceObservableUpDownCounter<TAttributes extends MetricAttributes = MetricAttributes> = MetricsServiceObservable<TAttributes>;
+/**
+ * An observable gauge metric that reports instantaneous values via callbacks.
+ *
+ * @alpha
+ */
+type MetricsServiceObservableGauge<TAttributes extends MetricAttributes = MetricAttributes> = MetricsServiceObservable<TAttributes>;
+/**
+ * A service that provides a facility for emitting metrics.
+ *
+ * @alpha
+ */
+interface MetricsService {
+    /**
+     * Creates a new counter metric.
+     *
+     * @param name - The name of the metric.
+     * @param opts - The options for the metric.
+     * @returns The counter metric.
+     */
+    createCounter<TAttributes extends MetricAttributes = MetricAttributes>(name: string, opts?: MetricOptions): MetricsServiceCounter<TAttributes>;
+    /**
+     * Creates a new up-down counter metric.
+     *
+     * @param name - The name of the metric.
+     * @param opts - The options for the metric.
+     * @returns The up-down counter metric.
+     */
+    createUpDownCounter<TAttributes extends MetricAttributes = MetricAttributes>(name: string, opts?: MetricOptions): MetricsServiceUpDownCounter<TAttributes>;
+    /**
+     * Creates a new histogram metric.
+     *
+     * @param name - The name of the metric.
+     * @param opts - The options for the metric.
+     * @returns The histogram metric.
+     */
+    createHistogram<TAttributes extends MetricAttributes = MetricAttributes>(name: string, opts?: MetricOptions): MetricsServiceHistogram<TAttributes>;
+    /**
+     * Creates a new gauge metric.
+     *
+     * @param name - The name of the metric.
+     * @param opts - The options for the metric.
+     * @returns The gauge metric.
+     */
+    createGauge<TAttributes extends MetricAttributes = MetricAttributes>(name: string, opts?: MetricOptions): MetricsServiceGauge<TAttributes>;
+    /**
+     * Creates a new observable counter metric.
+     *
+     * @param name - The name of the metric.
+     * @param opts - The options for the metric.
+     * @returns The observable counter metric.
+     */
+    createObservableCounter<TAttributes extends MetricAttributes = MetricAttributes>(name: string, opts?: MetricOptions): MetricsServiceObservableCounter<TAttributes>;
+    /**
+     * Creates a new observable up-down counter metric.
+     *
+     * @param name - The name of the metric.
+     * @param opts - The options for the metric.
+     * @returns The observable up-down counter metric.
+     */
+    createObservableUpDownCounter<TAttributes extends MetricAttributes = MetricAttributes>(name: string, opts?: MetricOptions): MetricsServiceObservableUpDownCounter<TAttributes>;
+    /**
+     * Creates a new observable gauge metric.
+     *
+     * @param name - The name of the metric.
+     * @param opts - The options for the metric.
+     * @returns The observable gauge metric.
+     */
+    createObservableGauge<TAttributes extends MetricAttributes = MetricAttributes>(name: string, opts?: MetricOptions): MetricsServiceObservableGauge<TAttributes>;
+}
+
 /**
  * Service for calling distributed actions
  *
@@ -109,6 +292,12 @@ declare const actionsRegistryServiceRef: _backstage_backend_plugin_api.ServiceRe
  * @alpha
  */
 declare const rootSystemMetadataServiceRef: _backstage_backend_plugin_api.ServiceRef<RootSystemMetadataService, "root", "singleton">;
+/**
+ * Service for managing metrics.
+ *
+ * @alpha
+ */
+declare const metricsServiceRef: _backstage_backend_plugin_api.ServiceRef<MetricsService, "plugin", "singleton">;
 
-export { actionsRegistryServiceRef, actionsServiceRef, rootSystemMetadataServiceRef };
-export type { ActionsRegistryActionContext, ActionsRegistryActionOptions, ActionsRegistryService, ActionsService, ActionsServiceAction, RootSystemMetadataService, RootSystemMetadataServicePluginInfo };
+export { actionsRegistryServiceRef, actionsServiceRef, metricsServiceRef, rootSystemMetadataServiceRef };
+export type { ActionsRegistryActionContext, ActionsRegistryActionOptions, ActionsRegistryService, ActionsService, ActionsServiceAction, MetricAdvice, MetricAttributeValue, MetricAttributes, MetricOptions, MetricsService, MetricsServiceCounter, MetricsServiceGauge, MetricsServiceHistogram, MetricsServiceObservable, MetricsServiceObservableCallback, MetricsServiceObservableCounter, MetricsServiceObservableGauge, MetricsServiceObservableResult, MetricsServiceObservableUpDownCounter, MetricsServiceUpDownCounter, RootSystemMetadataService, RootSystemMetadataServicePluginInfo };

package/dist/index.d.ts

@@ -1114,6 +1114,15 @@ interface SchedulerService {
      * @param id - The task ID
      */
     triggerTask(id: string): Promise<void>;
+    /**
+     * Cancels a currently running task by ID, marking it as idle.
+     *
+     * If the task doesn't exist, a NotFoundError is thrown. If the task is
+     * not currently running, a ConflictError is thrown.
+     *
+     * @param id - The task ID
+     */
+    cancelTask(id: string): Promise<void>;
     /**
      * Schedules a task function for recurring runs.
      *

package/dist/services/definitions/SchedulerService.cjs.js.map

@@ -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 (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,GAAA,EAC0D;AAC1D,EAAA,MAAM,KAAA,GAAQA,QAAA,CAAO,GAAA,CAAI,GAAG,CAAA;AAC5B,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAa,KAAA,CAA4B,IAAA,EAAM;AAClE,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,IACE,OAAO,KAAA,KAAU,QAAA,IAChB,KAAA,CAA+B,YAAY,QAAA,EAC5C;AACA,IAAA,OAAO,EAAE,SAAS,QAAA,EAAS;AAAA,EAC7B;AAEA,EAAA,OAAOC,6BAAA,CAAuBD,QAAA,EAAQ,EAAE,GAAA,EAAK,CAAA;AAC/C;AASO,SAAS,qDACdA,QAAA,EACwC;AACxC,EAAA,MAAM,SAAA,GAAY,aAAA,CAAcA,QAAA,EAAQ,WAAW,CAAA;AACnD,EAAA,MAAM,UAAUC,6BAAA,CAAuBD,QAAA,EAAQ,EAAE,GAAA,EAAK,WAAW,CAAA;AAEjE,EAAA,MAAM,YAAA,GAAeA,QAAA,CAAO,GAAA,CAAI,cAAc,CAAA,GAC1CC,6BAAA,CAAuBD,QAAA,EAAQ,EAAE,GAAA,EAAK,cAAA,EAAgB,CAAA,GACtD,MAAA;AAEJ,EAAA,MAAM,KAAA,GAAQA,QAAA,CAAO,iBAAA,CAAkB,OAAO,CAAA;AAC9C,EAAA,IAAI,KAAA,IAAS,CAAC,CAAC,QAAA,EAAU,OAAO,CAAA,CAAE,QAAA,CAAS,KAAK,CAAA,EAAG;AACjD,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,mFAAmF,KAAK,CAAA;AAAA,KAC1F;AAAA,EACF;AAEA,EAAA,OAAO;AAAA,IACL,SAAA;AAAA,IACA,OAAA;AAAA,IACA,YAAA;AAAA,IACA;AAAA,GACF;AACF;;;;"}
+{"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   * Cancels a currently running task by ID, marking it as idle.\n   *\n   * If the task doesn't exist, a NotFoundError is thrown. If the task is\n   * not currently running, a ConflictError is thrown.\n   *\n   * @param id - The task ID\n   */\n  cancelTask(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":";;;;AA4WA,SAAS,aAAA,CACPA,UACA,GAAA,EAC0D;AAC1D,EAAA,MAAM,KAAA,GAAQA,QAAA,CAAO,GAAA,CAAI,GAAG,CAAA;AAC5B,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAa,KAAA,CAA4B,IAAA,EAAM;AAClE,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,IACE,OAAO,KAAA,KAAU,QAAA,IAChB,KAAA,CAA+B,YAAY,QAAA,EAC5C;AACA,IAAA,OAAO,EAAE,SAAS,QAAA,EAAS;AAAA,EAC7B;AAEA,EAAA,OAAOC,6BAAA,CAAuBD,QAAA,EAAQ,EAAE,GAAA,EAAK,CAAA;AAC/C;AASO,SAAS,qDACdA,QAAA,EACwC;AACxC,EAAA,MAAM,SAAA,GAAY,aAAA,CAAcA,QAAA,EAAQ,WAAW,CAAA;AACnD,EAAA,MAAM,UAAUC,6BAAA,CAAuBD,QAAA,EAAQ,EAAE,GAAA,EAAK,WAAW,CAAA;AAEjE,EAAA,MAAM,YAAA,GAAeA,QAAA,CAAO,GAAA,CAAI,cAAc,CAAA,GAC1CC,6BAAA,CAAuBD,QAAA,EAAQ,EAAE,GAAA,EAAK,cAAA,EAAgB,CAAA,GACtD,MAAA;AAEJ,EAAA,MAAM,KAAA,GAAQA,QAAA,CAAO,iBAAA,CAAkB,OAAO,CAAA;AAC9C,EAAA,IAAI,KAAA,IAAS,CAAC,CAAC,QAAA,EAAU,OAAO,CAAA,CAAE,QAAA,CAAS,KAAK,CAAA,EAAG;AACjD,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,mFAAmF,KAAK,CAAA;AAAA,KAC1F;AAAA,EACF;AAEA,EAAA,OAAO;AAAA,IACL,SAAA;AAAA,IACA,OAAA;AAAA,IACA,YAAA;AAAA,IACA;AAAA,GACF;AACF;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-plugin-api",
-  "version": "1.7.0",
+  "version": "1.8.0-next.1",
   "description": "Core API used by Backstage backend plugins",
   "backstage": {
     "role": "node-library"
@@ -65,13 +65,13 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/cli-common": "^0.1.18",
-    "@backstage/config": "^1.3.6",
-    "@backstage/errors": "^1.2.7",
-    "@backstage/plugin-auth-node": "^0.6.13",
-    "@backstage/plugin-permission-common": "^0.9.6",
-    "@backstage/plugin-permission-node": "^0.10.10",
-    "@backstage/types": "^1.2.2",
+    "@backstage/cli-common": "0.2.0-next.2",
+    "@backstage/config": "1.3.6",
+    "@backstage/errors": "1.2.7",
+    "@backstage/plugin-auth-node": "0.6.14-next.2",
+    "@backstage/plugin-permission-common": "0.9.6",
+    "@backstage/plugin-permission-node": "0.10.11-next.1",
+    "@backstage/types": "1.2.2",
     "@types/express": "^4.17.6",
     "@types/json-schema": "^7.0.6",
     "@types/luxon": "^3.0.0",
@@ -81,8 +81,8 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "^1.11.0",
-    "@backstage/cli": "^0.35.4"
+    "@backstage/backend-test-utils": "1.11.1-next.2",
+    "@backstage/cli": "0.36.0-next.2"
   },
   "configSchema": "config.d.ts"
 }