docs(email-security): the message search is literal, and blank text is not a filter - #402
Open
maximelb wants to merge 3 commits into
Open
docs(email-security): the message search is literal, and blank text is not a filter#402maximelb wants to merge 3 commits into
maximelb wants to merge 3 commits into
Conversation
…s not a filter The API reference listed `q` among the message-index filters and said nothing about how the text is matched. It was matched as a SQL pattern, so `%` and `_` were wildcards: a search for `50% off` also returned `50 percent off`, and a lone `%` returned everything. The backend now matches the text literally (go-mailsec#163) and the gateway reads it once, trimmed (lc_api-go#947). This documents the contract that results: a literal, case-insensitive substring over subject and sender, whitespace ignored, whitespace-only text not a filter. Placed in "Shared behaviours" rather than in the `GET /messages` row so it does not collide with the held read-budget PR (#389), which rewrites that row.
Contributor
Author
|
merge with the prod release |
lcbill
previously approved these changes
Sep 9, 2026
Contributor
Author
|
/lc-review |
…listed, and correct the rate-limit claim Independent review of the free-text search docs. 1. The literal-search contract was published only in the API reference's shared behaviours. The page that documents the message-list filters still described `q` as "free-text over the message's identifying fields" — the sentence a reader looking up `q` actually lands on. It now says literal, names the two fields, and states the rules a caller trips over: no wildcards, whitespace ignored, needs something that bounds the read, 512 characters. 2. The EML download section claimed to be "the only [route] that is" rate-limited and that "No other Email Security route is rate-limited". That has been false since the read governor shipped: a `q` bounded only by time and a coverage call over an explicit window are counted per organization per read class and answer 429. The download quota's real distinction is that it fails CLOSED and the governor fails open, so that is what it now says.
Contributor
Author
|
/lc-review |
lcbill
previously approved these changes
Sep 9, 2026
lcbill
approved these changes
Sep 9, 2026
Contributor
Author
|
merge with the prod release |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Publishes the contract that go-mailsec#163 and lc_api-go#947 implement.
What was wrong. The API reference lists
qamong the message-index filters and saysnothing about how the text is matched. It was matched as a SQL pattern, so
%and_werewildcards and a backslash was an escape character: a search for
50% offalso returned50 percent off, a search forinvoice_2026also returnedinvoiceX2026, a lone%returned every message in the index, and
c:\tempreturned the row without the backslashand missed the one with it. None of that was documented, taught or refused — it was an
accident of the query, and the fix is to match literally rather than to document wildcards
nobody asked for.
What this adds. One bullet under "Shared behaviours":
qis a literal, case-insensitivesubstring over the message's subject and sender address;
%and_are ordinary characters;surrounding whitespace is ignored and whitespace-only text is not a filter.
It is placed in the shared-behaviours list rather than in the
GET /messagesrow on purpose:the held read-budget PR (#389) rewrites that row, and two PRs editing the same line would
collide at merge time. The two statements compose — that one is about what a search must be
accompanied by, this one about what the text means.
Hold. This describes behaviour that is not in production until the Email Security gateway
and collector ship there, and Email Security's prod rollout is on hold. Do not merge until
the prod release.