# Web-APIs

Über ECMAScript hinaus stellt Phasis mehrere aufeinander aufbauende Pakete mit WHATWG- / W3C-APIs bereit:

- **Web Platform Pack** — reine Werttypen, ohne E/A: `URL`, `URLSearchParams`, `URLPattern`, `TextEncoder`, `TextDecoder`, `atob`, `btoa`, `structuredClone`, `performance`, `DOMException`.
- **Fetch Pack** — echte HTTP von JavaScript: `fetch`, `Request`, `Response`, `Headers`, `Body`, `AbortController`, `AbortSignal`, `Blob`, `File`, `FormData`, `EventTarget`, `Event`, vollständige WHATWG Streams (`ReadableStream`, `WritableStream`, `TransformStream`, Queuing-Strategien, BYOB), `CompressionStream` / `DecompressionStream` (gzip / deflate / deflate-raw über zlib; brotli, wenn die `kjdev/php-ext-brotli`-PECL-Erweiterung geladen ist), `navigator` sowie das globale Alias gemäß HTML-Spezifikation `self` + `reportError`.
- **Crypto** — `crypto.getRandomValues`, `crypto.randomUUID` und vollständiges `SubtleCrypto`: Digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — einschließlich JWK-Import/-Export. Nutzt `ext-openssl`.
- **WebSocket** — Konstruktor, RFC-6455-Frame-Codec, Events. Der Standardtransport verwendet `stream_socket_client`; für ReactPHP / Ratchet / Test-Mocks lässt er sich über `Engine::setWebSocketTransport()` austauschen.
- **XMLHttpRequest** — baut auf dem Fetch-Transport auf, daher gelten dieselben Policy-Hooks und der austauschbare Transport.
- **Event loop** — `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `queueMicrotask`. Außerdem `AsyncContext` (Stage 3), das Werte über Microtask- / Timer-Grenzen hinweg weitergibt.

Alle Pakete sind **standardmäßig aktiviert**. Keine Flags, keine Einrichtung — `typeof fetch` gibt `"function"` in einem neuen `new Engine()` zurück.

## Konformität

Der importierte [Web Platform Tests](https://github.com/web-platform-tests/wpt)-Korpus (`tests/Wpt/fixtures/`) deckt `AbortController` / `AbortSignal`, `atob` / `btoa`, `Blob` / `File`, `TextEncoder` / `TextDecoder`, `EventTarget` / `Event`, `FormData`, `Headers`, `performance.now`, den vollständigen Streams Standard (`Readable`/`Writable`/`Transform` + BYOB + Queuing), `structuredClone`, `URL` / `URLSearchParams`, die vollständige **`crypto` / `SubtleCrypto`**-Oberfläche (Digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — einschließlich Tausender Permutationen von „derive bits“ aus `hkdf` und `pbkdf2`), die **`WebSocket`**-Zustandsmaschine (Konstruktor-URL und Subprotocol-Validierung, Close-Code-Semantik, `send()` für Strings / `ArrayBuffer` / Typed-Array-Views / `Blob`, `binaryType`, `bufferedAmount`, asynchrones Schließen während des Verbindungsaufbaus, Null-Zulässigkeit von Event-Handlern) sowie einen breiten Ausschnitt aus **`Fetch`** + **`XMLHttpRequest`** ab — `responseType`-Zustandsmaschine, Übergänge bei Abbruch und Versand, CORS-safelisted Header, Multipart-`FormData`-Uploads, `XMLHttpRequestUpload` + `ProgressEvent`, Validierung der `Response`/`Headers`-Initialisierung, die statischen `Response.json`- / `Response.error`-Konstruktoren, das Entfernen von Authorization bei Redirect-Ketten, `URL.createObjectURL`-Blob-URLs, das Aufbrauchen von Body-Mixins (`text` / `blob` / `json` / `formData` / `arrayBuffer`), `Response.clone` mit `structuredClone`-geteelten Streams und das synchrone Auslösen eines Netzwerkfehlers bei XHR. Alle importierten Untertests bestehen.

Um die Abdeckung zu erweitern, legst du eine neue `*.any.js` in `tests/Wpt/fixtures/<category>/` ab — der Runner erkennt sie automatisch. Die XHR-/Fetch-Suites werden von `tests/Wpt/fetch-server.php` ausgeführt, einem Emulator der WPT-`resources/*.py`-Handler in einer einzelnen Datei; die WebSocket-Suite verwendet einen inaktiven Transport im Runner, der Öffnen, Echo und Schließen simuliert und für die importierten Fixtures ausreicht. Führe den Korpus selbst aus:

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

## fetch()-Beispiel

```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();
```

Das funktioniert sofort. Der Standardtransport ist PHP `ext-curl`. Bodies werden über die WHATWG-`ReadableStream` gestreamt, die Phasis bereitstellt, sodass auch `for await (const chunk of res.body)` funktioniert.

## AbortController-Beispiel

```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)` ist ebenfalls implementiert (mit verzögerter Deadline — die Prüfung erfolgt beim Lesen von `aborted`, statt ein Event mitten im Event-Loop auszulösen; funktioniert bei Fetch-Transporten, die das Signal während der Übertragung abfragen).

## Steuerung durch den Embedder (PHP-Seite)

Drei Hooks in der `Phasis\Engine`-Klasse steuern das Fetch-Verhalten:

```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);
```

Wenn `setFetchTransport()` nicht aufgerufen wird, wird der Standardwert `CurlTransport` verwendet. Der Cookie-Jar ist **optional** — standardmäßig gibt es keinen Jar und es werden keine Cookies gespeichert, sofern du keinen bereitstellst.

## Streams-Beispiel

```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
```

Vollständige Streams-Spezifikation: `ReadableStream`, `WritableStream`, `TransformStream`, `ReadableStreamDefaultController`, `ReadableByteStreamController`, `ReadableStreamDefaultReader`, `ReadableStreamBYOBReader`, `ReadableStreamBYOBRequest`, `WritableStreamDefaultController`, `WritableStreamDefaultWriter`, `TransformStreamDefaultController`, `ByteLengthQueuingStrategy`, `CountQueuingStrategy` sowie `pipeTo` / `pipeThrough` / `tee`.

## Ereignisschleife

`setTimeout`, `setInterval`, `clearTimeout`, `clearInterval` und `queueMicrotask` befinden sich auf dem globalen Objekt. Microtasks (Promise-Handler, `queueMicrotask`) werden zwischen allen Macrotasks vollständig abgearbeitet; Timer werden über eine Realm-Warteschlange nach Deadline ausgelöst.

```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
```

Gesteuert durch Phasiss `Engine::runEventLoop()`, das `eval()` und `evalAsModule()` nach Abschluss des synchronen Codes automatisch aufruft. Standardmäßig läuft der Loop mit **virtueller Zeit** — `setTimeout(cb, 5000)` schläft nicht PHP; der Loop stellt seine Uhr bis zur Deadline vor, damit das Programm schnell fertig wird. Embedder mit Echtzeitsteuerung rufen `tickEventLoop()` selbst auf. Die hostseitige API findest du unter [API: Event loop](https://phasis.inline0.dev/de/docs/api#event-loop).

## Was nicht enthalten ist

Diese reinen Browser- oder Laufzeitmodell-APIs sind bewusst nicht enthalten — die vollständige Erläuterung findest du unter [Bekannte Einschränkungen](https://phasis.inline0.dev/de/docs/compatibility/limitations):

- `window`, `document`, der DOM-Baum
- `localStorage`, `sessionStorage`, `IndexedDB`
- `Worker`, `SharedWorker`, `MessageChannel`
- Service Workers, Push-API, Benachrichtigungen, BroadcastChannel

Die meisten davon lassen sich bei Bedarf vom Embedder über `$engine->setGlobal()` per Polyfill ergänzen.

## WPT-Korpus erweitern

`tests/Wpt/upstream/` ist ein Sparse-Checkout von [web-platform-tests/wpt](https://github.com/web-platform-tests/wpt), das `fetch/`, `streams/`, `FileAPI/`, `xhr/formdata/`, `dom/abort/`, `dom/events/` abdeckt. So erweiterst du die Abdeckung: Kopiere eine beliebige `*.any.js`-Datei aus `upstream/<area>/` nach `tests/Wpt/fixtures/<category>/`. Der Runner erkennt sie beim nächsten Lauf; Fehler werden über `bin/wpt --verbose` protokolliert.