@eyepop.ai/eyepop 3.23.0 → 3.25.0

package/dist/eyepop.index.d.ts

@@ -952,6 +952,11 @@ interface WorkerSession extends Session {
      * Transient sessions may not have a pipeline until the first source is processed.
      */
     readonly pipelineId: string | undefined;
+    /**
+     * Whether this session's endpoint runs in pipeline mode, without a worker session. A worker
+     * endpoint created from this session runs in pipeline mode too.
+     */
+    readonly isPipelineMode?: boolean | undefined;
     authenticationHeaders(): any;
 }
 declare enum VideoMode {
@@ -1465,32 +1470,102 @@ interface WorkerOptions extends Options {
     autoStart?: boolean;
     stopJobs?: boolean;
     isLocalMode?: boolean;
+    /**
+     * Run the endpoint's jobs on the pipeline API's socket instead of a worker session. The
+     * compute API at `eyepopUrl` names the pipeline API in its `/v1/configs`; with `isLocalMode`,
+     * `eyepopUrl` is the pipeline API itself. Takes no option that names a session or a pop id.
+     * Defaults to process.env['EYEPOP_PIPELINE_MODE'].
+     */
+    isPipelineMode?: boolean;
 }
 
+/**
+ * What a job runs, whatever backend runs it: one source, or a group of paths, streams or urls
+ * run as one inference unit, with its parameters.
+ */
+type WorkerWork = {
+    readonly kind: 'source';
+    readonly source: Source;
+    readonly params: ProcessParams;
+} | {
+    readonly kind: 'uploadGroup';
+    readonly paths: string[];
+    readonly params: ProcessParams;
+} | {
+    readonly kind: 'uploadStreamGroup';
+    readonly streams: Array<ReadableStream<Uint8Array> | Blob | BufferSource>;
+    readonly mimeTypes: string[] | undefined;
+    readonly params: ProcessParams;
+} | {
+    readonly kind: 'loadFromGroup';
+    readonly urls: string[];
+    readonly params: ProcessParams;
+};
+/** What a backend may use of its endpoint: the options, the HTTP client, the credential and the job queue. */
+interface WorkerContext {
+    readonly options: WorkerOptions;
+    readonly logger: Logger;
+    readonly requestLogger: Logger;
+    client(): HttpClient | null;
+    /** The job queue; a backend acquires a permit per job and releases it through `jobDone`. */
+    limit(): Semaphore;
+    jobDone(): void;
+    updateState(state?: EndpointState, message?: string): void;
+    eyepopUrl(): string;
+    eyepopWebApiUrl(): string;
+    /** `Bearer <token>` for the endpoint's own credential, exchanged and refreshed as needed; `Implicit` locally. */
+    credentialHeader(): Promise<string>;
+    /** Forget the endpoint's token, so the next `credentialHeader` authenticates again. */
+    forgetCredential(): void;
+    fetchWithRetry(fetcher: () => Promise<Response>, retries?: number): Promise<Response>;
+    /** The endpoint's credential as a session. */
+    credentialSession(): Promise<{
+        eyepopUrl: string;
+        accessToken: string;
+        validUntil: number;
+    }>;
+}
+/**
+ * What runs a WorkerEndpoint's jobs: a worker session, or the pipeline API's socket. The endpoint
+ * owns the public methods and their checks, the credential, the HTTP client and the job queue; it
+ * hands each job to its backend as a WorkerWork.
+ */
+interface WorkerBackend {
+    /** Reach whatever runs jobs; called when the endpoint connects. */
+    reconnect(): Promise<void>;
+    /**
+     * Release it when the endpoint disconnects. `closeEndpoint` waits for the endpoint's jobs (when
+     * asked to) and closes its HTTP client; the backend calls it before or after releasing its own.
+     */
+    disconnect(closeEndpoint: () => Promise<void>): Promise<void>;
+    session(): Promise<WorkerSession>;
+    pop(): Pop | null;
+    popName(): string | null;
+    changePop(pop: Pop): Promise<void>;
+    /** Start the work and return its predictions; the backend holds a job queue permit until it ends. */
+    submit(work: WorkerWork): Promise<ResultStream>;
+    /** A request answered with this status; a session backend forgets what it no longer reaches. */
+    onStatus(statusCode: number): void;
+    /** The endpoint's Authorization header for the worker's routes. */
+    authorizationHeader(): Promise<string>;
+}
+
+/**
+ * Endpoint to an EyePop.ai worker. Its jobs run on a backend: a worker session by default, or with
+ * `isPipelineMode` the pipeline API's socket. The methods are the same either way; a backend that
+ * cannot honour an option says so.
+ */
 declare class WorkerEndpoint extends Endpoint<WorkerEndpoint> {
-    private _baseUrl;
-    private _pipelineId;
-    private _popName;
-    private _sessionAccessToken;
-    private _sessionAccessTokenValidUntil;
-    private _accountId;
-    private _pipeline;
-    private _pipelineCreatePromise;
+    private readonly _backend;
     constructor(options: WorkerOptions);
     private options;
+    /** What runs this endpoint's jobs. */
+    backend(): WorkerBackend;
     disconnect(wait?: boolean): Promise<void>;
-    protected statusHandler404(_: number): void;
     session(): Promise<WorkerSession>;
     popName(): string | null;
     pop(): Pop | null;
-    /**
-     * A select forward's results come only at V3. Only a Pop that selects asks
-     * for it, so a worker too old to know V3 - which also rejects that Pop - is
-     * never sent a version it would not accept.
-     */
-    private predictionVersion;
     changePop(pop: Pop): Promise<void>;
-    private _authenticationHeaders;
     /**
      * @deprecated Pop ids are only retained for backwards compatibility.
      * Configure transient sessions with `WorkerOptions.pop`.
@@ -1513,41 +1588,20 @@ declare class WorkerEndpoint extends Endpoint<WorkerEndpoint> {
      * @param roi
      */
     process({ source, componentParams, motionDetect, roi }: ProcessRequest): Promise<ResultStream>;
-    private processV1;
     /**
      * Reject a source's calibration before any work is started for it.
      *
-     * Called by every entry point that takes ProcessParams rather than at the
-     * one boundary they share, because they have none: the group methods build
-     * their jobs directly instead of going through processV2. It runs before
-     * the concurrency limit is acquired, so a request that can never be sent
+     * Called by every entry point that takes ProcessParams, before the
+     * concurrency limit is acquired, so a request that can never be sent
      * does not hold a slot.
      */
     private validateProcessParams;
-    private processV2;
     uploadGroup(paths: string[], params?: ProcessParams): Promise<ResultStream>;
     uploadStreamGroup(streams: Array<ReadableStream<Uint8Array> | Blob | BufferSource>, mimeTypes?: string[], params?: ProcessParams): Promise<ResultStream>;
     loadFromGroup(urls: string[], params?: ProcessParams): Promise<ResultStream>;
-    private uploadFile;
-    private uploadStream;
-    private uploadPath;
-    private loadFrom;
-    private loadFromAssetUuid;
-    private loadMediaStream;
-    private jobDone;
-    private jobStatus;
+    private submit;
     protected reconnect(): Promise<WorkerEndpoint>;
-    private startWebApiSessionWithPopId;
-    private static WAIT_FOR_IS_READY;
-    private sessionReadyTimeoutMs;
-    private getComputeSession;
-    private startTransientPipeline;
-    private ensureTransientPipelineStarted;
-    private changeTransientPop;
-    private deleteTransientPipeline;
     protected authorizationHeader(): Promise<string>;
-    private computeAuthorizationHeader;
-    private setTransientPipelinePop;
 }
 
 interface DataOptions extends Options {
@@ -1905,6 +1959,203 @@ declare class ComputeAccountMismatchError extends Error {
     constructor(sessionUuid: string, sessionAccountId: string | undefined, accountId: string);
 }
 
+/** Runs jobs on a worker session: a compute API session, or a named pop found through its config. */
+declare class SessionBackend implements WorkerBackend {
+    private readonly ctx;
+    private _baseUrl;
+    private _pipelineId;
+    private _popName;
+    private _sessionAccessToken;
+    private _sessionAccessTokenValidUntil;
+    private _accountId;
+    private _pipeline;
+    private _pipelineCreatePromise;
+    constructor(ctx: WorkerContext);
+    disconnect(closeEndpoint: () => Promise<void>): Promise<void>;
+    private deleteOwnPipeline;
+    onStatus(statusCode: number): void;
+    session(): Promise<WorkerSession>;
+    popName(): string | null;
+    pop(): Pop | null;
+    /**
+     * A select forward's results come only at V3. Only a Pop that selects asks
+     * for it, so a worker too old to know V3 - which also rejects that Pop - is
+     * never sent a version it would not accept.
+     */
+    private predictionVersion;
+    changePop(pop: Pop): Promise<void>;
+    private _authenticationHeaders;
+    submit(work: WorkerWork): Promise<ResultStream>;
+    private process;
+    private start;
+    private uploadGroup;
+    private uploadStreamGroup;
+    private loadFromGroup;
+    private resolvePath;
+    /** Start a job once the transient pipeline runs and a queue permit is held; the permit is released if it cannot start. */
+    private startConnected;
+    private uploadFile;
+    private uploadStream;
+    private uploadPath;
+    private loadFrom;
+    private loadFromAssetUuid;
+    private loadMediaStream;
+    reconnect(): Promise<void>;
+    private startWebApiSessionWithPopId;
+    private static WAIT_FOR_IS_READY;
+    private sessionReadyTimeoutMs;
+    private getComputeSession;
+    private startTransientPipeline;
+    private ensureTransientPipelineStarted;
+    private changeTransientPop;
+    private deleteTransientPipeline;
+    authorizationHeader(): Promise<string>;
+    private computeAuthorizationHeader;
+    private setTransientPipelinePop;
+}
+
+declare const PIPELINE_PATH = "/api/v1/pipeline";
+declare const SUBPROTOCOL = "eyepop.v1";
+/** A socket may have this many open sources; one more is answered `queue_full`. */
+declare const MAX_OPEN_SOURCES = 256;
+/** Uploads up to this size go as one combined message, larger ones in chunks. */
+declare const COMBINED_UPLOAD_MAX_BYTES: number;
+/** Why pipeline mode refused its configuration. */
+type PipelineConfigurationProblem = 'session_options' | 'job_queue_length' | 'no_pipeline_api_url' | 'insecure_url';
+/** Pipeline mode cannot run as configured; `options` names the refused options for `session_options`. */
+declare class PipelineConfigurationError extends Error {
+    readonly problem: PipelineConfigurationProblem;
+    readonly options: string[];
+    constructor(problem: PipelineConfigurationProblem, message: string, options?: string[]);
+}
+/** A job in flight when the pipeline API's socket closed; the job is not sent again. */
+declare class PipelineSocketClosedError extends Error {
+    readonly code: number | undefined;
+    readonly reason: string;
+    constructor(code: number | undefined, reason: string);
+}
+/** The pipeline API answered a command with an error, for instance `queue_full`. */
+declare class PipelineCommandError extends Error {
+    readonly error: string;
+    readonly detail: string;
+    constructor(error: string, detail?: string);
+}
+/** A source ended with reason `error` or `preempted` rather than at its end of stream. */
+declare class PipelineSourceError extends Error {
+    readonly sourceId: string;
+    readonly reason: string;
+    readonly detail: string;
+    constructor(sourceId: string, reason: string, detail?: string);
+}
+type Message = Record<string, any>;
+type UploadBody$1 = ReadableStream<Uint8Array> | Blob | BufferSource;
+declare const CANCELLED: unique symbol;
+type InboxItem = Message | Error | typeof CANCELLED;
+/** An unbounded queue one consumer awaits. */
+declare class Inbox<T> {
+    private readonly _items;
+    private _waiter;
+    push(item: T): void;
+    next(): Promise<T>;
+}
+/** A chunked upload's credit, granted by the server's `send` and `credit`. */
+declare class Credit {
+    private _credit;
+    private _ended;
+    private _waiter;
+    grant(n: number): void;
+    end(): void;
+    take(most: number): Promise<number>;
+    private wake;
+}
+/** A job's source on one socket: the messages for its id, and its chunked uploads by member. */
+declare class OpenSource {
+    readonly id: string;
+    readonly inbox: Inbox<InboxItem>;
+    readonly uploads: Map<number | null, Credit>;
+    constructor(id: string);
+    close(error: Error): void;
+}
+/** One upload member's bytes: a fresh body and its content type, and its size when known. */
+interface Media {
+    readonly open: () => Promise<UploadBody$1>;
+    readonly contentType: string;
+    readonly size: number | undefined;
+}
+/** A job: one source on the endpoint's socket, its predictions read as an async iterable. */
+declare class PipelineJob implements ResultStream {
+    readonly source: Message;
+    readonly media: Media[];
+    readonly live: boolean;
+    readonly params: ProcessParams;
+    readonly mediaStream: MediaStream | undefined;
+    private readonly _results;
+    private _consumed;
+    private _cancelled;
+    openSource: OpenSource | null;
+    stopOnPipeline: (() => void) | null;
+    constructor(source: Message, media: Media[], live: boolean, params: ProcessParams, mediaStream?: MediaStream | undefined);
+    get cancelled(): boolean;
+    command(id: string): Message;
+    predicted(prediction: Prediction): void;
+    finish(error?: Error | null): void;
+    cancel(): void;
+    [Symbol.asyncIterator](): AsyncIterator<Prediction>;
+}
+/** Runs jobs on one socket to the pipeline API, opened when the endpoint connects. */
+declare class PipelineBackend implements WorkerBackend {
+    private readonly ctx;
+    private _pipelineApiUrl;
+    private _socket;
+    private _connecting;
+    private _sendChain;
+    private _disconnecting;
+    private _nextId;
+    private _currentPop;
+    private readonly _warned;
+    private _heartbeat;
+    private _reconnects;
+    constructor(ctx: WorkerContext);
+    reconnect(): Promise<void>;
+    disconnect(closeEndpoint: () => Promise<void>): Promise<void>;
+    onStatus(_statusCode: number): void;
+    popName(): string | null;
+    authorizationHeader(): Promise<string>;
+    private inOrder;
+    /** The open socket, or a new one with the last pop set on it. */
+    private ensureSocket;
+    private openSocket;
+    private startHeartbeat;
+    private socketUrl;
+    private configuredPipelineApiUrl;
+    private token;
+    /** Open the socket, waiting through 503 with Retry-After and exchanging the API key again after a 401. */
+    private upgrade;
+    private closed;
+    private dispatch;
+    private newId;
+    /** Send a command that is answered by `result` or `error` under its id. */
+    private command;
+    pop(): Pop | null;
+    /** Set the pop on the socket's pipeline; a pop it refuses rejects, and the last pop it took stays. */
+    changePop(pop: Pop): Promise<void>;
+    private setPopOn;
+    submit(work: WorkerWork): Promise<ResultStream>;
+    private notSent;
+    private jobOf;
+    private sourceJob;
+    private pathMedia;
+    /** Run the job's source to its end; a live source refused overloaded goes once more on a new socket. */
+    private run;
+    /** Send the job's setSource; the caller runs it in submission order. */
+    private setSource;
+    /** Hand the source's predictions to the job until it ends; true when the pipeline API was overloaded. */
+    private follow;
+    /** Send each upload member's bytes in chunks within its credit, then its uploaded. */
+    private upload;
+    session(): Promise<WorkerSession>;
+}
+
 type UploadBody = ReadableStream<Uint8Array> | Blob | BufferSource;
 declare class AbstractJob implements ResultStream {
     protected _getSession: () => Promise<WorkerSession>;
@@ -2034,4 +2285,4 @@ declare namespace EyePop {
     function dataEndpoint(opts?: DataOptions): DataEndpoint;
 }
 
-export { type AbilityAliasEntry, AbstractJob, type AccessTokenAuth, type AliasResolution, type Annotation, AnnotationInclusionMode, AnnotationType, type ApiKeyAuth, type Area, AreaType, ArtifactType, type Asset, type AssetImport, AssetInclusionMode, AssetStatus, AssetUrlType, type AssetUuidSource, type Auth0Options, type Authentication, type AutoAnnotate, type AutoAnnotateParams, type AutoAnnotatePrompt, AutoAnnotateStatus, AutoAnnotateTask, type AutoPromptConfig, type AutoTask, type BaseArea, type BaseComponent, type BaseTask, type Box, type Camera, type CameraDistortion, type CameraExtrinsics, type CameraIntrinsics, type ChangeEvent, ChangeType, type ClassificationTask, type CloudBounds, type CloudBox, type ComponentFinderComponent, type ComponentParams, ComputeAccountMismatchError, ComputeApiError, type Contour, type ContourArea, type ContourFinderComponent, ContourType, type CreateWorkflow, type CreateWorkflowConfig, DEFAULT_PREDICTION_VERSION, DataApiType, DataEndpoint, type DataOptions, type DataSession, type Dataset, type DatasetAutoAnnotate, type DatasetAutoAnnotateCreate, type DatasetAutoAnnotateUpdate, type DatasetCreate, type DatasetHeroAssetUpdate, type DatasetParent, type DatasetUpdate, type DatasetVersion, type DatasetVersionAssetStats, type Depth, DepthMap, type DepthSemantic, type DownloadResponse, Endpoint, EndpointState, type EvaluateConfig, type EvaluateFilter, type EvaluateRequest, type EvaluateResponse, type EvaluateRunInfo, EvaluationStatus, ExportedBy, EyePop, EyePopDataWebSocketError, EyepopLineDecoder, type FileSource, type ForwardComponent, ForwardOperatorType, type HttpClient, type InferRequest, type InferRunInfo, type InferRuntimeConfig, type InferenceComponent, InferenceType, type ListWorkFlowItem, type ListWorkFlowItemMetadata, type ListWorkflowItemMetadataLabels, LoadFromAssetUuidJob, LoadFromGroupJob, LoadFromJob, LoadMediaStreamJob, type LocalAuth, type Mask, type MediaStreamSource, type Model, type ModelCreate, type ModelExport, ModelExportStatus, ModelFormat, type ModelMetrics, ModelPrecisionType, type ModelSample, ModelStatus, ModelTask, type ModelTrainingProgress, ModelTrainingStage, ModelType, type ModelUpdate, type MotionDetectConfig, MotionModel, type MultipartContent, type MultipartPart, type OAuth2Auth, type OnChangeEvent, type Options, type PathSource, type PlatformSupport, type Point2d, type Point3d, PointCloud, type Pop, type PopComponent, PopComponentType, type PopCrop, type PopDepthMap, type PopForward, type PopForwardOperator, type PopSelect, type PredictedClass, type PredictedEmbedding, type PredictedKeyPoint, type PredictedKeyPoints, type PredictedMesh, type PredictedMotion, type PredictedObject, type PredictedText, type Prediction, PredictionVersion, type ProcessParams, type ProcessRequest, QUATERNION_TOLERANCE, type QcAiHubExportParams, type Quaternion, type RectangleArea, type ResponseSchema, type ResultStream, type Roi, SelectMode, Semaphore, type Session, type SessionAuth, type Source, type SourceDefaults, Stream, type StreamEvent, type StreamSource, type StreamTime, TaskMode, TaskType, type TimeSpan, type TrackingComponent, TranscodeMode, type TransformInto, TransientPopId, UploadGroupJob, UploadJob, type UploadSource, type UrlSource, UserReview, type Vector3, type Vector3d, VideoMode, type VlmAbility, type VlmAbilityCreate, type VlmAbilityGroup, type VlmAbilityGroupCreate, type VlmAbilityGroupUpdate, VlmAbilityStatus, type VlmAbilityUpdate, WebrtcBase, WebrtcWhep, WebrtcWhip, WorkerEndpoint, type WorkerOptions, type WorkerSession, type Workflow, WorkflowPhase, accessTokenCredential, apiKeyCredential, cloudOfDepth, cloudOfObject, cloudsOfPrediction, decodeDepthMap, decodePointCloud, EyePop as default, encodeMultipartFormData, getBaseUrl, isSelectOperator, popSelects, randomMultipartBoundary, readableStreamFromString, resolveAuth, validateCamera, validatePop };
+export { type AbilityAliasEntry, AbstractJob, type AccessTokenAuth, type AliasResolution, type Annotation, AnnotationInclusionMode, AnnotationType, type ApiKeyAuth, type Area, AreaType, ArtifactType, type Asset, type AssetImport, AssetInclusionMode, AssetStatus, AssetUrlType, type AssetUuidSource, type Auth0Options, type Authentication, type AutoAnnotate, type AutoAnnotateParams, type AutoAnnotatePrompt, AutoAnnotateStatus, AutoAnnotateTask, type AutoPromptConfig, type AutoTask, type BaseArea, type BaseComponent, type BaseTask, type Box, COMBINED_UPLOAD_MAX_BYTES, type Camera, type CameraDistortion, type CameraExtrinsics, type CameraIntrinsics, type ChangeEvent, ChangeType, type ClassificationTask, type CloudBounds, type CloudBox, type ComponentFinderComponent, type ComponentParams, ComputeAccountMismatchError, ComputeApiError, type Contour, type ContourArea, type ContourFinderComponent, ContourType, type CreateWorkflow, type CreateWorkflowConfig, DEFAULT_PREDICTION_VERSION, DataApiType, DataEndpoint, type DataOptions, type DataSession, type Dataset, type DatasetAutoAnnotate, type DatasetAutoAnnotateCreate, type DatasetAutoAnnotateUpdate, type DatasetCreate, type DatasetHeroAssetUpdate, type DatasetParent, type DatasetUpdate, type DatasetVersion, type DatasetVersionAssetStats, type Depth, DepthMap, type DepthSemantic, type DownloadResponse, Endpoint, EndpointState, type EvaluateConfig, type EvaluateFilter, type EvaluateRequest, type EvaluateResponse, type EvaluateRunInfo, EvaluationStatus, ExportedBy, EyePop, EyePopDataWebSocketError, EyepopLineDecoder, type FileSource, type ForwardComponent, ForwardOperatorType, type HttpClient, type InferRequest, type InferRunInfo, type InferRuntimeConfig, type InferenceComponent, InferenceType, type ListWorkFlowItem, type ListWorkFlowItemMetadata, type ListWorkflowItemMetadataLabels, LoadFromAssetUuidJob, LoadFromGroupJob, LoadFromJob, LoadMediaStreamJob, type LocalAuth, MAX_OPEN_SOURCES, type Mask, type MediaStreamSource, type Model, type ModelCreate, type ModelExport, ModelExportStatus, ModelFormat, type ModelMetrics, ModelPrecisionType, type ModelSample, ModelStatus, ModelTask, type ModelTrainingProgress, ModelTrainingStage, ModelType, type ModelUpdate, type MotionDetectConfig, MotionModel, type MultipartContent, type MultipartPart, type OAuth2Auth, type OnChangeEvent, type Options, PIPELINE_PATH, type PathSource, PipelineBackend, PipelineCommandError, PipelineConfigurationError, type PipelineConfigurationProblem, PipelineJob, PipelineSocketClosedError, PipelineSourceError, type PlatformSupport, type Point2d, type Point3d, PointCloud, type Pop, type PopComponent, PopComponentType, type PopCrop, type PopDepthMap, type PopForward, type PopForwardOperator, type PopSelect, type PredictedClass, type PredictedEmbedding, type PredictedKeyPoint, type PredictedKeyPoints, type PredictedMesh, type PredictedMotion, type PredictedObject, type PredictedText, type Prediction, PredictionVersion, type ProcessParams, type ProcessRequest, QUATERNION_TOLERANCE, type QcAiHubExportParams, type Quaternion, type RectangleArea, type ResponseSchema, type ResultStream, type Roi, SUBPROTOCOL, SelectMode, Semaphore, type Session, type SessionAuth, SessionBackend, type Source, type SourceDefaults, Stream, type StreamEvent, type StreamSource, type StreamTime, TaskMode, TaskType, type TimeSpan, type TrackingComponent, TranscodeMode, type TransformInto, TransientPopId, UploadGroupJob, UploadJob, type UploadSource, type UrlSource, UserReview, type Vector3, type Vector3d, VideoMode, type VlmAbility, type VlmAbilityCreate, type VlmAbilityGroup, type VlmAbilityGroupCreate, type VlmAbilityGroupUpdate, VlmAbilityStatus, type VlmAbilityUpdate, WebrtcBase, WebrtcWhep, WebrtcWhip, type WorkerBackend, type WorkerContext, WorkerEndpoint, type WorkerOptions, type WorkerSession, type WorkerWork, type Workflow, WorkflowPhase, accessTokenCredential, apiKeyCredential, cloudOfDepth, cloudOfObject, cloudsOfPrediction, decodeDepthMap, decodePointCloud, EyePop as default, encodeMultipartFormData, getBaseUrl, isSelectOperator, popSelects, randomMultipartBoundary, readableStreamFromString, resolveAuth, validateCamera, validatePop };