# Web-API'er

Ud over selve ECMAScript leverer Phasis flere lagdelte pakker med WHATWG / W3C-API'er:

- **Web Platform Pack** — rene værdityper uden I/O: `URL`, `URLSearchParams`, `URLPattern`, `TextEncoder`, `TextDecoder`, `atob`, `btoa`, `structuredClone`, `performance`, `DOMException`.
- **Fetch Pack** — ægte HTTP fra JavaScript: `fetch`, `Request`, `Response`, `Headers`, `Body`, `AbortController`, `AbortSignal`, `Blob`, `File`, `FormData`, `EventTarget`, `Event`, fulde WHATWG Streams (`ReadableStream`, `WritableStream`, `TransformStream`, køstrategier, BYOB), `CompressionStream` / `DecompressionStream` (gzip / deflate / deflate-raw via zlib; brotli når PECL-udvidelsen `kjdev/php-ext-brotli` er indlæst), `navigator` samt den globale alias `self`, der følger HTML-specifikationen, + `reportError`.
- **Crypto** — `crypto.getRandomValues`, `crypto.randomUUID` og fuld `SubtleCrypto`: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — samt JWK-import/eksport. Understøttet af `ext-openssl`.
- **WebSocket** — konstruktør, RFC 6455-frame-codec, hændelser. Standardtransporten bruger `stream_socket_client`; kan udskiftes via `Engine::setWebSocketTransport()` til ReactPHP / Ratchet / mocks i tests.
- **XMLHttpRequest** — bygget oven på fetch-transporten, så de samme politik-hooks og udskiftelige transport gælder.
- **Hændelsesløkke** — `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `queueMicrotask`. Desuden `AsyncContext` (trin 3), der viderefører værdier på tværs af mikrotask- og timergrænser.

Alle pakker er **aktiveret som standard**. Ingen flag, ingen opsætning — `typeof fetch` returnerer `"function"` på en ny `new Engine()`.

## Overensstemmelse

Det importerede korpus af [Web Platform Tests](https://github.com/web-platform-tests/wpt) (`tests/Wpt/fixtures/`) dækker `AbortController` / `AbortSignal`, `atob` / `btoa`, `Blob` / `File`, `TextEncoder` / `TextDecoder`, `EventTarget` / `Event`, `FormData`, `Headers`, `performance.now`, hele Streams-standarden (`Readable`/`Writable`/`Transform` + BYOB + køstyring), `structuredClone`, `URL` / `URLSearchParams`, hele overfladen for **`crypto` / `SubtleCrypto`** (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — inklusive tusindvis af derive-bits-permutationer fra `hkdf` og `pbkdf2`), tilstandsmaskinen for **`WebSocket`** (konstruktørens URL og validering af underprotokol, semantik for lukningskoder, `send()` for strenge / `ArrayBuffer` / typede array-visninger / `Blob`, `binaryType`, `bufferedAmount`, asynkron lukning under tilslutning, nullérbarhed for hændelseshandlere) og et bredt udsnit af **`Fetch`** + **`XMLHttpRequest`** — `responseType`-tilstandsmaskine, overgange for abort/send, headere på tilladelseslisten for CORS, multipart-uploads med `FormData`, `XMLHttpRequestUpload` + `ProgressEvent`, validering af `Response`/`Headers`-init, de statiske konstruktører `Response.json` / `Response.error`, fjernelse af Authorization ved redirect-kæder, `URL.createObjectURL`-blob-URL'er, forbrug af body-mixin (`text` / `blob` / `json` / `formData` / `arrayBuffer`), `Response.clone` med `structuredClone`-opdelte streams og synkron XHR, der kaster netværksfejl. Alle importerede undertests består.

Hvis du vil udvide yderligere, kan du lægge en ny `*.any.js` i `tests/Wpt/fixtures/<category>/` — runneren finder den automatisk. XHR-/Fetch-suiterne styres af `tests/Wpt/fetch-server.php` (en emulator i én fil af WPT `resources/*.py`-handlers); WebSocket-suiten bruger en inaktiv transport i runneren, der simulerer open/echo/close, hvilket er tilstrækkeligt til de importerede fixtures. Kør selv korpusset:

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

## Eksempel på 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();
```

Det virker direkte. Standardtransporten er PHP `ext-curl`. Bodies streames gennem WHATWG `ReadableStream` Phasis leverer, så `for await (const chunk of res.body)` virker også.

## AbortController-eksempel

```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)` er også implementeret (doven deadline — kontrolleres ved `aborted` læsning i stedet for at udløse en hændelse midt i hændelsesløkken; fungerer med fetch-transporter, der afprøver signalet under overførsel).

## Kontroller for indlejrer (PHP-siden)

Tre hooks på klassen `Phasis\Engine` styrer fetch-adfærden:

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

Hvis `setFetchTransport()` ikke kaldes, køres standarden `CurlTransport`. Cookie-glasset er **tilvalgfrit** — intet standardglas, og ingen cookies gemmes, medmindre du angiver et.

## Streams-eksempel

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

Fuld Streams-specifikation: `ReadableStream`, `WritableStream`, `TransformStream`, `ReadableStreamDefaultController`, `ReadableByteStreamController`, `ReadableStreamDefaultReader`, `ReadableStreamBYOBReader`, `ReadableStreamBYOBRequest`, `WritableStreamDefaultController`, `WritableStreamDefaultWriter`, `TransformStreamDefaultController`, `ByteLengthQueuingStrategy`, `CountQueuingStrategy` samt `pipeTo` / `pipeThrough` / `tee`.

## Hændelsesløkke

`setTimeout`, `setInterval`, `clearTimeout`, `clearInterval` og `queueMicrotask` findes på det globale objekt. Mikrotasks (Promise-handlere, `queueMicrotask`) afvikles helt mellem hver makrotask; timere udløses i deadline-rækkefølge via en kø pr. realm.

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

Styres af Phasiss `Engine::runEventLoop()`, som `eval()` og `evalAsModule()` kalder automatisk, når den synkrone kode er færdig. Løkken bruger som standard **virtuel tid** — `setTimeout(cb, 5000)` sover ikke i PHP; løkken flytter sit ur frem til deadline, så programmet afsluttes hurtigt. Indlejrede systemer i realtid styrer selv `tickEventLoop()`. Se [API: Hændelsesløkke](https://phasis.inline0.dev/da/docs/api#event-loop) for værtsidens overflade.

## Hvad der *ikke* leveres

Disse API'er, der kun findes i browsere, eller som hører til runtime-modellen, er bevidst uden for omfanget — se [Kendte begrænsninger](https://phasis.inline0.dev/da/docs/compatibility/limitations) for den fulde gennemgang:

- `window`, `document`, DOM-træet
- `localStorage`, `sessionStorage`, `IndexedDB`
- `Worker`, `SharedWorker`, `MessageChannel`
- Service Workers, Push API, notifikationer, BroadcastChannel

De fleste af disse kan om nødvendigt polyfilles af indlejrer via `$engine->setGlobal()`.

## Udvidelse af WPT-korpusset

`tests/Wpt/upstream/` er en sparse-checkout af [web-platform-tests/wpt](https://github.com/web-platform-tests/wpt), der dækker `fetch/`, `streams/`, `FileAPI/`, `xhr/formdata/`, `dom/abort/`, `dom/events/`. Sådan udvider du dækningen: Kopiér en hvilken som helst `*.any.js`-fil fra `upstream/<area>/` til `tests/Wpt/fixtures/<category>/`. Runneren finder den ved næste kørsel; fejl logges via `bin/wpt --verbose`.