Skip to content

fix(conformance): leave a rule a transport-followed off-origin redirect touched not decided - #355

Merged
thomasfosterau merged 2 commits into
trunkfrom
issue-344-transport-redirects
Oct 15, 2026
Merged

thomasfosterau merged 2 commits into
trunkfrom
issue-344-transport-redirects

Conversation

@thomasfosterau

@thomasfosterau thomasfosterau commented Oct 15, 2026 •

Copy link
Copy Markdown
Owner

Summary

Closes #344.

A transport that follows redirects itself (one wrapped in HttpClient.followRedirects) and answered from another origin was recorded by runner as a lost response with unfollowed: Option.none(), so undecidedByRedirects never saw it. Reproduced on trunk before the fix: spec/links/resource-self-dereferences Passed with the link noted; on the write fixture the spec/errors/* rules Passed on 2 of 3 requests, and unknown-query-parameter, include-unsupported-endpoint and delete-response Failed with false "was not rejected" / "got no response" findings.

Per the owner's decision on #333 (comment), a rule any of whose requests went off-origin is now Skipped and names the redirects. It is never partially passed. A finding on an answered request still fails the rule.

Fix (src/internal/conformance/core.ts)

  • Unfollowed.reason gains "transport". runner checks where the transport ended: the request behind its answer, or behind its failure (HttpClientError.request). It records the request as unfollowed, naming the URL the transport ended at, when that request (transportFollowed):
    • is on another origin than the one the kit sent. This covers an off-origin hop that fails, such as a refused connection or a DNS failure, which over real sockets is the common case (review B1);
    • carries another method. followRedirects turns a 301/302 POST, or a 303 on anything but GET, into a GET, and the kit's own follower refuses that, so the answer is no longer read as the answer to the original method (review S1).
  • Both go through undecidedByRedirects like any other redirect the kit does not follow. A same-origin 307 the transport followed, keeping the method, is still read.
  • unfollowedNote uses status for this case (N2):
    • "a redirect the transport followed itself, ending at with a 200, whose answer the kit does not read: …";
    • or, with status: 0, "… ending in a transport error at : …".
  • The why states only the fact: " is another origin than the one the request was sent to, , and the transport has already tried the request there", or "the transport turned the DELETE into a GET on the way, which the kit does not send in its place". The remedy lives only in the reachable finding (N3).
  • The undecided clause and the reachable finding now say "a redirect the kit does not follow or read" (N4).

Nits carried from #344

  • reachable advice (spec.ts). The remedy depends on the reason:
    • "cap": shorten the chain;
    • "transport": pass a client that does not follow redirects itself;
    • "unparseable": "fix the server's Location, which is not a URL the kit can resolve" (N5);
    • otherwise: point baseUrl at the URL that serves the api.
  • Changeset. The pending (unreleased) .changeset/conformance-same-origin-redirects.md is amended rather than adding a new one:
    • it names redirects "by their request and Location";
    • it describes the transport case: off-origin or method change, answer or transport error;
    • it lists the reachable remedies.
  • docs/conformance.md §9:
    • reworded the pagination-walk sentence;
    • added the fifth undecidedByRedirects unit test;
    • described the transport cases (answered, refused, same-origin method change).
  • "Two limits remain" (§1.2, verifyWith JSDoc, changeset). These no longer claim that no request reaches another origin when the client follows redirects itself. They now say that only the final URL and method are checked, so a chain off the origin and back (A → B → A) that keeps the method is read, undetected (N1). They also say the request has been made either way.

#353 rules. The unsupported-family / bracketed probe driver (probeFirstUsable) no longer describes a probe answered by a redirect the kit did not follow as "a server error, a rate limit, a request timeout or a lost response…".

Tests (src/Conformance.test.ts; followingOffsite(moved, ends) is built on HttpClient.followRedirects, and ends: "refused" makes elsewhere.test fail with HttpClientError / TransportError):

  • Flipped: the resource-self-dereferences test that pinned Passed now pins Skipped, with the exact reason.

  • Write fixture, off-origin (it.each, 8 cases). Each of only ?unknown=1, only the DELETE, every request with a query, and only the POSTs is run × the other origin answering or refusing. In each case no rule fails, and every rule's verdict equals the kit-seen 302 run.

  • Exact reasons:

  • Same origin, method changed (it.each): a 303 on DELETE, a 303 on PATCH, a 302 on POST and a 301 on POST, each followed by the transport. Every verdict equals the run where the kit sees the same redirect and refuses it, and a reason names "the transport turned the into a GET on the way". Control: a 307 DELETE followed within the origin leaves every verdict as against the server directly.

  • reachable remedies:

    • a same-origin chain past the cap;
    • a transport following every request off-origin, answered or refused;
    • a Location that does not parse (http://[).

    Each gives its remedy, fails only reachable, and passes nothing.

Verification

  • pnpm install --frozen-lockfile: pass
  • vp run build: pass
  • vp check: pass (0 errors, 4338 warnings, the same count as before this commit; none on a line this PR adds)
  • vp run check (sources, type-level tests, examples, emitted declarations): pass
  • vp run -r test:unit: pass (root 3332 tests, examples 45 + 43 + 54)
  • vp run docgen (every JSDoc @example compiled and executed): pass
  • fallow audit --format json --quiet --explain --gate-marker agent: verdict pass
  • fallow audit --base origin/trunk: pass ("No issues in 15 changed files"; 17 inherited findings excluded)

Mutation checks. The tests were written first and failed on unfixed code. For this round, the review-fix tests failed on 7ee2e52: 10 failing, including all 8 off-origin cases and the 4 method-change cases. The 307 control failed only while its fixture looped, and was fixed in the fixture. Each mutant was run against src/ and then reverted:

Mutant Tests that fail
Failure branch ignores the request behind the error (B1) 6
Method check removed (S1) 4
Method read from the request sent, not response.request (S1) 4
Origin check removed 9
status: 0 recorded for an answered transport redirect (N2) 8
"unparseable" remedy removed (N5) 1
(round 1) Runner records the transport answer with no unfollowed 7
(round 1) reachable remedy always says "point baseUrl…" 2
(round 1) The #353 skip keeps the lost-response clause for a redirect 1

Examples. The full Conformance outcomes of the blog, github and northwind suites were dumped on 7ee2e52 and on this head. All 52 outcomes per suite (tag, reason, note, message, findings) are identical.

Changeset

  • Amended the pending, unreleased .changeset/conformance-same-origin-redirects.md (patch). It is not yet in CHANGELOG.md.

Notes

  • Unfollowed is @internal, so the new "transport" member changes no public signature.

  • Flag for the owner (S1). The review suggested reason "method" for a transport-followed method change. I used "transport" for both cases, for two reasons:

    • unfollowedNote spells "method" as "a <3xx> redirect to , which the kit does not follow", but here the kit never sees the 3xx and the transport did follow it;
    • reachable would then advise moving baseUrl, when only a non-following client cures it.

    The why names the method change.

  • Limits of S1. Only what the transport's final request shows can be checked: its origin and method. Three cases go undetected:

    • a chain off the origin and back (A → B → A) that keeps the method;
    • a 301/302 on PATCH or DELETE, which followRedirects re-sends unchanged, so nothing is visible;
    • hop counts against the cap or budget.

    The docs say so.

  • For "transport", location is the URL the transport ended at, named as sent, so brackets in a query appear percent-encoded.

🤖 Generated with Claude Code


Generated by Claude Code

…ct touched not decided (#344)

A transport that follows redirects itself (one wrapped in
HttpClient.followRedirects) answered from another origin was recorded as
a lost response with no `unfollowed`, so undecidedByRedirects never saw
it: spec/links/resource-self-dereferences passed with the link noted,
the spec/errors/* rules passed on 2 of 3 requests, and
unknown-query-parameter, include-unsupported-endpoint and delete-response
failed with false "was not rejected" / "got no response" findings.

The runner now records such an answer as a redirect the kit did not
follow, with a new Unfollowed reason "transport" naming the URL the
transport ended at, so the rule is skipped (owner decision on #333),
unless a finding on an answered request stands.

Also:
- spec/target/reachable tells the caller what to change by reason:
  shorten a same-origin chain past the hop cap, or pass a client that
  does not follow redirects, rather than always moving baseUrl.
- The unsupported-family / bracketed probes (#353) no longer call a
  redirect the kit did not follow a lost response in their own reason.
- Changeset: redirects are named by their request and Location.
- docs/conformance.md: section 1.2 limits, the section 9 sentence on the
  pagination walk, the fifth undecidedByRedirects unit test and the new
  transport cases; verifyWith JSDoc updated.

Closes #344

Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc
Co-Authored-By: Claude <noreply@anthropic.com>
…changes the method, unread (#344)

Review fixes on #355.

- A redirect a transport followed itself (HttpClient.followRedirects)
  whose hop on another origin FAILS (a refused connection, a DNS failure)
  was still a lost response: with only ?unknown=1 redirected to a dead
  host the spec/errors/* rules passed on 2 of 3 requests and
  unknown-query-parameter failed "not rejected"; a DELETE or POST so
  redirected gave false findings. The runner now reads where the
  transport ended from the request behind its failure as well as behind
  its answer, and records either as reason "transport", the note saying
  "ending in a transport error at <url>".
- A redirect a transport followed within the origin that turned the
  method into a GET (a 301/302 on a POST, a 303 on anything but GET) was
  read as the answer to the original method. The runner now refuses it
  as the kit's own follower would ("the transport turned the DELETE into
  a GET on the way"), still with reason "transport", since only another
  client cures it.
- Unfollowed.status is used for "transport": the note gives the answer's
  status ("ending at <url> with a 200") or the transport error.
- The transport `why` no longer repeats the reachable finding's remedy.
- The undecided clause and the reachable finding say "a redirect the kit
  does not follow or read".
- spec/target/reachable tells the caller to fix a `Location` that does
  not parse, rather than to move baseUrl.
- docs/conformance.md, the verifyWith JSDoc and the changeset no longer
  claim no request reaches another origin when the client follows
  redirects itself, and say only the final URL and method are checked,
  so a chain off the origin and back (A -> B -> A) goes undetected.

Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc
Co-Authored-By: Claude <noreply@anthropic.com>
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.

bug(Conformance): a redirect the transport follows off-origin still lets a rule partially pass

2 participants