# Webes API-k

Magán az ECMAScripten túl a Phasis a WHATWG / W3C API-k több rétegét is biztosítja:

- **Web Platform Pack** — tiszta értéktípusok, I/O nélkül: `URL`, `URLSearchParams`, `URLPattern`, `TextEncoder`, `TextDecoder`, `atob`, `btoa`, `structuredClone`, `performance`, `DOMException`.
- **Fetch Pack** — valódi HTTP a JavaScript felől: `fetch`, `Request`, `Response`, `Headers`, `Body`, `AbortController`, `AbortSignal`, `Blob`, `File`, `FormData`, `EventTarget`, `Event`, teljes WHATWG Streams (`ReadableStream`, `WritableStream`, `TransformStream`, sorbaállítási stratégiák, BYOB), `CompressionStream` / `DecompressionStream` (gzip / deflate / deflate-raw a zlib segítségével; brotli, ha be van töltve a `kjdev/php-ext-brotli` PECL-bővítmény), `navigator` és a HTML-specifikációjú `self` globális alias + `reportError`.
- **Crypto** — `crypto.getRandomValues`, `crypto.randomUUID` és teljes `SubtleCrypto`: digest (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — valamint JWK-import/export. Alapja a `ext-openssl`.
- **WebSocket** — konstruktor, RFC 6455 keretkódoló/-dekódoló, események. Az alapértelmezett transzport a `stream_socket_client`; a `Engine::setWebSocketTransport()` segítségével lecserélhető ReactPHP / Ratchet / tesztbeli mockok használatára.
- **XMLHttpRequest** — a fetch-transzportra épül, így ugyanazok a házirend-hookok és a cserélhető transzport is érvényesek.
- **Eseményhurok** — `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `queueMicrotask`. Továbbá `AsyncContext` (Stage 3), amely mikrotaszk- és időzítőhatárokon át továbbítja az értékeket.

Minden csomag **alapértelmezés szerint be van kapcsolva**. Nincs kapcsoló vagy beállítás — a `typeof fetch` egy friss `new Engine()` példányon `"function"` értéket ad vissza.

## Megfelelőség

Az importált [Web Platform Tests](https://github.com/web-platform-tests/wpt) tesztkorpusz (`tests/Wpt/fixtures/`) lefedi a következőket: `AbortController` / `AbortSignal`, `atob` / `btoa`, `Blob` / `File`, `TextEncoder` / `TextDecoder`, `EventTarget` / `Event`, `FormData`, `Headers`, `performance.now`, a teljes Streams Standard (`Readable`/`Writable`/`Transform` + BYOB + sorbaállítás), `structuredClone`, `URL` / `URLSearchParams`, a teljes **`crypto` / `SubtleCrypto`** felület (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — több ezer bitszármaztatási kombinációval, többek között a `hkdf` és `pbkdf2` alapján), a **`WebSocket`** állapotgépe (konstruktor-URL és alprotokoll-ellenőrzés, zárókódok szemantikája, `send()` karakterláncokhoz / `ArrayBuffer` / típusos tömbnézetekhez / `Blob`, `binaryType`, `bufferedAmount`, aszinkron lezárás csatlakozás közben, eseménykezelők nullázhatósága), valamint a **`Fetch`** + **`XMLHttpRequest`** széles körű részét — `responseType` állapotgép, megszakítási/küldési átmenetek, CORS által engedélyezett fejlécek, többrészes `FormData`-feltöltések, `XMLHttpRequestUpload` + `ProgressEvent`, `Response`/`Headers` inicializálásának ellenőrzése, statikus `Response.json` / `Response.error` konstruktorok, Authorization fejlécek eltávolítása az átirányítási láncban, `URL.createObjectURL` blob-URL-ek, a törzs-mixin feldolgozása (`text` / `blob` / `json` / `formData` / `arrayBuffer`), `Response.clone` `structuredClone`-d felosztott adatfolyamokkal, valamint szinkron XHR esetén a hálózati hibák kiváltása. Minden importált részteszt sikeres.

A bővítéshez helyezzen el egy új `*.any.js` elemet a `tests/Wpt/fixtures/<category>/` mappában — a futtató automatikusan felismeri. Az XHR/Fetch tesztcsomagokat a `tests/Wpt/fetch-server.php` vezérli (a WPT `resources/*.py` kezelőinek egyfájlos emulátora); a WebSocket tesztcsomagja egy futtatóba épített, nem aktív transzportot használ, amely open/echo/close eseményeket állít elő, és elegendő az importált tesztadatokhoz. Futtassa le Ön is a korpuszt:

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

## fetch()-példa

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

Ez azonnal működik. Az alapértelmezett transzport: PHP `ext-curl`. A törzsek a WHATWG `ReadableStream` adatfolyamon keresztül továbbítódnak, amelyet a Phasis biztosít, így a `for await (const chunk of res.body)` is működik.

## AbortController-példa

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

A `AbortSignal.timeout(ms)` is meg van valósítva (lusta határidő-ellenőrzés — `aborted` olvasáskor ellenőriz, nem vált ki eseményt az eseményhurok közepén; olyan fetch-transzportoknál működik, amelyek az átvitel során lekérdezik a jelet).

## Beágyazó vezérlők (PHP oldala)

A `Phasis\Engine` osztály három hookja szabályozza a fetch működését:

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

Ha nem hívja meg a `setFetchTransport()` függvényt, akkor az alapértelmezett `CurlTransport` fut le. A sütitároló **csak külön bekapcsolva használatos** — alapértelmezés szerint nincs tároló, és nem tárolódnak sütik, hacsak nem ad meg egyet.

## Streams-példa

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

A Streams specifikáció teljes támogatása: `ReadableStream`, `WritableStream`, `TransformStream`, `ReadableStreamDefaultController`, `ReadableByteStreamController`, `ReadableStreamDefaultReader`, `ReadableStreamBYOBReader`, `ReadableStreamBYOBRequest`, `WritableStreamDefaultController`, `WritableStreamDefaultWriter`, `TransformStreamDefaultController`, `ByteLengthQueuingStrategy`, `CountQueuingStrategy`, valamint `pipeTo` / `pipeThrough` / `tee`.

## Eseményhurok

A globális objektumon érhető el: `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval` és `queueMicrotask`. A mikrotaszkok (Promise-kezelők, `queueMicrotask`) minden makrotaszk között teljesen lefutnak; az időzítők a határidők sorrendjében, realmenkénti soron keresztül aktiválódnak.

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

A vezérlést a Phasis `Engine::runEventLoop()` végzi, amely automatikusan meghívja a `eval()` és `evalAsModule()` függvényeket a szinkron kód befejeződése után. Alapértelmezés szerint az eseményhurok **virtuális időt** használ — a `setTimeout(cb, 5000)` nem vár PHP; az óra a határidőig előreugrik, így a program gyorsan befejeződik. A valós idejű beágyazók maguk működtetik a `tickEventLoop()` elemet. A gazdagépi felületről lásd: [API: Eseményhurok](https://phasis.inline0.dev/hu/docs/api#event-loop).

## Mi nincs benne

Ezek a kizárólag böngészőben elérhető vagy futtatókörnyezet-modellhez tartozó API-k szándékosan kívül esnek a hatókörön — a teljes leírást lásd az [Ismert korlátozások](https://phasis.inline0.dev/hu/docs/compatibility/limitations) oldalon:

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

Szükség esetén ezek többsége a beágyazó által, `$engine->setGlobal()` segítségével polifillelhető.

## A WPT tesztkorpusz bővítése

A `tests/Wpt/upstream/` a [web-platform-tests/wpt](https://github.com/web-platform-tests/wpt) ritkított letöltése, amely ezeket fedi le: `fetch/`, `streams/`, `FileAPI/`, `xhr/formdata/`, `dom/abort/`, `dom/events/`. A lefedettség bővítéséhez másolja át a `upstream/<area>/` bármelyik `*.any.js` fájlját a `tests/Wpt/fixtures/<category>/` mappába. A futtató a következő futáskor automatikusan felismeri; a hibákat a `bin/wpt --verbose` naplózza.