cloudflare

Import

Import

import * as api from "@fungi.computer/oyster/cloudflare";

Exports

Kind	Export	Description
Ttype alias	FrameBindingProps	Host-minted caller-frame routing props; never supplied by the App.
Ttype alias	FrameBindingMethod	The host’s maintained positional argument/result codecs and operation policy.
Ttype alias	FrameBindingMethods	Method descriptors for the closed App binding vocabulary.
Ttype alias	AppFacetStub	Native facet handle; method RPCs are decoded at the invocation boundary.
Ttype alias	AppInstanceContext	Only the native storage and facet capabilities used by an App Instance. FacetClass is the host’s Durable Object class type (DurableObjectClass on workerd, celld and Cloudflare); Oyster passes it through unopened.
Ttype alias	AppWorkerCode	The module set the Worker Loader runs for one App backend.
Ttype alias	AppInstanceLoader	Loader memoization and class lookup; entrypoint access is not required.
Ttype alias	FrameBindingReply	Private RPC envelope. Domain results, including domain refusals, stay inside value.
Ttype alias	FrameBindingWire	Native entrypoint methods carry the envelope; guest interfaces are restored by wrap.
Ttype alias	GuestLimits	Per-invocation budgets enforced by the guest Worker Loader, including facets.
constconstant	MAX_APP_REPLY_BYTES	Retained shard reply ceiling; replies settle before the frame aborts its facet.
constconstant	backgroundFrameMethods	Shared replay-only port codecs. Origin input is verified by the host and fails with a typed refusal.
constconstant	frameBindingPropsSchema	The shared RPC boundary decoder for host-minted invocation binding props.
fnfunction	checkBackendConstruction()	The Instance owns the disposable facet and supplies its already-read prior state schema. Only initialized App storage is copied; supervisor state and authority are never copied. A unique Loader ID isolates candidate globals. No invocation frame or guestEnv factory is accepted.
fnfunction	edgeVerifiedObjectCache()	The zone’s edge cache as a VerifiedObjectCache: each verified object under a digest-named key on origin that no route serves. A failed write is logged and answers unstored; the next reader verifies from the store again.
fnfunction	r2ArtifactStore()	Store Release artifacts without loading the Worker ownership barrel.
fnfunction	captureFrameBindingReply()	Encode supervisor refusals before native RPC can discard Error properties.
fnfunction	decodeFrameBindingProps()	Decode a host routing packet or refuse it before any Instance lookup.
fnfunction	frameBindingEntrypoint()	One native binding factory for both Hub and standalone, preserving RPC values.
fnfunction	createCloudflareInvocationGate()	End the native App facet when live authority closes early, before the gate admits again.
fnfunction	createCloudflareAppInstance()	Run an App Instance inside a SQLite-backed Durable Object on workerd, celld or Cloudflare. Supervisor state lives in the Durable Object’s own SQLite; the App backend runs in a named app facet loaded through the Worker Loader, so its database survives Release replacement and stays separate from the supervisor. Guest code gets only host gatekeeper bindings and no ambient outbound access.

FrameBindingPropsTtype alias

Signature

type FrameBindingProps = Readonly<{
  instanceId: string;
  binding: AppBackendBindingName;
  frameId: string;
}>;

Host-minted caller-frame routing props; never supplied by the App.

---

FrameBindingMethodTtype alias

Signature

type FrameBindingMethod<Result> = Readonly<{
  decodeArgs: (raw) => readonly unknown[];
  decodeResult: z.ZodType<Result>["parse"];
  requiredOperations: (args) => readonly string[];
}>;

The host’s maintained positional argument/result codecs and operation policy.

Type Parameters

Type Parameter
Result

---

FrameBindingMethodsTtype alias

Signature

type FrameBindingMethods<Result> = Readonly<
  Partial<
    Record<
      AppBackendBindingName,
      Readonly<Record<string, FrameBindingMethod<Result>>>
    >
  >
>;

Method descriptors for the closed App binding vocabulary.

Type Parameters

Type Parameter
Result

---

AppFacetStubTtype alias

Signature

type AppFacetStub = Readonly<{
  fetch: (request) => Promise<Response>;
}>;

Native facet handle; method RPCs are decoded at the invocation boundary.

---

AppInstanceContextTtype alias

Signature

type AppInstanceContext<FacetClass> = Readonly<{
  id: Readonly<{
    name?: string;
  }>;
  storage: WatchdogSqliteOwner;
  facets: Readonly<{
    get: (name, prepare) => AppFacetStub;
    abort: (name, reason) => void;
    delete: (name) => void;
    clone?: (source, destination) => void;
  }>;
}>;

Only the native storage and facet capabilities used by an App Instance. FacetClass is the host’s Durable Object class type (DurableObjectClass on workerd, celld and Cloudflare); Oyster passes it through unopened.

Type Parameters

Type Parameter
FacetClass

