FLUXLAY

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

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

Signature

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

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:

# 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.