snailmail 0.1.0__tar.gz

snailmail-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments / uv
+.venv/
+venv/
+env/
+.uv/
+
+# Packaging / build backends
+*.whl
+*.tar.gz
+
+# Testing / coverage / type / lint caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+
+# Tooling caches
+.cache/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+*~
+.DS_Store
+
+# Jupyter
+.ipynb_checkpoints/
+.jupyter/
+*.ipynb_ystore.db
+
+# Local scratch data the server might be pointed at (don't commit big test files)
+/data/
+*.h5ad
+*.tiff
+*.zarr/

snailmail-0.1.0/AGENTS.md

@@ -0,0 +1,122 @@
+# AGENTS.md
+
+Onboarding for an agent or contributor picking up snailmail. Read the
+[README](README.md) first for what it is and why; this file is the "how it works,
+how to work on it" layer.
+
+## Goal
+
+A zero-setup, in-process harness to benchmark range-based readers under realistic
+network conditions, and to answer concurrency questions honestly. The product is the
+measurement: GET count, bytes, and **peak concurrency** (`max_in_flight`) — that
+last one is the whole point. Wall-clock can't distinguish "fast because cached" from
+"fast because concurrent"; `max_in_flight` can.
+
+## Layout
+
+```
+src/snailmail/
+  __init__.py     # public exports
+  latency.py      # LatencyDist + LogNormal / Normal / Exponential / Fixed
+  bandwidth.py    # AsyncSharedPipe
+  server.py       # LatencyRangeServer (the threaded aiohttp wrapper)
+  cli.py          # the `snailmail` CLI (main, --dist arg wiring)
+tests/
+  test_server.py     # range correctness, latency, bandwidth, concurrency, counters
+  test_directory.py  # directory serving, misses, traversal, stats, set_latency, --version
+  test_latency.py    # distributions + CLI --dist wiring
+```
+
+One file per concern; keep each small and single-purpose. The split is to stay
+easily editable, not an invitation to grow a framework — the whole thing should stay
+readable in a sitting.
+
+## Develop
+
+```bash
+uv sync                       # aiohttp, numpy + dev: pytest, ruff, mypy
+uv run pytest                 # all green
+uv run ruff check src tests
+uv run mypy                   # type gate (config in pyproject)
+```
+
+Pre-commit hooks (ruff lint + ruff format + mypy + file hygiene) run via
+[prek](https://github.com/j178/prek): `prek install` once, then they fire on commit;
+`prek run --all-files` to run them by hand.
+
+## Conventions
+
+- **Commits:** do not co-sign — no `Co-Authored-By` / tool trailers.
+- **Comments:** tight and useful — explain *why*, not *what*. No session- or
+  conversation-specific notes ("as we discussed", change logs, dates); a comment
+  must make sense to someone reading the file cold a year from now.
+
+## Design decisions (read before changing things)
+
+- **aiohttp `web.FileResponse` owns all HTTP correctness** — 206, `Content-Range`,
+  suffix ranges, 416, conditional requests — and streams from disk. Do **not**
+  reimplement range handling; that was the whole reason to rewrite off the original
+  hand-rolled `BaseHTTPRequestHandler`. The file is never read into RAM, so multi-GB
+  files work. Our consumers issue single-range GETs only, so multi-range responses
+  are out of scope.
+
+- **Serves a directory, always.** The root is served with aiohttp's `add_static`
+  (range-correct *and* traversal-safe — don't hand-roll path joining). One object per
+  file is the shape that matters for the Icechunk/object-store use case; to benchmark
+  a single file, point at the directory containing it. There is deliberately no
+  single-file mode — it added a `url`-vs-`base` duality and a custom handler for no
+  real benefit. `base` is the root; `url(key)` builds a key URL. `FileResponse` defers
+  its 404 to send time, so **misses are detected up front** via `_target_size()`
+  (which also yields the size for byte accounting), not by inspecting the response
+  status — a miss is a read whose path resolves to no file under the root, counted in
+  `n_misses`.
+- **Latency = a pluggable `LatencyDist`** (`latency.py`): `LogNormal`, `Normal`,
+  `Exponential`, `Fixed`. **Lognormal is the recommended default and the one to reach
+  for** — object-store GET RTT is a unimodal hump with a long right tail, which it
+  fits; it's parameterised by the PDF **mode** (`mode_ms`) and shape `sigma`. The
+  others exist for comparison, not because they model object stores well — notably
+  `Exponential`'s peak sits at the floor, which is *wrong* for GET RTT; offer it, but
+  don't recommend it. Every dist **pre-generates its pool once with numpy and serves
+  it round-robin** — O(1) in the hot path, no per-request RNG, exactly reproducible
+  per seed. The pool index is unsynchronised on purpose: all requests run on one
+  event-loop thread, so it's safe. If you ever move to multiple loops/threads, that
+  assumption breaks. Negative draws (Normal's left tail) are truncated at 0.
+- **Bandwidth = one shared FIFO pipe** (`AsyncSharedPipe`): per-request RTTs stay
+  parallel; response *bytes* serialize through the pipe, so egress is capped and
+  over-read costs real time.
+- **Async, in a background thread.** One event loop means many requests' latency
+  sleeps overlap with no thread-pool ceiling — exactly what makes the
+  peak-concurrency measurement clean. `start()` spawns the loop thread; `stop()`
+  stops it. Don't reintroduce thread-per-request.
+- **Counters under a lock.** `stats()` is a post-hoc, atomic snapshot (counts, total
+  bytes, 404 misses, peak `max_in_flight`, and per-method / per-path breakdowns) that
+  persists until `reset_counts()`. For accounting only, `_range_bytes` reuses aiohttp's
+  own `request.http_range` parser (not a hand-rolled one) so the counted bytes match
+  what the static handler serves; serving correctness still comes entirely from
+  aiohttp. See `_target_size`'s docstring for why size/miss are resolved up front
+  rather than read back from aiohttp.
+
+- **Compose aiohttp, don't subclass it.** aiohttp has no server base class meant for
+  extension (its docs steer you to middlewares/signals over subclassing
+  `web.Application`). `LatencyRangeServer` is a threaded lifecycle + counters facade
+  around `web.Application` + `AppRunner`/`TCPSite`; keep it that way. The one private
+  touch is reading the bound ephemeral port off `site._server.sockets` — aiohttp
+  exposes no public API for it.
+- **Injected latency is added on top** of the real (sub-ms, local-SSD) range read, so
+  the modelled RTT stays dominated by the knob. Revisit for spinning disks or very
+  large single ranges.
+
+## Non-goals
+
+- **Transport-accurate shaping.** snailmail models latency and bandwidth at the
+  application layer (a `sleep()` plus a byte pipe), not on real packets. For
+  kernel-level RTT/bandwidth use `tc netem` (Linux) or `dnctl`/`pfctl` (macOS) in
+  front of any file server. Don't grow snailmail toward packet shaping.
+- **A general-purpose web server.** It serves a directory on loopback for benchmarks.
+
+## Working notes
+
+Current status, open tasks, and origin/context live in
+[docs/NOTES.md](docs/NOTES.md) — the mutable worklog agents update. Keep *this* file
+durable (purpose, design, conventions, non-goals); put anything time-specific in the
+worklog.

snailmail-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-18
+
+Initial public release.
+
+### Added
+- `LatencyRangeServer`: a loopback HTTP server that serves a **directory tree** over
+  HTTP Range with injectable latency and bandwidth limits, for benchmarking range /
+  object-store / virtual-chunk reads. One object per file (the shape of an Icechunk
+  virtual dataset), range- and traversal-safe; `base` is the root, `url(key)` builds a
+  key URL, and `files()` lists the served keys.
+- Pluggable per-request latency distributions: `LogNormal` (the recommended default),
+  `Normal`, `Exponential`, and `Fixed`, each with explicit, distribution-specific
+  parameters. Draws are pre-generated and served round-robin (O(1), reproducible per
+  seed).
+- Shared FIFO bandwidth pipe (`AsyncSharedPipe`) so response bytes serialize through a
+  capped egress while round-trips stay parallel.
+- Request accounting via `stats()`: GET/request counts, 404 misses (`n_misses`), total
+  bytes, peak concurrency (`max_in_flight`), and per-method / per-path breakdowns;
+  persists until `reset_counts()`.
+- `snailmail` CLI with a `--dist` selector and explicit per-distribution flags, a
+  `--json` machine-readable address line (flushed before serving), and `--version`.
+
+[0.1.0]: https://github.com/ianhi/snailmail/releases/tag/v0.1.0

snailmail-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Hunt-Isaak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

snailmail-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: snailmail
+Version: 0.1.0
+Summary: A local HTTP server that serves a directory over Range with injectable latency and bandwidth limits, for benchmarking range / object-store / virtual-chunk reads under realistic network conditions.
+Project-URL: Homepage, https://github.com/ianhi/snailmail
+Project-URL: Repository, https://github.com/ianhi/snailmail
+Project-URL: Issues, https://github.com/ianhi/snailmail/issues
+Project-URL: Changelog, https://github.com/ianhi/snailmail/blob/main/CHANGELOG.md
+Author-email: Ian Hunt-Isaak <ian@earthmover.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bandwidth,benchmark,http,icechunk,latency,object-store,range-requests,zarr
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: System :: Benchmark
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: numpy>=1.24
+Description-Content-Type: text/markdown
+
+# snailmail
+
+A local HTTP server that serves a directory over HTTP Range, injecting per-request
+latency and a bandwidth cap, and counts GETs and peak concurrency.
+
+Use it to benchmark range-based readers — object stores, Zarr/Icechunk virtual
+chunks, tiled image formats — under realistic network conditions, on your laptop,
+with no cloud and no root.
+
+## Why you'd want it
+
+Local disk hides the cost that dominates remote reads: network round-trips.
+A read pattern that finishes instantly against a warm page cache can take
+minutes of serial round-trips against object storage. snailmail adds a
+per-request latency draw and a shared bandwidth pipe so you can measure how a
+reader behaves over the wire. `max_in_flight` tells you peak concurrency, which
+wall-clock time alone cannot.
+
+## Install
+
+```bash
+uv add snailmail        # or: pip install snailmail
+```
+
+## Use it in a benchmark
+
+snailmail serves a directory. Every file under the root is reachable at its path
+relative to the root, which matches the shape of an object store or Icechunk virtual
+dataset (one object per file). Point your reader at `server.base` and have it fetch
+keys like `chunks/0.0.0`.
+
+```python
+from snailmail import LatencyRangeServer, LogNormal
+
+with LatencyRangeServer("my_zarr_store/", latency=LogNormal(mode_ms=40), bandwidth_mbs=100) as server:
+    server.reset_counts()
+    open_and_read(server.base)         # your reader: obstore, icechunk, zarr, ...
+    print(server.stats())
+    # {'n_gets': 312, 'n_requests': 312, 'n_misses': 0, 'max_in_flight': 16,
+    #  'total_bytes': .., 'methods': {'GET': 312}, 'paths': {..}}
+```
+
+`open_and_read` stands in for the reader you're benchmarking. It makes HTTP GETs
+(with `Range` headers) against `server.base`; snailmail injects the latency, meters
+the bytes through the bandwidth pipe, and streams the file from disk in response. A
+direct request looks like this:
+
+```python
+import urllib.request
+
+with LatencyRangeServer("my_zarr_store/") as server:
+    req = urllib.request.Request(server.url("chunks/0.0.0"), headers={"Range": "bytes=0-1023"})
+    first_kib = urllib.request.urlopen(req).read()
+```
+
+`server.url(key)` builds the URL for a key; `server.files()` lists the served keys.
+`stats()` is a snapshot of request counters since the last `reset_counts()`:
+`n_requests` counts every request, `n_gets` only the GETs, and `n_misses` the
+requests for keys that don't exist (404, like an object store's NoSuchKey). Tune
+between measurements with `set_latency(dist)`, `set_bandwidth_mbs(x)`, and
+`reset_counts()`.
+
+Latency is a pluggable distribution passed as `latency=`:
+
+```python
+from snailmail import LogNormal, Normal, Exponential, Fixed
+
+LogNormal(mode_ms=45, sigma=0.5)   # unimodal hump with long right tail; fits object-store GET RTT
+Normal(mean_ms=45, std_ms=10)      # symmetric, truncated at 0
+Exponential(mean_ms=45)            # peak at 0; a poor model for GET RTT
+Fixed(20)                          # deterministic
+```
+
+`latency=None` (the default) injects no latency.
+
+## From the CLI
+
+```bash
+snailmail ./store --dist lognormal --mode-ms 45 --sigma 0.5
+snailmail ./store --dist normal --mean-ms 45 --std-ms 10
+snailmail ./store --dist exponential --mean-ms 45
+snailmail ./store --dist fixed --value-ms 20
+snailmail ./store --bandwidth-mbs 100 --port 8080 --json   # no latency; JSON address line
+```
+
+The argument is the directory to serve.
+
+`--json` prints a single machine-readable line and flushes it before serving,
+so a script can spawn snailmail, read the bound address from stdout, and proceed.
+
+The CLI rejects a flag that doesn't belong to the chosen `--dist`. Omit `--dist`
+for no injected latency.
+
+## What it models
+
+**Latency** is a per-request draw from the chosen distribution. `lognormal` is
+the recommended default: parameterise it by the PDF mode (`--mode-ms`) and shape
+(`--sigma`). `normal`, `exponential`, and `fixed` are available for comparison.
+
+**Bandwidth** is a single shared FIFO pipe (`--bandwidth-mbs`, MB/s = 1e6 bytes/s).
+Per-request round-trips run in parallel, but response bytes serialize through the
+pipe, so aggregate egress is capped and over-read costs real transfer time. Omit
+for unlimited bandwidth.
+
+HTTP correctness (206, `Content-Range`, suffix ranges, 416, conditional requests)
+and on-disk streaming come from aiohttp's `web.FileResponse`. Files are never
+loaded into RAM, so multi-gigabyte files work.
+
+Missing keys return 404 and are counted in `n_misses`, matching object-store
+NoSuchKey behavior.
+
+## Notes
+
+- Loopback only (binds `127.0.0.1`); nothing leaves the machine.
+- Consumers must opt into plain HTTP: obstore `client_options={"allow_http": True}`,
+  icechunk `http_store({"allow_http": "true"})`.
+- The injected latency is added to the real (sub-millisecond, local-SSD)
+  range-read time, so the modelled RTT is dominated by the configured value.
+- For transport-accurate shaping on real packets, use `tc netem` (Linux) or
+  `dnctl`/`pfctl` (macOS) in front of any file server. snailmail trades that
+  for zero-setup, in-process instrumentation.
+
+Contributing? See [AGENTS.md](AGENTS.md). MIT licensed.

snailmail-0.1.0/README.md

@@ -0,0 +1,123 @@
+# snailmail
+
+A local HTTP server that serves a directory over HTTP Range, injecting per-request
+latency and a bandwidth cap, and counts GETs and peak concurrency.
+
+Use it to benchmark range-based readers — object stores, Zarr/Icechunk virtual
+chunks, tiled image formats — under realistic network conditions, on your laptop,
+with no cloud and no root.
+
+## Why you'd want it
+
+Local disk hides the cost that dominates remote reads: network round-trips.
+A read pattern that finishes instantly against a warm page cache can take
+minutes of serial round-trips against object storage. snailmail adds a
+per-request latency draw and a shared bandwidth pipe so you can measure how a
+reader behaves over the wire. `max_in_flight` tells you peak concurrency, which
+wall-clock time alone cannot.
+
+## Install
+
+```bash
+uv add snailmail        # or: pip install snailmail
+```
+
+## Use it in a benchmark
+
+snailmail serves a directory. Every file under the root is reachable at its path
+relative to the root, which matches the shape of an object store or Icechunk virtual
+dataset (one object per file). Point your reader at `server.base` and have it fetch
+keys like `chunks/0.0.0`.
+
+```python
+from snailmail import LatencyRangeServer, LogNormal
+
+with LatencyRangeServer("my_zarr_store/", latency=LogNormal(mode_ms=40), bandwidth_mbs=100) as server:
+    server.reset_counts()
+    open_and_read(server.base)         # your reader: obstore, icechunk, zarr, ...
+    print(server.stats())
+    # {'n_gets': 312, 'n_requests': 312, 'n_misses': 0, 'max_in_flight': 16,
+    #  'total_bytes': .., 'methods': {'GET': 312}, 'paths': {..}}
+```
+
+`open_and_read` stands in for the reader you're benchmarking. It makes HTTP GETs
+(with `Range` headers) against `server.base`; snailmail injects the latency, meters
+the bytes through the bandwidth pipe, and streams the file from disk in response. A
+direct request looks like this:
+
+```python
+import urllib.request
+
+with LatencyRangeServer("my_zarr_store/") as server:
+    req = urllib.request.Request(server.url("chunks/0.0.0"), headers={"Range": "bytes=0-1023"})
+    first_kib = urllib.request.urlopen(req).read()
+```
+
+`server.url(key)` builds the URL for a key; `server.files()` lists the served keys.
+`stats()` is a snapshot of request counters since the last `reset_counts()`:
+`n_requests` counts every request, `n_gets` only the GETs, and `n_misses` the
+requests for keys that don't exist (404, like an object store's NoSuchKey). Tune
+between measurements with `set_latency(dist)`, `set_bandwidth_mbs(x)`, and
+`reset_counts()`.
+
+Latency is a pluggable distribution passed as `latency=`:
+
+```python
+from snailmail import LogNormal, Normal, Exponential, Fixed
+
+LogNormal(mode_ms=45, sigma=0.5)   # unimodal hump with long right tail; fits object-store GET RTT
+Normal(mean_ms=45, std_ms=10)      # symmetric, truncated at 0
+Exponential(mean_ms=45)            # peak at 0; a poor model for GET RTT
+Fixed(20)                          # deterministic
+```
+
+`latency=None` (the default) injects no latency.
+
+## From the CLI
+
+```bash
+snailmail ./store --dist lognormal --mode-ms 45 --sigma 0.5
+snailmail ./store --dist normal --mean-ms 45 --std-ms 10
+snailmail ./store --dist exponential --mean-ms 45
+snailmail ./store --dist fixed --value-ms 20
+snailmail ./store --bandwidth-mbs 100 --port 8080 --json   # no latency; JSON address line
+```
+
+The argument is the directory to serve.
+
+`--json` prints a single machine-readable line and flushes it before serving,
+so a script can spawn snailmail, read the bound address from stdout, and proceed.
+
+The CLI rejects a flag that doesn't belong to the chosen `--dist`. Omit `--dist`
+for no injected latency.
+
+## What it models
+
+**Latency** is a per-request draw from the chosen distribution. `lognormal` is
+the recommended default: parameterise it by the PDF mode (`--mode-ms`) and shape
+(`--sigma`). `normal`, `exponential`, and `fixed` are available for comparison.
+
+**Bandwidth** is a single shared FIFO pipe (`--bandwidth-mbs`, MB/s = 1e6 bytes/s).
+Per-request round-trips run in parallel, but response bytes serialize through the
+pipe, so aggregate egress is capped and over-read costs real transfer time. Omit
+for unlimited bandwidth.
+
+HTTP correctness (206, `Content-Range`, suffix ranges, 416, conditional requests)
+and on-disk streaming come from aiohttp's `web.FileResponse`. Files are never
+loaded into RAM, so multi-gigabyte files work.
+
+Missing keys return 404 and are counted in `n_misses`, matching object-store
+NoSuchKey behavior.
+
+## Notes
+
+- Loopback only (binds `127.0.0.1`); nothing leaves the machine.
+- Consumers must opt into plain HTTP: obstore `client_options={"allow_http": True}`,
+  icechunk `http_store({"allow_http": "true"})`.
+- The injected latency is added to the real (sub-millisecond, local-SSD)
+  range-read time, so the modelled RTT is dominated by the configured value.
+- For transport-accurate shaping on real packets, use `tc netem` (Linux) or
+  `dnctl`/`pfctl` (macOS) in front of any file server. snailmail trades that
+  for zero-setup, in-process instrumentation.
+
+Contributing? See [AGENTS.md](AGENTS.md). MIT licensed.

snailmail-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "snailmail"
+dynamic = ["version"]
+description = "A local HTTP server that serves a directory over Range with injectable latency and bandwidth limits, for benchmarking range / object-store / virtual-chunk reads under realistic network conditions."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ian Hunt-Isaak", email = "ian@earthmover.io" }]
+keywords = ["http", "latency", "bandwidth", "benchmark", "range-requests", "object-store", "zarr", "icechunk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Topic :: System :: Benchmark",
+]
+dependencies = [
+    "aiohttp>=3.9",
+    "numpy>=1.24",
+]
+
+[project.scripts]
+snailmail = "snailmail.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/ianhi/snailmail"
+Repository = "https://github.com/ianhi/snailmail"
+Issues = "https://github.com/ianhi/snailmail/issues"
+Changelog = "https://github.com/ianhi/snailmail/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.11"]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/snailmail"]
+
+[tool.hatch.build.targets.sdist]
+# Ship source + the docs a consumer might want; leave out the internal worklog and
+# repo/CI plumbing.
+include = ["src", "tests", "README.md", "CHANGELOG.md", "LICENSE", "AGENTS.md"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.mypy]
+files = ["src/snailmail"]
+python_version = "3.10"

