# ウェブ API

ECMAScript自体に加えて、PhasisにはWHATWG / W3C APIの複数のレイヤーパックが含まれています:

- **Web Platform Pack** — I/Oを行わない純粋な値型：`URL`、`URLSearchParams`、`URLPattern`、`TextEncoder`、`TextDecoder`、`atob`、`btoa`、`structuredClone`、`performance`、`DOMException`。
- **Fetch Pack** — JavaScript由来の実際のHTTP：`fetch`、`Request`、`Response`、`Headers`、`Body`、`AbortController`、`AbortSignal`、`Blob`、`File`、`FormData`、`EventTarget`、`Event`、WHATWG Streamsの完全な実装（`ReadableStream`、`WritableStream`、`TransformStream`、キューイング戦略、BYOB）、`CompressionStream` / `DecompressionStream`（zlibによるgzip / deflate / deflate-raw。brotliは`kjdev/php-ext-brotli` PECL拡張が読み込まれている場合に利用可能）、`navigator`、およびHTML仕様の`self`グローバルエイリアスと`reportError`。
- **Crypto** — `crypto.getRandomValues`、`crypto.randomUUID`、完全な`SubtleCrypto`：ダイジェスト（SHA-1/256/384/512）、HMAC、AES-GCM/CBC/CTR、RSA-OAEP/PSS/PKCS1、ECDSA（P-256/384/521）、ECDH、HKDF、PBKDF2、およびJWKのインポート/エクスポート。`ext-openssl`を基盤としています。
- **WebSocket** — コンストラクター、RFC 6455フレームコーデック、イベント。デフォルトのトランスポートは`stream_socket_client`を使用し、テストでは`Engine::setWebSocketTransport()`を使ってReactPHP / Ratchet / モックに差し替えられます。
- **XMLHttpRequest** — fetchトランスポート上に構築されているため、同じポリシーフックと差し替え可能なトランスポートを利用できます。
- **イベントループ** — `setTimeout`、`setInterval`、`clearTimeout`、`clearInterval`、`queueMicrotask`。さらに、マイクロタスク / タイマーの境界を越えて値を伝播する`AsyncContext`（Stage 3）も利用できます。

すべてのパックは**デフォルトで有効**です。フラグも設定も不要で、新しい`new Engine()`では`typeof fetch`が`"function"`を返します。

## 適合性

