Skip to content

fix: report a timeout or budget limit instead of folding it into "no match" - #8

Merged
tannevaled merged 2 commits into
mainfrom
fix/report-timeout-and-budget
Oct 5, 2026
Merged

tannevaled merged 2 commits into
mainfrom
fix/report-timeout-and-budget

Conversation

@tannevaled

@tannevaled tannevaled commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

The defect

Every match path in regexp.go collapsed on the same line:

caps, matched, err := vm.MatchTimeoutFrom(m.prog, s, from, vm.DefaultBudget, re.deadline())
if err != nil || !matched {
	return 0, 0, false
}

ErrTimeout and ErrBudget were folded into a clean non-match. For a Regexp
used as a validator, a denylist or any other guard that is fail-open: a
crafted subject reads as "the guard did not fire" and passes the check. Ruby's
Regexp::TimeoutError exists to prevent exactly this, and the Ruby layers above
this package could never raise it, because the information did not leave the
engine.

This did not need a timeout to be configured. ErrBudget is reached under
the default DefaultBudget on a catastrophically backtracking pattern:

subject (a+)+\1b result (before)
"a"*20 0.166 s no match, err == nil (search completed)
"a"*22 0.688 s no match, err == nil (search completed)
"a"*24 0.873 s ErrBudget, swallowed into "no match"
"a"*26 0.829 s ErrBudget, swallowed into "no match"
"a"*28 0.822 s ErrBudget, swallowed into "no match"

So the fail-open was reachable at the default settings, not only when a
caller had asked for a limit.

Change 1 — the limits are reportable

ErrTimeout and ErrBudget are exported, and four …Err methods report them:

method serves
MatchBoundsErr(s) MatchString, Match, MatchBounds, FindStringIndex, FindString
MatchBoundsAtErr(s, pos) MatchBoundsAt
FindStringSubmatchIndexErr(s) FindStringSubmatchIndex, FindStringSubmatch, FindAll*, ReplaceAll*
FindStringSubmatchIndexAtErr(s, pos) FindStringSubmatchIndexAt

These are the four internal funnels every other match method already went
through, so this is the complete set of places a limit can be reached — not a
sample. Nothing new can reach a limit without going through one of them.

The standard-library-shaped methods keep their signatures and still fold both
reasons into "no match". Their doc comments now say so and name the …Err twin,
and TestNonErrFormsStillFoldTheLimit pins that shape across all twelve of them,
so the divergence from regexp.Regexp is a recorded decision rather than an
accident waiting to be "fixed" by someone adding a thirteenth.

Change 2 — the anchored paths carried no deadline at all

MatchBoundsAt and FindStringSubmatchIndexAt called vm.MatchAt — the
budget-only entry point — so WithTimeout was silently ignored on every
anchored match, however small the limit. They now call vm.MatchTimeoutAt with
re.deadline(); that function already existed, it was simply never wired up.

Measured through the Ruby layers above this one, String#rindex (which probes
one anchored start position after another) on a 26-byte subject with a 0.05 s
limit:

before after
"a"*26.rindex(/(a+)+\1b/) with timeout: 0.05 3.593 s (72× over) 0.128 s

What does not change

  • The lazy-NFA subset cannot reach either limit. TestLazyNFASubsetReportsNoError
    asserts err == nil there, so a caller cannot be handed a spurious refusal —
    including for (a+)+b, the classic one-line ReDoS, which is linear here.
  • Every input that does not reach a limit behaves identically through every
    method, …Err or not.
  • FindAll* and ReplaceAll* keep ending their walk at a reached limit with
    the results found so far, exactly as a genuine non-match ends it. That family
    has no channel to report the difference; the comments in allMatches and
    replaceAll now say so and point at the …Err primitives. This is the
    one remaining fail-open surface in the package
    and it is deliberate: the
    alternative is seventeen …Err twins, of which the 100 % coverage gate would
    make thirteen dead weight. The Ruby layer does not use that family — it drives
    its own scan loop over the primitives.

Cost

Both additions sit on every match: one type assertion on the VM's class-level
default in the Ruby layer's matcher, and one extra error return per call. Measured through the
repo's own Ruby-level regexp benchmarks (internal/vm/bench_test.go), origin/main
vs this branch, interleaved main/fix over 5 rounds at -benchtime=2s on an
otherwise idle machine, from pre-built test binaries:

