Re: пожелания по документации rewrite

[Maxim Dounin]

Hello!

On Fri, Nov 23, 2012 at 05:07:51PM +0400, Ruslan Ermilov wrote:

> On Fri, Nov 23, 2012 at 02:44:53PM +0400, Maxim Dounin wrote:
> > Hello!
> > 
> > On Fri, Nov 23, 2012 at 01:58:18PM +0400, Anton Yuzhaninov wrote:
> > 
> > > Тз текущего описания rewrite не очевидно, что после обычного rewrite
> > > будет использовкаться конфигурация из нового location, а при rewrite
> > > ... break остается конфигурация текущего location.
> > > 
> > > Например с таким конфигом:
> > > 
> > > location = /test1.txt {
> > >     add_header X-Location test1;
> > >     deny all;
> > > }
> > > 
> > > location = /test2.txt {
> > >     add_header X-Location test2;
> > >     rewrite ^ /test1.txt break;
> > > }
> > > 
> > > location = /test3.txt {
> > >     add_header X-Location test3;
> > >     rewrite ^ /test2.txt;
> > > }
> > > 
> > > При запросе на /test3.txt будет отдан файл test1.txt, с заголовком test2.
> > > 
> > > Було бы неплохо упомянуть в документации такую особенность rewrite break.
> > 
> > Всмысле - прописать явно, что break "завершает обработку ..." без 
> > поиска нового location'а?  Так-то там даже пример про это есть.  
> > Но вообще да, наверное имеет смысл.
> 
> Так плохо, т.к. rewrite ... break или break (ещё одно место),
> указанные на уровне server, не отключат поиск нового location'а.
> Моё предложение такое.
> 
> Было:
> 
> Директивы модуля ngx_http_rewrite_module обрабатываются в следующем порядке:
> 
> - выполняются директивы этого модуля, описанные на уровне сервера;
> 
> - ищется location для запроса;
> 
> - выполняются директивы этого модуля, описанные в выбранном location, и если
>   они изменяли URI, то ищется новый location для уже нового URI. Этот цикл
>   может повторяться до 10 раз, после чего возвращается ошибка 500 (Internal
>   Server Error).
> 
> Стало:
> 
> [...]
> 
> - выполняются директивы этого модуля, описанные в выбранном location, и если
>   они изменяли URI и не было break, то ищется новый location для уже нового URI.
>   Этот цикл может повторяться до 10 раз, после чего возвращается ошибка 500
>   (Internal Server Error).

Не думаю, что надо тащить это сюда.  Это описание наиболее общего 
случае отсутствия всяких специальных флагов/операций, и там есть 
ещё 100500 вариантов, когда поиска нового location'а не будет 
(return, rewrite ... redirect, rewrite ... permanent).  Нет смысла 
все их описывать тут.

Кроме того, подобная формулировка - предполагает, что на этапе 
чтения этого (общего) описания работы читатель уже знает, что 
такое break.  С другой стороны, флаг break остаётся всё так же 
недоописанным (то, на что жалуется Антон) - и требует для 
понимания прочтения этого общего описания работы, которое в свою 
очередь...  Где-то тут, после 10 раз, у читающего случится 500 
Internal Server Error.  :)

IMHO, имеет смысл как-то так:

--- xml/ru/docs/http/ngx_http_rewrite_module.xml	(revision 776)
+++ xml/ru/docs/http/ngx_http_rewrite_module.xml	(working copy)
@@ -62,6 +62,8 @@
 <para>
 Завершает обработку текущего набора директив модуля
 <literal>ngx_http_rewrite_module</literal>.
+В случае, если location для запроса уже выбран, дальнейшая обработка запроса
+продолжится в выбранном location.
 </para>
 
 <para>
@@ -256,7 +258,7 @@
 
 <tag-name><literal>break</literal></tag-name>
 <tag-desc>
-завершает обработку текущего набора директив модуля
+<link id="break">завершает обработку</link> текущего набора директив модуля
 <literal>ngx_http_rewrite_module</literal>;
 </tag-desc>
 

(На конкретных формулироваках не настаиваю.)

-- 
Maxim Dounin
http://nginx.com/support.html