外部 API の取得 (CORS 回避)

壁紙は fluxlay:// という独立した origin で動作するため、外向きの HTTP リクエストは 2 段階のゲートを通ります:

1. CSP connect-src — fluxlay.yaml の network: で宣言した origin にしか到達できない。
2. CORS — CSP を通過しても、相手サーバが Access-Control-Allow-Origin を返さなければブラウザがレスポンスをブロックする。

普通の REST API は CORS を返してくれるのでそのまま fetch で動きますが、ICS フィードや公開 RSS、静的ファイルホストなど CORS を意識していないエンドポイントだと 2 番目の壁で止まります。その場合は proxiedFetch を使ってください。

通常パターン: 直接 fetch

CORS を返す API なら何もせず標準の fetch で OK です。network: だけ宣言します。

# fluxlay.yaml
network:
  - origin: https://api.github.com
    reason: Open PR と review-requested PR の取得。

const res = await fetch("https://api.github.com/search/issues?q=is:open+is:pr+author:@me", {
  headers: { Authorization: `Bearer ${token}` }
});

CORS で弾かれた時: proxiedFetch

ブラウザに「Origin ... is not allowed by Access-Control-Allow-Origin」と怒られたら、相手サーバが CORS を返していないサインです。fetch を proxiedFetch に置き換えるだけで動きます。

# fluxlay.yaml
network:
  - origin: https://calendar.google.com
    reason: 公開 ICS カレンダーの取得。

import { proxiedFetch } from "@fluxlay/react";
 
const res = await proxiedFetch("https://calendar.google.com/calendar/ical/.../basic.ics");
const ics = await res.text();

proxiedFetch の中身は POST /v1/network-proxy 経由でホスト (Rust) にリクエストを投げるだけです。ホスト側で実際の fetch が行われるためブラウザの CORS は適用されません。target URL の origin が network: に宣言されているかはホストが検証するので、セキュリティモデルは直接 fetch と同じです。

どちらを使うか

迷ったら 直接 fetch を試して、CORS エラーが出たら proxiedFetch に切り替えてください。proxiedFetch はストリーミング非対応・10 MiB 上限などの制約があるので、対応しているなら直接 fetch の方が素直です。

よくあるハマりどころ

• network: 宣言を忘れている → CSP connect-src で弾かれて Failed to fetch になる。エラーメッセージにヒントが無いので、まず yaml を確認する。
• GitHub に User-Agent 必須エラー → proxiedFetch 経由なら Fluxlay-Wallpaper-Proxy/<version> が自動付与されるので追加対応不要。
• Cookie が送られない → proxiedFetch は Cookie ヘッダを意図的に転送しない。認証は Authorization ヘッダで明示的に渡す。

詳細は proxiedFetch リファレンスを参照してください。