# Fetchトランスポート

Phasisのデフォルトの`fetch()`は、PHPの`ext-curl`を通じて動作します。つまり`CURLOPT_FOLLOWLOCATION=false`を使い、仕様に沿ったリダイレクトループはPhasis側で実行され、`CURLOPT_PROGRESSFUNCTION`が`AbortSignal`を確認します。多くの埋め込み用途ではこれで十分です。

それ以外の用途 — プロキシ、カスタムDNS、ホストアプリ既存のHTTPクライアント、ネットワークサンドボックス化、テストでのモック化など — では、トランスポートを**差し替え可能**です。

## インターフェース

```php
public function setFetchTransport(callable $transport): void
```

呼び出し可能オブジェクトには次の値が渡されます。

```php
function (array $request, ?\Phasis\Value\JsObject $signal): array
```

`$request`は連想配列です。

| キー | 型 | 備考 |
|---|---|---|
| `method` | `string` | すでに大文字（`GET`、`POST`、…） |
| `url` | `string` | URLパーサーとリダイレクトチェーンの後に解決された絶対URL |
| `headers` | `list<list<string>>` | `[name, value]`のペア。大文字・小文字は仕様に従って正規化されます。複数値のエントリーは個別のペアになります（Set-Cookieなど）。 |
| `body` | `string` | 生のバイト列。ボディのないメソッドでは空文字列です。 |
| `redirect` | `string` | `"follow"` / `"error"` / `"manual"`（トランスポートで追従しないでください。リダイレクトループはPhasisで実行されます） |
| `timeout` | `int` | ミリ秒単位の実時間予算。`0` = 制限なし。 |
| `credentials` | `string` | `"omit"` / `"same-origin"` / `"include"` — 参考情報です。Cookieは`setCookieJar()`を介して別途設定します。 |

リクエストにシグナルが指定されていない場合、`$signal`は`null`です。指定されている場合は、`aborted`と`reason`を公開する`JsObject`です。長時間の転送中にポーリングしてください。

戻り値の形式：

```php
return [
    'status'     => 200,                          // int
    'statusText' => 'OK',                         // string
    'headers'    => [['content-type', 'text/plain'], ['x-custom', '1']],
    'body'       => '...response bytes...',       // string
];
```

トランスポートが例外をスローすると、Phasisが捕捉して変換します：

- `$e->kind === "aborted"`を持つ`Phasis\BuiltIn\Fetch\TransportException`の場合、`fetch`は`AbortError DOMException`で拒否されます。
- `kind === "timeout"`の場合、`TypeError`がメッセージを引き継ぎます。
- `kind === "network-error"`（デフォルト）の場合、`TypeError`になります。
- その他の場合、例外メッセージを含む`TypeError`になります。

## 使用例

### Guzzle

```php
use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;

$client = new Client(['allow_redirects' => false]);

$engine->setFetchTransport(function (array $req, $signal) use ($client) {
    try {
        $r = $client->request($req['method'], $req['url'], [
            'headers'     => collect($req['headers'])->groupBy(0)->map->pluck(1)->all(),
            'body'        => $req['body'],
            'timeout'     => max(1, $req['timeout'] / 1000.0),
            'http_errors' => false,
        ]);
    } catch (GuzzleException $e) {
        throw new \Phasis\BuiltIn\Fetch\TransportException($e->getMessage(), 'network-error');
    }
    $headers = [];
    foreach ($r->getHeaders() as $name => $values) {
        foreach ($values as $v) {
            $headers[] = [$name, $v];
        }
    }
    return [
        'status'     => $r->getStatusCode(),
        'statusText' => $r->getReasonPhrase(),
        'headers'    => $headers,
        'body'       => (string) $r->getBody(),
    ];
});
```

### Symfony HttpClient

