One package for what rproxy and waf send each other #425

Open
opened 2026-11-19 17:12:14 +01:00 by clawbot · 2 comments
Collaborator

From the architecture review, "What rproxy and discriminator send each other": #283 (comment). Approved for building: #283 (comment). The code was read at 809d266 on next, where discriminator is now waf. Line numbers are that commit's.

What is there

  • SPEC's "waf" section defines three messages between the two daemons: the question, the answer and the report. No package owns them.
  • The names live in internal/waf (waf.go, proxy.go). rproxy's production code imports waf for eleven of them: ClientHeader, PeerHeader, ContentLengthHeader, DispositionHeader, DispositionAllow, DispositionDeny, DispositionClose, QuestionBodyMaxBytes, ReportPath, HealthPath and the type Report.
  • Each message is written in one package and read in the other:
    • the question: newQuestion (internal/rproxy/waf.go) writes it; readQuestion and asTheVisitorSentIt (internal/waf/waf.go) read it;
    • the answer: allow, deny and setLookupHeaders in waf write it; noteAnswer in rproxy reads it;
    • the report: finish and postReport in rproxy write it; readReport in waf reads it.
  • Five values both sides must agree on are declared twice, once in each package:
    • requestIDHeader;
    • asnHeader;
    • countryHeader;
    • ownEndpointPrefix;
    • the highest status a report may give: reportStatusMax in internal/rproxy/request.go, maxHTTPStatus in internal/waf/waf.go.

Why it matters

  • Importing waf makes rproxy depend on every package the decisions use: the Core Rule Set, the ban ledger, the lookups, the state files. rproxy needs only the format of the messages.
  • A change to a message is made in two packages. Only the tests that start both daemons show whether the two halves still agree. newQuestion and asTheVisitorSentIt must mirror each other header for header, and nothing pairs them.
  • A duplicated name that drifts compiles, and fails only when the daemons are up.

What changes

  • One new package under internal/ owns the three messages. Default name: internal/wafprotocol. Changing the name later is one commit.
  • It holds:
    • the header names, the three dispositions, QuestionBodyMaxBytes, ReportPath, HealthPath, the /_sww/ prefix and the highest report status, each declared once;
    • Report, with its range check;
    • for the question and for the answer, one function that writes it and one that reads it, moved from the two packages;
    • for the report, the code that encodes it and the code that reads it;
    • a test that passes each message through its writer and then its reader.
  • rproxy, waf and sww import it.

What stays

  • MetricsPath, BansPath and ClientsPath stay in waf: rproxy never uses them.
  • What waf does with a question once it is read stays in waf: refusing a second question with an id it holds, the 400 answer and its log message.
  • peerAddress, isInside, scheme and the two responseWriter types stay once in each package. Each is a few lines, the two scheme functions differ, and a shared home for them would be the util package the Go style guide bans.
  • No message changes: every header, path, field and status stays as SPEC gives it.

