Drills 01–11 are implemented. This is the first of the deliberately deferred ones, and the most honest remaining gap in the session layer.
Venues cap how fast you may send. Exceed it and behavior varies: a reject, a silently dropped message, a queue that builds until it collapses, or a disconnect. docs/drills/11-session-reject.md already notes that "repeated rejects from a session attract attention, and some venues throttle or disconnect" — with nothing anywhere showing what that looks like.
It is also the one limit a client discovers by exceeding it, usually in production, usually while trying to cancel everything at once during an incident. That is the worst possible moment to learn the shape of it.
What the drill should teach
- A venue-side rate limit, and what the venue does when you cross it
- Client-side pacing: the difference between dropping the excess, queueing it, and blocking the caller — and why the right answer differs for a new order versus a cancel
- That a throttle applies to what you send, so a resend you requested can pace the venue back at you
- The interaction nobody expects: recovering from a large gap can itself hit the limit
Implementation sketch
- Venue: per-session token bucket, configurable via the settings file
POST /admin/throttle?msgs=&per= to set it at runtime, matching how every other drill is driven- Client: a pacing helper in
internal/session, since this is a thing every reader will need and none of them should write twice
- Wire trace showing the limit being crossed and the venue reacting
Versus real B3
Order-entry sessions are provisioned with a per-second message allowance. The specifics belong in B3's documentation, not here — this drill should demonstrate the mechanism and point at the spec for the number, consistent with the rest of the repo.
Acceptance
docs/drills/12-throttling.md following the established shape: Goal / Run it / Wire trace / What to notice / Versus real B3- A test asserting the venue enforces the limit and the client paces below it
- The README drill table updated
Drills 01–11 are implemented. This is the first of the deliberately deferred ones, and the most honest remaining gap in the session layer.
Venues cap how fast you may send. Exceed it and behavior varies: a reject, a silently dropped message, a queue that builds until it collapses, or a disconnect.
docs/drills/11-session-reject.mdalready notes that "repeated rejects from a session attract attention, and some venues throttle or disconnect" — with nothing anywhere showing what that looks like.It is also the one limit a client discovers by exceeding it, usually in production, usually while trying to cancel everything at once during an incident. That is the worst possible moment to learn the shape of it.
What the drill should teach
Implementation sketch
POST /admin/throttle?msgs=&per=to set it at runtime, matching how every other drill is driveninternal/session, since this is a thing every reader will need and none of them should write twiceVersus real B3
Order-entry sessions are provisioned with a per-second message allowance. The specifics belong in B3's documentation, not here — this drill should demonstrate the mechanism and point at the spec for the number, consistent with the rest of the repo.
Acceptance
docs/drills/12-throttling.mdfollowing the established shape: Goal / Run it / Wire trace / What to notice / Versus real B3