s3 Phase 3: Async-native client (AsyncS3Client)

[elena-oaklight]

Parent: #109

Scope

Native async client using asyncio + aiohttp or stdlib asyncio streams, removing the need for asyncio.to_thread() wrappers in async callers like veilrender's StorageManager.

Motivation

Current approach (and Phase 1/2) wraps synchronous operations in asyncio.to_thread(). This works but ties up thread pool workers for I/O-bound operations. A native async client avoids the overhead and integrates more naturally with async frameworks (FastAPI, aiohttp, etc.).

Deliverables

AsyncS3Client

Mirrors the S3Client API with async def methods:

class AsyncS3Client:
    async def bucket_exists(self, bucket: str) -> bool: ...
    async def make_bucket(self, bucket: str) -> None: ...
    async def get_object(self, bucket: str, key: str) -> AsyncResponse: ...
    async def put_object(self, bucket: str, key: str, data, length: int, ...) -> None: ...
    # + Phase 2 ops as async

HTTP backend options (TBD)

• Option A: aiohttp (external dep, feature-rich, widely used)
• Option B: stdlib asyncio streams + manual HTTP/1.1 (zero deps, more work)
• Option C: httpx async (external dep, clean API)

Decision: evaluate whether an external dep is acceptable for the async variant, or if zerodep philosophy requires stdlib-only. Could ship as a separate optional module (s3_async).

Shared signing logic

SigV4 signing from Phase 1 is sync/CPU-only, reusable as-is in async context — no changes needed there.

AsyncResponse

class AsyncResponse:
    async def read(self) -> bytes: ...
    async def aiter_bytes(self, chunk_size=65536) -> AsyncIterator[bytes]: ...
    async def aclose(self) -> None: ...
    async def __aenter__(self): ...
    async def __aexit__(self, *args): ...

Notes

• If stdlib-only is required, asyncio.open_connection() + manual HTTP/1.1 framing is feasible but non-trivial for chunked responses
• Streaming large get_object responses without buffering is the main async advantage
• veilrender StorageManager would drop all asyncio.to_thread() wrappers

[Oaklight]

Phase 3 architecture decision: raw asyncio streams, not httpclient

Context

We ran A/B benchmarks comparing the current stdlib http.client backend against a httpclient module backend for sync S3Client. Results:

Operation	stdlib (ms)	httpclient (ms)	Overhead
PUT 1KB	0.62	1.64	2.7×
GET 1KB	0.81	2.80	3.5×
bucket_exists	0.30	0.98	3.3×
stat_object	0.74	1.96	2.6×
list 1500 objects	17.73	92.06	5.2×
PUT 1MB	6.82	8.44	1.2×
GET 1MB	5.26	5.73	1.1×

httpclient's _prepare_request pipeline (URL parsing, header construction, body encoding, response decompression checks) adds 2-5× overhead per request. For small/metadata operations this dominates; for large payloads it washes out in I/O — but the s3 module's main use case (cache operations, listings) is predominantly small objects.

Decision

• Sync: keep http.client (stdlib) — proven, lightweight, zero overhead
• Async: use raw asyncio.open_connection() + manual HTTP/1.1 framing — mirrors the sync approach but non-blocking
• deps: stays [] — no dependency on httpclient

Async implementation plan

AsyncS3Client will:

1. Reuse all SigV4 signing code (sync, CPU-only)
2. Use asyncio.open_connection(ssl=ctx) for TCP/TLS connections
3. Hand-write HTTP/1.1 request/response framing:
   • Request: status line + headers + body → writer.write()
   • Response: parse status line, headers (until \r\n\r\n), then read body by Content-Length or chunked transfer encoding
4. Mirror all 10 S3Client public methods as async def
5. No connection pooling in Phase 3 (one connection per request, same as sync)

What this means for #116 / httpclient

The httpclient CaseInsensitiveDict fix (#117) is still valuable for other consumers — it just won't be used by the s3 module. The s3 module manages its own headers via SigV4 signing, which already lowercases canonical header names.