Opened 4 years ago

Last modified 4 years ago

#1216 new defect

Confusing use of 'URI' when referring to a path in the proxy_pass documentation

Reported by: ankon@… Owned by:
Priority: minor Milestone:
Component: documentation Version: 1.9.x
Keywords: proxy_pass Cc:
uname -a: N/A
nginx -V: N/A

Description

In http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass it states:


A request URI is passed to the server as follows:

If the proxy_pass directive is specified with a URI, then when a request is passed to the server, the part of a normalized request URI matching the location is replaced by a URI specified in the directive:

location /name/ {

proxy_pass http://127.0.0.1/remote/;

}

If proxy_pass is specified without a URI, the request URI is passed to the server in the same form as sent by a client when the original request is processed, or the full normalized request URI is passed when processing the changed URI:

location /some/path/ {

proxy_pass http://127.0.0.1;

}


The highlighted uses of 'URI' should IMVHO be 'path', as in both cases a URI (with a scheme and a host, and the path in the first case) is given.

Change History (2)

comment:1 by Maxim Dounin, 4 years ago

See this message for explanation why "URI" is used in this meaning:

http://mailman.nginx.org/pipermail/nginx/2017-January/052730.html

Basically, this is because of how URIs are used in HTTP, and how nginx, as an HTTP server, sees them. This meaning is assumed almost everywhere in the documentation and code, including various variable names ($uri, $request_uri), so this is very unlikely to be changed.

comment:2 by ankon@…, 4 years ago

Thanks for the pointer, that does help to understand the documentation.

Instead of modifying it here, was there any (obvious) place I missed that would have helped in understanding this? As much as I understand the "legacy" argument, it clearly does make the documentation harder to understand for readers that are not familiar with the history and code of nginx -- given that the link points to a very recent mail I'm suspecting this might come up more often. :)

Note: See TracTickets for help on using tickets.