@temporalio/worker/lib/connection.d.ts

Temporal.io SDK Worker sub-package

import { AsyncLocalStorage } from 'node:async_hooks';
import { native } from '@temporalio/core-bridge';
import { ConnectionLike, Metadata, CallContext, WorkflowService, OperatorService, HealthService, TestService } from '@temporalio/client';
import { NativeConnectionOptions } from './connection-options';
import { Runtime } from './runtime';
/**
 * A Native Connection object that delegates calls to the Rust Core binary extension.
 *
 * A Worker must use this class to connect to the server.
 *
 * This class can be used to power `@temporalio/client`'s Client objects.
 */
export declare class NativeConnection implements ConnectionLike {
    private readonly runtime;
    private readonly nativeClient;
    private readonly enableTestService;
    readonly plugins: NativeConnectionPlugin[];
    /**
     * referenceHolders is used internally by the framework, it can be accessed with `extractReferenceHolders` (below)
     */
    private readonly referenceHolders;
    /**
     * Raw gRPC access to Temporal Server's {@link
     * https://github.com/temporalio/api/blob/master/temporal/api/workflowservice/v1/service.proto | Workflow service}
     */
    readonly workflowService: WorkflowService;
    /**
     * Raw gRPC access to Temporal Server's
     * {@link https://github.com/temporalio/api/blob/master/temporal/api/operatorservice/v1/service.proto | Operator service}
     *
     * The Operator Service API defines how Temporal SDKs and other clients interact with the Temporal
     * server to perform administrative functions like registering a search attribute or a namespace.
     *
     * This Service API is NOT compatible with Temporal Cloud. Attempt to use it against a Temporal
     * Cloud namespace will result in gRPC `unauthorized` error.
     */
    readonly operatorService: OperatorService;
    /**
     * Raw gRPC access to the standard gRPC {@link https://github.com/grpc/grpc/blob/92f58c18a8da2728f571138c37760a721c8915a2/doc/health-checking.md | health service}.
     */
    readonly healthService: HealthService;
    /**
     * Raw gRPC access to Temporal Server's
     * {@link https://github.com/temporalio/api/blob/master/temporal/api/testservice/v1/service.proto | Test service}
     *
     * Will be `undefined` if connected to a server that does not support the test service.
     */
    readonly testService: TestService | undefined;
    readonly callContextStorage: AsyncLocalStorage<CallContext>;
    /**
     * nativeClient is intentionally left private, framework code can access it with `extractNativeClient` (below)
     */
    protected constructor(runtime: Runtime, nativeClient: native.Client, enableTestService: boolean, plugins: NativeConnectionPlugin[]);
    /**
     * No-op. This class can only be created via eager connection.
     */
    ensureConnected(): Promise<void>;
    private sendRequest;
    /**
     * Set a deadline for any service requests executed in `fn`'s scope.
     *
     * The deadline is a point in time after which any pending gRPC request will be considered as failed;
     * this will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
     * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}; see {@link isGrpcDeadlineError}.
     *
     * It is stronly recommended to explicitly set deadlines. If no deadline is set, then it is
     * possible for the client to end up waiting forever for a response.
     *
     * @param deadline a point in time after which the request will be considered as failed; either a
     *                 Date object, or a number of milliseconds since the Unix epoch (UTC).
     * @returns the value returned from `fn`
     *
     * @see https://grpc.io/docs/guides/deadlines/
     */
    withDeadline<ReturnType>(deadline: number | Date, fn: () => Promise<ReturnType>): Promise<ReturnType>;
    /**
     * Set metadata for any service requests executed in `fn`'s scope.
     *
     * The provided metadata is merged on top of any existing metadata in current scope, including metadata provided in
     * {@link NativeConnectionOptions.metadata}.
     *
     * @returns value returned from `fn`
     *
     * @example
     *
     * ```ts
     * const workflowHandle = await conn.withMetadata({ apiKey: 'secret' }, () =>
     *   conn.withMetadata({ otherKey: 'set' }, () => client.start(options)))
     * );
     * ```
     */
    withMetadata<ReturnType>(metadata: Metadata, fn: () => Promise<ReturnType>): Promise<ReturnType>;
    /**
     * Set an {@link AbortSignal} that, when aborted, cancels any ongoing service requests executed in
     * `fn`'s scope. This will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
     * with code {@link grpc.status.CANCELLED|CANCELLED}; see {@link isGrpcCancelledError}.
     *
     * This method is only a convenience wrapper around {@link NativeConnection.withAbortSignal}.
     *
     * @example
     *
     * ```ts
     * const ctrl = new AbortController();
     * setTimeout(() => ctrl.abort(), 10_000);
     * // 👇 throws if incomplete by the timeout.
     * await conn.withAbortSignal(ctrl.signal, () => client.workflow.execute(myWorkflow, options));
     * ```
     *
     * @returns value returned from `fn`
     *
     * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
     */
    withAbortSignal<ReturnType>(abortSignal: AbortSignal, fn: () => Promise<ReturnType>): Promise<ReturnType>;
    /**
     * @deprecated use `connect` instead
     */
    static create(options?: NativeConnectionOptions): Promise<NativeConnection>;
    /**
     * Eagerly connect to the Temporal server and return a NativeConnection instance
     */
    static connect(options?: NativeConnectionOptions): Promise<NativeConnection>;
    /**
     * Close this connection.
     *
     * Make sure any Workers using this connection are stopped before calling
     * this method or it will throw an {@link IllegalStateError}
     */
    close(): Promise<void>;
    /**
     * Mapping of gRPC metadata (HTTP headers) to send with each request to the server.
     *
     * Use {@link NativeConnectionOptions.metadata} to set the initial metadata for client creation.
     */
    setMetadata(metadata: Metadata): Promise<void>;
    /**
     * Update the API key for this client. This is only set if `metadata` doesn't already have an
     * "authorization" key.
     *
     * Use {@link NativeConnectionOptions.apiKey} to set the initial metadata for client creation.
     */
    setApiKey(apiKey: string): Promise<void>;
}
/**
 * Extract the private native client instance from a `NativeConnection` instance.
 *
 * Only meant to be used by the framework.
 */
export declare function extractNativeClient(conn: NativeConnection): native.Client;
/**
 * Extract the private referenceHolders set from a `NativeConnection` instance.
 *
 * Only meant to be used by the framework.
 */
export declare function extractReferenceHolders(conn: NativeConnection): Set<native.Worker>;
/**
 * Internal class used when a Worker directly instantiates a connection with no external references.
 *
 * This class is only used as a "marker" during Worker shutdown to decide whether to close the connection.
 */
export declare class InternalNativeConnection extends NativeConnection {
}
/**
 * Plugin to control the configuration of a native connection.
 *
 * @experimental Plugins is an experimental feature; APIs may change without notice.
 */
export interface NativeConnectionPlugin {
    /**
     * Gets the name of this plugin.
     */
    get name(): string;
    /**
     * Hook called when creating a native connection to allow modification of configuration.
     */
    configureNativeConnection?(options: NativeConnectionOptions): NativeConnectionOptions;
}