Platform I/O (id_effect_platform)

Workspace crate id_effect_platform mirrors Effect.ts @effect/platform: HTTP, filesystem, and process capabilities as typed services in R, not as ad hoc reqwest / std::fs / tokio::process calls scattered through domain code.

The crate is a single build: HTTP (reqwest + http + bytes), Tokio fs/process, and URI helpers ship together—no Cargo feature matrix to toggle when learning or publishing docs.

Why separate from id_effect?

  • Ports, not drivers — traits like HttpClient, FileSystem, and ProcessRuntime describe what your program needs; production stacks install concrete implementations via layers (same pattern as Layers).
  • Test doubles — TestFileSystem is an in-memory FileSystem for fast, deterministic tests; production uses LiveFileSystem backed by Tokio.
  • Stable HTTP boundary — domain code depends on HttpClientKey + execute, not on reqwest::RequestBuilder. The default implementation is ReqwestHttpClient, swappable in tests.

Modules at a glance

ModuleResponsibility
errorHttpError, FsError, ProcessError, unified PlatformError
httpHttpRequest / HttpResponse, HttpClient, ReqwestHttpClient, layer_http_client, execute
fsFileSystem, live + test impls, FileSystemKey, read helper
processCommandSpec, ProcessRuntime, TokioProcessRuntime, spawn_wait
uriSmall helpers around http::Uri

Wiring pattern

  1. Declare R that includes Service<HttpClientKey, …> (or fs/process keys) via Context / Cons as in A Complete DI Example.
  2. Build a Layer from layer_http_client, layer_file_system, or layer_process_runtime.
  3. Call execute, read, or spawn_wait from handlers; drive with id_effect_tokio::run_async (see Tokio bridge).

Security note (filesystem)

TestFileSystem rejects path keys containing ... Live I/O follows OS semantics—sandbox or canonicalize untrusted paths at a higher layer when exposing file access.

Runnable example

cargo run -p id_effect_platform --example 010_platform_http_get

Spec and parity

  • RFC: docs/effect-ts-parity/rfcs/0001-id-effect-platform.md
  • Crate README: crates/id_effect_platform/README.md

Next

For reqwest-shaped APIs (pools, RequestBuilder, schema-decoded JSON helpers), see HTTP via reqwest and decide when to prefer platform ports vs reqwest adapters.