Repository navigation
docs: document redirect status code method-change semantics per RFC 7231 - #83
Conversation
Add Javadoc to RedirectStatusCode enum constants and the redirect() method explaining which codes change the request method (301/302/303) and which preserve it (307/308), with references to RFC 7231 §6.4 and RFC 7538 §3. Closes #75 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Documents redirect status code semantics in HttpResponseUtils to help developers choose between method-changing (301/302/303) and method-preserving (307/308) redirects, addressing Issue #75.
Changes:
- Added enum-level and per-constant Javadoc for
RedirectStatusCodewith RFC references. - Updated
HttpResponseUtils.redirect()Javadoc to warn about redirect-induced request method changes and recommend 307/308 when needed.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * <p>Codes 301, 302, and 303 are <em>method-changing</em>: user agents MAY (and in practice always do) | ||
| * resubmit the request as GET regardless of the original method (RFC 7231 §6.4.2–6.4.4). | ||
| * Use 303 when you explicitly want a POST-to-GET redirect after a form submission. |
There was a problem hiding this comment.
The enum-level Javadoc overstates the RFC semantics: for 301/302 the spec only allows changing POST to GET (not “regardless of the original method”), and it’s not accurate to say user agents “always” resubmit as GET (many non-browser clients preserve the method or make it configurable). Consider rephrasing to something like “browsers commonly change POST to GET for 301/302; 303 explicitly redirects to a GET/HEAD request” to keep this aligned with RFC 7231 §6.4.2–6.4.4.
| * <p>Codes 301, 302, and 303 are <em>method-changing</em>: user agents MAY (and in practice always do) | |
| * resubmit the request as GET regardless of the original method (RFC 7231 §6.4.2–6.4.4). | |
| * Use 303 when you explicitly want a POST-to-GET redirect after a form submission. | |
| * <p>For 301 and 302, RFC 7231 allows user agents to change a POST request to a GET when following | |
| * the redirect, and browsers commonly do so in practice (RFC 7231 §6.4.2–6.4.3). Status code 303 | |
| * explicitly instructs the user agent to perform a GET (or HEAD) when following the redirect | |
| * (RFC 7231 §6.4.4), and is typically used for POST-redirect-GET flows after form submission. |
| * <p><strong>Method-change warning:</strong> status codes 301, 302, and 303 allow user agents to | ||
| * change the request method to GET when following the redirect. If you need the original method | ||
| * (e.g. POST or PUT) to be repeated at the new URI, use {@link RedirectStatusCode#TEMPORARY_REDIRECT} | ||
| * (307) or {@link RedirectStatusCode#PERMANENT_REDIRECT} (308) instead. |
There was a problem hiding this comment.
The redirect() Javadoc says 301/302/303 “allow user agents to change the request method to GET”. That’s not quite accurate: 303 redirects to a GET/HEAD retrieval, while 301/302 only permit (and browsers commonly perform) a POST-to-GET rewrite. Tightening this wording would avoid implying that any method can be rewritten for 301/302 or that 303 is merely optional.
- 301/302: "MAY change POST to GET" (not "any method", not "always") - 303: "MUST follow with GET or HEAD" (mandatory, not optional) - Remove "all major browsers do" — accurate only for browsers, not all UA Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Fixed both:
- Enum-level Javadoc: 301/302 now say "RFC 7231 permits user agents to change a POST to GET; browsers commonly do so" (not "always", not "any method"). 303 described as instructing GET/HEAD (mandatory, per reviewer suggestion).
redirect()method Javadoc: same distinction — 301/302 say "browsers commonly change POST to GET", 303 says "MUST follow with GET or HEAD".
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| /** | ||
| * 303 See Other (RFC 7231 §6.4.4). | ||
| * The response to the redirect MUST be retrieved with GET. |
There was a problem hiding this comment.
The SEE_OTHER (303) enum constant Javadoc says the redirect "MUST be retrieved with GET", but elsewhere in this same file 303 is described as GET or HEAD. Please align these docs (e.g., mention GET or HEAD for 303) so the semantics are consistent.
| * The response to the redirect MUST be retrieved with GET. | |
| * The response to the redirect MUST be retrieved with GET or HEAD. |
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Fixed: SEE_OTHER constant Javadoc now says "GET or HEAD" to match the wording in the redirect() method Javadoc and RFC 7231 §6.4.4.
Summary
RedirectStatusCodeenum constants clarifying which codes are method-changing (301, 302, 303) and which are method-preserving (307, 308), with RFC 7231 §6.4 and RFC 7538 §3 referencesredirect()Javadoc pointing developers to 307/308 when method preservation is neededTest plan
enkan-webtests pass (no logic change)Closes #75
🤖 Generated with Claude Code