Skip to content

email security: document the replay budget on POST /rules/backtest and POST /hunts - #399

Merged
maximelb merged 1 commit into
mailsec-read-governor-docsfrom
mailsec-post-read-governor-docs
Sep 9, 2026
Merged

email security: document the replay budget on POST /rules/backtest and POST /hunts#399
maximelb merged 1 commit into
mailsec-read-governor-docsfrom
mailsec-post-read-governor-docs

Conversation

@maximelb

@maximelb maximelb commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Documents the second Email Security read budget added by lc_api-go#946 — the one covering POST /rules/backtest and POST /hunts.

Stacked on #389 deliberately. That PR introduces the ## Read budgets section for the two GET reads; this extends it rather than opening a competing section, so the base here is mailsec-read-governor-docs and not master. Merge #389 first.

What it says

  • The section now has two subsections — The query budget (unchanged, docs(email-security): the read budget, and why free text needs a window [HOLD until the gateway ships to prod] #389's) and The replay budget — with an opening paragraph saying why there are two: the reads are expensive in different resources, are counted separately, refill on different clocks, and carry different rate_bucket values.
  • The replay budget in the terms a customer can act on: it is counted in messages re-read, one call is charged the most it could re-read (2,000), the allowance is 12,000 per 10 minutes = 6 backtests per 10 minutes across every credential in the org, and it fails open.
  • rate_bucket: mailsec_post_read is not mailsec_read, stated explicitly with the consequence: a client that treated them as one budget would retry a backtest on advice that does not apply to it.
  • The honest bit the query budget's advice does not carry over: no narrower request shape takes a backtest out of this budget — the charge is the same whatever window you name. A filtered search leaves the query budget entirely; a narrower backtest does not. Asking for a narrower window is still worth doing, and the text says why (speed, not budget).
  • Why POST /hunts is counted while it still answers not_implemented: budgeting it on the day the engine lands would be a change of contract for clients that had already shipped.
  • Notes on the two pages a rule author actually reads — custom-rules.md (under Backtesting) and cli.md (beside rule backtest).

Held

This must not be merged until the gateway reaches production. The docs site publishes on merge, and until lc_api-go#946 ships to api.limacharlie.io this page would tell customers their backtests are budgeted while they are not.

Anchors were checked by hand — this repository does not validate URL fragments. #the-replay-budget and #registered-but-not-implemented-yet both resolve, and the existing #read-budgets links from automation.md, cli.md and messages.md still resolve because the H2 is unchanged.

…d POST /hunts

The read-budget section documented in documentation#389 covers the two GET reads,
which are priced in database work. The rule backtest is priced in something else
entirely: it re-reads every stored message in its window — fetch, decrypt,
decompress, parse, evaluate — so it carries its own budget, its own rate_bucket
and its own refill window.

Says what a client actually needs: that mailsec_post_read is NOT mailsec_read
and must not be retried on the other's advice, that 6 backtests per 10 minutes
is the allowance across every credential in the organization, that it fails open
like its sibling, and that no narrower request shape takes a backtest out of the
budget the way a filtered search leaves the query budget.

Also states why POST /hunts is counted while it still refuses: budgeting it on
the day the engine lands would be a change of contract for clients that shipped
against it first.

Stacked on documentation#389 because it extends that PR's Read budgets section.
@maximelb

maximelb commented Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

merge with the prod release

@maximelb
maximelb merged commit b1381b9 into mailsec-read-governor-docs Sep 9, 2026
7 checks passed
@maximelb
maximelb deleted the mailsec-post-read-governor-docs branch September 9, 2026 15:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants