# proxiedFetch

`fetch`-compatible wrapper that routes the request through the Fluxlay host process. Use this for declared `network:` origins that do not return `Access-Control-Allow-Origin` headers (e.g. Google Calendar ICS feeds, public RSS endpoints). The host issues the upstream request as a regular HTTP client, so browser CORS does not apply.

## Import

```tsx
import { proxiedFetch } from "@fluxlay/react";
```

## Signature

```tsx
function proxiedFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
```

The argument shape matches the native `fetch` API. The returned `Response` carries the upstream status, body, and a forwarded subset of upstream headers.

## Usage

```tsx
import { proxiedFetch } from "@fluxlay/react";

async function loadEvents(icsUrl: string) {
  const res = await proxiedFetch(icsUrl);
  if (!res.ok) throw new Error(`ICS ${res.status}`);
  return res.text();
}
```

The target origin must be declared under `network:` in `fluxlay.yaml`:

```yaml
# fluxlay.yaml
network:
  - origin: https://calendar.google.com
    reason: Fetch the user's public ICS calendar feed.
```

## Why this exists

Wallpapers run in an isolated `fluxlay://` origin. Two layers gate outbound requests:

1. **CSP `connect-src`.** The wallpaper webview can only reach origins listed under `network:` in `fluxlay.yaml`.
2. **CORS.** Even when CSP allows the origin, the browser blocks the response unless the upstream returns `Access-Control-Allow-Origin`. Many real-world endpoints (ICS feeds, static file hosts, public RSS) do not.

`proxiedFetch` solves the second problem: it POSTs the request description to the local Fluxlay API (`POST /v1/network-proxy`), which performs the fetch from Rust and returns the body to the wallpaper. CORS does not apply to host-side HTTP, so any URL whose origin is declared in `network:` becomes reachable.

The first gate is unchanged — non-declared origins still return 403 from the proxy, so the security model is identical to direct `fetch`.

## Restrictions vs. native `fetch`

- Only `http:` / `https:` URLs are accepted. `file:` / `data:` / custom schemes are rejected with 400.
- `Cookie` / `Origin` / `Host` / `Referer` request headers are stripped before the upstream call.
- Response body is capped at 10 MiB. Larger bodies return 502 from the proxy.
- Streaming response bodies are not supported. The upstream body is fully buffered before the wallpaper receives the `Response`.
- Forwarded response headers are limited to `Content-Type`, `Cache-Control`, `ETag`, `Last-Modified`. Other headers (including `Set-Cookie`) are dropped.
- Request timeout is 30 seconds; redirects are followed up to 5 hops.

## Notes

- Authorization headers passed via `init.headers` are forwarded as-is. Tokens never touch the wallpaper origin's storage; they simply pass through the host on each call.
- A custom `User-Agent` is set automatically (`Fluxlay-Wallpaper-Proxy/<version>`) when the caller does not provide one. APIs that require a `User-Agent` (e.g. GitHub) work without manual configuration.
- `AbortSignal` from `init.signal` is honoured: aborting cancels the wallpaper-side fetch promise. The host-side request continues to completion in the background.