feat: per-route timeout and throttle (#140) - #253

… parsing

Adds per-route Timeout (time.Duration) and Throttle (int) fields to the
URLMapper struct. Zero values preserve existing global-fallback behavior.

extendMapper now propagates both fields through the simple-extension path
so routes like /api/ -> /dst/ don't silently lose per-route config before
reaching Match().

File (yaml) provider parses timeout as a duration string and throttle as
int. Negative timeout/throttle values surface as parse errors.

Part of plan 20260512-per-route-timeout-throttle.md (Task 1 of 10).

Extend rule format from server,source,dest[,ping[,forward-health-checks]]
to server,source,dest[,ping[,forward-health-checks[,timeout[,throttle]]]].
Empty positional fields inherit global defaults; invalid duration,
non-integer throttle, or negative values return parse errors at startup.

Read reproxy.<n>.timeout and reproxy.<n>.throttle labels via the
existing labelN helper. Invalid duration, non-integer, or negative
values warn and fall back to zero (matches the warn-and-zero pattern
of forward-health-checks/keep-host), so a single bad label cannot
crash discovery for the entire fleet.

Parse reproxy.timeout and reproxy.throttle labels with warn-and-zero
semantics matching the docker provider behavior.

When a matched URLMapper has Timeout > 0, wrap the request context with
context.WithTimeout and override the connection's read/write deadlines via
http.ResponseController. The middleware runs immediately after matchHandler
and before per-route auth/throttle so auth and limiter work runs inside the
per-route deadline. http.ErrNotSupported from ResponseController is treated
as expected (context timeout still propagates).

When matched route has Throttle > 0, apply a per-route rate limiter keyed
by [ip, dst] so per-user behavior is preserved while the route gets its
own bucket. Cache route limiters in a sync.Map keyed by server|src|rate;
including rate in the key means config edits produce new limiters on
next request.

Build the global limiter lazily via sync.Once and drop the early-return
to passThroughHandler when global rate is 0 — that path now still
consults per-route Throttle, so route overrides work even when the
global throttle is disabled.

Add integration test that wires up a real Http server with provider.File
pointing at a fixture with four routes (timeout, throttle, both, control).
Tests verify per-route timeout fires and returns 502, throttle blocks
excess rapid requests with 429, chain ordering keeps throttle 429 inside
the deadline window, and control route remains unaffected.

While building the test, two behaviors needed implementation fixes:

- routeTimeoutHandler now sets the write deadline 500ms after the ctx
  deadline (writeDeadlineGrace) so the proxy's default ErrorHandler can
  flush 502 to the client before the conn is severed; without the grace
  ctx and conn-write fire simultaneously and the client sees EOF instead
  of the documented 502.
- Both read and write deadlines are reset to zero in a defer so kept-alive
  connections do not carry expired deadlines into subsequent requests.

Updated the Task 5 deadlines unit test to verify both the arm and the
deferred clear, and the plan file to document the discovered behaviors.

Add provider-specific documentation for the new per-route timeout and
throttle options across file, static, docker, and consul-catalog providers.
Add a "Per-route timeout and throttle" subsection covering global-vs-per-route
precedence, the write-deadline override, and the response-header-timeout
limitation.

Mark Task 10 final steps complete and relocate the plan file under
docs/plans/completed/ now that all implementation, tests, README updates,
and acceptance verification have landed.

Rename local variable in file.List() from d to dur to avoid shadowing
the *File receiver d. The shadowing was harmless in scope (no receiver
calls inside the block) but flagged by smells analysis as a readability
issue inconsistent with the consulcatalog provider, which already uses
dur for the same parsed duration.

- handlers.go: use NUL separator in route limiter cache key to avoid
  collisions when regex source contains pipe characters
- handlers.go: drop unnecessary sync.Once for global limiter; build
  eagerly at handler construction
- handlers.go: log non-ErrNotSupported errors when clearing connection
  deadlines, consistent with the setter side
- handlers.go: expand godoc on limiterUserHandler and routeTimeoutHandler
  to document key composition and connection-deadline side effects
- file.go: replace contradictory "can't parse N: negative duration"
  error wording with the static provider's non-negative phrasing
- consulcatalog.go: move timeout/throttle label parsing below the
  enabled check so disabled services don't emit parse warnings
- README.md: clarify that empty positional fields skip optional values
  rather than inherit non-existent global defaults
- CLAUDE.md: list per-route overrides on the URLMapper summary