Network¶
The request, event, and requestSequence assertions match against the observed-request model, NetworkExchange.
bajutsu.common.evidence.network
¶
Network observation — the exchange model and the in-process collector.
How traffic is observed (DESIGN: network): a Simulator app runs as a host process
and shares the Mac's loopback, so the app POSTs each request/response it makes to a
small collector bajutsu runs on 127.0.0.1:<port> (the port is injected into the app
via launch env, BAJUTSU_COLLECTOR, and a per-run shared token via
BAJUTSU_COLLECTOR_TOKEN — the collector accepts only requests that prove that token, so
another local process can't inject fabricated exchanges). A current BajutsuKit signs each request
with the token rather than sending it (BE-0459, _hmac_auth), and a collector bound beyond the
loopback, for a real device, accepts the signed scheme alone. The collector keeps the
exchanges in memory so a step's request assertion can be evaluated in real time, and
dumps them to network.json as scenario evidence.
The same receiver also accepts screen-transition reports on /transitions
(BE-0310): the opt-in BajutsuScreen observer in BajutsuKit (a
UIViewController.viewDidAppear hook) POSTs one record per completed appearance. They are
kept in an independent store from the network exchanges — the readiness gate and the
settled wait read only this one, never network-capture state, so the two stay independent
as documented.
The same receiver also carries the in-app control channel (BE-0365): bajutsu queues a command
naming one piece of its own in-app instrumentation and the state that piece should take, the app
drains the queue over an authenticated GET /commands, and reports back on /commands/ack whether
it applied the command. A command either toggles one piece of that instrumentation or, for the stub
table, replaces the whole table the app launched with.
That direction is what lets a capability change within a scenario rather than only at launch, and
it needs no new server, port, or authentication scheme — the app opens no socket, and the per-run
token above guards the commands exactly as it guards the reports. The channel carries no judgement:
nothing on it may influence whether a step passes, and no assertion reads from it.
The in-app side that captures and POSTs the exchanges is a separate Swift package
(BajutsuKit); this module is only the bajutsu-side receiver and data model.
AppCommand
¶
Bases: BaseModel
One command bajutsu asks the running app to apply (BE-0365).
bajutsu-side only — the collector serializes these out and never parses one back, so this model is strict and frozen rather than forward-compatible like the reports the app POSTs. It carries no judgement: nothing here may influence whether a step passes, and no assertion reads it.
enabled is the whole state a toggle capability takes. A capability whose state is not a toggle
(the mid-scenario stub table, BE-0365 unit 4) arrives as the sibling AppStubTableCommand,
discriminated on capability, not as another optional field here: widening this one would make the invalid cross-product — a stub table with
no table, a toggle carrying one — representable, and leave a validator to rule out what a union
rules out structurally (the shape config/effective.py already argues for).
AppCommandReport
¶
Bases: BaseModel
The app's report on one command it drained (BE-0365).
Inbound, so forward-compatible like the exchange and transition reports — but applied carries
no default, because "applied it" and "drained it and could not apply it" must not reach the
acknowledgement wait as the same message, and a default would quietly make one of them the
other. An app whose capability was compiled out, or whose handler raised, says so here with its
own reason, so the wait fails with the cause rather than timing out blind (BE-0365 unit 3).
AppStubTableCommand
¶
Bases: BaseModel
One command replacing the running app's stub table mid-scenario (BE-0365 unit 4).
The sibling AppCommand's docstring asks for: a stub table is not a toggle, so it carries the
whole table and no enabled. The table replaces the one BajutsuKit loaded from BAJUTSU_MOCKS
rather than extending it, so the app's rules after the command are exactly mocks — an empty
list removes every stub. Serialized with the same alias keys dump_mocks writes, so the app
parses one wire shape whether the table arrived at launch or on this channel.
Collector
¶
Bases: Protocol
The exchange source the run loop and evidence writer drive.
Independent of how it observed the traffic: the iOS NetworkCollector receives POSTs over HTTP;
the web WebNetworkCollector hooks Playwright events — both satisfy this, so the pipeline stays
backend-agnostic.
ControlChannel
¶
Bases: Protocol
The inbound half of a collector: the calls a mid-scenario command needs (BE-0365).
Deliberately a sibling of Collector rather than more methods on it. Which collectors carry a
channel is the question unit 3 has to answer, and answering it structurally means a collector
that has no way to reach the app simply does not satisfy this — no stub method that raises, and
nothing for WebNetworkCollector or a test fake to implement. NetworkCollector satisfies it
because its receiver already holds the queue, and the driver-observed collectors do not — but
that split is narrower than "can this backend carry a channel?": Android is an
external-receiver platform too (BE-0283) — as is fake — so those leases hold a
NetworkCollector and satisfy this even though nothing on the other end drains the queue.
orchestrator.control_channel turns a command issued against a channel-less collector into a
loud failure rather than a silent skip; against an Android one it can only time out, so keeping
the command from being issued there is the caller's job, not this protocol's.
InAppCapability
¶
Bases: StrEnum
A piece of bajutsu's own in-app instrumentation the control channel may address (BE-0365).
Closed on purpose, and that is the boundary rather than a comment about it: the channel controls what bajutsu put inside the app, never the application's own state. A command that seeded app data or drove navigation would move per-app knowledge into the tool (prime directive 3), so a new capability is argued for here instead of being named as a free string at a call site.
NetworkCollector
¶
Receives exchanges POSTed by the app and holds them for assertion + evidence.
Thread-safe: the HTTP server runs on a background thread while the run loop reads
snapshot() on the main thread. clear() between scenarios scopes the exchanges.
refused_bearer_count
property
¶
How many bearer headers with this run's token a non-loopback binding refused.
nonce_count
property
¶
How many signed requests this collector has accepted, one nonce each.
add(data)
¶
Validate and store one reported exchange.
A payload that fails validation is dropped rather than raised, so an SDK change can't break
the run mid-flight (forward-compatible, matching NetworkExchange's extra="ignore").
add_transition(data)
¶
Validate and store one reported screen-transition event (BE-0310).
Same forward-compatible drop-on-failure behavior as add, and stored in its own list so
the readiness/settled signal never depends on network-capture state.
enqueue_command(capability, *, enabled)
¶
Queue one command for the app to drain, and return the id that identifies it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
capability
|
ToggleCapability
|
which piece of bajutsu's in-app instrumentation the command addresses. |
required |
enabled
|
bool
|
the state that capability should take. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The command's id, to condition-wait on through |
enqueue_stub_table(mocks)
¶
Queue a replacement of the app's whole stub table, and return the id that identifies it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mocks
|
Sequence[Mock]
|
the table the app should serve from now on, replacing the one it launched with; empty removes every stub. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The command's id, to condition-wait on through |
drain_commands()
¶
Take every pending command, leaving the queue empty.
Draining under the lock bounds delivery at at most once: two polls racing cannot both take the same command and have the app apply it twice. It buys nothing about the reply — the queue is emptied before the response is written, so a reply lost in flight (a killed app, a client timeout, a reset peer) is not redelivered. That loss surfaces as the acknowledgement wait's loud timeout (BE-0365 unit 3), never as a second application, so a caller must not read a successful drain as proof the app received anything.
record_report(data)
¶
Store the app's report on one command; false when it names no command this run issued.
Refusing a payload rather than dropping it is the one place this collector departs from
add / add_transition's forward-compatible drop: a report is the only news the
acknowledgement wait ever gets, so one bajutsu cannot read has to fail visibly (the handler
answers 400) instead of leaving the wait to time out as though the app had stayed silent.
Requiring the id to be one this run issued is the same guarantee against a stale report
straggling in across a clear() and releasing the next scenario's wait.
Neither refusal is recorded anywhere else, so the wait a refused report was meant for still fails by timing out rather than by naming the report bajutsu turned away.
report_for(command_id)
¶
The app's report on this command, or None while none has arrived.
Three answers, none of them collapsed into another: None keeps the acknowledgement wait
waiting, applied=False fails it at once with the app's own reason, and applied=True
releases it (BE-0365 unit 3).
check_token(candidate)
¶
Constant-time compare of a presented token against this run's token.
Mirrors serve's own token check; false before start() mints a token.
check_bearer(candidate)
¶
Whether a bearer header may authenticate: on the loopback binding alone (BE-0459).
Beyond the loopback the token would cross the network in cleartext, so every bearer is refused there. One that carries this run's token is counted — an app built against a BajutsuKit that predates signing — and a made-up value is not, so a stranger reaching the listener cannot raise a false warning.
nonce_spent(nonce)
¶
Whether a signed request with this nonce has already been accepted.
claim_nonce(nonce)
¶
Record a verified request's nonce; False when another copy already claimed it.
The check and the record are one step under the lock, so of two copies handled at once on the server's threads exactly one passes.
snapshot()
¶
The exchanges received so far, in arrival order.
snapshot_timed()
¶
Each exchange with its receive time (monotonic), in arrival order.
transitions_snapshot_timed()
¶
Each observed screen-transition event with its receive time, in arrival order.
clear()
¶
Drop everything scoped to one scenario — exchanges, transitions, and channel state.
start(port=0, *, host='127.0.0.1')
¶
Start the receiver and begin accepting the app's POSTs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
port
|
int
|
TCP port to bind; |
0
|
host
|
str
|
The address to bind. The loopback, unless the app runs on a real device that does
not share it; |
'127.0.0.1'
|
Returns:
| Type | Description |
|---|---|
int
|
The actual bound port (resolved when |
int
|
|
start_bridgeable()
¶
Start the receiver on a port a leased device can mirror, for the adb reverse bridge.
start()'s OS-chosen port is host-local, but the adb backend tunnels the collector with
adb reverse tcp:<port> tcp:<port> (BE-0283) — the emulator has to bind the same number.
An OS-chosen port comes from the host's ephemeral range, which is the guest's as well
(32768-60999 on Linux), so it lands where the emulator is already handing ports out to its
own sockets; when the guest happens to hold that one, adbd's bind fails and the bridge dies
with cannot bind listener: Address already in use, taking the lease with it. Any guest
socket collides, not just a listener — an outbound connection, or one left in TIME_WAIT.
Preferring a band below both ephemeral ranges removes that collision class rather than narrowing it: nothing on either side allocates these ports by chance, so the number is free on the device precisely because it was free on the host.
Returns:
| Type | Description |
|---|---|
int
|
The bound port, as |
Raises:
| Type | Description |
|---|---|
OSError
|
no reserved-band port was bindable. An occupancy error (EADDRINUSE) on one port advances to the next; any other bind error, and exhausting the whole band, raise rather than fall back to an OS-chosen ephemeral port — that fallback would sit in the shared range and reopen the guest-side collision this method removes. |
stop()
¶
Stop the receiver and release its socket. Idempotent — a no-op if never started.
NetworkExchange
¶
Bases: BaseModel
One request/response the app reported.
Extra keys from the SDK are ignored (forward-compatible); field names accept their JSON aliases.
ScreenTransition
¶
Bases: BaseModel
One screen-transition event the app's BajutsuScreen observer reported (BE-0310).
Minimal by design: no screen content, only what a positive "the transition finished"
signal needs. Extra keys are ignored and the app's own timestamp is informational only —
the collector stamps its own receive time (snapshot_timed), the same monotonic clock
domain the readiness gate and the settled wait already poll in, so nothing here depends on
the app process's separate clock.