Home /Modules/http-3.0/FLOW.md

FLOW.md

http-3.0/station/FLOW.md · 120 line(s) · markdown

Station Signaling — Data Flow (Spec → Code)

Maps the Station design (STATION-SIGNALING-SPEC.md, J-STA-0001) to the source, and traces one negotiation from a TCP-flag signal to a witnessed outcome. Companion: STATUS.md.

The data, and where it lives

Spec conceptSectionType / symbolFile
TCP flag bits§2SL_TCP_*station_abi.h
8-URG magnitude§2.1urg_units, SL_STATION_URG_MAXstation_abi.h
HOP verbs (DIST±N)§3sl_hop_verb_t, sl_classify_hopstation_abi.h / station_classifier.c
Conditions§5sl_condition_t, sl_classify_conditionstation_abi.h / station_classifier.c
Premise triple§4sl_premise_t, sl_classify_signalstation_abi.h / station_classifier.c
Signal (raw evidence)§2sl_signal_tstation_abi.h
Witnessed record§8sl_record_tstation_abi.h
Session + state machine§6/§7sl_session_t, sl_session_signalstation_session.{h,c}
Witnessed view§7sl_session_view_t, sl_session_viewstation_abi.h / station_session.c
Known API (ioctl)§9SL_IOC_OPEN/SIGNAL/QUERY/CLOSEstation_abi.h
Kernel driver + hook§9sl_dev_ioctl, sl_nf_hookkernel/sleela_station.c
Userland transports§9sl_station_* (sim + device)station_backend.{h,c}

End-to-end trace (one signal → witnessed state)

          PARTY A / PARTY B  (two clients)
                │  emit a TCP segment on the signaling port
                │  flags = URG|ACK|... , urg_ptr = urg_units, hop field
                ▼
   ┌─────────────────────────────────────────────┐
   │  Router = STATION                            │
   │                                              │
   │  (kernel)  Netfilter PRE_ROUTING hook        │  kernel/sleela_station.c
   │    parse TCP flags/urg/hop -> sl_signal_t     │
   │      OR                                       │
   │  (userland) SL_IOC_SIGNAL / simulation        │  station_backend.c
   │    submit sl_signal_t directly                │
   │                │                              │
   │                ▼  §4/§5 classify (SHARED)     │  station_classifier.c
   │   sl_classify_signal(sig, current_open)       │
   │     -> condition, premise, hop_verb           │
   │                │                              │
   │                ▼  §6/§7/§8 fold + witness      │  station_session.c
   │   sl_session_signal(session, sig, &record)    │
   │     - append immutable record (seq++)         │
   │     - update this party's open_premise/ack    │
   │     - recompute joint state                   │
   │                │                              │
   │                ▼                              │
   │   state: OPEN -> CLEAR | UNCLEAR | HUNG-UP |  │
   │                          DISASTROUS           │
   └─────────────────────────────────────────────┘
                │  SL_IOC_QUERY / sl_station_query
                ▼
        sl_session_view_t  (witnessed outcome + record count)

Premise triple (the "8 URG with HOP = DIST±N")

A: urg=3 hop=DIST+1 (ADVANCE)  -> premise START          (opens)
B: urg=3 hop=DIST+1 (ADVANCE)  -> premise START
A: urg=5 hop=DIST+1 (ADVANCE)  -> premise INTERMEDIARY    (mediated) + ACK
B: urg=5 hop=DIST+1 (ADVANCE)  -> premise INTERMEDIARY               + ACK
   => both at INTERMEDIARY, both ACKed  => STATE = CLEAR

   any party: hop=DIST-1 (CANCEL) -> premise CANCELLING   => STATE = UNCLEAR
   any party: FIN                 -> HUNG-UP
   any party: RST                 -> DISASTROUS

HOP = DIST+0 (HOLD) re-asserts the current premise (witnessed, not advanced).

Condition classification (§5)

Flags + magnitudeCondition
URG, urg_units≥1INTENTIONAL
URG+ACK, urg_units==8LEGAL
URG+PSHWARNING
URG+PSH+ACK, urg_units==8EMERGENCY
no URG / urg_units==0NONE (bare ACK/keepalive)

Kernel / userland split (§9)

station_abi.h        <-- single ABI, included by BOTH sides
station_classifier.c <-- SHARED judgment (kernel #includes it; userland links it)
station_session.c    <-- SHARED state machine (same)

kernel/sleela_station.c   -> /dev/sleela_station (ioctl) + Netfilter hook
station/station_backend.c -> device backend (ioctl)  OR  simulation backend

The device and simulation backends expose the identical userland API, and both resolve to the same classifier/session code, so a negotiation witnessed in the kernel and one witnessed in userland reach the same verdict by construction.

Run it

cd http-3.0
make station        # build the userland Station + demo
make station-test   # run the manualog demo + Python parity tests
make test           # everything: pipeline + station + flow tests
make kernel-check   # confirms the kernel build scaffold (needs kernel headers to build the .ko)

# On a host with kernel headers:
cd kernel && make && sudo make load   # builds + inserts sleela_station.ko

Boundary note

The Station witnesses and records; it is an intermediary, not a party. A LEGAL condition records a legal framing, not an adjudication — consistent with the HTTP 3.0 principle that context is never authority. The stored terminal state is evidence of what the Station witnessed, distinct from any claim about what the parties intended.