migratory-world-server

Asyncio world server for the Migratory boid-style simulation. Binary WebSocket protocol, fixed-timestep tick loop, off-loop simulation execution.

Running

uv run python -m migratory_server --config config/default.yaml

Configuration

server.terrain_wire

Controls how the static terrain grid is encoded and delivered on the wire. Defaults match the slice 317 design: f32 + zstd, single-shot for grids under 4 MiB post-compression and chunked above.

server:
  terrain_wire:
    dtype: f32                    # f32 (default), uint16, f64
    compression: auto             # auto = zstd; explicit zstd | lz4 | none
    chunk_transport_threshold_bytes: 4194304   # 4 MiB; above this → chunked
    chunk_target_bytes: 1048576                # 1 MiB; uncompressed chunk size
    quantization_range: auto      # auto (computes min/max from grid) | fixed
    quantization_min: null        # required if quantization_range=fixed
    quantization_max: null        # required if quantization_range=fixed

LZ4 is an optional extra: uv sync --extra terrain-lz4. Selecting compression: lz4 without it installed raises a clear startup error.

server.client_backpressure

Controls per-client outbound queue depth and the graduated slow-client eviction policy. A client that fills its queue grace_overflow_events times without an intervening successful send is disconnected with the configured close code. Terrain messages are non-droppable: a client that cannot accept terrain within terrain_enqueue_timeout_seconds is evicted immediately.

server:
  client_backpressure:
    send_queue_max_messages: 16       # per-client queue depth cap
    grace_overflow_events: 20         # consecutive overflows before eviction
    eviction_close_code: 1013         # IANA "Try Again Later"
    eviction_close_timeout_seconds: 1.0   # close-handshake timeout before transport.abort()
    terrain_enqueue_timeout_seconds: 2.0  # per-message put timeout during terrain delivery
    log_overflow_at_warn: true        # log drops at WARN (false → DEBUG)

No protocol change — viewer and other clients are unaffected. Counters (state_updates_dropped, overflow_events, queue_depth_hwm) are logged at INFO on every disconnect.

Wire Protocol Reference

The canonical TERRAIN v2 wire-format spec (single-shot 0x03, TERRAIN_CHUNK 0x04, TERRAIN_HEADER 0x05) lives at project-documents/reference/terrain-wire-protocol-v2.md. Client implementers (browser viewer, future tooling) should code against that document.

Development

Tests

uv run pytest              # unit tests (load tier excluded by default)
uv run pytest -m load      # run the opt-in load tier

Load tests run against an in-process server at the v1 operating envelope (5K entities × 60 Hz × 5 clients) and are gated in CI as a separate step.

Diagnostics

MIGRATORY_DEBUG=1 uv run python -m migratory_server --config config/default.yaml

Enables asyncio debug mode with slow_callback_duration=0.05s. Use when investigating suspected event-loop-blocking regressions. Off by default; ~10–30% scheduling overhead when on.