# 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"` — 정보 제공용입니다. 쿠키는 `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` 삽입 |
| 쿠키 | 저장되지 않습니다. 활성화하려면 `setCookieJar()`을 사용하세요. |
| 정책 훅 | 없음. 명시적으로 거부하지 않는 한 모든 요청을 허용합니다. |
| AbortSignal | curl 진행률 콜백 폴링을 통해 전송 중에도 처리됩니다. |

## 관련 항목

- [API 참조 — Fetch 훅](https://phasis.inline0.dev/ko/docs/api#fetch-hooks) — 간단한 시그니처 참조.
- [웹 API](https://phasis.inline0.dev/ko/docs/compatibility/web-apis) — 전체 Fetch Pack 기능.
- [쿠키 저장소](https://phasis.inline0.dev/ko/docs/interop/cookie-jar) — PHP 또는 JS 저장소 객체로 fetch 간 쿠키 유지.