snailmail-0.1.0/src/snailmail/__init__.py

@@ -0,0 +1,26 @@
+"""snailmail — a local HTTP file server with injectable latency and bandwidth limits.
+
+For benchmarking range / object-store / virtual-chunk reads under realistic network
+conditions. See :class:`LatencyRangeServer`.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from snailmail.bandwidth import AsyncSharedPipe
+from snailmail.latency import Exponential, Fixed, LatencyDist, LogNormal, Normal
+from snailmail.server import LatencyRangeServer
+
+try:
+    __version__ = version("snailmail")  # derived from the git tag at build time (hatch-vcs)
+except PackageNotFoundError:  # running from a source tree with no install
+    __version__ = "0+unknown"
+
+__all__ = [
+    "LatencyRangeServer",
+    "AsyncSharedPipe",
+    "LatencyDist",
+    "LogNormal",
+    "Normal",
+    "Exponential",
+    "Fixed",
+]

snailmail-0.1.0/src/snailmail/bandwidth.py

@@ -0,0 +1,35 @@
+"""Bandwidth limiting for responses."""
+
+from __future__ import annotations
+
+import asyncio
+
+
+class AsyncSharedPipe:
+    """A FIFO bandwidth limiter modelling ONE shared client downlink (async).
+
+    Every response's byte transfer is reserved through a single pipe of ``B``
+    bytes/s, so aggregate egress can't exceed ``B`` no matter how many requests
+    overlap, and over-read directly costs pipe time. Per-request latency stays
+    parallel (handled separately); only bytes serialize here. ``B is None`` disables.
+    """
+
+    def __init__(self, bytes_per_s: float | None):
+        self.B = bytes_per_s if bytes_per_s and bytes_per_s > 0 else None
+        self._lock = asyncio.Lock()
+        self._free = 0.0  # loop-clock timestamp the pipe is next free
+
+    async def transfer(self, nbytes: int) -> None:
+        if self.B is None or nbytes <= 0:
+            return
+        loop = asyncio.get_running_loop()
+        async with self._lock:
+            start = max(loop.time(), self._free)
+            self._free = start + nbytes / self.B
+            finish = self._free
+        delay = finish - loop.time()
+        if delay > 0:
+            await asyncio.sleep(delay)
+
+    def reset(self) -> None:
+        self._free = 0.0