@pipedog/core 0.0.0 → 0.1.0

package/dist/pipeline/service_switcher.d.ts

@@ -0,0 +1,287 @@
+/**
+ * Service switcher for switching between different services at runtime, with
+ * different switching strategies.
+ */
+import { ErrorFrame, type Frame, ServiceSwitcherFrame, ServiceUpdateSettingsFrame } from "../frames/frames.ts";
+import { FrameDirection, type FrameProcessor } from "../processors/frame_processor.ts";
+import { BaseObject } from "../utils/base_object.ts";
+import { ParallelPipeline } from "./parallel_pipeline.ts";
+/**
+ * Base class for service switching strategies.
+ *
+ * Note: strategy classes are instantiated internally by ServiceSwitcher.
+ * Developers should pass the strategy class (not an instance) to
+ * ServiceSwitcher.
+ *
+ * Event handlers available:
+ *
+ * - on_service_switched: called when the active service changes.
+ *
+ * @example
+ * strategy.eventHandler("on_service_switched", async (strategy, service) => { ... });
+ */
+export declare class ServiceSwitcherStrategy extends BaseObject {
+    protected _services: FrameProcessor[];
+    protected _activeService: FrameProcessor;
+    /**
+     * Initialize the service switcher strategy with a list of services.
+     *
+     * Note: this is called internally by ServiceSwitcher. Do not instantiate
+     * directly.
+     *
+     * @param services List of frame processors to switch between.
+     */
+    constructor(services: FrameProcessor[]);
+    /** The list of available services. */
+    get services(): FrameProcessor[];
+    /** The currently active service. */
+    get activeService(): FrameProcessor;
+    /** The services that can still be given work, in order. */
+    get usableServices(): FrameProcessor[];
+    /**
+     * Handle a frame that controls service switching.
+     *
+     * The base implementation returns null for all frames. Subclasses override
+     * this to implement specific switching behaviors.
+     *
+     * @param frame The frame to handle.
+     * @param direction The direction of the frame (upstream or downstream).
+     * @returns The newly active service if a switch occurred, or null otherwise.
+     */
+    handleFrame(_frame: ServiceSwitcherFrame, _direction: FrameDirection): Promise<FrameProcessor | null>;
+    /**
+     * Handle an error from the active service.
+     *
+     * Called by `ServiceSwitcher` for every `ErrorFrame` the active service
+     * pushes upstream, whether or not the service can carry on from it.
+     * Subclasses override this to decide which errors are worth switching away
+     * from: `error.processor.isUsable` tells a service that is finished apart
+     * from one having a bad moment, and a subclass is free to switch on either.
+     *
+     * @param error The error frame pushed by the active service.
+     * @returns The newly active service if a switch occurred, or null otherwise.
+     */
+    handleError(_error: ErrorFrame): Promise<FrameProcessor | null>;
+    /**
+     * Set the active service to the given one, if it is in the list of
+     * available services.
+     *
+     * If it's not in the list, the request is ignored, as it may have been
+     * intended for another ServiceSwitcher in the pipeline. A service that can
+     * no longer do its job (`isUsable` false) is refused, since making it active
+     * would only route work to something that can't handle it; call
+     * `FrameProcessor.setUsable` on it first once whatever stopped it working
+     * has been dealt with.
+     *
+     * @param service The service to set as active.
+     * @returns The newly active service, or null if the service was not found
+     *   or can no longer be given work.
+     */
+    protected _setActiveIfAvailable(service: FrameProcessor): Promise<FrameProcessor | null>;
+}
+/**
+ * A strategy for switching between services manually.
+ *
+ * This strategy allows the user to manually select which service is active.
+ * The initial active service is the first one in the list.
+ *
+ * @example
+ * const sttSwitcher = new ServiceSwitcher([stt1, stt2], {
+ *   strategyType: ServiceSwitcherStrategyManual,
+ * });
+ */
+export declare class ServiceSwitcherStrategyManual extends ServiceSwitcherStrategy {
+    /**
+     * Handle a frame that controls service switching.
+     *
+     * @param frame The frame to handle.
+     * @param direction The direction of the frame (upstream or downstream).
+     * @returns The newly active service if a switch occurred, or null otherwise.
+     */
+    handleFrame(frame: ServiceSwitcherFrame, _direction: FrameDirection): Promise<FrameProcessor | null>;
+}
+/**
+ * A strategy that automatically switches to a backup service on failure.
+ *
+ * This strategy switches when the active service reports an error that leaves
+ * it unable to do its job (`isUsable` false), moving to the next service in
+ * the list that can still do its own. Errors the service can carry on from are
+ * left alone, so a provider hiccup doesn't cost a failover. Recovery and
+ * fallback policies are left to application code via the
+ * `on_service_switched` event.
+ *
+ * Event handlers available:
+ *
+ * - on_service_switched: called when the active service changes.
+ *
+ * @example
+ * const switcher = new ServiceSwitcher([primaryStt, backupStt], {
+ *   strategyType: ServiceSwitcherStrategyFailover,
+ * });
+ *
+ * switcher.strategy.eventHandler("on_service_switched", async (strategy, service) => {
+ *   // App decides when/how to recover the failed service
+ * });
+ */
+export declare class ServiceSwitcherStrategyFailover extends ServiceSwitcherStrategyManual {
+    /**
+     * Handle an error from the active service by failing over.
+     *
+     * Only an error that leaves the service unable to do its job is worth a
+     * failover; anything it can carry on from is ignored. When one does,
+     * switches to the next service in the list that can still do its job,
+     * wrapping around from the end. The failed service stays in the list and can
+     * be switched back to once it has been brought back with
+     * `FrameProcessor.setUsable`.
+     *
+     * @param error The error frame pushed by the active service.
+     * @returns The newly active service if a switch occurred, or null if the
+     *   error didn't warrant one or no other service can be given work.
+     */
+    handleError(error: ErrorFrame): Promise<FrameProcessor | null>;
+}
+/** A strategy class, as passed to `ServiceSwitcher`. */
+export type StrategyType<S extends ServiceSwitcherStrategy = ServiceSwitcherStrategy> = new (services: FrameProcessor[]) => S;
+export interface ServiceSwitcherOptions<S extends ServiceSwitcherStrategy> {
+    /**
+     * The strategy class to use for switching between services. Defaults to
+     * `ServiceSwitcherStrategyManual`.
+     */
+    strategyType?: StrategyType<S>;
+}
+/**
+ * Parallel pipeline that routes frames to one active service at a time.
+ *
+ * Wraps each service in a pair of filters that gate frame flow based on which
+ * service is currently active. Switching is controlled by
+ * `ServiceSwitcherFrame` frames and delegated to a pluggable
+ * `ServiceSwitcherStrategy`.
+ *
+ * `ServiceUpdateSettingsFrame` is the exception to the gating. A settings
+ * update addressed to a member service (`service`) reaches it whether or not
+ * it is active, and one marked `reachInactiveServices` reaches every member,
+ * so whichever service becomes active later is already configured. Any other
+ * settings update applies to the active service alone.
+ *
+ * @example
+ * const switcher = new ServiceSwitcher([stt1, stt2]);
+ */
+export declare class ServiceSwitcher<S extends ServiceSwitcherStrategy = ServiceSwitcherStrategyManual> extends ParallelPipeline {
+    protected _services: FrameProcessor[];
+    protected _strategy: S;
+    protected _inactiveServiceUpdates: number[];
+    protected _announcedUsable: boolean;
+    /**
+     * Initialize the service switcher with a list of services and a switching strategy.
+     *
+     * @param services List of frame processors to switch between.
+     * @param options.strategyType The strategy class to use for switching
+     *   between services. Defaults to `ServiceSwitcherStrategyManual`.
+     */
+    constructor(services: FrameProcessor[], options?: ServiceSwitcherOptions<S>);
+    /**
+     * Ignore an attempt to set this switcher's usability directly.
+     *
+     * A switcher has no usability of its own to set: what it reports is a
+     * reading of its services. Bring an individual service back with its own
+     * `FrameProcessor.setUsable`, which brings the switcher back with it.
+     *
+     * @param isUsable Whether the switcher can be given work. Ignored.
+     */
+    setUsable(isUsable: boolean): Promise<void>;
+    /**
+     * Announce this switcher's usability after a service changed its own.
+     *
+     * @param service The service whose usability changed.
+     * @param isUsable Whether that service can now be given work.
+     */
+    protected _onServiceUsableChanged(_service: FrameProcessor, _isUsable: boolean): Promise<void>;
+    /** Raise `on_usable_changed` if what this switcher reports has moved. */
+    protected _announceUsable(): Promise<void>;
+    /** The active switching strategy. */
+    get strategy(): S;
+    /** The list of available services. */
+    get services(): FrameProcessor[];
+    /**
+     * Whether any of the switched services can still be given work.
+     *
+     * A switcher is only as dead as its last service: it can keep doing its job
+     * by moving work to a different one, so it reports itself unusable only once
+     * none of them can do theirs. This is a reading of the services rather than
+     * a state of its own, so bringing a service back with
+     * `FrameProcessor.setUsable` brings the switcher back too, and calling that
+     * on the switcher itself does nothing. The switcher raises
+     * `on_usable_changed` for itself as the reading moves, so watching it is
+     * enough to hear about the services it holds.
+     *
+     * @returns True while at least one service can be given work.
+     */
+    get isUsable(): boolean;
+    protected static _makePipelineDefinitions(services: FrameProcessor[], strategy: ServiceSwitcherStrategy): FrameProcessor[][];
+    protected static _makePipelineDefinition(service: FrameProcessor, strategy: ServiceSwitcherStrategy): FrameProcessor[];
+    /**
+     * Push a frame out of the service switcher.
+     *
+     * Suppresses `ServiceSwitcherRequestMetadataFrame` targeting the active
+     * service (since it has already been handled) and `ServiceMetadataFrame`
+     * from inactive services so only the active service's metadata reaches
+     * downstream processors. One case this happens is with `StartFrame` since
+     * all the filters let it pass, and `StartFrame` causes the service to
+     * generate `ServiceMetadataFrame`.
+     *
+     * Also suppresses the copies of a `ServiceUpdateSettingsFrame` handed to
+     * the inactive services, so that the update the rest of the pipeline sees
+     * is the one travelling the active service's branch.
+     *
+     * `ErrorFrame` instances from the services being switched between are
+     * answered for here rather than travelling on, since the rest of the
+     * pipeline deals with the switcher and not with what it holds. Errors from
+     * a service the switcher isn't using stop here outright. Every error from
+     * the active service is forwarded to the strategy via `handleError`, which
+     * decides whether it warrants a switch; a successful switch absorbs it, the
+     * switcher having gone on doing its job. An error that leaves the active
+     * service unable to do its job with no switch to be made is reported
+     * against the switcher, so that the rest of the pipeline judges it by what
+     * the switcher has left rather than by the one service that failed. Every
+     * other error travels upstream as usual.
+     */
+    pushFrame(frame: Frame, direction?: FrameDirection): Promise<void>;
+    /**
+     * Report a service failure the switcher could not switch away from.
+     *
+     * Re-attributes the error to the switcher, which is the processor the rest
+     * of the pipeline deals with. Whether losing this service matters depends
+     * on what the switcher has left, not on the service that just failed, so
+     * `isUsable` on the reported error answers for the switcher as a whole.
+     *
+     * @param failedService The service that can no longer do its job.
+     * @param error The error it reported.
+     */
+    protected _reportServiceFailure(failedService: FrameProcessor, error: ErrorFrame): Promise<void>;
+    /**
+     * Process a frame, handling frames which affect service switching.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of the frame (upstream or downstream).
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+    /**
+     * Hand a settings update to the member services that aren't active.
+     *
+     * The active service receives the update through its branch like any other
+     * frame. The inactive ones sit behind closed filters, so each is handed its
+     * own copy directly.
+     *
+     * @param frame The settings update to hand over.
+     * @param direction The direction the settings update is travelling.
+     */
+    protected _updateInactiveServices(frame: ServiceUpdateSettingsFrame, direction: FrameDirection): Promise<void>;
+    /**
+     * Return the inactive member services that should apply a settings update.
+     *
+     * @param frame The settings update to route.
+     * @returns The services to hand the update to, which may be empty.
+     */
+    protected _inactiveUpdateTargets(frame: ServiceUpdateSettingsFrame): FrameProcessor[];
+}
+//# sourceMappingURL=service_switcher.d.ts.map