---

AppWorkerCodeTtype alias

Signature

type AppWorkerCode = Readonly<{
  compatibilityDate: string;
  mainModule: string;
  modules: Readonly<Record<string, string>>;
  env: object;
  globalOutbound: null;
  limits: GuestLimits;
}>;

The module set the Worker Loader runs for one App backend.

---

AppInstanceLoaderTtype alias

Signature

type AppInstanceLoader<FacetClass> = Readonly<{
  get: (
    id,
    configure,
  ) => Readonly<{
    getDurableObjectClass: (exportName) => FacetClass;
  }>;
}>;

Loader memoization and class lookup; entrypoint access is not required.

Type Parameters

Type Parameter
FacetClass

---

FrameBindingReplyTtype alias

Signature

type FrameBindingReply<Value> =
  | Readonly<{
      kind: "result";
      value: Value;
    }>
  | Readonly<{
      kind: "local_refusal";
      code: AppInstanceErrorCode;
    }>;

Private RPC envelope. Domain results, including domain refusals, stay inside value.

Type Parameters

Type Parameter
Value

---

FrameBindingWireTtype alias

Signature

type FrameBindingWire<Methods> = {
  [Name in keyof Methods]: Methods[Name] extends (
    args: infer Args,
  ) => Promise<infer Value>
    ? (args: Args) => Promise<FrameBindingReply<Value>>
    : never;
};

Native entrypoint methods carry the envelope; guest interfaces are restored by wrap.

Type Parameters

Type Parameter
Methods

---

GuestLimitsTtype alias

Signature

type GuestLimits = Readonly<{
  cpuMs: number;
  subRequests: number;
}>;

Per-invocation budgets enforced by the guest Worker Loader, including facets.

MAX_APP_REPLY_BYTESconstconstant

Signature

const MAX_APP_REPLY_BYTES: number;

Retained shard reply ceiling; replies settle before the frame aborts its facet.

---

backgroundFrameMethodsconstconstant

Signature

const backgroundFrameMethods: object;

Shared replay-only port codecs. Origin input is verified by the host and fails with a typed refusal.

Type Declaration

Name	Type	Description
BACKGROUND	object	-
BACKGROUND.admit	object	-
BACKGROUND.admit.decodeArgs()	(raw) => [unknown] | undefined[]	Malformed arity supplies invalid origin evidence for the host’s typed refusal.
BACKGROUND.admit.decodeResult()	(raw) => | { kind: "admitted"; } | { kind: "refused"; code: "access_changed"; }	Preserve the host’s closed admitted/refused result.
BACKGROUND.admit.requiredOperations()	() => string[]	Only the host-minted replay grant supplies this operation.

---

frameBindingPropsSchemaconstconstant

Signature

const frameBindingPropsSchema: Struct<{
  instanceId: Codec<InstanceId, string, never, never>;
  frameId: String;
  binding: refine<
    | "BACKGROUND"
    | "GIT"
    | "EVENTS"
    | "APPS"
    | "WORKFLOWS"
    | "APP_STORAGE"
    | "MEDIA"
    | "COMPUTER"
    | "INBOX"
    | "AGENTS",
    String
  >;
}>;

The shared RPC boundary decoder for host-minted invocation binding props.

checkBackendConstruction()fnfunction

Signature

function checkBackendConstruction<FacetClass>(
  ctx,
  loader,
  artifact,
  limits,
  priorStateSchema,
): Promise<void>;

The Instance owns the disposable facet and supplies its already-read prior state schema. Only initialized App storage is copied; supervisor state and authority are never copied. A unique Loader ID isolates candidate globals. No invocation frame or guestEnv factory is accepted.

Type Parameters

Type Parameter
FacetClass

Parameters

Parameter	Type
ctx	Pick<AppInstanceContext<FacetClass>, "facets">
loader	| Readonly<{ get: (id, configure) => Readonly<{ getDurableObjectClass: (exportName) => FacetClass; }>; }> | undefined
artifact	Backend
limits	GuestLimits
priorStateSchema	number | null

Returns

Promise<void>

---

edgeVerifiedObjectCache()fnfunction

Signature

function edgeVerifiedObjectCache(cache, origin): VerifiedObjectCache;

The zone’s edge cache as a VerifiedObjectCache: each verified object under a digest-named key on origin that no route serves. A failed write is logged and answers unstored; the next reader verifies from the store again.

Parameters

Parameter	Type
cache	Pick<Cache, "match" | "put">
origin	string

Returns

VerifiedObjectCache

---

r2ArtifactStore()fnfunction

Signature

function r2ArtifactStore(bucket): Readonly<{
  get: (artifactRef) => Promise<Uint8Array<ArrayBufferLike> | null>;
  put: (artifactRef, bytes) => Promise<void>;
}> &
  Readonly<{
    head: (artifactRef) => Promise<Readonly<{
      byteLength: number;
      digest: Sha256Digest | null;
    }> | null>;
  }> &
  Readonly<{
    stream: (
      artifactRef,
      signal?,
    ) => Promise<ReadableStream<Uint8Array<ArrayBufferLike>> | null>;
  }>;

