cloudflare

Import

Import

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

Exports

Kind	Export	Description
Cclass	MediaOperationDO	Cloudflare lifecycle and RPC surface around the durable media owner.
Ttype alias	MediaAiPort	Workers AI results vary by model; the provider decodes them at this boundary.
Ttype alias	MediaImagePort	Only image metadata and the bounded resize chain are consumed by Media.
Ttype alias	MediaOperationCloudflareEnvironment	Retention storage and native background provider bindings for the operation DO.
fnfunction	createWorkersAiMediaProvider()	Media’s provider port on the Workers AI binding, with fixed options such as the AI Gateway route.
fnfunction	createImagesReferenceFitter()	Media’s reference preparation on the Images binding: decode the real bytes, scale an oversized image down to MAX_REFERENCE_DIMENSION as PNG, then decode the output so its metadata describes the bytes actually sent.
fnfunction	createImagesViewFitter()	Fit one image for a model to look at on the Images binding: always re-encode it as JPEG (quality 80), scaled down within maxDimension, and decode the output so its metadata describes the bytes actually returned.

MediaOperationDOCclass

Cloudflare lifecycle and RPC surface around the durable media owner.

Extends

• DurableObject<MediaOperationCloudflareEnvironment>

Constructors

Constructor

Signature

new MediaOperationDO(ctx, env): MediaOperationDO;

Parameters

Parameter	Type
ctx	DurableObjectState
env	MediaOperationCloudflareEnvironment

Returns

MediaOperationDO

Overrides

Signature

DurableObject<MediaOperationCloudflareEnvironment>.constructor

Methods

read()

Signature

read(...input):
  | Readonly<{
  operationId: string;
  requestId: string;
  namespace: string;
  owner: string;
  state:   | "admitted"
     | "estimating"
     | "generating"
     | "writing"
     | "charging"
     | "written"
     | "succeeded"
     | "interrupted";
  spentFailure: "output_format_mismatch" | null;
  providerFailure:   | Readonly<{
     stage: "provider" | "normalization";
     safetyRefused: boolean;
     provider?: MediaProviderDiagnostic;
   }>
     | null;
  estimatedCostMilliunits: number | null;
  image:   | {
     bytes: number;
     format: string;
   }
     | null;
  result:   | {
     generationId: string;
     bytes: number;
     format: string;
     costMilliunits: number;
   }
     | null;
  createdAt: number;
  updatedAt: number;
}>
  | null;

Read the safe persisted operation projection, or null before admission or after erasure.

Parameters

Parameter	Type
…input	[]

Returns

| Readonly<{ operationId: string; requestId: string; namespace: string; owner: string; state: | "admitted" | "estimating" | "generating" | "writing" | "charging" | "written" | "succeeded" | "interrupted"; spentFailure: "output_format_mismatch" | null; providerFailure: | Readonly<{ stage: "provider" | "normalization"; safetyRefused: boolean; provider?: MediaProviderDiagnostic; }> | null; estimatedCostMilliunits: number | null; image: | { bytes: number; format: string; } | null; result: | { generationId: string; bytes: number; format: string; costMilliunits: number; } | null; createdAt: number; updatedAt: number; }> | null

preflightErasure()

Signature

preflightErasure(...input): ReturnType<MediaOperationOwner["preflightErasure"]>;

Check host namespace, request identity and inactivity before erasure.

Parameters

Parameter	Type	Description
…input	[string, string]	-

Returns

ReturnType<MediaOperationOwner["preflightErasure"]>

erase()

Signature

erase(...input): Promise<Readonly<{
  clear: boolean;
}>>;

Erase inactive output and local storage, then retain the durable erasure marker.

Parameters

Parameter	Type	Description
…input	[string, string]	-

Returns

Promise<Readonly<{ clear: boolean; }>>

readErasure()

Signature

readErasure(...input): Promise<Readonly<{
  clear: boolean;
}>>;

Read back empty SQL, alarm and retained output with the durable erasure marker.

Parameters

Parameter	Type
…input	[]

Returns

Promise<Readonly<{ clear: boolean; }>>

admit()

Signature

admit(...input): ReturnType<MediaOperationOwner["admit"]>;

Capture immutable host identity and input, replaying exact requests and refusing changed input.

Parameters

Parameter	Type	Description
…input	[string, object, string, MediaOperationRequest]	-

Returns

ReturnType<MediaOperationOwner["admit"]>

claim()

Signature

