Skip to content

docs: clarify description for redir directive#539

Open
felixauringer wants to merge 1 commit into
caddyserver:masterfrom
felixauringer:docs-redir
Open

docs: clarify description for redir directive#539
felixauringer wants to merge 1 commit into
caddyserver:masterfrom
felixauringer:docs-redir

Conversation

@felixauringer
Copy link
Copy Markdown

@felixauringer felixauringer commented May 9, 2026

I find the current documentation for the redir directive slightly confusing.

It describes the HTTP status code 302 as temporary redirect. This is correct but the full status code is 302 Found and there is another status code 307 Temporary Redirect. In my opinion, those two can be easily confused with the current documentation.

Additionally, 308 Permanent Redirect is not mentioned although I would argue that it is often more appropriate than 301, for example for manual HTTP to HTTPS redirects.

I hope that my modifications improve the documentation in those regards.

@francislavoie
Copy link
Copy Markdown
Member

Yeah we have some open discussions about this (see caddyserver/caddy#7348 and related issues) about possibly changing the default and possibly adding new named mappings to the status codes, but it hasn't gone anywhere yet.

- A positive integer in the `3xx` range, or `401`

- `temporary` for a temporary redirect (`302`, this is the default)
- `temporary` for a temporary redirect (`302 — Found`, this is the default)
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `temporary` for a temporary redirect (`302 Found`, this is the default)
- `temporary` for a temporary redirect (`302 Found`, this is the default)

- `temporary` for a temporary redirect (`302 — Found`, this is the default)

- `permanent` for a permanent redirect (`301`)
- `permanent` for a permanent redirect (`301 — Moved Permanently`)
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `permanent` for a permanent redirect (`301 Moved Permanently`)
- `permanent` for a permanent redirect (`301 Moved Permanently`)



Note that both `temporary` and `permanent` allow the user agent to change the method (e.g. from `POST` to `GET`).
The status codes `307 — Temporary Redirect` and `308 — Permanent Redirect` should be used if the method must be the same in the second request.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The status codes `307 Temporary Redirect` and `308 Permanent Redirect` should be used if the method must be the same in the second request.
The status codes `307 Temporary Redirect` and `308 Permanent Redirect` should be used if the method must be the same in the second request.

@felixauringer
Copy link
Copy Markdown
Author

Yeah we have some open discussions about this (see caddyserver/caddy#7348 and related issues) about possibly changing the default and possibly adding new named mappings to the status codes, but it hasn't gone anywhere yet.

I agree with Matt's opinion from the linked issue and do not want to changed the named status codes as that would probably break many existing setups.
However, I still think that the documentation could be a little bit more clear, hence this PR :)

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.

2 participants