```php
use Symfony\Component\HttpClient\HttpClient;

$client = HttpClient::create(['max_redirects' => 0]);

$engine->setFetchTransport(function (array $req, $signal) use ($client) {
    $headers = [];
    foreach ($req['headers'] as [$name, $value]) {
        $headers[$name][] = $value;
    }
    $r = $client->request($req['method'], $req['url'], [
        'headers'      => $headers,
        'body'         => $req['body'],
        'timeout'      => $req['timeout'] / 1000.0,
        'max_redirects'=> 0,
    ]);
    return [
        'status'     => $r->getStatusCode(),
        'statusText' => '',
        'headers'    => collect($r->getHeaders(false))
            ->flatMap(fn ($values, $name) => array_map(fn ($v) => [$name, $v], $values))
            ->values()->all(),
        'body'       => $r->getContent(false),
    ];
});
```

### すべて拒否

```php
$engine->setFetchTransport(function () {
    throw new \Phasis\BuiltIn\Fetch\TransportException(
        'network access disabled in this sandbox',
        'network-error',
    );
});
```

これにより、すべての`fetch()`呼び出しがTypeErrorで拒否されます。ユーザー提供のJSをサンドボックス化するのに便利です。

### テスト用モック

```php
$canned = [
    'https://api.example.com/users' => ['status' => 200, 'body' => '{"users":[]}'],
    'https://api.example.com/404'   => ['status' => 404, 'body' => 'not found'],
];

$engine->setFetchTransport(function (array $req) use ($canned) {
    $r = $canned[$req['url']] ?? ['status' => 500, 'body' => 'no mock'];
    return [
        'status'     => $r['status'],
        'statusText' => $r['status'] === 200 ? 'OK' : 'ERR',
        'headers'    => [['content-type', 'application/json']],
        'body'       => $r['body'],
    ];
});
```

## ポリシーフック

トランスポートはリクエストを実行し、**ポリシーフック**は実行するかどうかを判断します。HTTPSのみの適用、ヘッダーの挿入、URLの書き換え、許可リスト、テナントごとの認証情報のバインドに使用できます。

```php
public function setFetchPolicy(callable $hook): void
```

フックのシグネチャ：`function (JsObject $request): ?JsObject`。`null`を返すと、そのまま許可されます。Requestを返すと書き換えられます。例外をスローすると、そのエラーでfetchが拒否されます。

```php
$allowedHosts = ['api.example.com', 'cdn.example.com'];

$engine->setFetchPolicy(function ($req) use ($allowedHosts) {
    $url = parse_url($req->get('url')->value);
    if (!in_array($url['host'] ?? '', $allowedHosts, true)) {
        throw new \RuntimeException("host not allowed: " . ($url['host'] ?? ''));
    }
    // Inject internal-only auth header
    $req->get('headers')->call('set', 'X-Internal-Token', $secret);
    return null;
});
```

ポリシーフックはトランスポートの**前に**実行されるため、バグのあるトランスポートや信頼できないトランスポートでも回避できません。

## デフォルト動作のまとめ

| 項目 | デフォルト |
|---|---|
| トランスポート | `CurlTransport`（PHP `ext-curl`） |
| リダイレクト | 仕様に従い最大20回追従します。`redirect: "manual"`の場合は、`type: "opaqueredirect"`を含むリダイレクトResponseを返します。 |
| タイムアウト | 実時間で30秒、接続に10秒 |
| TLS検証 | `CURLOPT_SSL_VERIFYPEER = true`（無効化できません。トランスポートを置き換えて変更できます） |
| User-Agent | 未設定の場合にのみ`Phasis/0.1`を挿入 |
| Cookie | 保存されません。有効にするには`setCookieJar()`を使用してください。 |
| ポリシーフック | なし。明示的に拒否しない限り、すべてのリクエストを許可します。 |
| AbortSignal | curlの進捗コールバックによるポーリングで、処理中も確認されます。 |

## 関連項目

- [APIリファレンス — Fetchフック](https://phasis.inline0.dev/ja/docs/api#fetch-hooks) — 簡潔なシグネチャ一覧。
- [Web API](https://phasis.inline0.dev/ja/docs/compatibility/web-apis) — Fetch Packの全機能。
- [Cookie jar](https://phasis.inline0.dev/ja/docs/interop/cookie-jar) — PHPまたはJSのjarオブジェクトを使って、fetch間でCookieを保持します。