claim(...input): Promise<Readonly<{
  kind:   | "admitted"
     | "succeeded"
     | "interrupted"
     | "conflict"
     | "replayed"
     | "claimed"
     | "pending";
  operation: MediaOperationProjection;
  leaseId?: string;
}>>;

Claim a safe dispatch or save lease, recovering retained output without redispatching inference.

Parameters

Parameter	Type
…input	[]

Returns

Promise<Readonly<{ kind: | "admitted" | "succeeded" | "interrupted" | "conflict" | "replayed" | "claimed" | "pending"; operation: MediaOperationProjection; leaseId?: string; }>>

recordEstimate()

Signature

recordEstimate(...input): ReturnType<MediaOperationOwner["recordEstimate"]>;

Pin the admitted price and begin the generation lease.

Parameters

Parameter	Type	Description
…input	[string, number]	-

Returns

ReturnType<MediaOperationOwner["recordEstimate"]>

dispatchInBackground()

Signature

dispatchInBackground(...input): Promise<Readonly<{
  operationId: string;
  requestId: string;
  namespace: string;
  owner: string;
  state:   | "admitted"
     | "estimating"
     | "generating"
     | "writing"
     | "charging"
     | "written"
     | "succeeded"
     | "interrupted";
  spentFailure: "output_format_mismatch" | null;
  providerFailure:   | Readonly<{
     stage: "provider" | "normalization";
     safetyRefused: boolean;
     provider?: MediaProviderDiagnostic;
   }>
     | null;
  estimatedCostMilliunits: number | null;
  image:   | {
     bytes: number;
     format: string;
   }
     | null;
  result:   | {
     generationId: string;
     bytes: number;
     format: string;
     costMilliunits: number;
   }
     | null;
  createdAt: number;
  updatedAt: number;
}>>;

Hand a long (video) generation to this owner’s alarm. The caller’s request returns at once; the alarm dispatches the provider exactly once, retains the output, and releases the lease so a later retry saves and charges it.

Parameters

Parameter	Type	Description
…input	[string, readonly Readonly<{ bytes: Uint8Array; format: ImageFormat; width: number; height: number; filename?: string; }>[]]	-

Returns

Promise<Readonly<{ operationId: string; requestId: string; namespace: string; owner: string; state: | "admitted" | "estimating" | "generating" | "writing" | "charging" | "written" | "succeeded" | "interrupted"; spentFailure: "output_format_mismatch" | null; providerFailure: | Readonly<{ stage: "provider" | "normalization"; safetyRefused: boolean; provider?: MediaProviderDiagnostic; }> | null; estimatedCostMilliunits: number | null; image: | { bytes: number; format: string; } | null; result: | { generationId: string; bytes: number; format: string; costMilliunits: number; } | null; createdAt: number; updatedAt: number; }>>

alarm()

Signature

alarm(...input): Promise<void>;

Run a background generation once; a retried alarm never redispatches.

Parameters

Parameter	Type
…input	[]

Returns

Promise<void>

Overrides

Signature

DurableObject.alarm;

interruptGeneration()

Signature

interruptGeneration(...input): ReturnType<MediaOperationOwner["interruptGeneration"]>;

An aborted in-flight provider call is terminal for this request ID.

Parameters

Parameter	Type	Description
…input	[string, Readonly<{ stage: "provider" | "normalization"; safetyRefused: boolean; provider?: MediaProviderDiagnostic; }>]	-

Returns

ReturnType<MediaOperationOwner["interruptGeneration"]>

recordGenerated()

Signature

recordGenerated(...input): Promise<MediaRetentionResult>;

Retain immutable provider output before making the save state visible.

Parameters

Parameter	Type	Description
…input	[string, Uint8Array<ArrayBufferLike>, string]	-

Returns

Promise<MediaRetentionResult>

readGenerated()

Signature

readGenerated(...input): Promise<Uint8Array<ArrayBufferLike>>;

Read exact retained bytes under the current save lease.

Parameters

Parameter	Type	Description
…input	[string]	-

Returns

Promise<Uint8Array<ArrayBufferLike>>

releaseWrite()

Signature

releaseWrite(...input): ReturnType<MediaOperationOwner["releaseWrite"]>;

A fixed-path exact-byte save is safe to retry without repeating generation.

Parameters

Parameter	Type	Description
…input	[string]	-

Returns

ReturnType<MediaOperationOwner["releaseWrite"]>

recordWritten()

Signature

