# Žiniatinklio API

Be paties ECMAScript, Phasis pateikia kelis sluoksniuotus WHATWG / W3C API paketus:

- **Žiniatinklio platformos paketas** — grynųjų reikšmių tipai, be įvesties ir išvesties: `URL`, `URLSearchParams`, `URLPattern`, `TextEncoder`, `TextDecoder`, `atob`, `btoa`, `structuredClone`, `performance`, `DOMException`.
- **Fetch paketas** — tikras HTTP iš JavaScript: `fetch`, `Request`, `Response`, `Headers`, `Body`, `AbortController`, `AbortSignal`, `Blob`, `File`, `FormData`, `EventTarget`, `Event`, visas WHATWG srautų API (`ReadableStream`, `WritableStream`, `TransformStream`, eilių strategijos, BYOB), `CompressionStream` / `DecompressionStream` (gzip / deflate / deflate-raw per zlib; brotli, kai įkeliamas `kjdev/php-ext-brotli` PECL plėtinys), `navigator` ir HTML specifikacijos `self` globalus pseudonimas bei `reportError`.
- **Kriptografija** — `crypto.getRandomValues`, `crypto.randomUUID` ir visas `SubtleCrypto`: santrauka (SHA-1/256/384/512), HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA (P-256/384/521), ECDH, HKDF, PBKDF2 ir JWK importavimas / eksportavimas. Pagrįsta `ext-openssl`.
- **WebSocket** — konstruktorius, RFC 6455 kadrų koduotuvas, įvykiai. Pagal numatytąsias nuostatas transportui naudojamas `stream_socket_client`; jį galima pakeisti per `Engine::setWebSocketTransport()`, kad tiktų ReactPHP / Ratchet / netikriesiems objektams testuose.
- **XMLHttpRequest** — sluoksniuota virš Fetch transporto, todėl taikomi tie patys politikos kabliai ir pakeičiamas transportas.
- **Įvykių ciklas** — `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `queueMicrotask`. Be to, `AsyncContext` (3 etapas) perduoda reikšmes per mikroužduočių / laikmačių ribas.

Visi paketai **įjungti pagal numatytąsias nuostatas**. Nereikia nei vėliavėlės, nei sąrankos — `typeof fetch` naujame `new Engine()` pateikia `"function"`.

## Atitiktis

Importuotas [Web Platform Tests](https://github.com/web-platform-tests/wpt) rinkinys (`tests/Wpt/fixtures/`) apima `AbortController` / `AbortSignal`, `atob` / `btoa`, `Blob` / `File`, `TextEncoder` / `TextDecoder`, `EventTarget` / `Event`, `FormData`, `Headers`, `performance.now`, visą Streams Standard (`Readable`/`Writable`/`Transform` + BYOB + eilių valdymą), `structuredClone`, `URL` / `URLSearchParams`, visą **`crypto` / `SubtleCrypto`** sąsają (santrauka, HMAC, AES-GCM/CBC/CTR, RSA-OAEP/PSS/PKCS1, ECDSA, ECDH, HKDF, PBKDF2, įskaitant tūkstančius išvedimo bitų permutacijų iš `hkdf` ir `pbkdf2`), **`WebSocket`** būsenų automatą (konstruktoriaus URL ir subprotokolo tikrinimą, uždarymo kodų semantiką, `send()` eilutėms / `ArrayBuffer` / tipuotų masyvų rodiniams / `Blob`, `binaryType`, `bufferedAmount`, asinchroninį uždarymą prisijungiant, apdorojimo funkcijų null reikšmes) ir plačią **`Fetch`** + **`XMLHttpRequest`** dalį — `responseType` būsenų automatą, atšaukimo / siuntimo perėjimus, CORS leidžiamų antraščių sąrašą, multipart `FormData` įkėlimus, `XMLHttpRequestUpload` + `ProgressEvent`, pradinės konfigūracijos tikrinimą `Response`/`Headers`, statinius konstruktorius `Response.json` / `Response.error`, Authorization antraštės pašalinimą iš peradresavimų sekos, `URL.createObjectURL` blob URL, turinio mišinio skaitymą (`text` / `blob` / `json` / `formData` / `arrayBuffer`), `Response.clone` su `structuredClone` pagrįstais padalytais srautais ir sinchroninį XHR tinklo klaidos išmetimą. Visi importuoti papildomi testai sėkmingai vykdomi.

Norėdami išplėsti aprėptį, įdėkite naują `*.any.js` į `tests/Wpt/fixtures/<category>/` — paleidimo programa jį aptiks automatiškai. XHR/Fetch rinkinius valdo `tests/Wpt/fetch-server.php` (vieno failo WPT `resources/*.py` apdorojimo funkcijų emuliatorius); WebSocket rinkiniui naudojamas neveikiantis transportas paleidimo programoje, imituojantis atidarymą / aido atsakymą / uždarymą ir tinkamas importuotiems bandymų rinkiniams. Paleiskite rinkinį patys:

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

## fetch() pavyzdys

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

Veikia iš karto. Pagal numatytąsias nuostatas transportas yra PHP `ext-curl`. Turiniai srautiniu būdu perduodami per WHATWG `ReadableStream`, kurį teikia Phasis, todėl veikia ir `for await (const chunk of res.body)`.

## AbortController pavyzdys

```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)` taip pat įgyvendintas (atidėtas patikrinimas pagal terminą — tikrinama skaitant `aborted`, o ne siunčiant įvykį įvykių ciklo viduryje; veikia su Fetch transportais, kurie perdavimo metu tikrina signalą).

## Įterpimo aplinkos valdikliai (PHP pusė)

Trys kabliukai klasėje `Phasis\Engine` valdo fetch veikimą:

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

Jei `setFetchTransport()` neiškviečiamas, vykdomas numatytasis `CurlTransport`. Slapukų saugykla pasirenkama — pagal numatytuosius nustatymus ji nenaudojama, slapukai nesaugomi, nebent ją pateikiate.

## Streams pavyzdys

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

Visa Streams specifikacija: `ReadableStream`, `WritableStream`, `TransformStream`, `ReadableStreamDefaultController`, `ReadableByteStreamController`, `ReadableStreamDefaultReader`, `ReadableStreamBYOBReader`, `ReadableStreamBYOBRequest`, `WritableStreamDefaultController`, `WritableStreamDefaultWriter`, `TransformStreamDefaultController`, `ByteLengthQueuingStrategy`, `CountQueuingStrategy`, taip pat `pipeTo` / `pipeThrough` / `tee`.

## Įvykių ciklas

`setTimeout`, `setInterval`, `clearTimeout`, `clearInterval` ir `queueMicrotask` yra globaliame objekte. Mikroužduotys (Promise apdorojimo funkcijos, `queueMicrotask`) visiškai įvykdomos tarp kiekvienų makroužduočių; laikmačiai suveikia terminų tvarka pagal kiekvienos aplinkos eilę.

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

Veikia Phasis `Engine::runEventLoop()`, kurią `eval()` ir `evalAsModule()` iškviečia automatiškai, kai baigiamas sinchroninis kodas. Pagal numatytuosius nustatymus ciklas naudoja **virtualųjį laiką** — `setTimeout(cb, 5000)` nelaukia PHP; ciklas pasuka laikrodį iki termino, todėl programa greitai baigiama. Realaus laiko įterptosios aplinkos pačios valdo `tickEventLoop()`. Žr. [: Įvykių ciklasAPI](https://phasis.inline0.dev/lt/docs/api#event-loop), kur aprašyta pagrindinės aplinkos sąsaja.

## Kas nepateikiama

Šios tik naršyklėse arba vykdymo aplinkos modelyje veikiančios API sąmoningai nepatenka į apimtį — išsamiau žr. [Žinomi apribojimai](https://phasis.inline0.dev/lt/docs/compatibility/limitations):

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

Jei reikia, daugumą jų įterpianti programa gali įgyvendinti naudodama `$engine->setGlobal()`.

## WPT rinkinio plėtra

`tests/Wpt/upstream/` yra dalinė [web-platform-tests/wpt](https://github.com/web-platform-tests/wpt) išskaita, apimanti `fetch/`, `streams/`, `FileAPI/`, `xhr/formdata/`, `dom/abort/`, `dom/events/`. Norėdami išplėsti aprėptį, nukopijuokite bet kurį `*.any.js` failą iš `upstream/<area>/` į `tests/Wpt/fixtures/<category>/`. Vykdyklė jį aptiks kitą kartą paleista; klaidos registruojamos per `bin/wpt --verbose`.