Japanese source

The original specification and guide are authored in Japanese. The Japanese route contains the same source text; this English route is a reading aid, not a separate translation or an implementation-availability claim.

Version-fixed Form specification

This version-fixed URL serves the Japanese normative source. Read the exact source. Publication does not imply Host or provider support.

ModuleWorker 0.3.0

このFormは、一つのJavaScript module Workerの同一性を表す。コード、変数、Bindingは WorkerVersion 0.5.0に置き、稼働中の版とHTTPトラフィックの配分は WorkerDeployment 0.4.0が決める。Workerを作っただけでは実行コードも公開URLも生じない。HTTP endpoint、cron、queue consumerは別のFormによる添付である。このResourceのCRUD、認可と管理Operationの再試行は Takoform Host API v2に従う。実行時のfetch、queue、Actor、Workflowは別の通信・処理であり、管理用の Idempotency-KeyやOperation IDを引数に取らない。各実行操作の再試行は本Formと参照先FormのInterface章が定める。この版のForm URLは上記の完全な文字列で識別する。本文は仕様であって、いずれかのHostの対応・稼働・公開を主張しない。

入力、状態、操作

specは必須の空オブジェクト {} だけである。既定値も秘密入力もない。未知のキー、 null、配列は拒否する。GETのspecも {} である。observedは未確認なら {}、確認済みなら activeDeploymentUid（有効なDeploymentがなければnull）とready（真偽値）を返す。 ready:trueは、選ばれたDeploymentとその版がこのFormの配信・実行条件を満たし、Hostが新しいイベントを受け付けられる状態を意味する。これは特定のHTTP要求の成功や外部到達性を保証しない。 observedAtとobservedGenerationは共通APIの時点を示す。outputは {} である。

作成は空のWorker同一性を確保する。作成成功はコードの評価やURLの割当を意味しない。
取得は管理記録と最後の観測を返す。GETごとの実行先再照会は要求しない。
更新は同じ空specの全体置換のみ受け付ける。新しいIdempotency-Keyによる同一specのPUTも新しいOperationとgenerationを持つ。実行コードは更新せず、別のWorkerVersionとDeploymentで変える。
削除はそのWorkerへの生きたVersion、Deployment、ActorNamespace、DurableWorkflow、 service Binding、endpoint等の参照がある間、変更前に409 dependency_conflictで拒否する。参照がなくても未完了実行を停止・隔離できない間は完了にしない。成功はこのWorkerの同一性だけを解放する。Binding先、外部サービス、他のWorker、独立した永続データを連鎖削除しない。

実行Interface: module Worker

HostがこのFormを対応表に載せるには、以下のABIとWorkerVersionのasset配信を一体として実装する。コードを持つWorkerVersionではbundleが指す WorkerBundle 0.2.0のmain ES moduleを読み、そのdefault exportはplain object、fetch、scheduled、queueは宣言されたものだけが callableなown propertyでなければならない。Versionが宣言していないhandlerや未exportの handlerを推測して呼ばない。bundleのない静的専用Versionではmoduleを読み込まず、 handlerやnamed class exportを実行しない。import可能なmedia typeは application/javascript+module、text/plain（UTF-8文字列）、 application/octet-stream（ArrayBuffer）、application/wasm（コンパイル済みModule）である。 source mapは補助物でありimport対象にしない。JSON moduleはこのABIにない。

Moduleの解決

WorkerBundleのmanifestはbundle rootからの正規化されたPOSIX相対pathを列挙し、 entrypointはそのうちJavaScript ES module一つを正確に指す。Hostはimport先を manifest内の完全なpath一致だけで探す。./と../で始まるspecifierはimport元の directoryからPOSIX segmentとして解決し、先頭/はbundle rootから解決する。 ..でroot外へ出るもの、空segment、backslash、query ?、fragment #、bare specifier（node:を含む）、HTTP(S)/data URL、import mapは認めない。percent escapeを URLとしてdecodeせず、文字列をそのままpathと比較する。.jsの補完やdirectoryの index推測、大文字小文字の正規化、外部取得はしない。相対specifierを正規化した結果が manifestの一つのimportable entryに一致しない場合はmodule_not_found、auxiliary source mapを指せばunsupported_media_typeである。

static import/export-fromとimport(specifier)は同じ解決規則を使う。staticな不一致・ syntax errorはVersionをReadyにする前に拒否する。dynamic importの値は実行時に検証し、不一致ならそのPromiseを該当エラーでrejectする。循環するES module graphはECMAScriptの live binding/評価順に従い、循環だけを理由に拒否しない。Hostはbundle外のmoduleを暗黙に補わない。text/plainは正しいUTF-8からdecodeした文字列、 application/octet-streamはそのbytesを持つArrayBuffer、application/wasmは compile済みWebAssembly.Moduleを、それぞれdefault exportのみのmoduleとして投影する。 WebAssemblyのinstantiateやimport objectはアプリが選び、Hostは自動実行しない。不正UTF-8、invalid wasm、JavaScriptの構文・評価失敗はReady検証または実行失敗として明示し、別media typeへfallbackしない。

