Mercurial > hg > nginx-site

comparison xml/en/docs/dev/development_guide.xml @ 1967:ef27e3ef0c46

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
The HTTP request redirection section of the development guide.
author Roman Arutyunyan <arut@nginx.com>
date Wed, 19 Apr 2017 18:35:05 +0300
parents 9550ea66abdd
children 69908bd68481
comparison
equal deleted inserted replaced
1966:4146aaa62fc1 1967:ef27e3ef0c46
4627 } 4627 }
4628 </programlisting> 4628 </programlisting>
4629 Given the request <literal>r</literal> and previously compiled 4629 Given the request <literal>r</literal> and previously compiled
4630 value <literal>cv</literal> the function will evaluate 4630 value <literal>cv</literal> the function will evaluate
4631 expression and put result into <literal>res</literal>. 4631 expression and put result into <literal>res</literal>.
4632 </para>
4633
4634 </section>
4635
4636
4637 <section name="Request redirection" id="http_request_redirection">
4638
4639 <para>
4640 An HTTP request is always connected to a location via the
4641 <literal>loc_conf</literal> field of the <literal>ngx_http_request_t</literal>
4642 structure.
4643 This means that at any point the location configuration of any module can be
4644 retrieved from the request by calling
4645 <literal>ngx_http_get_module_loc_conf(r, module)</literal>.
4646 Request location may be changed several times throughout its lifetime.
4647 Initially, a default server location of the default server is assigned to a
4648 request.
4649 Once a request switches to a different server (chosen by the HTTP
4650 <header>Host</header> header or SSL SNI extension), the request switches to the
4651 default location of that server as well.
4652 The next change of the location takes place at the
4653 <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> request phase.
4654 At this phase a location is chosen by request URI among all non-named locations
4655 configured for the server.
4656 The
4657 <link doc="../http/ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>
4658 may change the request URI at the
4659 <literal>NGX_HTTP_REWRITE_PHASE</literal> request phase as a result of
4660 <link doc="../http/ngx_http_rewrite_module.xml" id="rewrite">rewrite</link> and
4661 return to the <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> phase for choosing a
4662 new location based on the new URI.
4663 </para>
4664
4665 <para>
4666 It is also possible to redirect a request to a new location at any point by
4667 calling one of the functions
4668 <literal>ngx_http_internal_redirect(r, uri, args)</literal> or
4669 <literal>ngx_http_named_location(r, name)</literal>.
4670 </para>
4671
4672 <para>
4673 The function <literal>ngx_http_internal_redirect(r, uri, args)</literal> changes
4674 the request URI and returns the request to the
4675 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> phase.
4676 The request proceeds with a server default location.
4677 Later at <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> a new location is chosen
4678 based on the new request URI.
4679 </para>
4680
4681 <para>
4682 The following example performs an internal redirect with the new request
4683 arguments.
4684 </para>
4685
4686 <programlisting>
4687 ngx_int_t
4688 ngx_http_foo_redirect(ngx_http_request_t *r)
4689 {
4690 ngx_str_t uri, args;
4691
4692 ngx_str_set(&amp;uri, "/foo");
4693 ngx_str_set(&amp;args, "bar=1");
4694
4695 return ngx_http_internal_redirect(r, &amp;uri, &amp;args);
4696 }
4697 </programlisting>
4698
4699 <para>
4700 The function <literal>ngx_http_named_location(r, name)</literal> redirects
4701 a request to a named location. The name of the location is passed as the
4702 argument. The location is looked up among all named locations of the current
4703 server, after which the requests switches to the
4704 <literal>NGX_HTTP_REWRITE_PHASE</literal> phase.
4705 </para>
4706
4707 <para>
4708 The following example performs a redirect to a named location @foo.
4709 </para>
4710
4711 <programlisting>
4712 ngx_int_t
4713 ngx_http_foo_named_redirect(ngx_http_request_t *r)
4714 {
4715 ngx_str_t name;
4716
4717 ngx_str_set(&amp;name, "foo");
4718
4719 return ngx_http_named_location(r, &amp;name);
4720 }
4721 </programlisting>
4722
4723 <para>
4724 Both functions <literal>ngx_http_internal_redirect(r, uri, args)</literal>
4725 and <literal>ngx_http_named_location(r, name)</literal> may be called when
4726 a request already has some contexts saved in its <literal>ctx</literal> field
4727 by nginx modules. These contexts could become inconsistent with the new
4728 location configuration. To prevent inconsistency, all request contexts are
4729 erased by both redirect functions.
4730 </para>
4731
4732 <para>
4733 Redirected and rewritten requests become internal and may access the
4734 <link doc="../http/ngx_http_core_module.xml" id="internal">internal</link>
4735 locations. Internal requests have the <literal>internal</literal> flag set.
4632 </para> 4736 </para>
4633 4737
4634 </section> 4738 </section>
4635 4739
4636 4740