fix(vector): stop a failed restore from deleting multi-layer URL layers (#1761)

* fix(vector): stop a failed restore from deleting multi-layer URL layers

A multi-layer container (a KMZ of KML folders, a GeoPackage of tables)
becomes one store layer per source layer, and every one of them keeps the
container's URL. Three problems compounded from there, reported against
NASA FIRMS fire-footprint KMZ feeds in discussion #1757.

Restoring such a project replays each layer independently, and any layer
whose replay failed was then pruned by the closing store sync, which reads
"the control does not have this layer" as "the user removed it". A feed
that was briefly unreachable therefore deleted the layers from the project
outright, and the next save wrote that loss to disk. Restore now records
which replays failed and keeps those layers, and refresh (the button and
the auto-refresh tick) falls through to a new replay path so the next
successful fetch brings the layer back instead of leaving a dead entry.

Each of those sibling layers also downloaded the container separately: on
desktop a six-layer KMZ pulled the same archive six times over on every
project open and every refresh interval, and unzipped and registered it
into DuckDB six times. Add Vector Layer downloads are now collapsed to one
in-flight request per URL, handing every sibling the identical File so the
control's per-source unzip and registration caches collapse with them.

Those six concurrent downloads then ran into the native fetch command's
tile-sized 8s budget, which is what produced the reporter's "Could not read
response body" failures at exactly 8.4s. fetch_url_bytes now accepts a
caller-supplied timeout, clamped so it can only be raised and never
removed, and the vector loader asks for a download-sized budget.

Finally, a store layer that outlives its map layers no longer has its
style synced, which was filling the Diagnostics panel with "Cannot get
style of non-existing layer" the user could do nothing about.

Ref: #1757

* Address CodeRabbit and Claude review feedback

- Do not fall back to a browser fetch when the native command rejected the
  URL by policy. The webview is not subject to the backend SSRF guard, so a
  link-local or metadata URL it refused could still be reached through the
  fallback. New isBlockedUrlError mirrors the guard's messages and re-throws
  those, leaving the fallback for genuine transport failures.
- Give both browser fetch paths the same 180s budget via AbortSignal.timeout.
  Siblings now await one shared download, so a stalled fetch would have held
  all of them pending rather than only itself.
- Correct the timeoutSecs doc: the backend clamps into [8, 600] rather than
  falling back to the default, and move the field onto a fetchUrlBytes-only
  options type since resolve_url_redirect hardcodes its own timeout.
- Drop the embedded-source branch from replayVectorControlLayerById. Refresh
  is gated on isVectorControlRefreshLayer, which requires an HTTP URL, so it
  was unreachable. Restore still preserves such layers.
- Guard replayVectorControlLayerById against concurrent calls for one id. The
  getLayer check cannot hold across the addData await, so two callers would
  both pass it and the second would throw on the duplicate id.

* Address Claude review feedback on the review fixes

- Give each download attempt its own budget instead of sharing one signal.
  The shared deadline started before the native call, so in the exact case
  the fallbacks exist for (a slow origin exhausting the native timeout) they
  were handed an already-aborted signal and rejected instantly. Each attempt
  now gets a fresh AbortSignal.timeout.
- Claim replaying ids during project restore too, not only in
  replayVectorControlLayerById. The control does not register a layer until
  its data has loaded, so an auto-refresh tick landing mid-restore saw the id
  as absent and started a second addData for a layer restore was already
  loading. restoreVectorLayers now tracks its in-flight replays through the
  same registry, which closes the window for all three restore branches.

* Address CodeRabbit review feedback

- Preserve a local-file layer whose replay fails, matching the URL and
  embedded branches. The file had already been read successfully, so the
  failure was in the load rather than a missing source, and reopening the
  project re-reads the same path. Only a failed read still drops the layer,
  which is the case where the file is genuinely gone; replayVectorLayer
  settles its own rejection, so that outer catch never saw replay failures
  anyway and no restructuring was needed.

* Cover the missing-native-layer sync guard with regression tests

Locks in that a store layer whose map layers are absent (a preserved failed
restore) makes no style, visibility, or ordering calls, and that a stale id
alongside a live one skips only the stale one rather than dropping the whole
sync. Both fail without the getLayer guard.

* Address review feedback

- Tighten GeoLibreAppAPI.fetchVectorUrl to Promise<File | null>. The whole
  cache-collapsing benefit depends on returning a File rather than a bare
  Blob, and the type now enforces that instead of only documenting it.
- Fix a test fixture comment that named the wrong layer id.

* Guard restoreVectorLayers against replaying an in-flight layer

Project loading can invoke the restore pass more than once before the
first pass finishes. addData does not expose a layer through getLayer
until its async ingest completes, so getLayer alone let a second pass
replay the same id and race the first when adding its MapLibre source
("Source ... already exists"). Skip ids already claimed in
replayingLayerIds, which also blocks refresh replays for the same
in-flight id.

* Address Claude review feedback

- Close a redirect/DNS SSRF bypass in the native fetch path. The guarded
  redirect policy stopped a blocked hop with `attempt.stop()`, which reqwest
  documents as returning the 30x response as `Ok` — so it reached the frontend
  as "Request failed with status 302", which `isBlockedUrlError` does not
  match, and `fetchVectorUrl` then retried the URL with an unguarded webview
  `fetch` that followed the very redirect the policy refused. A blocked hop now
  fails via `attempt.error(SSRF_BLOCKED_MESSAGE)`, and `request_error_message`
  walks the error source chain so both that and `GuardedDnsResolver`'s
  rejection (which reqwest's connector buries the same way) surface with the
  guard's own wording. The 10-hop cap keeps `stop()`: an over-long chain is not
  an SSRF rejection. Covered by a new `is_ssrf_guard_error` unit test.

- Hoist `failedLayerIds` to module scope beside `replayingLayerIds`. The two
  were mismatched in lifetime: overlapping restore passes divide the layers
  between them via the shared claim, but each pass ran its own closing
  `syncVectorLayersToStore`, and the last to run — which the shared suspension
  counter decides — knew only its own pass's failures and pruned its sibling's,
  reintroducing the exact layer loss this PR fixes. `trackReplay` clears an id
  when a fresh attempt starts so a successful refresh drops a stale mark, and
  the closing sync prunes ids the store no longer knows about.

Author: giswqs

apps/geolibre-desktop/src-tauri/src/lib.rs

@@ -136,6 +136,10 @@ const UV_INSTALL_BASE_URL: &str = "https://astral.sh/uv";
 const REMOTE_TILE_TIMEOUT_SECS: u64 = 8;
 const REMOTE_TILE_CONNECT_TIMEOUT_SECS: u64 = 4;
 const URL_RESOLVE_TIMEOUT_SECS: u64 = 15;
+/// Ceiling for a caller-supplied `fetch_url_bytes` budget. The default suits a
+/// tile; callers that download a whole dataset (Add Vector Layer) ask for more,
+/// but not without bound, so a bad value cannot wedge a request indefinitely.
+const MAX_FETCH_TIMEOUT_SECS: u64 = 600;
 
 #[cfg(all(unix, not(feature = "mas")))]
 const SIGTERM: i32 = 15;
@@ -821,18 +825,59 @@ fn ensure_fetchable_url(url: &str) -> Result<(), String> {
 
 /// A redirect policy that re-applies [`url_is_fetchable`] to every hop, so a
 /// public URL that 3xx-redirects to an internal address is not followed.
+///
+/// A blocked hop fails the request via `attempt.error` rather than
+/// `attempt.stop`: stopping makes reqwest hand the 30x response back as `Ok`,
+/// which reaches the frontend as a bland "Request failed with status 302" that
+/// [`is_ssrf_guard_error`] cannot recognise — and an unrecognised failure is
+/// retried by the webview's unguarded `fetch`, which would follow the very
+/// redirect this policy refused. Failing with [`SSRF_BLOCKED_MESSAGE`] in the
+/// error's source chain keeps that fallback closed. The hop cap still uses
+/// `stop`: an over-long but otherwise allowed chain is not an SSRF rejection
+/// and must not be reported as one.
 fn guarded_redirect_policy() -> reqwest::redirect::Policy {
     reqwest::redirect::Policy::custom(|attempt| {
         if attempt.previous().len() >= 10 {
             return attempt.stop();
         }
         match url_is_fetchable(attempt.url()) {
             Ok(()) => attempt.follow(),
-            Err(_) => attempt.stop(),
+            Err(_) => attempt.error(SSRF_BLOCKED_MESSAGE),
         }
     })
 }
 
+/// True when a reqwest failure was caused by the SSRF guard rather than by the
+/// network.
+///
+/// Neither guard's rejection is visible in the top-level `Display`: the redirect
+/// policy's error is wrapped in reqwest's "error following redirect", and
+/// [`GuardedDnsResolver`]'s is wrapped by the connector. Both keep
+/// [`SSRF_BLOCKED_MESSAGE`] in the source chain, so walk it.
+fn is_ssrf_guard_error(error: &dyn std::error::Error) -> bool {
+    let mut current = Some(error);
+    while let Some(error) = current {
+        if error.to_string().contains(SSRF_BLOCKED_MESSAGE) {
+            return true;
+        }
+        current = error.source();
+    }
+    false
+}
+
+/// Renders a request failure for the frontend, preserving
+/// [`SSRF_BLOCKED_MESSAGE`] verbatim when the guard was what refused it.
+///
+/// `isBlockedUrlError` in `src/lib/vector-url-fetch.ts` matches on that wording
+/// to decide whether retrying in the webview is safe, so a guard rejection that
+/// reaches it as a generic transport error fails *open* into an unguarded fetch.
+fn request_error_message(error: &reqwest::Error) -> String {
+    if is_ssrf_guard_error(error) {
+        return SSRF_BLOCKED_MESSAGE.to_string();
+    }
+    format!("Request failed: {error}")
+}
+
 /// A DNS resolver that drops any address in a blocked range, so reqwest connects
 /// only to IPs that passed [`is_disallowed_ip`].
 ///
@@ -1035,23 +1080,41 @@ fn build_guarded_http_client() -> Result<reqwest::blocking::Client, String> {
         .map_err(|error| format!("Could not create HTTP client: {error}"))
 }
 
+/// Fetches a URL's bytes, bypassing browser CORS.
+///
+/// `timeout_secs` overrides the tile-sized default for callers that download a
+/// whole dataset rather than a tile; it is clamped to
+/// `[REMOTE_TILE_TIMEOUT_SECS, MAX_FETCH_TIMEOUT_SECS]`, so the budget can only
+/// ever be raised and never removed.
 #[tauri::command]
-async fn fetch_url_bytes(url: String) -> Result<Vec<u8>, String> {
-    tauri::async_runtime::spawn_blocking(move || fetch_url_bytes_blocking(url))
+async fn fetch_url_bytes(url: String, timeout_secs: Option<u64>) -> Result<Vec<u8>, String> {
+    tauri::async_runtime::spawn_blocking(move || fetch_url_bytes_blocking(url, timeout_secs))
         .await
         .map_err(|error| format!("Tile fetch task failed: {error}"))?
 }
 
-fn fetch_url_bytes_blocking(url: String) -> Result<Vec<u8>, String> {
+/// Resolves the request budget for a fetch, defaulting to the tile timeout and
+/// clamping a caller-supplied value into `[REMOTE_TILE_TIMEOUT_SECS,
+/// MAX_FETCH_TIMEOUT_SECS]`. A caller can therefore only ever raise the budget,
+/// and never past the ceiling or down to zero (which reqwest reads as "no
+/// timeout" and would let a stalled request hang forever).
+fn resolve_fetch_timeout_secs(timeout_secs: Option<u64>) -> u64 {
+    timeout_secs
+        .unwrap_or(REMOTE_TILE_TIMEOUT_SECS)
+        .clamp(REMOTE_TILE_TIMEOUT_SECS, MAX_FETCH_TIMEOUT_SECS)
+}
+
+fn fetch_url_bytes_blocking(url: String, timeout_secs: Option<u64>) -> Result<Vec<u8>, String> {
     ensure_fetchable_url(&url)?;
 
     let client = guarded_http_client()?;
+    let timeout = resolve_fetch_timeout_secs(timeout_secs);
 
     let response = client
         .get(&url)
-        .timeout(Duration::from_secs(REMOTE_TILE_TIMEOUT_SECS))
+        .timeout(Duration::from_secs(timeout))
         .send()
-        .map_err(|error| format!("Request failed: {error}"))?;
+        .map_err(|error| request_error_message(&error))?;
     let status = response.status();
     if !status.is_success() {
         return Err(format!("Request failed with status {status}"));
@@ -1552,7 +1615,7 @@ fn resolve_url_redirect_blocking(url: String) -> Result<String, String> {
         .header("accept", "application/json, text/plain;q=0.9, */*;q=0.8")
         .timeout(timeout)
         .send()
-        .map_err(|error| format!("Request failed: {error}"))?;
+        .map_err(|error| request_error_message(&error))?;
     if has_xyz_placeholders(response.url().as_str()) {
         return Ok(response.url().to_string());
     }
@@ -4002,7 +4065,8 @@ mod tests {
     use super::{
         client_cert_is_pkcs12, client_cert_password_without_path, ensure_fetchable_url,
         is_allowed_local_vector_path, is_allowed_project_path, is_disallowed_ip,
-        is_safe_absolute_path, path_is_under, tcp_table_port,
+        is_safe_absolute_path, is_ssrf_guard_error, path_is_under, resolve_fetch_timeout_secs,
+        tcp_table_port, MAX_FETCH_TIMEOUT_SECS, REMOTE_TILE_TIMEOUT_SECS, SSRF_BLOCKED_MESSAGE,
     };
     #[cfg(target_os = "linux")]
     use super::{linux_uses_nvidia_renderer, nvidia_is_primary_gpu};
@@ -4258,6 +4322,35 @@ mod tests {
         assert!(ensure_fetchable_url("http://[::1]:8081/data.pmtiles").is_ok());
     }
 
+    #[test]
+    fn ssrf_guard_error_is_detected_through_the_source_chain() {
+        use std::error::Error;
+        use std::fmt;
+
+        #[derive(Debug)]
+        struct Wrapper(Box<dyn Error + Send + Sync>);
+        impl fmt::Display for Wrapper {
+            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+                // Deliberately hides the cause, the way reqwest's "error
+                // following redirect" / connector errors hide theirs.
+                write!(f, "error following redirect for url (https://example.com/)")
+            }
+        }
+        impl Error for Wrapper {
+            fn source(&self) -> Option<&(dyn Error + 'static)> {
+                Some(self.0.as_ref())
+            }
+        }
+
+        let blocked = Wrapper(SSRF_BLOCKED_MESSAGE.into());
+        assert!(!blocked.to_string().contains(SSRF_BLOCKED_MESSAGE));
+        assert!(is_ssrf_guard_error(&blocked));
+
+        // A genuine transport failure must stay fallback-eligible.
+        let transport = Wrapper("connection reset by peer".into());
+        assert!(!is_ssrf_guard_error(&transport));
+    }
+
     #[test]
     fn project_path_guard_allows_projects_and_blocks_secrets() {
         assert!(is_allowed_project_path("/home/u/map.geolibre.json"));
@@ -4661,6 +4754,26 @@ mod tests {
         assert_eq!(tcp_table_port(0x0000_223E), 0x3E22);
     }
 
+    // Add Vector Layer downloads a whole dataset through the same command that
+    // fetches tiles, so it asks for a longer budget. The clamp is what keeps
+    // that override from becoming a way to disable the timeout entirely.
+    #[test]
+    fn clamps_the_fetch_timeout_into_the_allowed_range() {
+        // No override: the tile-sized default.
+        assert_eq!(resolve_fetch_timeout_secs(None), REMOTE_TILE_TIMEOUT_SECS);
+        // A dataset-sized budget is honored as asked.
+        assert_eq!(resolve_fetch_timeout_secs(Some(180)), 180);
+        // Zero would mean "no timeout" to reqwest, so it is raised to the floor
+        // rather than letting a stalled request hang forever.
+        assert_eq!(resolve_fetch_timeout_secs(Some(0)), REMOTE_TILE_TIMEOUT_SECS);
+        // Below the floor is raised; above the ceiling is capped.
+        assert_eq!(resolve_fetch_timeout_secs(Some(1)), REMOTE_TILE_TIMEOUT_SECS);
+        assert_eq!(
+            resolve_fetch_timeout_secs(Some(u64::MAX)),
+            MAX_FETCH_TIMEOUT_SECS
+        );
+    }
+
     // The image-path guard is what keeps the reaper from killing a Jupyter the
     // user installed themselves: only executables under our own runtime
     // directory are ours to terminate.

apps/geolibre-desktop/src/components/panels/LayerPanel.tsx

@@ -55,6 +55,7 @@ import {
   materializeEmbeddableVectorLayers,
   RASTER_SOURCE_KIND,
   reloadVectorControlLayer,
+  replayVectorControlLayerById,
   SKETCHES_SOURCE_KIND,
   TIME_SLIDER_PLUGIN_ID,
   type TimePropertyCandidate,
@@ -1376,10 +1377,16 @@ export function LayerPanel({
           return;
         }
         if (isVectorControlRefreshLayer(layer)) {
-          const info = await reloadVectorControlLayer(layer.id);
+          // A layer whose restore failed stays in the project but never made it
+          // into the control, so reloadLayer cannot find it. Replaying it is
+          // what brings such a layer back once the source is reachable again,
+          // which is why refresh (manual and automatic) tries that second.
+          const info =
+            (await reloadVectorControlLayer(layer.id)) ??
+            (await replayVectorControlLayerById(layer.id));
           if (!info) {
             // The control is unavailable (panel never opened, or torn down
-            // and not yet replayed) or no longer knows this layer id.
+            // and not yet replayed) or the replay above did not succeed.
             // Automatic ticks fire on a timer the user didn't initiate, so
             // skip silently and clear the transient note instead of surfacing
             // an error every interval until the control comes back.

apps/geolibre-desktop/src/hooks/usePlugins.ts

@@ -121,6 +121,11 @@ import { appendDiagnostic } from "../lib/diagnostics";
 import { pickZarrDirectory, zarrDirectoryPickerSupported } from "../lib/zarr-directory-picker";
 import { openExternalLink } from "../lib/open-external";
 import { fetchUrlBytes } from "../lib/native-http";
+import {
+  dedupeVectorUrlFetch,
+  isBlockedUrlError,
+  vectorDownloadFileName,
+} from "../lib/vector-url-fetch";
 import { partitionProjectPluginManifestUrls } from "../lib/plugin-trust";
 import { setTimeSliderOpenedByBinding, shouldCloseTimeSliderDock } from "../lib/time-slider-dock";
 import { createWmsTileUrl, normalizeWmsVersion } from "../components/layout/add-data/helpers";
@@ -1033,35 +1038,57 @@ export function createAppAPI(mapControllerRef?: RefObject<MapController | null>)
     // presence to auto-discover shapefile sidecars instead of forcing the user
     // to select every component, and to capture the file's path for restore.
     pickVectorFilesWithSidecars: isTauriRuntime() ? pickVectorFilesWithSidecars : undefined,
-    fetchVectorUrl: async (url: string) => {
-      if (isTauriRuntime()) {
-        try {
-          const bytes = await fetchUrlBytes(url, { context: "Add Vector Layer" });
-          const array = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
-          return new Blob([array as Uint8Array<ArrayBuffer>]);
-        } catch {
-          // The shared native command has a short, tile-oriented timeout.
-          // Preserve the former browser path for large CORS-enabled datasets.
+    // Shared across the sibling layers of one multi-layer container, which all
+    // carry the container's URL: without this a six-layer KMZ downloaded itself
+    // six times over on every project open and every refresh tick.
+    fetchVectorUrl: (url: string) =>
+      dedupeVectorUrlFetch(url, async () => {
+        const name = vectorDownloadFileName(url);
+        // Each attempt gets its own budget rather than sharing one across all
+        // three. A shared deadline would be spent by the native call in exactly
+        // the case the fallbacks exist for (a slow origin), leaving them to
+        // reject instantly on an already-aborted signal. Sibling layers now
+        // await a single download, so an unbounded fetch would hold all of them
+        // pending, which is why each attempt is bounded at all.
+        const budget = () => AbortSignal.timeout(VECTOR_DOWNLOAD_TIMEOUT_SECS * 1000);
+        if (isTauriRuntime()) {
           try {
-            const response = await fetch(url);
-            if (!response.ok) {
-              throw new Error(`HTTP ${response.status} ${response.statusText}`);
+            const bytes = await fetchUrlBytes(url, {
+              context: "Add Vector Layer",
+              // The default budget on this command is tile-sized (8s). A vector
+              // dataset is not a tile. A few megabytes from a slow origin
+              // routinely needs longer, and timing out here used to drop the
+              // layer entirely, so ask for a download-sized budget instead.
+              timeoutSecs: VECTOR_DOWNLOAD_TIMEOUT_SECS,
+            });
+            const array = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+            return new File([array as Uint8Array<ArrayBuffer>], name);
+          } catch (error) {
+            // The webview is not subject to the backend's SSRF guard, so a URL
+            // the native command refused by policy must not be retried here.
+            if (isBlockedUrlError(error)) throw error;
+            // Keep the browser path as a fallback for CORS-enabled origins the
+            // native command could not reach.
+            try {
+              const response = await fetch(url, { signal: budget() });
+              if (!response.ok) {
+                throw new Error(`HTTP ${response.status} ${response.statusText}`);
+              }
+              return new File([await response.blob()], name);
+            } catch {
+              // GitHub's /raw route rejects browser CORS, so fall through to the
+              // same guarded proxy used by the web build.
             }
-            return response.blob();
-          } catch {
-            // GitHub's /raw route rejects browser CORS, so fall through to the
-            // same guarded proxy used by the web build.
           }
         }
-      }
-      const proxyUrl = githubRawVectorProxyUrl(url);
-      if (!proxyUrl) return null;
-      const response = await fetch(proxyUrl);
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status} ${response.statusText}`);
-      }
-      return response.blob();
-    },
+        const proxyUrl = githubRawVectorProxyUrl(url);
+        if (!proxyUrl) return null;
+        const response = await fetch(proxyUrl, { signal: budget() });
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status} ${response.statusText}`);
+        }
+        return new File([await response.blob()], name);
+      }),
     readLocalVectorFile: readVectorFileWithSidecars,
     exportTextFile: (filename: string, content: string, options?: GeoLibreFileDialogOptions) => {
       const description = options?.description ?? "GeoJSON";
@@ -1333,6 +1360,14 @@ function isTauriRuntime(): boolean {
 
 const GITHUB_RAW_VECTOR_PROXY = "https://tiles.geolibre.app/github-raw";
 
+/**
+ * Budget for a native Add Vector Layer download, in seconds. Deliberately far
+ * above `fetch_url_bytes`'s tile-sized default: this command carries whole
+ * datasets, not 256px tiles, and a timeout here is not a slow tile that resolves
+ * next frame but a layer that fails to restore.
+ */
+const VECTOR_DOWNLOAD_TIMEOUT_SECS = 180;
+
 function githubRawVectorProxyUrl(value: string): string | null {
   let url: URL;
   try {

apps/geolibre-desktop/src/lib/native-http.ts

@@ -22,6 +22,22 @@ interface NativeHttpOptions {
   context?: string;
 }
 
+/**
+ * Options for {@link fetchUrlBytes}. `timeoutSecs` lives here rather than on
+ * {@link NativeHttpOptions} because only the `fetch_url_bytes` command accepts
+ * a timeout argument; `resolve_url_redirect` hardcodes its own, so offering the
+ * field there would invite a caller to set it and silently have no effect.
+ */
+interface FetchUrlBytesOptions extends NativeHttpOptions {
+  /**
+   * Request budget in seconds, overriding the command's tile-sized default.
+   * Set it for calls that carry a whole dataset rather than a tile. The backend
+   * clamps it into `[8, 600]`, so a smaller value is raised to 8 and a larger
+   * one is capped at 600; the timeout can be raised but never removed.
+   */
+  timeoutSecs?: number;
+}
+
 function recordSource(command: NativeHttpCommand, context?: string): string {
   return context ? `native ${command} — ${context}` : `native ${command}`;
 }
@@ -79,11 +95,16 @@ export function nativeHttpFailureRecord(
 async function invokeNativeHttp<T>(
   command: NativeHttpCommand,
   url: string,
-  options?: NativeHttpOptions,
+  options?: FetchUrlBytesOptions,
 ): Promise<T> {
   const startedAt = performance.now();
   try {
-    const result = await invoke<T>(command, { url });
+    // `timeoutSecs` is omitted rather than sent as undefined so the Rust side
+    // sees an absent argument and applies its own default.
+    const result = await invoke<T>(command, {
+      url,
+      ...(options?.timeoutSecs === undefined ? {} : { timeoutSecs: options.timeoutSecs }),
+    });
     appendDiagnostic(
       nativeHttpSuccessRecord(
         command,
@@ -112,12 +133,13 @@ async function invokeNativeHttp<T>(
  * subject to browser CORS), recording the request in the diagnostics log.
  *
  * @param url - The absolute HTTP(S) URL to fetch.
- * @param options - Optional context label for the diagnostics record.
+ * @param options - Optional context label for the diagnostics record, and an
+ *   optional request budget for callers downloading more than a tile.
  * @returns The response body bytes (Tauri may hand back a plain number array).
  */
 export function fetchUrlBytes(
   url: string,
-  options?: NativeHttpOptions,
+  options?: FetchUrlBytesOptions,
 ): Promise<number[] | Uint8Array> {
   return invokeNativeHttp<number[] | Uint8Array>("fetch_url_bytes", url, options);
 }