# Web-API:t

ECMAScriptin lisäksi Phasis sisältää useita WHATWG / W3C -rajapintapaketteja:

- **Web Platform -paketti** — puhtaita arvotyyppejä, ei I/O:ta: `URL`, `URLSearchParams`, `URLPattern`, `TextEncoder`, `TextDecoder`, `atob`, `btoa`, `structuredClone`, `performance`, `DOMException`.
- **Fetch-paketti** — todellinen HTTP lähteestä JavaScript: `fetch`, `Request`, `Response`, `Headers`, `Body`, `AbortController`, `AbortSignal`, `Blob`, `File`, `FormData`, `EventTarget`, `Event`, täydet WHATWG Streams -rajapinnat (`ReadableStream`, `WritableStream`, `TransformStream`, jonotusstrategiat, BYOB), `CompressionStream` / `DecompressionStream` (gzip / deflate / deflate-raw zlibin kautta; brotli, kun `kjdev/php-ext-brotli` PECL -laajennus on ladattu), `navigator` ja HTML-määrityksen mukainen `self`-yleisalias sekä `reportError`.
- **Crypto** — `crypto.getRandomValues`, `crypto.randomUUID` ja täysi `SubtleCrypto`: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — sekä JWK:n tuonti ja vienti. Pohjautuu `ext-openssl`:een.
- **WebSocket** — konstruktori, RFC 6455-kehyskooderi, tapahtumat. Oletussiirto käyttää `stream_socket_client`:tä; sen voi vaihtaa `Engine::setWebSocketTransport()`-koukulla ReactPHP-ympäristöä / Ratchet-ympäristöä / testeissä käytettäviä valekohteita varten.
- **XMLHttpRequest** — toteutettu fetch-siirron päälle, joten samat käytäntökoukut ja vaihdettava siirto ovat käytettävissä.
- **Tapahtumasilmukka** — `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `queueMicrotask`. Lisäksi `AsyncContext` (Stage 3) välittää arvoja mikrotehtävä- ja ajastinrajojen yli.

Kaikki paketit ovat **oletusarvoisesti käytössä**. Ei lippuja eikä määrityksiä — `typeof fetch` palauttaa `"function"`:n uudessa `new Engine()`-ympäristössä.

## Vaatimustenmukaisuus

Tuotu [Web Platform Tests](https://github.com/web-platform-tests/wpt) -testikorpus (`tests/Wpt/fixtures/`) kattaa seuraavat osa-alueet: `AbortController` / `AbortSignal`, `atob` / `btoa`, `Blob` / `File`, `TextEncoder` / `TextDecoder`, `EventTarget` / `Event`, `FormData`, `Headers`, `performance.now`, Streams-standardin kaikki osat (`Readable`/`Writable`/`Transform` + BYOB + jonotus), `structuredClone`, `URL` / `URLSearchParams`, koko **`crypto` / `SubtleCrypto`**-rajapinta (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — mukaan lukien tuhannet derive-bits-yhdistelmät lähteistä `hkdf` ja `pbkdf2`), **`WebSocket`**-tilakone (konstruktori URL ja alikäytäntöjen validointi, sulkemiskoodien semantiikka, `send()` merkkijonoille / `ArrayBuffer` / tyypitetyille taulukkonäkymille / `Blob`, `binaryType`, `bufferedAmount`, asynkroninen sulkeminen yhdistettäessä, tapahtumankäsittelijöiden null-arvot) sekä laaja osa-alue **`Fetch`**- ja **`XMLHttpRequest`**-rajapinnoista — `responseType`-tilakone, keskeytys- ja lähetyssiirtymät, CORS-sallitut otsakkeet, multipart-`FormData`-lataukset, `XMLHttpRequestUpload` + `ProgressEvent`, `Response`/`Headers`-määrityksen validointi, staattiset `Response.json` / `Response.error`-konstruktorit, Authorization-otsakkeen poistaminen uudelleenohjausketjussa, `URL.createObjectURL`-blob-URL-osoitteet, runko-mixin käyttö (`text` / `blob` / `json` / `formData` / `arrayBuffer`), `Response.clone` ja `structuredClone`-osissa jaetut virrat sekä verkon virheen aiheuttava synkroninen XHR. Jokainen tuotu alitesti läpäistään.

Laajenna korpusta lisäämällä uusi `*.any.js` kohteeseen `tests/Wpt/fixtures/<category>/` — suoritusohjelma löytää sen automaattisesti. XHR-/Fetch-testisarjoja ohjaa `tests/Wpt/fetch-server.php` (yhden tiedoston emulaattori WPT:n `resources/*.py`-käsittelijöille); WebSocket-testisarja käyttää suoritusohjelmaan sisältyvää passiivista siirtoa, joka synnyttää avaus-, kaiku- ja sulkemistapahtumat ja riittää tuoduille testitiedostoille. Suorita korpus itse:

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

## fetch()-esimerkki

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

Se toimii suoraan. Oletusvastaanottaja on PHP `ext-curl`. Rungot virtaavat WHATWG:n `ReadableStream` Phasis-toimitusten kautta, joten myös `for await (const chunk of res.body)` toimii.

## AbortController-esimerkki

```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)` on myös toteutettu (laiska määräajan tarkistus — tarkistus tehdään `aborted`-luvun yhteydessä tapahtuman laukaisemisen sijaan kesken tapahtumasilmukan; toimii fetch-siirroissa, jotka tarkistavat signaalin siirron aikana).

## Upottajan säätimet (PHP-puoli)

Kolme koukkua luokassa `Phasis\Engine` ohjaavat fetch-toimintaa:

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

Jos `setFetchTransport()`-funktiota ei kutsuta, suoritetaan oletusarvoinen `CurlTransport`. Evästepurkki on **valinnainen** — oletuspurkkia ei ole eikä evästeitä tallenneta, ellet anna purkkia käyttöön.

## Streams-esimerkki

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

Koko Streams-määritys: `ReadableStream`, `WritableStream`, `TransformStream`, `ReadableStreamDefaultController`, `ReadableByteStreamController`, `ReadableStreamDefaultReader`, `ReadableStreamBYOBReader`, `ReadableStreamBYOBRequest`, `WritableStreamDefaultController`, `WritableStreamDefaultWriter`, `TransformStreamDefaultController`, `ByteLengthQueuingStrategy`, `CountQueuingStrategy` sekä `pipeTo` / `pipeThrough` / `tee`.

## Tapahtumasilmukka

`setTimeout`, `setInterval`, `clearTimeout`, `clearInterval` ja `queueMicrotask` ovat yleisobjektissa. Mikrotehtävät (Promise-käsittelijät, `queueMicrotask`) suoritetaan loppuun jokaisen makrotehtävän välissä; ajastimet laukeavat määräaikajärjestyksessä ympäristökohtaisen jonon kautta.

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

Toiminta perustuu Phasis-olion `Engine::runEventLoop()`-ominaisuuteen, jonka `eval()` ja `evalAsModule()` kutsuvat automaattisesti synkronisen koodin suorituksen päätyttyä. Oletusarvoisesti silmukka käyttää **virtuaaliaikaa** — `setTimeout(cb, 5000)` ei nukuta PHP, vaan silmukka siirtää kellonsa määräaikaan, jolloin ohjelma valmistuu nopeasti. Reaaliaikaiset upottajat ajavat `tickEventLoop()`-toimintoa itse. Katso [API: Tapahtumasilmukka](https://phasis.inline0.dev/fi/docs/api#event-loop) isäntäpuolen rajapinnasta.

## Mitä ei toimiteta

Nämä vain selaimissa tai tietyissä suoritusympäristömalleissa käytettävät rajapinnat on jätetty tarkoituksella soveltamisalan ulkopuolelle — katso koko keskustelu kohdasta [Tunnetut rajoitukset](https://phasis.inline0.dev/fi/docs/compatibility/limitations):

- `window`, `document`, DOM-puu
- `localStorage`, `sessionStorage`, `IndexedDB`
- `Worker`, `SharedWorker`, `MessageChannel`
- Service Workers, Push API, Notifications, BroadcastChannel

Upottaja voi tarvittaessa toteuttaa useimmat näistä polyfilleillä `$engine->setGlobal()`-rajapinnan kautta.

## WPT-testikorpuksen laajentaminen

`tests/Wpt/upstream/` on kohteen [web-platform-tests/wpt](https://github.com/web-platform-tests/wpt) harva osakloonaus, joka kattaa `fetch/`, `streams/`, `FileAPI/`, `xhr/formdata/`, `dom/abort/` ja `dom/events/`. Laajenna kattavuutta kopioimalla mikä tahansa `*.any.js`-tiedosto kohteesta `upstream/<area>/` kohteeseen `tests/Wpt/fixtures/<category>/`. Suoritusohjelma löytää sen seuraavalla suorituskerralla; virheet kirjataan kohteen `bin/wpt --verbose` kautta.