Skip to content

Concepts

Four invariants shape every decision in the Remote Lab Manager — one lab per host, FIFO queueing, content-hash topology identity, reference-counted reuse.

Four invariants shape every decision in the Remote Lab Manager:

  • one lab per host,
  • strict FIFO queueing,
  • SHA-256 topology identity, and
  • reference-counted reuse.

Read these four pages in order if you want to reason about edge cases before they hit you — especially the ones the HTTP surface papers over.

In this section

  •   Three-minute tour

    The four-step session-and-lab lifecycle without queue mechanics or refcount math. Read first; the rest is the deep version.

  •   Architecture

    Three cooperating components (FastAPI server, LabManager singleton, Python client + pytest plugin); the one-server and one-lab guards; the async discipline; where run_netlab sits.

  •   Session queue

    FIFO state machine, strict-in-order promotion, the 423 access boundary, heartbeats, stale-session eviction (300 s active, 600 s waiting).

  •   Lab lifecycle

    Content-hash topology identity, try_acquire vs acquire, reference-counted reuse, idle labs, and the atexit cleanup safety net.

  •   Topology format

    The Netlab YAML shape we consume, the extra_files multipart contract, vendor defaults, and local validation before upload.

  • REST API — the endpoint-by-endpoint contract these invariants enforce.
  • Pytest Fixtures — how remote_lab_fixture wraps these invariants into a stable public API.
  • Operator runbook — the operator runbook that handles the failure modes these invariants allow.