# Networking and Async IO Guidelines

## HTTP and APIs

- Use `httpx` or `requests` for simple synchronous HTTP; `httpx` or `aiohttp` for async workflows.
- Always set:
  - explicit timeouts
  - retry policy where appropriate
  - sane default headers (including User-Agent when needed).
- Validate responses:
  - check status codes
  - handle error body formats gracefully.

## Concurrency and async

- Prefer `asyncio` for high-concurrency IO-bound tasks.
- Avoid mixing sync and async in confusing ways; when necessary, clearly separate boundaries.
- Use connection pooling and session reuse instead of creating clients per request.

## Protocols and serialization

- Be explicit about:
  - encoding (UTF-8 by default)
  - content types (JSON, protobuf, etc.).
- For binary protocols or performance-critical paths, consider:
  - struct packing
  - memoryviews
  - minimized copies.

## Robustness

- Handle network errors explicitly:
  - timeouts
  - connection errors
  - transient failures.
- Implement backoff strategies and circuit breakers where applicable.
- Log enough context to debug issues without exposing sensitive data.