取り込まれた[Web Platform Tests](https://github.com/web-platform-tests/wpt)コーパス（`tests/Wpt/fixtures/`）では、`AbortController` / `AbortSignal`、`atob` / `btoa`、`Blob` / `File`、`TextEncoder` / `TextDecoder`、`EventTarget` / `Event`、`FormData`、`Headers`、`performance.now`、Streams Standardの全機能（`Readable`/`Writable`/`Transform` + BYOB + キューイング）、`structuredClone`、`URL` / `URLSearchParams`、**`crypto` / `SubtleCrypto`** の全機能（digest、HMAC、AES-GCM/CBC/CTR、RSA-OAEP/PSS/PKCS1、ECDSA、ECDH、HKDF、PBKDF2。`hkdf`と`pbkdf2`による数千通りのderive-bits組み合わせを含む）、**`WebSocket`** の状態マシン（コンストラクターURLとサブプロトコルの検証、close-codeの意味論、文字列 / `ArrayBuffer` / 型付き配列ビュー / `Blob` を送信する `send()`、`binaryType`、`bufferedAmount`、接続中の非同期close、イベントハンドラーのnull許容性）、そして **`Fetch`** + **`XMLHttpRequest`** の広範な機能（`responseType`の状態マシン、中断/送信の状態遷移、CORSセーフリスト対象ヘッダー、マルチパート`FormData`アップロード、`XMLHttpRequestUpload` + `ProgressEvent`、`Response`/`Headers`の初期化検証、静的な`Response.json` / `Response.error`コンストラクター、リダイレクトチェーンでのAuthorization削除、`URL.createObjectURL`のblob URL、本文ミックスインの消費（`text` / `blob` / `json` / `formData` / `arrayBuffer`）、`structuredClone`-dのteeストリームを使った`Response.clone`、同期XHRでのネットワークエラーのスロー）を対象としています。取り込まれたサブテストはすべて合格します。

対象をさらに広げるには、`tests/Wpt/fixtures/<category>/`に新しい`*.any.js`を追加してください。次回の実行時にランナーが自動で取り込みます。XHR/Fetchスイートは`tests/Wpt/fetch-server.php`（WPTの`resources/*.py`ハンドラーを単一ファイルでエミュレートするもの）で実行されます。WebSocketスイートでは、インランナーの動作しないトランスポートがopen/echo/closeを合成し、取り込み済みのフィクスチャに十分な機能を提供します。コーパスを自分で実行するには:

```bash
bin/wpt                # everything
bin/wpt --category headers --verbose   # one area, per-subtest output
bin/wpt --json         # machine-readable
```

## fetch()の例

```js
const res = await fetch("https://api.example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "alice" }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const user = await res.json();
```

そのまま使えます。デフォルトのトランスポートはPHP `ext-curl`です。本文は`ReadableStream` Phasisのストリームとして流れ、`for await (const chunk of res.body)`も動作します。

## AbortControllerの例

```js
const ctrl = new AbortController();
setTimeout(() => ctrl.abort(), 5000);
try {
  const res = await fetch(slowUrl, { signal: ctrl.signal });
} catch (e) {
  if (e.name === "AbortError") {
    // request was cancelled
  }
}
```

`AbortSignal.timeout(ms)`も実装されています（遅延期限方式。イベントループの途中でイベントを発火するのではなく、`aborted`の読み取り時に確認します。転送中にシグナルをポーリングするfetchトランスポートで動作します）。

## 埋め込み側の制御（PHP側）

`Phasis\Engine`クラスには、fetchの動作を制御するフックが3つあります:

```php
$engine = new Phasis\Engine();

// 1. Swap the HTTP transport. The callable receives a request descriptor
//    and an optional AbortSignal; returns a response descriptor.
$engine->setFetchTransport(function (array $request, $signal) {
    // ... use Guzzle, Symfony HttpClient, your stub, etc.
    return [
        'status' => 200,
        'statusText' => 'OK',
        'headers' => [['content-type', 'application/json']],
        'body' => '{"data":"value"}',
    ];
});

// 2. Pre-flight policy hook — rewrite, deny, or allow.
$engine->setFetchPolicy(function ($request) {
    $url = $request->get('url')->value;
    if (!str_starts_with($url, 'https://')) {
        throw new \RuntimeException('HTTPS only');
    }
    return null;  // allow as-is; return modified Request to rewrite
});

// 3. Cookie jar. Opt-in. Accepts any object with get(url):string and
//    set(url, header):void methods. JsObject or PHP object both work.
$engine->setCookieJar($myJar);
```

`setFetchTransport()`が呼び出されない場合は、デフォルトの`CurlTransport`が実行されます。Cookie jarは**オプトイン**です。デフォルトでは用意されず、指定しない限りCookieは保存されません。

## Streamsの例

```js
// Producer: ReadableStream that yields numbers 1..5
const rs = new ReadableStream({
  start(controller) {
    for (let i = 1; i <= 5; i++) controller.enqueue(i);
    controller.close();
  },
});

// Consumer: async iteration
for await (const value of rs) {
  console.log(value);  // 1, 2, 3, 4, 5
}

// Pipe through a transform
const ts = new TransformStream({
  transform(chunk, controller) { controller.enqueue(chunk * 2); },
});
const doubled = new ReadableStream({
  start(c) { [1, 2, 3].forEach(n => c.enqueue(n)); c.close(); }
}).pipeThrough(ts);
for await (const v of doubled) console.log(v);  // 2, 4, 6
```

Streams仕様の全機能: `ReadableStream`、`WritableStream`、`TransformStream`、`ReadableStreamDefaultController`、`ReadableByteStreamController`、`ReadableStreamDefaultReader`、`ReadableStreamBYOBReader`、`ReadableStreamBYOBRequest`、`WritableStreamDefaultController`、`WritableStreamDefaultWriter`、`TransformStreamDefaultController`、`ByteLengthQueuingStrategy`、`CountQueuingStrategy`に加え、`pipeTo` / `pipeThrough` / `tee`。

## イベントループ

`setTimeout`、`setInterval`、`clearTimeout`、`clearInterval`、`queueMicrotask`はグローバルオブジェクトにあります。マイクロタスク（Promiseハンドラー、`queueMicrotask`）は、各マクロタスクの間にすべて実行されます。タイマーはレルムごとのキューを使い、期限順に発火します。

```js
console.log('sync');
queueMicrotask(() => console.log('microtask'));
setTimeout(() => console.log('timer'), 0);
// → sync, microtask, timer

const id = setInterval(() => console.log('tick'), 1000);
// ...later
clearInterval(id);

await new Promise(r => setTimeout(r, 50));   // common "delay" pattern works
```

Phasisの`Engine::runEventLoop()`によって制御され、同期コードの実行後に`eval()`と`evalAsModule()`が自動で呼び出されます。デフォルトでは**仮想時間**を使います。`setTimeout(cb, 5000)`はPHPの間スリープせず、プログラムがすぐに完了するよう、ループが期限までクロックを進めます。リアルタイムの埋め込み側では`tickEventLoop()`を独自に動かします。ホスト側の機能については[API: イベントループ](https://phasis.inline0.dev/ja/docs/api#event-loop)を参照してください。

## 提供対象外の機能

ブラウザー専用APIやランタイムモデルAPIは意図的に対象外です。詳しくは[既知の制限](https://phasis.inline0.dev/ja/docs/compatibility/limitations)を参照してください:

- `window`、`document`、DOMツリー
- `localStorage`、`sessionStorage`、`IndexedDB`
- `Worker`、`SharedWorker`、`MessageChannel`
- Service Workers、Push API、Notifications、BroadcastChannel

必要に応じて、これらの大半は埋め込み側で`$engine->setGlobal()`を使ってポリフィルできます。

## WPTコーパスの拡張

`tests/Wpt/upstream/`は[web-platform-tests/wpt](https://github.com/web-platform-tests/wpt)のスパースチェックアウトで、`fetch/`、`streams/`、`FileAPI/`、`xhr/formdata/`、`dom/abort/`、`dom/events/`を対象としています。対象を広げるには、`upstream/<area>/`にある任意の`*.any.js`ファイルを`tests/Wpt/fixtures/<category>/`にコピーしてください。次回の実行時にランナーが取り込み、失敗は`bin/wpt --verbose`経由で記録されます。