Skip to content

Latest commit

 

History

History
170 lines (130 loc) · 6.69 KB

API.md

File metadata and controls

170 lines (130 loc) · 6.69 KB

Conditioner API

HTTPS on port 10443 on the gateway, with a self-signed certificate made at install. Clients must either trust that certificate or skip verification (curl -k). No authentication yet.

Base path: /v1. The retired Raspberry Pi build served the same API.

Concepts

Devices under test join one of two test SSIDs, each on its own VLAN:

SSID Subnet Gateway bridge
test-a 192.0.2.0/24 br10
test-b 198.51.100.0/24 br20

The gateway routes between VLANs in software, so traffic between a test-VLAN device and anything on another network — the main LAN, the other test VLAN, the internet — passes through its kernel and can be conditioned. Traffic between two devices on the same test VLAN is switched by the AP and switch, never reaches the gateway, and cannot be shaped.

A shape targets a device's IP. An IP outside the test subnets is accepted, but the response carries a warning: its traffic never reaches the shaper.

When both ends of a flow are shaped - one device on each test VLAN - both shapes apply: the sender's upload shape and the receiver's download shape stack.

POST /v1/shape is declarative by default: the array you send becomes the complete set of active shapes, and any IP not in the array is returned to unshaped. This makes repeated calls safe and free of state drift - you never need to clear before setting.

Pass "merge": true to touch only the IPs you list and leave every other device's shaping alone.

POST /v1/shape

{
  "shapes": [
    { "ip": "192.0.2.10", "latencyMs": 120, "mbit": 1.5 },
    { "ip": "192.0.2.20", "latencyMs": 0,   "mbit": 10  }
  ]
}
Field Type Default Meaning
ip IPv4 string required Device to shape
latencyMs number ≥ 0 0 Delay added in each direction
jitterMs number ≥ 0 0 Uniform jitter, giving latencyMs ± jitterMs
mbit number ≥ 0 0 Bandwidth cap, fractions allowed. 0 = uncapped
lossPct number ≥ 0 0 Random packet loss percentage

Top-level alongside shapes:

Field Type Default Meaning
merge boolean false Only touch the listed IPs, leaving others alone

Removing shaping

An entry naming an IP with no conditioning on it - { "ip": "..." }, or every field zero - means "this device is unshaped", and clears anything already applied to it. Combine that with merge to undo one device without disturbing the rest:

# clear 192.0.2.10, leave every other shaped device exactly as it was
curl -sk -X POST https://gateway.example:10443/v1/shape -H 'Content-Type: application/json' \
  -d '{"merge":true,"shapes":[{"ip":"192.0.2.10"}]}'

Without merge, that same call also clears everything you did not list, because the array is the complete desired state. Clearing an IP that was never shaped is a harmless no-op, and shaping and clearing can be mixed in one call:

curl -sk -X POST https://gateway.example:10443/v1/shape -H 'Content-Type: application/json' \
  -d '{"merge":true,"shapes":[
        {"ip":"192.0.2.10"},
        {"ip":"192.0.2.20","latencyMs":250,"mbit":0.5}
      ]}'

latencyMs is one-way per direction, so round-trip latency rises by roughly 2 × latencyMs. A latencyMs of 100 produces about 200 ms of added ping time - measured 211 ms against a 9 ms baseline. The response returns expectedRttDeltaMs so this is never ambiguous.

Response:

{
  "ok": true,
  "merge": false,
  "cleared": ["192.0.2.20"],  // IPs returned to unshaped by this call
  "applied": [
    { "ip": "192.0.2.10", "latencyMs": 120, "jitterMs": 0, "mbit": 1.5,
      "lossPct": 0, "slot": 1, "expectedRttDeltaMs": 240 }
  ],
  "applyDurationMs": 6.1,      // whole request, server side
  "tcDurationMs": 5.4,         // time inside the single tc invocation
  "commandCount": 8,
  "warnings": []               // e.g. an IP that is not on a test VLAN
}

Up to 32 devices may be shaped simultaneously. Beyond that the extra shapes are dropped and named in warnings.

Other endpoints

Method Path Purpose
GET /v1/health { ok, version, iface, interfaces, radios, uptimeMs, treeIntact, activeCount, maxSlots }
GET /v1/shape Current active shapes
DELETE /v1/shape Clear all shaping
POST /v1/reset Tear down and rebuild the whole tc tree
GET /v1/devices Clients on the test VLANs, with IP, network, SSID and hostname
GET /v1/stats Raw tc -s class counters for both directions
GET /v1/history Every shaping change, newest first: time, caller IP, request, result. ?limit=N

interfaces in /v1/health lists each shaped bridge with name, ssid, subnet, present and hooked (shaping is attached to it). radios is the same list under the Pi build's name.

GET /v1/devices is how a test agent discovers what it can shape without hard-coding addresses. It joins the gateway's neighbour table with its DHCP leases. Each device has mac, ip, iface, ssid, hostname, state, and ipSource: arp for a live neighbour entry, lease for a DHCP lease with no live entry.

Examples

# What can I shape?
curl -sk https://gateway.example:10443/v1/devices

# Degrade one device, leave another alone
curl -sk -X POST https://gateway.example:10443/v1/shape -H 'Content-Type: application/json' \
  -d '{"shapes":[{"ip":"192.0.2.10","latencyMs":150,"jitterMs":30,"mbit":1.5}]}'

# Back to normal
curl -sk -X DELETE https://gateway.example:10443/v1/shape

Performance

Measured 2026-09-11 over HTTPS from a wired Mac on the main LAN, a new TLS connection per call:

HTTPS round-trip, p50 22 ms
HTTPS round-trip, max 43 ms
Server-side apply ~6–15 ms
Inside tc ~5–13 ms

Comfortably inside a 100 ms budget, so an agent can sweep conditions in a tight loop. The qdisc tree is built once at startup with 32 pre-made slots; a shape change is a tc class change plus a tc qdisc change, plus a filter when the slot's device changes, all issued in a single batched tc invocation. No teardown, no rebuild, and changing one device never disturbs another.

History

Every call that changes shaping (POST /v1/shape, DELETE /v1/shape, POST /v1/reset, including rejected ones) is recorded with its time, the caller's IP, the shapes it asked for and what was applied or cleared. The last 500 are served by GET /v1/history; every one is also written to the gateway's journal as a shape-call JSON line, which survives restarts:

journalctl -u udm-conditioner --no-pager | grep shape-call

When several agents share the conditioner, this is how to tell who shaped what.