Done when

  • the new package holds the above, and no value both daemons must agree on is declared twice;
  • no non-test file of internal/rproxy imports internal/waf;
  • SPEC's package list under "Architecture" names the new package, and no longer says internal/waf holds the question, answer and report;
  • behaviour is unchanged: every existing test passes with no assertion changed;
  • make check passes;
  • the PR body lists every new package, file, type and exported function name. Each says what the thing is to a reader of that one file, the standard of the symbol names audit (#213).

If this is more than one PR can carry, say so on this issue instead of starting.

Model: fable-5-2

From the architecture review, "What `rproxy` and `discriminator` send each other": https://git.eeqj.de/sneak/smallwebwaf/issues/283#issuecomment-173839. Approved for building: https://git.eeqj.de/sneak/smallwebwaf/issues/283#issuecomment-183550. The code was read at `809d266` on `next`, where `discriminator` is now `waf`. Line numbers are that commit's. ### What is there - SPEC's "`waf`" section defines three messages between the two daemons: the question, the answer and the report. No package owns them. - The names live in `internal/waf` (`waf.go`, `proxy.go`). `rproxy`'s production code imports `waf` for eleven of them: `ClientHeader`, `PeerHeader`, `ContentLengthHeader`, `DispositionHeader`, `DispositionAllow`, `DispositionDeny`, `DispositionClose`, `QuestionBodyMaxBytes`, `ReportPath`, `HealthPath` and the type `Report`. - Each message is written in one package and read in the other: - the question: `newQuestion` (`internal/rproxy/waf.go`) writes it; `readQuestion` and `asTheVisitorSentIt` (`internal/waf/waf.go`) read it; - the answer: `allow`, `deny` and `setLookupHeaders` in `waf` write it; `noteAnswer` in `rproxy` reads it; - the report: `finish` and `postReport` in `rproxy` write it; `readReport` in `waf` reads it. - Five values both sides must agree on are declared twice, once in each package: - `requestIDHeader`; - `asnHeader`; - `countryHeader`; - `ownEndpointPrefix`; - the highest status a report may give: `reportStatusMax` in `internal/rproxy/request.go`, `maxHTTPStatus` in `internal/waf/waf.go`. ### Why it matters - Importing `waf` makes `rproxy` depend on every package the decisions use: the Core Rule Set, the ban ledger, the lookups, the state files. `rproxy` needs only the format of the messages. - A change to a message is made in two packages. Only the tests that start both daemons show whether the two halves still agree. `newQuestion` and `asTheVisitorSentIt` must mirror each other header for header, and nothing pairs them. - A duplicated name that drifts compiles, and fails only when the daemons are up. ### What changes - One new package under `internal/` owns the three messages. Default name: `internal/wafprotocol`. Changing the name later is one commit. - It holds: - the header names, the three dispositions, `QuestionBodyMaxBytes`, `ReportPath`, `HealthPath`, the `/_sww/` prefix and the highest report status, each declared once; - `Report`, with its range check; - for the question and for the answer, one function that writes it and one that reads it, moved from the two packages; - for the report, the code that encodes it and the code that reads it; - a test that passes each message through its writer and then its reader. - `rproxy`, `waf` and `sww` import it. ### What stays - `MetricsPath`, `BansPath` and `ClientsPath` stay in `waf`: `rproxy` never uses them. - What `waf` does with a question once it is read stays in `waf`: refusing a second question with an id it holds, the 400 answer and its log message. - `peerAddress`, `isInside`, `scheme` and the two `responseWriter` types stay once in each package. Each is a few lines, the two `scheme` functions differ, and a shared home for them would be the `util` package the Go style guide bans. - No message changes: every header, path, field and status stays as SPEC gives it. ### Done when - the new package holds the above, and no value both daemons must agree on is declared twice; - no non-test file of `internal/rproxy` imports `internal/waf`; - SPEC's package list under "Architecture" names the new package, and no longer says `internal/waf` holds the question, answer and report; - behaviour is unchanged: every existing test passes with no assertion changed; - `make check` passes; - the PR body lists every new package, file, type and exported function name. Each says what the thing is to a reader of that one file, the standard of the symbol names audit (https://git.eeqj.de/sneak/smallwebwaf/issues/213). If this is more than one PR can carry, say so on this issue instead of starting. Model: fable-5-2
clawbot self-assigned this 2026-11-19 17:12:14 +01:00
Author
Collaborator

PR: #461, branch issue-425-wafprotocol-package.

New package internal/wafprotocol writes and reads the question, the answer and the report, and declares each shared header, path and limit once. internal/rproxy no longer imports internal/waf. SPEC's and README's package lists name the new package. The PR body lists every new name.

Disclosure: the process warning for a question whose body stops arriving now prefixes its error field with "the body stopped arriving: ".

Model: opus-5-5

PR: https://git.eeqj.de/sneak/smallwebwaf/pulls/461, branch `issue-425-wafprotocol-package`. New package `internal/wafprotocol` writes and reads the question, the answer and the report, and declares each shared header, path and limit once. `internal/rproxy` no longer imports `internal/waf`. SPEC's and README's package lists name the new package. The PR body lists every new name. Disclosure: the process warning for a question whose body stops arriving now prefixes its `error` field with "the body stopped arriving: ". Model: opus-5-5
Author
Collaborator

Once #464 lands, the dispositions are the type waf.Disposition, which moves with them. The new package sits below config and requestlog, so config.RProxy.WAFBackendNoAnswerDisposition and requestlog.Line.Disposition can then take that type; today they cannot, because waf imports both.

Model: opus-5-5

Once https://git.eeqj.de/sneak/smallwebwaf/pulls/464 lands, the dispositions are the type `waf.Disposition`, which moves with them. The new package sits below `config` and `requestlog`, so `config.RProxy.WAFBackendNoAnswerDisposition` and `requestlog.Line.Disposition` can then take that type; today they cannot, because `waf` imports both. Model: opus-5-5
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/smallwebwaf#425