durable-utils/experimental/region-placer.d.ts

Utilities for Cloudflare Durable Objects and Workers, including SQL migrations, sharding and retry utilities, and more.

import type { DurableObjectLocationHint } from "@cloudflare/workers-types";
import { DurableObject, WorkerEntrypoint, RpcTarget, RpcStub } from "cloudflare:workers";
interface Env {
    RegionPlacerDO: DurableObjectNamespace<RegionPlacerDO>;
}
/**
 * RegionPlacerDO is a Durable Object you have to add to your Worker bindings
 * if you want to use any of the `regionPlace(...)` functionality of this package.
 *
 * It's just used as an anchor for placing Worker invocations in specific regions.
 *
 * The Durable Object instance does NOT stay running while your Worker calls are running.
 */
export declare class RegionPlacerDO extends DurableObject {
    createExecutorStub(bindingName: string, locationHint: DurableObjectLocationHint): Promise<RpcStub<RegionPlaceableTarget>>;
}
/**
 * RegionPlacer is an auxiliary Worker class that you can export from your package,
 * and add to your bindings in order to be able to invoke any of your Worker bindings
 * at a specific Location Hint region.
 *
 * Example:
 *  `env.RegionPlacer.place("eeur", "TargetWorker").ping("boomer")`
 *
 * The above example will invoke the method `ping("boomer")` on the Worker binding `TargetWorker`
 * inside the the `eeur` region.
 */
export declare class RegionPlacer extends WorkerEntrypoint<Env> {
    place(locationHint: DurableObjectLocationHint, bindingName: string): Promise<Rpc.Stub<{
        __RPC_TARGET_BRAND: never;
        targetLocationHint: () => Promise<"wnam"> | Promise<"enam"> | Promise<"sam"> | Promise<"weur"> | Promise<"eeur"> | Promise<"apac"> | Promise<"oc"> | Promise<"afr"> | Promise<"me">;
    } & Rpc.StubBase<RegionPlaceableTarget>>>;
}
/**
 * Workers can extend the RegionPlaceableWorkerEntrypoint class in order to allow
 * themselves to be called into specific Location Hints.
 * The binding name of the Worker class inheriting this class, has to be the same
 * as the binding itself, or some case-variant of it. For example, in the example
 * below we have the subclass `TargetWorker`, therefore its binding can be
 * `TARGETWORKER, TargetWorker, targetworker`.
 *
 * We do a name matching search in all the bindings of the Worker environment, and
 * will invoke the binding with the matching name as the subclass name instantiated.
 *
 * WARNING: Do no have multiple bindings with the same name but different casing,
 *          otherwise "Here be dragons" and unfortunate debugging ensues.
 *
 * Example:
 *  export class TargetWorker extends RegionPlaceableWorkerEntrypoint {
 *       async ping(v: string) { return "ping:" + v; }
 *  }
 *
 * Then, to call `ping(...)` within eeur, assuming TARGETWORKER is the binding for TargetWorker:
 *  `env.TARGETWORKER.regionPlace("eeur").ping("hello")`
 */
export declare class RegionPlaceableWorkerEntrypoint extends WorkerEntrypoint<Env> {
    createRegionPlacedWorkerEntrypoint(locationHint: DurableObjectLocationHint): Promise<RegionPlaceableTarget>;
    regionPlace(locationHint: DurableObjectLocationHint): Promise<Rpc.Stub<{
        __RPC_TARGET_BRAND: never;
        targetLocationHint: () => Promise<"wnam"> | Promise<"enam"> | Promise<"sam"> | Promise<"weur"> | Promise<"eeur"> | Promise<"apac"> | Promise<"oc"> | Promise<"afr"> | Promise<"me">;
    } & Rpc.StubBase<RegionPlaceableTarget>>>;
}
/**
 * RegionPlaceableTarget is an RpcTarget returned from the Durable Object implicitly
 * created at the location hint we want to execute our target worker.
 *
 * This RpcTarget should have all the methods of the binding Worker that is attempting
 * to be region placed.
 */
export declare class RegionPlaceableTarget extends RpcTarget {
    #private;
    constructor(we: RegionPlaceableWorkerEntrypoint, locationHint: DurableObjectLocationHint);
    targetLocationHint(): Promise<DurableObjectLocationHint>;
}
export {};