Skip to content

Glossary

Every term the docs use, in one place. One-line definitions; each entry links to the in-depth page where the concept actually lives.

For peer-project terminology (Function Block, Worker, Workflow, Provider, Blackboard, Context), see Neops ecosystem.

Sessions and queueing

Session : A logical reservation in the server’s FIFO queue, identified by a UUID. Either WAITING (queued) or ACTIVE (head of queue). See Session queue.

Session queue : Server-side FIFO list that decides who drives the lab next; promotion is first-come, first-served. See Session queue → Promotion order.

Heartbeat : POST /session/heartbeat — refreshes last_seen_at so the server does not evict the session as stale. See Session queue → The heartbeat.

X-Session-ID : The HTTP header that gates /lab/*; the only access boundary on the lab surface. See REST API → The X-Session-ID contract.

Labs and topologies

Lab : A running Netlab topology on the host — at most one at a time. See Lab lifecycle.

Topology : A Netlab YAML file (.yml) declaring nodes, links, modules, and provider. See Topology format.

Topology identity : The SHA-256 of the topology file’s bytes — not the filename. See Lab lifecycle → Topology identity.

Reference count : Counter on the running lab; reuse=true increments, release decrements, hitting zero leaves the lab idle (not torn down). See Lab lifecycle → Reuse.

Lab reuse : Opt-in (reuse=true / reuse_lab=True) sharing of a running lab across sessions whose topology content hash matches. See Lab lifecycle → Reuse.

One-lab rule : Netlab’s “only one topology per host” constraint; the queue exists because of it. See Invariants → One lab per host.

Locking and concurrency

LabManager : Class-only singleton (no instances) that owns the running lab and enforces one-lab-per-host. See LabManager singleton.

GLOBAL_LOCK : filelock.FileLock at <tempdir>/netlab_pytest.lock — serializes lab operations across processes. See Invariants → One lab per host.

Single-instance filelock : Separate FileLock in __main__.py that prevents two server processes on one host. See Invariants → One server instance per host.

try_acquire vs acquire : try_acquire is non-blocking (server uses this); acquire polls forever (local fixtures only). Mixing them deadlocks the event loop. See LabManager → try_acquire vs acquire.

atexit teardown : Synchronous, silent cleanup hook that tears down any live lab on interpreter exit. Never add async code. See atexit + lifespan.

Data models

*Dto suffix : Every Pydantic request/response model ends in Dto; code review enforces it. See Invariants → *Dto suffix.

DeviceInfoDto : {name, raw} — one entry per device in a running lab. Returned by POST /lab and GET /lab/devices.

AcquireResponseDto : {reused, devices} — response body of POST /lab.

SessionStatusResponseDto : {status, position} — response body of GET /session/{id}.

CreateSessionResponseDto : {session_id, position} — response body of POST /session.

LabStatusDto : Response body of GET /lab — running topology and current device list.

Testing & client

remote_lab_fixture : The factory creating a function-scoped pytest fixture bound to a topology — the stable public API of this project. See Pytest fixtures.

remote_lab_client : Session-scoped pytest fixture wrapping a single RemoteLabClient; fails fast if REMOTE_LAB_URL is unset. See Python client.

Fixture : A pytest setup/teardown hook injected into a test by parameter name. See pytest docs.

Fixture scope : How long pytest keeps a fixture alive (function, class, module, package, session). See pytest docs.

conftest.py : pytest-discovered file whose contents auto-load for tests in that directory tree without an import. See pytest docs.

pytest11 entry point : [project.entry-points.pytest11] — how pytest discovers installed plugins. neops-remote-lab registers itself this way. See pytest docs.

Fixture rank : Auto-incremented integer per remote_lab_fixture; the ordering plugin uses ranks to keep tests against the same lab contiguous. See Pytest fixtures → Test execution ordering.

Upstream tools

Netlab : The lab orchestrator this service wraps. Used via neops_remote_lab.netlab.connector.run_netlab only. See Netlab host setup.

Containerlab : Netlab’s default provider (provider: clab); pulls vendor NOS containers and wires them.

FRR : Open-source software router; the default device: in most topologies. See Vendor setup (FRR tab).

Nokia SR Linux : Container-native vendor NOS, free under Nokia EULA. See Vendor setup (Nokia SR Linux tab).

Cisco IOL : IOS-on-Linux, license required. See Vendor setup (Cisco IOL tab).

Headscale : Self-hosted Tailscale control plane; the recommended enclosure for the no-auth lab service. See Headscale VPN.

Headplane : Web UI for Headscale.

Tailscale : The mesh VPN whose protocol Headscale implements.

Subnet router : A Tailscale node advertising lab subnet routes to the rest of the mesh — typically the lab host itself. See Headscale VPN → Quick setup.

Peer-project terminology

Peer-project terminology (Function Block, Worker, Workflow, Provider, Blackboard, Context, etc.) — see How Remote Lab fits with neops.