Module io 

Runtime-agnostic I/O abstractions for networking and caching.

This module contains the engine’s I/O boundary types. The engine itself never performs I/O directly – it defines traits and data structures that the host application implements to bridge to the platform’s networking and file-system stacks.

Module map

Type	Role
HttpClient	Trait the host implements to perform HTTP requests.
HttpRequest	Description of an outgoing request (URL, method, headers).
HttpResponse	A completed response (status, body, headers).
SharedHttpClient	Deduplicating HttpClient wrapper that coalesces concurrent requests for the same URL across subscribers.
FetchPool	Concurrency-limited, priority-ordered download scheduler wrapping an HttpClient.
DiskCache	(feature disk-cache) Flat-file on-disk tile cache ({z}/{x}/{y}.bin).
DiskCacheError	(feature disk-cache) Error type for disk cache operations.

Design principles

1. No async runtime. The engine runs on a synchronous send / poll loop so it can be embedded in Bevy, a winit event loop, a game engine, or a headless CLI tool without pulling in tokio, async-std, or any other executor.

2. No platform dependencies. This module compiles on every rustc target. Platform-specific code lives in the host’s HttpClient implementation.

3. Composable layers.

   Engine (TileManager / HttpTileSource)
      |
      v
   FetchPool  -- concurrency limit + priority queue
      |
      v
   SharedHttpClient (optional) -- cross-source request dedup
      |
      v
   HttpClient  -- host-provided transport (reqwest, web_sys, etc.)
      |
      v
   DiskCache (optional) -- flat-file persistence

   Each layer is independent and optional. HttpTileSource can use a raw HttpClient without FetchPool, and DiskCache can sit in front of or behind the network layer.

Structs

DiskCache

A flat-file on-disk tile cache.

FetchPool

A concurrency-limited, priority-ordered download scheduler.

HttpRequest

Description of an outgoing HTTP request.

HttpResponse

A completed HTTP response.

SharedHttpClient

A deduplicating HTTP client wrapper that can be cheaply cloned.

Enums

DiskCacheError

Errors from disk cache operations.

Traits

HttpClient

Abstract HTTP client.