recordWritten(...input): ReturnType<MediaOperationOwner["recordWritten"]>;

Record a destination write and move to idempotent settlement.

Parameters

Parameter	Type	Description
…input	[string, string, object]	-

Returns

ReturnType<MediaOperationOwner["recordWritten"]>

recordWrittenWithoutSettlement()

Signature

recordWrittenWithoutSettlement(...input): ReturnType<MediaOperationOwner["recordWrittenWithoutSettlement"]>;

Persist a completed Computer write without claiming billing success. A lost receipt may replay the exact retained bytes to the captured path; it never repeats provider generation.

Parameters

Parameter	Type	Description
…input	[string, string, object]	-

Returns

ReturnType<MediaOperationOwner["recordWrittenWithoutSettlement"]>

recordSucceeded()

Signature

recordSucceeded(...input): ReturnType<MediaOperationOwner["recordSucceeded"]>;

Commit the settled receipt after verifying the saved output and admitted price.

Parameters

Parameter	Type	Description
…input	[string, object]	-

Returns

ReturnType<MediaOperationOwner["recordSucceeded"]>

releaseEstimate()

Signature

releaseEstimate(...input): ReturnType<MediaOperationOwner["releaseEstimate"]>;

Release preparation or refused admission so the same request can retry.

Parameters

Parameter	Type	Description
…input	[string]	-

Returns

ReturnType<MediaOperationOwner["releaseEstimate"]>

MediaAiPortTtype alias

Signature

type MediaAiPort = object;

Workers AI results vary by model; the provider decodes them at this boundary.

Methods

run()

Signature

run(
   model,
   input,
   options?
): Promise<MediaAiResult>;

Dispatch to the native Workers AI binding.

Parameters

Parameter	Type
model	string
input	Record<string, unknown>
options?	AiOptions

Returns

Promise<MediaAiResult>

---

MediaImagePortTtype alias

Signature

type MediaImagePort = object;

Only image metadata and the bounded resize chain are consumed by Media.

Methods

info()

Signature

info(input): Promise<ImageInfoResponse>;

Read decoded image metadata through the Images binding.

Parameters

Parameter	Type
input	ReadableStream<Uint8Array<ArrayBufferLike>>

Returns

Promise<ImageInfoResponse>

input()

Signature

input(input): object;

Start the native resize and encode chain.

Parameters

Parameter	Type
input	ReadableStream<Uint8Array<ArrayBufferLike>>

Returns

Name	Type	Description
transform()	(options) => object	Apply the native scale-down transform.

---

MediaOperationCloudflareEnvironmentTtype alias

Signature

type MediaOperationCloudflareEnvironment = MediaOperationEnvironment &
  Readonly<{
    AI?: MediaAiPort;
    AI_GATEWAY_ID?: string;
  }>;

Retention storage and native background provider bindings for the operation DO.

createWorkersAiMediaProvider()fnfunction

Signature

function createWorkersAiMediaProvider(ai, options?): MediaProvider;

Media’s provider port on the Workers AI binding, with fixed options such as the AI Gateway route.

Parameters

Parameter	Type
ai	MediaAiPort
options?	AiOptions

Returns

MediaProvider

---

createImagesReferenceFitter()fnfunction

Signature

function createImagesReferenceFitter(images): ReferenceImageFitter;

Media’s reference preparation on the Images binding: decode the real bytes, scale an oversized image down to MAX_REFERENCE_DIMENSION as PNG, then decode the output so its metadata describes the bytes actually sent.

Parameters

Parameter	Type
images	MediaImagePort

Returns

ReferenceImageFitter

---

createImagesViewFitter()fnfunction

Signature

function createImagesViewFitter(images): ImageViewFitter;

Fit one image for a model to look at on the Images binding: always re-encode it as JPEG (quality 80), scaled down within maxDimension, and decode the output so its metadata describes the bytes actually returned.

Parameters

Parameter	Type
images	MediaImagePort

Returns

ImageViewFitter

References

MediaOperationCoordinates

Re-exports MediaOperationCoordinates

---

MediaOperationRequest

Re-exports MediaOperationRequest

---

MediaAiResult

Re-exports MediaAiResult

---

MediaOperationOwner

Re-exports MediaOperationOwner

---

MediaOperationContext

Re-exports MediaOperationContext

---

MediaOperationStorage

Re-exports MediaOperationStorage

---

MediaOperationBucket

Re-exports MediaOperationBucket

---

MediaOperationObject

Re-exports MediaOperationObject