Skip to content

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 report_for (BE-0365 unit 3).

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 report_for (BE-0365 unit 4).

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 requests an ephemeral port.

0
host str

The address to bind. The loopback, unless the app runs on a real device that does not share it; "::" then binds every IPv4 and IPv6 interface, which the per-run token every request must prove keeps closed to anything but this run's app. Beyond the loopback, a request signs with the token rather than carrying it (BE-0459).

'127.0.0.1'

Returns:

Type Description
int

The actual bound port (resolved when port is 0), to inject into the app via

int

BAJUTSU_COLLECTOR.

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 start() does.

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.

query_params cached property

The URL-decoded query parameters, every occurrence kept; ?debug reads as "".

request_json_object cached property

The request body parsed as a JSON object, or None when absent, not JSON, or not an object.

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.