ADR 0008: Validate the whole signal before any broker call¶
- Status: Accepted
- Date: 2026-11-11
Context¶
Before this step the handler read the webhook lines field by field and the use case validated them only as far as it got. The roadmap's defect list pinned what that cost:
- With
Invert, any direction other than exactlybuy(Buy,BUY) opened a buy. WithNonInvertit was sent to the broker unchanged. - An invalid
Invert/NonInvertflag stopped anopenonly after the instrument's positions were closed, leaving the account flat. - A malformed lot crashed the handler after the balance read. A lot that
parsed but made no sense (
0/100,-0.01/100,inf/100,nan/100) was sent to the broker as quantity 0, negative, infinite or NaN. - An unknown action, including
Openoropen, was silently ignored. - A truncated payload or a non-numeric take profit or stop loss raised an
IndexErrororValueErrorin the webhook thread. closeneeded valid lot, take profit, stop loss and inversion lines that it never used.
Decision¶
- The payload is parsed into a domain signal before the lock and before
any broker call.
parse_signalintradelocker_bot.domain.signalreturnsOk(OpenSignal | CloseSignal)orErr(InvalidSignal). The use case only ever receives a valid signal, andExecuteSignal.executekeepsBrokerFailureas its only error (ADR 0006). - Rejection. An
Erris reported by one red operator line, for exampleSignal rejected: line 2 (direction) is 'long', expected buy or sell. It makes no broker call, does not take the lock and raises nothing, so the webhook thread ends normally. The owner chose this over also raising: the line says everything a traceback would. Only the first line that stops the signal is reported. The webhook still answers200 OKbefore handling. Answering the caller is step 6. Update: step 6k kept the answer as it is: it acknowledges receipt, not the outcome (ADR 0023). - Case and surrounding spaces. The owner decided that they do not change
what a direction (line 2) or an action (line 6) means.
Buy,SELL,Openandcloseare accepted. Anything else is rejected. Line 7 was not part of that decision and stays exact:InvertorNonInvert. closereads only what it uses. The owner decided this too: junk in a lineclosenever reads must not keep a position open.closeneeds lines 1 and 6 only, so a six-linecloseis complete. Because it sizes nothing,closeno longer reads the account balance. That removes one broker call from a valid signal, and the call-sequence pins change accordingly.openneeds every line, read in order 2, 3, 4, 5, 7 after the symbol and the action:- Direction:
buyorsellas in item 3. - Lot:
<lot>/<balance step>, both positive and finite. The rule sits inLotSizing's constructor, so no code path can build a sizing that is zero, negative, infinite or NaN. - Take profit and stop loss: whatever
int()accepts. - Inversion: resolved here into the side to trade, so it can no longer fail after a close.
- Direction:
- What is not on the defect list is kept. Input that worked before stays
accepted, so a change here cannot break a running strategy unannounced:
- spaces around the lot numbers;
- signs, spaces, zero and negative values in the offsets;
- lines after the seventh, which are still ignored;
- the symbol, which is used verbatim; only a blank one is rejected.
- The rejection line escapes the value. The value comes from the
webhook, and
splitlines()keeps control characters such as ESC in a line. The console prints it withreprand cuts it after 40 characters, so a payload cannot colour, rewrite or flood the operator's log.
Not in this step¶
Some rejections need the broker's answer. They stay pinned as defects until roadmap step 3b, which must refuse each of them before the first close request:
- an account state without a balance, still a
TypeError; - an unknown symbol, still the client's
ValueError, raised after the balance read; - a quantity that is unusable once the balance is known: zero when the
balance is too small for it to round above zero, infinite when the product
overflows (
1e306/1). Both are still sent to the broker.
Update: step 3b
(ADR 0009) refuses
all three before any close request. A broker-side refusal is a second error
kind of execute, next to BrokerFailure, so decision 1's "only error" no
longer holds.
Consequences¶
- The frozen webhook contract changes: lines 2 and 6 now ignore case and
surrounding spaces, and
closeneeds lines 1 and 6 only. Every alert that was handled correctly before is still handled the same way, except thatcloseno longer reads the balance. - Some alerts that did nothing before now trade. An action such as
Openorcloseused to be ignored, and aclosewith an invalid unused line used to crash. Both now act. A strategy that relied on either, knowingly or not, changes behaviour on upgrade. The README's Updating section says so. - Every input error is visible to the operator by line number, in one line, instead of as a traceback or not at all.
- An invalid alert does not wait for the lock and does not hold it, so it cannot delay a valid one.
- ADR 0006's condition for step 5 is met for input errors. The missing balance still raises from the use case until step 3b.
order_sideis gone.Sideand itsoppositereplace it, and the broker port and the retry line take aSideinstead of a string.
Alternatives considered¶
- Validate inside the use case and return
Err(InvalidSignal)fromexecute. Rejected: the use case would accept text it cannot act on, and its callers would branch on two unrelated error types. Parsing at the edge gives the use case a type that cannot be invalid. - Report every invalid line at once. Rejected for now: one line is easier to read in a container log, and fixing the first usually reveals the rest.
- Accept
invert/noninverttoo. Not decided by the owner, and nothing sends them today. A later step can widen it if needed.