呼出し形はfetch(request: Request, env, ctx): Response | Promise<Response>、 scheduled(event, env, ctx): void | Promise<void>、 queue(batch, env, ctx): void | Promise<void>である。eventはUTCのscheduledTime （Unixミリ秒）と一致した5-field cronを持つ。batchはbatchId（1〜256文字）、 queue名（対象Queue Resourceのnameそのまま。共通Host APIのResource名文法 [A-Za-z0-9][A-Za-z0-9._-]{0,127}に従う1〜128文字）、1〜100件の順序付きmessage列を持つ。各messageには安定した id（1〜256文字）、受理時の非負整数timestampMillis、body bytes、1から始まる整数 attemptsを含む。JavaScriptのbodyはUint8Arrayであり、JSONや文字列へ暗黙変換しない。 queueの明示的なack/retryと未settle時の扱いは AtLeastOnceQueue 0.2.0と QueueConsumer 0.3.0の章に従う。fetchのrequest/response bodyは streamとして扱い、Hostはhandler前に全文を文字列化しない。不正な戻り値または未捕捉例外は機密を含まないHost生成のHTTP 500となる。scheduled/queueの未捕捉例外は失敗として観測し、 HTTP応答へ変換しない。ctx.waitUntil(promise)は同じinvocationの後続作業を登録し、 settlementまではisolateを回収しない。settlement済み応答は書き換えず、拒否は診断へ記録する。失効したctxへの登録はcontext_expiredで失敗する。

queue handlerが受け取るbatchは次のJavaScript形を持つ。bodyは元のmessage bytesを copyしたUint8Arrayであり、metadataは上記の値域に従う。settlementはこのbatchだけで行い、 envのqueue producer Bindingにはこれらのmethodを出さない。

typescript

interface QueueBatch {
  readonly batchId: string;
  readonly queue: string;
  readonly messages: readonly {
    readonly id: string;
    readonly timestampMillis: number;
    readonly body: Uint8Array;
    readonly attempts: number;
  }[];
  acknowledge(messageId: string): Promise<void>;
  retry(messageId: string, delaySeconds?: number): Promise<void>;
  acknowledgeAll(): Promise<void>;
  retryAll(delaySeconds?: number): Promise<void>;
}

messageIdはこのbatch内のID、delaySecondsは省略または0〜43200の整数で、省略時は ConsumerのretryDelaySecondsを使う。成功はdurableなsettlement確定を意味する。失敗はError.nameがunknown_batch、unknown_message、already_settled、 backend_unavailableのいずれかである。acknowledgeAll/retryAllはbatch内の未settled分だけを対象とし、既settledの結果を反転しない。通常returnでは残る未settled分をacknowledgeし、 throw/rejectでは残る未settled分をretryする。重複配送があるためhandlerの外部効果は idempotentに設計する。これは管理ResourceのOperation/Idempotency-Keyとは別である。

実行環境envのown enumerable keyは、Versionに宣言した非秘密vars、Hostが別経路で設定した requiredSensitiveVars、型付きBinding名の和に正確に一致する。重複名はVersion保存前に拒否する。 Host固有の追加globalやBindingはportableな契約にならない。最低限のglobalはRequest、 Response、Headers、URL、URLSearchParams、ReadableStream、TextEncoder、 TextDecoder、AbortController、AbortSignal、crypto、fetch、consoleと標準timerである。外向きfetchはHostが持つ外部通信権限と制限に従い、BindingやForm URLから権限を得ない。

ActorNamespaceとDurableWorkflowのnamed classはdefault handlerとは別exportである。そのconstructor、turn、永続状態、step/replayは各Formの Actor章とWorkflow章で定める。同じWorkerの全weighted Versionは、参照中の全classを提供しなければReadyにならない。単にWorkerを作成しただけでActor/Workflowの能力があると表示してはならない。

Workerへのservice Binding

WorkerVersion 0.5.0のserviceBindings[].resourceがこのWorker UIDを参照すると、呼出し元のenv.NAMEは次を提供する。

typescript

interface WorkerService {
  fetch(request: Request): Promise<Response>;
  fetch(url: string, init?: RequestInit): Promise<Response>;
}

このfetchはHost内の論理的なWorker UIDに届き、相手の現在有効なDeploymentが選ぶVersionのHTTP経路（asset探索または宣言済みfetch handler）を、公開endpointと同じWorkerVersionの配信規則で実行する。public endpoint、DNS名、公開HTTP routeは不要で、 URLのhost名は配送先の選択に使わない。RequestとResponseのbodyは双方streamし、配送前に全文bufferしない。相手handlerの未捕捉例外は相手のHost生成500 ResponseとしてPromiseが resolveする。配送を開始できない場合だけError.name === "backend_unavailable"でrejectする。相手が応答までに完了した副作用はその応答に先行する。service Bindingは相手のenv、 Host credential、認可された利用者identity、他のBindingを呼出し元へ渡さない。 Resource参照があること自体はHost管理操作の認可を与えない。WebSocket upgrade予約は Hostが元client requestに結び付けるため、このservice callで転送・作成できない。

参照と拡張

このFormの入力に参照やBindingはない。WorkerVersionなどはこのResourceのUIDを参照する。 UIDが違う同名Workerは別の同一性であり、参照を名前で再解決しない。将来の入力・runtime ABI・ observedの意味の変更には新しいForm URLを用い、このURLの空specに未知の入力を足さない。

ModuleWorker 0.3.0 ​

入力、状態、操作 ​

実行Interface: module Worker ​

Moduleの解決 ​