Store Release artifacts without loading the Worker ownership barrel.

Parameters

Parameter	Type
bucket	R2Bucket

Returns

Readonly<{ get: (artifactRef) => Promise<Uint8Array<ArrayBufferLike> | null>; put: (artifactRef, bytes) => Promise<void>; }> & Readonly<{ head: (artifactRef) => Promise< | Readonly<{ byteLength: number; digest: Sha256Digest | null; }> | null>; }> & Readonly<{ stream: (artifactRef, signal?) => Promise<ReadableStream<Uint8Array<ArrayBufferLike>> | null>; }>

---

captureFrameBindingReply()fnfunction

Signature

function captureFrameBindingReply<Value>(
  run,
): Promise<FrameBindingReply<Value>>;

Encode supervisor refusals before native RPC can discard Error properties.

Type Parameters

Type Parameter
Value

Parameters

Parameter	Type
run	() => Promise<Value>

Returns

Promise<FrameBindingReply<Value>>

---

decodeFrameBindingProps()fnfunction

Signature

function decodeFrameBindingProps(raw): FrameBindingProps;

Decode a host routing packet or refuse it before any Instance lookup.

Parameters

Parameter	Type
raw	unknown

Returns

FrameBindingProps

---

frameBindingEntrypoint()fnfunction

Signature

function frameBindingEntrypoint<Env, Result>(
  methods,
  dispatch,
): typeof WorkerEntrypoint;

One native binding factory for both Hub and standalone, preserving RPC values.

Type Parameters

Type Parameter
Env
Result

Parameters

Parameter	Type
methods	FrameBindingMethods<Result>
dispatch	(env, props, method, args) => Promise<FrameBindingReply<unknown>>

Returns

typeof WorkerEntrypoint

---

createCloudflareInvocationGate()fnfunction

Signature

function createCloudflareInvocationGate<Host, FacetClass>(
  ctx,
  close,
): InvocationGate<Host>;

End the native App facet when live authority closes early, before the gate admits again.

Type Parameters

Type Parameter
Host
FacetClass

Parameters

Parameter	Type
ctx	Pick<AppInstanceContext<FacetClass>, "facets">
close	(frame) => Promise<void>

Returns

InvocationGate<Host>

---

createCloudflareAppInstance()fnfunction

Signature

function createCloudflareAppInstance<FacetClass, Host>(
  ctx,
  loader,
  resolve,
  guestEnv,
  bootUi,
  limits?,
  onAbort?,
): AppInstance<Host>;

Run an App Instance inside a SQLite-backed Durable Object on workerd, celld or Cloudflare. Supervisor state lives in the Durable Object’s own SQLite; the App backend runs in a named app facet loaded through the Worker Loader, so its database survives Release replacement and stays separate from the supervisor. Guest code gets only host gatekeeper bindings and no ambient outbound access.

Type Parameters

Type Parameter
FacetClass
Host

Parameters

Parameter	Type	Description
ctx	AppInstanceContext<FacetClass>	The Durable Object’s name, storage and facets.
loader	| Readonly<{ get: (id, configure) => Readonly<{ getDurableObjectClass: (exportName) => FacetClass; }>; }> | undefined	The Worker Loader binding; without it backend execution is unavailable.
resolve	(release, scope) => Effect<Readonly<{ release: Release; digest: Sha256Digest; backend: DurableBackend; }>, Error>	Resolves a Release ID to its verified durable backend.
guestEnv	(frame) => object	Mints loopbacks bound to the captured invocation frame.
bootUi	(release) => Promise< | { kind: "passed"; } | { kind: "failed"; code: "ui_mount_failed"; diagnostics?: { failedPredicate: | "unexpected_candidate_request" | "response_status" | "request_failed" | "page_error" | "candidate_not_mounted"; errorName?: | "TypeError" | "RangeError" | "SyntaxError" | "AbortError" | "TimeoutError" | "Other" | "Error"; finalUrlPath: string; consoleErrors: string[]; pageErrors: string[]; failedRequests: object[]; droppedCount: number; }; } | { kind: "not_checked"; code: | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed" | "ui_check_not_run_on_host"; } | null>	Host-owned UI check, or null when this executor deliberately skips it (for example, after the signed host already checked).
limits?	Partial<Readonly<{ cpuMs: number; subRequests: number; }>>	Guest CPU and subrequest budgets; omitted fields use safe defaults.
onAbort?	(reason) => Promise<void>	Close the host’s existing invocation frame after its state is fenced.

Returns

AppInstance<Host>

References

BackgroundFrameState

Re-exports BackgroundFrameState