Skip to main content

rustial_engine/io/
mod.rs

1//! Runtime-agnostic I/O abstractions for networking and caching.
2//!
3//! This module contains the engine's I/O boundary types.  The engine
4//! itself **never performs I/O directly** -- it defines traits and
5//! data structures that the host application implements to bridge to
6//! the platform's networking and file-system stacks.
7//!
8//! # Module map
9//!
10//! | Type | Role |
11//! |------|------|
12//! | [`HttpClient`] | Trait the host implements to perform HTTP requests. |
13//! | [`HttpRequest`] | Description of an outgoing request (URL, method, headers). |
14//! | [`HttpResponse`] | A completed response (status, body, headers). |
15//! | [`SharedHttpClient`] | Deduplicating `HttpClient` wrapper that coalesces concurrent requests for the same URL across subscribers. |
16//! | [`FetchPool`] | Concurrency-limited, priority-ordered download scheduler wrapping an `HttpClient`. |
17//! | [`DiskCache`] | *(feature `disk-cache`)* Flat-file on-disk tile cache (`{z}/{x}/{y}.bin`). |
18//! | [`DiskCacheError`] | *(feature `disk-cache`)* Error type for disk cache operations. |
19//!
20//! # Design principles
21//!
22//! 1. **No async runtime.** The engine runs on a synchronous
23//!    `send` / `poll` loop so it can be embedded in Bevy, a winit
24//!    event loop, a game engine, or a headless CLI tool without
25//!    pulling in tokio, async-std, or any other executor.
26//!
27//! 2. **No platform dependencies.** This module compiles on every
28//!    `rustc` target.  Platform-specific code lives in the host's
29//!    `HttpClient` implementation.
30//!
31//! 3. **Composable layers.**
32//!
33//!    ```text
34//!    Engine (TileManager / HttpTileSource)
35//!       |
36//!       v
37//!    FetchPool  -- concurrency limit + priority queue
38//!       |
39//!       v
40//!    SharedHttpClient (optional) -- cross-source request dedup
41//!       |
42//!       v
43//!    HttpClient  -- host-provided transport (reqwest, web_sys, etc.)
44//!       |
45//!       v
46//!    DiskCache (optional) -- flat-file persistence
47//!    ```
48//!
49//!    Each layer is independent and optional.  `HttpTileSource` can
50//!    use a raw `HttpClient` without `FetchPool`, and `DiskCache`
51//!    can sit in front of or behind the network layer.
52
53// ---------------------------------------------------------------------------
54// Sub-modules
55// ---------------------------------------------------------------------------
56
57#[cfg(all(feature = "disk-cache", not(target_arch = "wasm32")))]
58mod disk_cache;
59mod fetch_pool;
60mod http_client;
61mod shared_http_client;
62
63// ---------------------------------------------------------------------------
64// Public re-exports
65// ---------------------------------------------------------------------------
66
67#[cfg(all(feature = "disk-cache", not(target_arch = "wasm32")))]
68pub use disk_cache::{DiskCache, DiskCacheError};
69pub use fetch_pool::FetchPool;
70pub use http_client::{HttpClient, HttpRequest, HttpResponse};
71pub use shared_http_client::SharedHttpClient;