fix(docker): allocate session networks from configured pool

[evergardener]

Summary

• add validated Docker session-network pool and prefix settings
• allocate Bay session bridge networks with explicit Docker IPAM instead of Docker's automatic address pool
• skip any candidate subnet overlapping an existing Docker network
• fail explicitly when the configured pool is exhausted instead of silently falling back to automatic IPAM
• document the production Docker default: 10.252.0.0/16 split into /24 session networks

Motivation

On Docker Desktop, automatic bridge allocation can select 192.168.0.0/20, which overlaps common physical 192.168.x.x LANs and breaks container access to LAN dependencies. Explicit per-session IPAM keeps sandbox isolation while avoiding Docker Desktop's opaque default pool selection.

Validation

• cd pkgs/bay && uv sync --frozen
• cd pkgs/bay && uv run pytest tests/unit/drivers/test_docker_session_network.py -v --tb=short — 9 passed
• cd pkgs/bay && uv run ruff check app/config.py app/drivers/docker/docker.py tests/unit/drivers/test_docker_session_network.py — passed
• cd pkgs/bay && uv run pytest tests/unit -v --tb=short — 365 passed, 121 errors. The errors are outside this change and occur during async SQLAlchemy test setup because greenlet is not installed by the current locked dependency environment. The focused IPAM tests pass using the same environment.

Scope

This change only affects newly created Docker session networks. It does not alter existing networks, Cargo paths, deployment secrets, or persistent data.

Summary by Sourcery

Configure deterministic Docker session bridge networks from a validated private address pool and avoid overlapping existing Docker networks.

New Features:

• Introduce configurable Docker session network pool and subnet prefix for session-scoped bridge networks.

Enhancements:

• Add validation for Docker session network pool and prefix to ensure canonical IPv4 networks and compatible prefixes.
• Derive session network subnets from the configured pool and explicitly pass IPAM configuration when creating Docker networks.
• Document the production Docker session network pool and prefix in the Docker deploy config.

Tests:

• Add unit tests covering Docker session network configuration validation and deterministic IPAM behavior, including pool exhaustion handling.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[sourcery-ai]

Hey - I've left some high level feedback:

• The subnet selection currently has a TOCTOU race between networks.list() and networks.create(); consider catching Docker errors for overlapping subnets and retrying with the next candidate subnet rather than failing the whole session creation.
• _used_docker_subnets assumes networks is a list of dicts, but the Docker SDK commonly returns Network objects; to make this more robust, consider handling both objects (via .attrs) and plain dicts when extracting IPAM config.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The subnet selection currently has a TOCTOU race between `networks.list()` and `networks.create()`; consider catching Docker errors for overlapping subnets and retrying with the next candidate subnet rather than failing the whole session creation.
-  `_used_docker_subnets` assumes `networks` is a list of dicts, but the Docker SDK commonly returns `Network` objects; to make this more robust, consider handling both objects (via `.attrs`) and plain dicts when extracting IPAM config.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}