benchmark origin/main median this branch median delta within-side noise floor
InlineRegexpMatch 877,811 ns/op 877,951 ns/op +0.02 % 4.71 % (main), 1.37 % (fix)
InlineRegexpScan 2,164,617 ns/op 2,162,340 ns/op −0.11 % 1.28 % (main), 0.46 % (fix)

Allocations are identical — 10,982 allocs/op on Match and 34,331 on Scan
on both sides, with byte counts agreeing to within a few bytes of 424 KB and
1.977 MB. The deltas are an order of magnitude below the run-to-run spread within
each side, so the honest statement is no measurable cost, in either direction.
The zero-limit path allocates nothing new by construction: with both limits unset
the type assertion fails and matcher returns the receiver's engine Regexp
unwrapped, exactly as before, and the VM never reads the clock.

Verification

  • go test -race with the CI's -coverpkg: all green, coverage 100.0 % (the
    gate this repo enforces).
  • gofmt -l clean on regexp.go, replace.go and the new test file. (gofmt -l .
    reports 18 files on this repo, all of them pre-existing test files untouched by
    this change — git stash && gofmt -l . | wc -l gives the same 18 on origin/main.)
  • GOOS=wasip1 / GOOS=js (GOARCH=wasm) builds: both green.

Paired PRs

This is one of three. None of them is useful alone:

Merge order is this PR, then the wrapper, then rbgo; each downstream go.mod
currently points at the upstream branch commit and needs re-pointing at the
tagged release as each merges.

🤖 Generated with Claude Code

tannevaled and others added 2 commits October 5, 2026 15:43
…match"

A match abandoned at a limit was indistinguishable from a subject that
genuinely does not match: every match path collapsed on

	if err != nil || !matched { return 0, 0, false }

so ErrTimeout and ErrBudget both read as a clean non-match. For a Regexp
used as a validator or a denylist that is fail-open — a crafted subject
reads as "the guard did not fire" and passes the check. Ruby's
Regexp::TimeoutError exists to prevent exactly this, and could never be
raised through this API because the information did not leave the engine.

Two things change.

1. ErrTimeout and ErrBudget are exported, and four `…Err` methods report
   them: MatchBoundsErr, MatchBoundsAtErr, FindStringSubmatchIndexErr and
   FindStringSubmatchIndexAtErr. They are the four internal funnels every
   other match method already went through, so this is the complete set of
   places a limit can be reached — not a sample. The standard-library-shaped
   methods keep their signatures and still fold both reasons into "no
   match"; their doc comments now say so and point at the `…Err` twin, and
   a test pins that shape so it is a recorded decision rather than an
   accident.

   ErrBudget needs no timeout to be configured to be reached: on `(a+)+\1b`
   against "a"*26 the default budget is exhausted in ~0.83s, so the
   fail-open was reachable at the default settings, not only when a caller
   had asked for a limit.

2. The anchored paths carried no deadline at all. MatchBoundsAt and
   FindStringSubmatchIndexAt called vm.MatchAt, the budget-only entry point,
   so WithTimeout was silently ignored on every anchored match however small
   the limit. They now call vm.MatchTimeoutAt with re.deadline(), which
   already existed. Measured through the Ruby layer above this one,
   String#rindex on a 26-byte subject with a 0.05s limit took 3.593s before
   and 0.128s after.

No behaviour changes on the lazy-NFA subset, which cannot reach either
limit; a test asserts err is nil there, so a caller cannot be handed a
spurious refusal. The non-Err methods are unchanged for every input that
does not reach a limit.

Paired with go-ruby-regexp/regexp and go-embedded-ruby/ruby#776, which
cannot report Regexp::TimeoutError without this.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The README's only timeout row named `WithTimeout`/`Timeout` and nothing about
what a reached limit reports. `ErrTimeout` and `ErrBudget` appeared nowhere in
it, although they are now the package's safety contract: a caller who reads only
this table takes away the old model, in which a limit is silently a non-match.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@tannevaled
tannevaled merged commit d10226a into main Oct 5, 2026
11 checks passed
@tannevaled
tannevaled deleted the fix/report-timeout-and-budget branch October 5, 2026 16:01
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.

1 participant