# Interfejsy API platformy WWW

Poza samym ECMAScript Phasis dostarcza kilka warstwowych pakietów interfejsów API WHATWG / W3C:

- **Pakiet platformy WWW** — czyste typy wartości, bez wejścia/wyjścia: `URL`, `URLSearchParams`, `URLPattern`, `TextEncoder`, `TextDecoder`, `atob`, `btoa`, `structuredClone`, `performance`, `DOMException`.
- **Pakiet Fetch** — rzeczywiste HTTP z JavaScript: `fetch`, `Request`, `Response`, `Headers`, `Body`, `AbortController`, `AbortSignal`, `Blob`, `File`, `FormData`, `EventTarget`, `Event`, pełne WHATWG Streams (`ReadableStream`, `WritableStream`, `TransformStream`, strategie kolejkowania, BYOB), `CompressionStream` / `DecompressionStream` (gzip / deflate / deflate-raw przez zlib; brotli, gdy załadowane jest rozszerzenie PECL `kjdev/php-ext-brotli`), `navigator` oraz globalny alias `self` zgodny ze specyfikacją HTML wraz z `reportError`.
- **Crypto** — `crypto.getRandomValues`, `crypto.randomUUID` oraz pełna obsługa `SubtleCrypto`: skróty (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 — oraz import/eksport JWK. Oparte na `ext-openssl`.
- **WebSocket** — konstruktor, koder ramek RFC 6455, zdarzenia. Domyślny transport używa `stream_socket_client`; można go wymienić przez `Engine::setWebSocketTransport()` na potrzeby ReactPHP / Ratchet / atrap w testach.
- **XMLHttpRequest** — warstwa nad transportem fetch, dzięki czemu obowiązują te same zaczepy zasad i możliwość wymiany transportu.
- **Pętla zdarzeń** — `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `queueMicrotask`. Ponadto `AsyncContext` (etap 3) przenosi wartości przez granice mikrozadań / timerów.

Wszystkie pakiety są **domyślnie włączone**. Bez flag i konfiguracji — świeży obiekt `new Engine()` zwracany przez `typeof fetch` ma dostęp do `"function"`.

## Zgodność

Zaimportowany korpus [Web Platform Tests](https://github.com/web-platform-tests/wpt) (`tests/Wpt/fixtures/`) obejmuje `AbortController` / `AbortSignal`, `atob` / `btoa`, `Blob` / `File`, `TextEncoder` / `TextDecoder`, `EventTarget` / `Event`, `FormData`, `Headers`, `performance.now`, pełny standard Streams (`Readable`/`Writable`/`Transform` + BYOB + kolejkowanie), `structuredClone`, `URL` / `URLSearchParams`, pełny zakres **`crypto` / `SubtleCrypto`** (digest, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2 — w tym tysiące permutacji derive-bits z `hkdf` i `pbkdf2`), maszynę stanów **`WebSocket`** (konstruktor URL i walidację podprotokołu, semantykę kodów zamknięcia, `send()` dla ciągów znaków / `ArrayBuffer` / widoków tablic typowanych / `Blob`, `binaryType`, `bufferedAmount`, asynchroniczne zamykanie podczas łączenia, dopuszczanie wartości null dla obsługi zdarzeń) oraz szeroki zakres **`Fetch` + `XMLHttpRequest`** — maszynę stanów `responseType`, przejścia anulowania/wysyłania, nagłówki dozwolone przez CORS, wysyłanie multipart `FormData`, `XMLHttpRequestUpload` + `ProgressEvent`, walidację init `Response`/`Headers`, statyczne konstruktory `Response.json` / `Response.error`, usuwanie Authorization z łańcucha przekierowań, adresy URL blobów `URL.createObjectURL`, odczytywanie treści przez body-mixin (`text` / `blob` / `json` / `formData` / `arrayBuffer`), strumienie dzielone przez `structuredClone`-d `Response.clone` oraz zgłaszanie błędu sieciowego przez synchroniczne XHR. Wszystkie zaimportowane podtesty przechodzą.

Aby rozszerzyć zestaw, dodaj nowy plik `*.any.js` do `tests/Wpt/fixtures/<category>/` — runner wykryje go automatycznie. Zestawy XHR/Fetch obsługuje `tests/Wpt/fetch-server.php` (jednoplikowy emulator procedur obsługi `resources/*.py` WPT); zestaw WebSocket korzysta z nieaktywnego transportu wbudowanego w runner, który symuluje otwarcie/odpowiedź/zamknięcie i wystarcza do zaimportowanych zestawów testowych. Uruchom korpus samodzielnie:

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

## Przykład 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();
```

Działa od razu. Domyślnym transportem jest PHP `ext-curl`. Treści są przesyłane strumieniowo przez WHATWG `ReadableStream` dostarczane przez Phasis, więc działa też `for await (const chunk of res.body)`.

## Przykład 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)` także jest zaimplementowane (termin sprawdzany leniwie — kontrola przy każdym `aborted` odczycie zamiast wywoływania zdarzenia w środku pętli zdarzeń; działa w przypadku transportów fetch, które podczas przesyłania sprawdzają sygnał).

## Sterowanie przez osadzający program (strona PHP)

Trzy zaczepy w klasie `Phasis\Engine` sterują zachowaniem fetch:

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

Jeśli nie wywołano `setFetchTransport()`, uruchamia się domyślny `CurlTransport`. Słoik na pliki cookie jest **opcjonalny** — domyślnie nie ma słoika ani zapisywanych plików cookie, dopóki go nie dostarczysz.

## Przykład strumieni

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

Pełna specyfikacja Streams: `ReadableStream`, `WritableStream`, `TransformStream`, `ReadableStreamDefaultController`, `ReadableByteStreamController`, `ReadableStreamDefaultReader`, `ReadableStreamBYOBReader`, `ReadableStreamBYOBRequest`, `WritableStreamDefaultController`, `WritableStreamDefaultWriter`, `TransformStreamDefaultController`, `ByteLengthQueuingStrategy`, `CountQueuingStrategy`, a także `pipeTo` / `pipeThrough` / `tee`.

## Pętla zdarzeń

`setTimeout`, `setInterval`, `clearTimeout`, `clearInterval` i `queueMicrotask` są dostępne w obiekcie globalnym. Mikrozadania (obsługi Promise, `queueMicrotask`) są wykonywane do końca między każdym makrozadaniem; timery uruchamiają się według terminów za pośrednictwem kolejki przypisanej do danego 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
```

Sterowanie odbywa się przez `Engine::runEventLoop()` obiektu Phasis; metody `eval()` i `evalAsModule()` wywołują ją automatycznie po zakończeniu kodu synchronicznego. Domyślnie pętla używa **czasu wirtualnego** — `setTimeout(cb, 5000)` nie usypia PHP; pętla przesuwa zegar do wyznaczonego terminu, dzięki czemu program kończy się szybko. Osadzające programy działające w czasie rzeczywistym samodzielnie sterują `tickEventLoop()`. Interfejs po stronie hosta opisano na stronie [API: Pętla zdarzeń](https://phasis.inline0.dev/pl/docs/api#event-loop).

## Czego *nie* ma w pakiecie

Te interfejsy API dostępne tylko w przeglądarce lub związane z modelem środowiska wykonawczego celowo pominięto — pełne omówienie znajdziesz w sekcji [Znane ograniczenia](https://phasis.inline0.dev/pl/docs/compatibility/limitations):

- `window`, `document`, drzewo DOM
- `localStorage`, `sessionStorage`, `IndexedDB`
- `Worker`, `SharedWorker`, `MessageChannel`
- Service Workers, interfejs Push API, powiadomienia, BroadcastChannel

W razie potrzeby większość z nich można wypełnić polyfillami po stronie programu osadzającego za pomocą `$engine->setGlobal()`.

## Rozbudowa korpusu WPT

`tests/Wpt/upstream/` to częściowe pobranie [web-platform-tests/wpt](https://github.com/web-platform-tests/wpt) obejmujące `fetch/`, `streams/`, `FileAPI/`, `xhr/formdata/`, `dom/abort/` i `dom/events/`. Aby rozszerzyć zakres, skopiuj dowolny plik `*.any.js` z `upstream/<area>/` do `tests/Wpt/fixtures/<category>/`. Runner wykryje go przy następnym uruchomieniu; błędy są zapisywane przez `bin/wpt --verbose`.