Mercurial > hg > nginx-site

comparison xml/en/docs/dev/development_guide.xml @ 1929:7f290929b32d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
HTTP section of the development guide.
author Roman Arutyunyan <arut@nginx.com>
date Tue, 14 Mar 2017 12:56:59 +0300
parents 2c14a16c61eb
children 937e03180281
comparison
equal deleted inserted replaced
1928:2c14a16c61eb 1929:7f290929b32d
3385 </section> 3385 </section>
3386 3386
3387 </section> 3387 </section>
3388 3388
3389 3389
3390 <section name="HTTP" id="http">
3391
3392
3393 <section name="Connection" id="http_connection">
3394
3395 <para>
3396 Each client HTTP connection runs through the following stages:
3397 </para>
3398
3399 <list type="bullet">
3400
3401 <listitem>
3402 <literal>ngx_event_accept()</literal> accepts a client TCP connection.
3403 This handler is called in response to a read notification on a listen socket.
3404 A new <literal>ngx_connecton_t</literal> object is created at this stage.
3405 The object wraps the newly accepted client socket.
3406 Each nginx listener provides a handler to pass the new connection object to.
3407 For HTTP connections it's <literal>ngx_http_init_connection(c)</literal>
3408 </listitem>
3409
3410 <listitem>
3411 <literal>ngx_http_init_connection()</literal> performs early initialization of
3412 an HTTP connection.
3413 At this stage an <literal>ngx_http_connection_t</literal> object is created for
3414 the connection and its reference is stored in connection's
3415 <literal>data</literal> field.
3416 Later it will be substituted with an HTTP request object.
3417 PROXY protocol parser and SSL handshake are started at this stage as well
3418 </listitem>
3419
3420 <listitem>
3421 <literal>ngx_http_wait_request_handler()</literal> is a read event handler, that
3422 is called when data is available in the client socket.
3423 At this stage an HTTP request object <literal>ngx_http_request_t</literal> is
3424 created and set to connection's <literal>data</literal> field
3425 </listitem>
3426
3427 <listitem>
3428 <literal>ngx_http_process_request_line()</literal> is a read event handler,
3429 which reads client request line.
3430 The handler is set by <literal>ngx_http_wait_request_handler()</literal>.
3431 Reading is done into connection's <literal>buffer</literal>.
3432 The size of the buffer is initially set by the directive
3433 <link doc="../http/ngx_http_core_module.xml" id="client_header_buffer_size"/>.
3434 The entire client header is supposed to fit the buffer.
3435 If the initial size is not enough, a bigger buffer is allocated, whose size is
3436 set by the <literal>large_client_header_buffers</literal> directive
3437 </listitem>
3438
3439 <listitem>
3440 <literal>ngx_http_process_request_headers()</literal> is a read event handler,
3441 which is set after <literal>ngx_http_process_request_line()</literal> to read
3442 client request header
3443 </listitem>
3444
3445 <listitem>
3446 <literal>ngx_http_core_run_phases()</literal> is called when the request header
3447 is completely read and parsed.
3448 This function runs request phases from
3449 <literal>NGX_HTTP_POST_READ_PHASE</literal> to
3450 <literal>NGX_HTTP_CONTENT_PHASE</literal>.
3451 The last phase is supposed to generate response and pass it along the filter
3452 chain.
3453 The response in not necessarily sent to the client at this phase.
3454 It may remain buffered and will be sent at the finalization stage
3455 </listitem>
3456
3457 <listitem>
3458 <literal>ngx_http_finalize_request()</literal> is usually called when the
3459 request has generated all the output or produced an error.
3460 In the latter case an appropriate error page is looked up and used as the
3461 response.
3462 If the response is not completely sent to the client by this point, an
3463 HTTP writer <literal>ngx_http_writer()</literal> is activated to finish
3464 sending outstanding data
3465 </listitem>
3466
3467 <listitem>
3468 <literal>ngx_http_finalize_connection()</literal> is called when the response is
3469 completely sent to the client and the request can be destroyed.
3470 If client connection keepalive feature is enabled,
3471 <literal>ngx_http_set_keepalive()</literal> is called, which destroys current
3472 request and waits for the next request on the connection.
3473 Otherwise, <literal>ngx_http_close_request()</literal> destroys both the
3474 request and the connection
3475 </listitem>
3476
3477 </list>
3478
3479 </section>
3480
3481
3482 <section name="Request" id="http_request">
3483
3484 <para>
3485 For each client HTTP request the <literal>ngx_http_request_t</literal> object is
3486 created. Some of the fields of this object:
3487 </para>
3488
3489 <list type="bullet">
3490
3491 <listitem>
3492
3493 <para>
3494 <literal>connection</literal> - pointer to a <literal>ngx_connection_t</literal>
3495 client connection object.
3496 Several requests may reference the same connection object at the same time -
3497 one main request and its subrequests.
3498 After a request is deleted, a new request may be created on the same connection.
3499 </para>
3500
3501 <para>
3502 Note that for HTTP connections <literal>ngx_connection_t</literal>'s
3503 <literal>data</literal> field points back to the request.
3504 Such request is called active, as opposed to the other requests tied with the
3505 connection.
3506 Active request is used to handle client connection events and is allowed to
3507 output its response to the client.
3508 Normally, each request becomes active at some point to be able to send its
3509 output
3510 </para>
3511
3512 </listitem>
3513
3514 <listitem>
3515
3516 <para>
3517 <literal>ctx</literal> - array of HTTP module contexts.
3518 Each module of type <literal>NGX_HTTP_MODULE</literal> can store any value
3519 (normally, a pointer to a structure) in the request.
3520 The value is stored in the <literal>ctx</literal> array at the module's
3521 <literal>ctx_index</literal> position.
3522 The following macros provide a convenient way to get and set request contexts:
3523 </para>
3524
3525 <list type="bullet">
3526
3527 <listitem>
3528 <literal>ngx_http_get_module_ctx(r, module)</literal> - returns
3529 <literal>module</literal>'s context
3530 </listitem>
3531
3532 <listitem>
3533 <literal>ngx_http_set_ctx(r, c, module)</literal> - sets <literal>c</literal>
3534 as <literal>module</literal>'s context
3535 </listitem>
3536
3537 </list>
3538
3539 </listitem>
3540
3541 <listitem>
3542 <literal>main_conf, srv_conf, loc_conf</literal> - arrays of current request
3543 configurations.
3544 Configurations are stored at module's <literal>ctx_index</literal> positions
3545 </listitem>
3546
3547 <listitem>
3548 <literal>read_event_handler</literal>, <literal>write_event_handler</literal> -
3549 read and write event handlers for the request.
3550 Normally, an HTTP connection has <literal>ngx_http_request_handler()</literal>
3551 set as both read and write event handlers.
3552 This function calls <literal>read_event_handler</literal> and
3553 <literal>write_event_handler</literal> handlers of the currently active request
3554 </listitem>
3555
3556 <listitem>
3557 <literal>cache</literal> - request cache object for caching upstream response
3558 </listitem>
3559
3560 <listitem>
3561 <literal>upstream</literal> - request upstream object for proxying
3562 </listitem>
3563
3564 <listitem>
3565 <literal>pool</literal> - request pool.
3566 This pool is destroyed when the request is deleted.
3567 The request object itself is allocated in this pool.
3568 For allocations which should be available throughout the client connection's
3569 lifetime, <literal>ngx_connection_t</literal>'s pool should be used instead
3570 </listitem>
3571
3572 <listitem>
3573 <literal>header_in</literal> - buffer where client HTTP request header in read
3574 </listitem>
3575
3576 <listitem>
3577 <literal>headers_in, headers_out</literal> - input and output HTTP headers
3578 objects.
3579 Both objects contain the <literal>headers</literal> field of type
3580 <literal>ngx_list_t</literal> keeping the raw list of headers.
3581 In addition to that, specific headers are available for getting and setting as
3582 separate fields, for example <literal>content_length_n</literal>,
3583 <literal>status</literal> etc
3584 </listitem>
3585
3586 <listitem>
3587 <literal>request_body</literal> - client request body object
3588 </listitem>
3589
3590 <listitem>
3591 <literal>start_sec, start_msec</literal> - time point when the request was
3592 created.
3593 Used for tracking request duration
3594 </listitem>
3595
3596 <listitem>
3597 <literal>method, method_name</literal> - numeric and textual representation of
3598 client HTTP request method.
3599 Numeric values for methods are defined in
3600 <literal>src/http/ngx_http_request.h</literal> with macros
3601 <literal>NGX_HTTP_GET, NGX_HTTP_HEAD, NGX_HTTP_POST</literal> etc
3602 </listitem>
3603
3604 <listitem>
3605 <literal>http_protocol, http_version, http_major, http_minor</literal> -
3606 client HTTP protocol version in its original textual form ("HTTP/1.0",
3607 "HTTP/1.1" etc), numeric form (<literal>NGX_HTTP_VERSION_10</literal>,
3608 <literal>NGX_HTTP_VERSION_11</literal> etc) and separate major and minor
3609 versions
3610 </listitem>
3611
3612 <listitem>
3613 <literal>request_line, unparsed_uri</literal> - client original request line
3614 and URI
3615 </listitem>
3616
3617 <listitem>
3618 <literal>uri, args, exten</literal> - current request URI, arguments and file
3619 extention.
3620 The URI value here might differ from the original URI sent by the client due to
3621 normalization.
3622 Throughout request processing, these value can change while performing internal
3623 redirects
3624 </listitem>
3625
3626 <listitem>
3627 <literal>main</literal> - pointer to a main request object.
3628 This object is created to process client HTTP request, as opposed to
3629 subrequests, created to perform a specific sub-task within the main request
3630 </listitem>
3631
3632 <listitem>
3633 <literal>parent</literal> - pointer to a parent request of a subrequest
3634 </listitem>
3635
3636 <listitem>
3637 <literal>postponed</literal> - list of output buffers and subrequests in the
3638 order they are sent and created.
3639 The list is used by the postpone filter to provide consistent request output,
3640 when parts of it are created by subrequests
3641 </listitem>
3642
3643 <listitem>
3644 <literal>post_subrequest</literal> - pointer to a handler with context to be
3645 called when a subrequest gets finalized.
3646 Unused for main requests
3647 </listitem>
3648
3649 <listitem>
3650
3651 <para>
3652 <literal>posted_requests</literal> - list of requests to be started or
3653 resumed.
3654 Starting or resuming is done by calling the request's
3655 <literal>write_event_handler</literal>.
3656 Normally, this handler holds the request main function, which at first runs
3657 request phases and then produces the output.
3658 </para>
3659
3660 <para>
3661 A request is usually posted by the
3662 <literal>ngx_http_post_request(r, NULL)</literal> call.
3663 It is always posted to the main request <literal>posted_requests</literal> list.
3664 The function <literal>ngx_http_run_posted_requests(c)</literal> runs all
3665 requests, posted in the main request of the passed connection's active request.
3666 This function should be called in all event handlers, which can lead to new
3667 posted requests.
3668 Normally, it's called always after invoking a request's read or write handler
3669 </para>
3670
3671 </listitem>
3672
3673 <listitem>
3674 <literal>phase_handler</literal> - index of current request phase
3675 </listitem>
3676
3677 <listitem>
3678 <literal>ncaptures, captures, captures_data</literal> - regex captures produced
3679 by the last regex match of the request.
3680 While processing a request, there's a number of places where a regex match can
3681 happen: map lookup, server lookup by SNI or HTTP Host, rewrite, proxy_redirect
3682 etc.
3683 Captures produced by a lookup are stored in the above mentioned fields.
3684 The field <literal>ncaptures</literal> holds the number of captures,
3685 <literal>captures</literal> holds captures boundaries,
3686 <literal>captures_data</literal> holds a string, against which the regex was
3687 matched and which should be used to extract captures.
3688 After each new regex match request captures are reset to hold new values
3689 </listitem>
3690
3691 <listitem>
3692 <literal>count</literal> - request reference counter.
3693 The field only makes sense for the main request.
3694 Increasing the counter is done by simple <literal>r->main->count++</literal>.
3695 To decrease the counter <literal>ngx_http_finalize_request(r, rc)</literal>
3696 should be called.
3697 Creation of a subrequest or running request body read process increase the
3698 counter
3699 </listitem>
3700
3701 <listitem>
3702 <literal>subrequests</literal> - current subrequest nesting level.
3703 Each subrequest gets the nesting level of its parent decreased by one.
3704 Once the value reaches zero an error is generated.
3705 The value for the main request is defined by the
3706 <literal>NGX_HTTP_MAX_SUBREQUESTS</literal> constant
3707 </listitem>
3708
3709 <listitem>
3710 <literal>uri_changes</literal> - number of URI changes left for the request.
3711 The total number of times a request can change its URI is limited by the
3712 <literal>NGX_HTTP_MAX_URI_CHANGES</literal> constant.
3713 With each change the value is decreased until it reaches zero.
3714 In the latter case an error is generated.
3715 The actions considered as URI changes are rewrites and internal redirects to
3716 normal or named locations
3717 </listitem>
3718
3719 <listitem>
3720 <literal>blocked</literal> - counter of blocks held on the request.
3721 While this value is non-zero, request cannot be terminated.
3722 Currently, this value is increased by pending AIO operations (POSIX AIO and
3723 thread operations) and active cache lock
3724 </listitem>
3725
3726 <listitem>
3727 <literal>buffered</literal> - bitmask showing which modules have buffered the
3728 output produced by the request.
3729 A number of filters can buffer output, for example sub_filter can buffer data
3730 due to a partial string match, copy filter can buffer data because of the lack
3731 of free output_buffers etc.
3732 As long as this value is non-zero, request is not finalized, expecting the flush
3733 </listitem>
3734
3735 <listitem>
3736 <literal>header_only</literal> - flag showing that output does not require body.
3737 For example, this flag is used by HTTP HEAD requests
3738 </listitem>
3739
3740 <listitem>
3741 <para>
3742 <literal>keepalive</literal> - flag showing if client connection keepalive is
3743 supported.
3744 The value is inferred from HTTP version and <header>Connection</header> header
3745 value
3746 </para>
3747 </listitem>
3748
3749 <listitem>
3750 <literal>header_sent</literal> - flag showing that output header has already
3751 been sent by the request
3752 </listitem>
3753
3754 <listitem>
3755 <literal>internal</literal> - flag showing that current request is internal.
3756 To enter the internal state, a request should pass through an internal
3757 redirect or be a subrequest.
3758 Internal requests are allowed to enter internal locations
3759 </listitem>
3760
3761 <listitem>
3762 <literal>allow_ranges</literal> - flag showing that partial response can be
3763 sent to client, if requested by the HTTP Range header
3764 </listitem>
3765
3766 <listitem>
3767 <literal>subrequest_ranges</literal> - flag showing that a partial response is
3768 allowed to be sent while processing a subrequest
3769 </listitem>
3770
3771 <listitem>
3772 <literal>single_range</literal> - flag showing that only a single continuous
3773 range of output data can be sent to the client.
3774 This flag is usually set when sending a stream of data, for example from a
3775 proxied server, and the entire response is not available at once
3776 </listitem>
3777
3778 <listitem>
3779 <literal>main_filter_need_in_memory, filter_need_in_memory</literal> - flags
3780 showing that the output should be produced in memory buffers but not in files.
3781 This is a signal to the copy filter to read data from file buffers even if
3782 sendfile is enabled.
3783 The difference between these two flags is the location of filter modules which
3784 set them.
3785 Filters called before the postpone filter in filter chain, set
3786 <literal>filter_need_in_memory</literal> requesting that only the current
3787 request output should come in memory buffers.
3788 Filters called later in filter chain set
3789 <literal>main_filter_need_in_memory</literal> requiring that both the main
3790 request and all the subrequest read files in memory while sending output
3791 </listitem>
3792
3793 <listitem>
3794 <literal>filter_need_temporary</literal> - flag showing that the request output
3795 should be produced in temporary buffers, but not in readonly memory buffers or
3796 file buffers.
3797 This is used by filters which may change output directly in the buffers, where
3798 it's sent </listitem>
3799
3800 </list>
3801
3802 </section>
3803
3804
3805 <section name="Configuration" id="http_conf">
3806
3807 <para>
3808 Each HTTP module may have three types of configuration:
3809 </para>
3810
3811 <list type="bullet">
3812
3813 <listitem>
3814 Main configuration.
3815 This configuration applies to the entire nginx http{} block. This is global
3816 configuration.
3817 It stores global settings for a module
3818 </listitem>
3819
3820 <listitem>
3821 Server configuration.
3822 This configuraion applies to a single nginx server{}.
3823 It stores server-specific settings for a module
3824 </listitem>
3825
3826 <listitem>
3827 Location configuration.
3828 This configuraion applies to a single location{}, if{} or limit_except() block.
3829 This configuration stores settings specific to a location
3830 </listitem>
3831
3832 </list>
3833
3834 <para>
3835 Configuration structures are created at nginx configuration stage by calling
3836 functions, which allocate these structures, initialize them and merge.
3837 The following example shows how to create a simple module location
3838 configuration.
3839 The configuration has one setting <literal>foo</literal> of unsiged integer
3840 type.
3841 </para>
3842
3843 <programlisting>
3844 typedef struct {
3845 ngx_uint_t foo;
3846 } ngx_http_foo_loc_conf_t;
3847
3848
3849 static ngx_http_module_t ngx_http_foo_module_ctx = {
3850 NULL, /* preconfiguration */
3851 NULL, /* postconfiguration */
3852
3853 NULL, /* create main configuration */
3854 NULL, /* init main configuration */
3855
3856 NULL, /* create server configuration */
3857 NULL, /* merge server configuration */
3858
3859 ngx_http_foo_create_loc_conf, /* create location configuration */
3860 ngx_http_foo_merge_loc_conf /* merge location configuration */
3861 };
3862
3863
3864 static void *
3865 ngx_http_foo_create_loc_conf(ngx_conf_t *cf)
3866 {
3867 ngx_http_foo_loc_conf_t *conf;
3868
3869 conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_foo_loc_conf_t));
3870 if (conf == NULL) {
3871 return NULL;
3872 }
3873
3874 conf->foo = NGX_CONF_UNSET_UINT;
3875
3876 return conf;
3877 }
3878
3879
3880 static char *
3881 ngx_http_foo_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
3882 {
3883 ngx_http_foo_loc_conf_t *prev = parent;
3884 ngx_http_foo_loc_conf_t *conf = child;
3885
3886 ngx_conf_merge_uint_value(conf->foo, prev->foo, 1);
3887 }
3888 </programlisting>
3889
3890 <para>
3891 As seen in the example, <literal>ngx_http_foo_create_loc_conf()</literal>
3892 function creates a new configuration structure and
3893 <literal>ngx_http_foo_merge_loc_conf()</literal> merges a configuration with
3894 another configuration from a higher level.
3895 In fact, server and location configuration do not only exist at server and
3896 location levels, but also created for all the levels above.
3897 Specifically, a server configuration is created at the main level as well and
3898 location configurations are created for main, server and location levels.
3899 These configurations make it possible to specify server and location-specific
3900 settings at any level of nginx configuration file.
3901 Eventually configurations are merged down.
3902 To indicate a missing setting and ignore it while merging, nginx provides a
3903 number of macros like <literal>NGX_CONF_UNSET</literal> and
3904 <literal>NGX_CONF_UNSET_UINT</literal>.
3905 Standard nginx merge macros like <literal>ngx_conf_merge_value()</literal> and
3906 <literal>ngx_conf_merge_uint_value()</literal> provide a convenient way to
3907 merge a setting and set the default value if none of configurations provided an
3908 explicit value.
3909 For complete list of macros for different types see
3910 <literal>src/core/ngx_conf_file.h</literal>.
3911 </para>
3912
3913 <para>
3914 To access configuration of any HTTP module at configuration time, the following
3915 macros are available.
3916 They receive <literal>ngx_conf_t</literal> reference as the first argument.
3917 </para>
3918
3919 <list type="bullet">
3920
3921 <listitem>
3922 <literal>ngx_http_conf_get_module_main_conf(cf, module)</literal>
3923 </listitem>
3924
3925 <listitem>
3926 <literal>ngx_http_conf_get_module_srv_conf(cf, module)</literal>
3927 </listitem>
3928
3929 <listitem>
3930 <literal>ngx_http_conf_get_module_loc_conf(cf, module)</literal>
3931 </listitem>
3932
3933 </list>
3934
3935 <para>
3936 The following example gets a pointer to a location configuration of
3937 standard nginx core module
3938 <link doc="../http/ngx_http_core_module.xml">ngx_http_core_module</link>
3939 and changes
3940 location content handler kept in the <literal>handler</literal> field of the
3941 structure.
3942 </para>
3943
3944 <programlisting>
3945 static ngx_int_t ngx_http_foo_handler(ngx_http_request_t *r);
3946
3947
3948 static ngx_command_t ngx_http_foo_commands[] = {
3949
3950 { ngx_string("foo"),
3951 NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS,
3952 ngx_http_foo,
3953 0,
3954 0,
3955 NULL },
3956
3957 ngx_null_command
3958 };
3959
3960
3961 static char *
3962 ngx_http_foo(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
3963 {
3964 ngx_http_core_loc_conf_t *clcf;
3965
3966 clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
3967 clcf->handler = ngx_http_bar_handler;
3968
3969 return NGX_CONF_OK;
3970 }
3971 </programlisting>
3972
3973 <para>
3974 In runtime the following macros are available to get configurations of HTTP
3975 modules.
3976 </para>
3977
3978 <list type="bullet">
3979
3980 <listitem>
3981 <literal>ngx_http_get_module_main_conf(r, module)</literal>
3982 </listitem>
3983
3984 <listitem>
3985 <literal>ngx_http_get_module_srv_conf(r, module)</literal>
3986 </listitem>
3987
3988 <listitem>
3989 <literal>ngx_http_get_module_loc_conf(r, module)</literal>
3990 </listitem>
3991
3992 </list>
3993
3994 <para>
3995 These macros receive a reference to an HTTP request
3996 <literal>ngx_http_request_t</literal>.
3997 Main configuration of a request never changes.
3998 Server configuration may change from a default one after choosing a virtual
3999 server for a request.
4000 Request location configuration may change multiple times as a result of a
4001 rewrite or internal redirect.
4002 The following example shows how to access HTTP configuration in runtime.
4003 </para>
4004
4005 <programlisting>
4006 static ngx_int_t
4007 ngx_http_foo_handler(ngx_http_request_t *r)
4008 {
4009 ngx_http_foo_loc_conf_t *flcf;
4010
4011 flcf = ngx_http_get_module_loc_conf(r, ngx_http_foo_module);
4012
4013 ...
4014 }
4015 </programlisting>
4016
4017 </section>
4018
4019
4020 <section name="Phases" id="http_phases">
4021
4022 <para>
4023 Each HTTP request passes through a list of HTTP phases.
4024 Each phase is specialized in a particular type of processing.
4025 Most phases allow installing handlers.
4026 The phase handlers are called successively once the request reaches the phase.
4027 Many standard nginx modules install their phase handlers as a way to get called
4028 at a specific request processing stage.
4029 Following is the list of nginx HTTP phases.
4030 </para>
4031
4032 <list type="bullet">
4033
4034 <listitem>
4035 <literal>NGX_HTTP_POST_READ_PHASE</literal> is the earliest phase.
4036 The <link doc="../http/ngx_http_realip_module.xml">ngx_http_realip_module</link>
4037 installs its handler at this phase.
4038 This allows to substitute client address before any other module is invoked
4039 </listitem>
4040
4041 <listitem>
4042 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> is used to run rewrite script,
4043 defined at the server level, that is out of any location block.
4044 The
4045 <link doc="../http/ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>
4046 installs its handler at this phase
4047 </listitem>
4048
4049 <listitem>
4050 <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> - a special phase used to choose a
4051 location based on request URI.
4052 This phase does not allow installing any handlers.
4053 It only performs the default action of choosing a location.
4054 Before this phase, the server default location is assigned to the request.
4055 Any module requesting a location configuration, will receive the default server
4056 location configuration.
4057 After this phase a new location is assigned to the request
4058 </listitem>
4059
4060 <listitem>
4061 <literal>NGX_HTTP_REWRITE_PHASE</literal> - same as
4062 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal>, but for a new location,
4063 chosen at the prevous phase
4064 </listitem>
4065
4066 <listitem>
4067 <literal>NGX_HTTP_POST_REWRITE_PHASE</literal> - a special phase, used to
4068 redirect the request to a new location, if the URI was changed during rewrite.
4069 The redirect is done by going back to
4070 <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal>.
4071 No handlers are allowed at this phase
4072 </listitem>
4073
4074 <listitem>
4075 <literal>NGX_HTTP_PREACCESS_PHASE</literal> - a common phase for different
4076 types of handlers, not associated with access check.
4077 Standard nginx modules
4078 <link doc="../http/ngx_http_limit_conn_module.xml">ngx_http_limit_conn_module
4079 </link> and
4080 <link doc="../http/ngx_http_limit_req_module.xml">
4081 ngx_http_limit_req_module</link> register their handlers at this phase
4082 </listitem>
4083
4084 <listitem>
4085 <literal>NGX_HTTP_ACCESS_PHASE</literal> - used to check access permissions
4086 for the request.
4087 Standard nginx modules such as
4088 <link doc="../http/ngx_http_access_module.xml">ngx_http_access_module</link> and
4089 <link doc="../http/ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module
4090 </link> register their handlers at this phase.
4091 If configured so by the
4092 <link doc="../http/ngx_http_core_module.xml" id="satisfy"/> directive, only one
4093 of access phase handlers may allow access to the request in order to confinue
4094 processing
4095 </listitem>
4096
4097 <listitem>
4098 <literal>NGX_HTTP_POST_ACCESS_PHASE</literal> - a special phase for the
4099 <link doc="../http/ngx_http_core_module.xml" id="satisfy">satisfy any</link>
4100 case.
4101 If some access phase handlers denied the access and none of them allowed, the
4102 request is finalized.
4103 No handlers are supported at this phase
4104 </listitem>
4105
4106 <listitem>
4107 <literal>NGX_HTTP_TRY_FILES_PHASE</literal> - a special phase, for the
4108 <link doc="../http/ngx_http_core_module.xml" id="try_files"/> feature.
4109 No handlers are allowed at this phase
4110 </listitem>
4111
4112 <listitem>
4113 <literal>NGX_HTTP_CONTENT_PHASE</literal> - a phase, at which the response
4114 is supposed to be generated.
4115 Multiple nginx standard modules register their handers at this phase, for
4116 example
4117 <link doc="../http/ngx_http_index_module.xml">ngx_http_index_module</link> or
4118 <literal>ngx_http_static_module</literal>.
4119 All these handlers are called sequentially until one of them finally produces
4120 the output.
4121 It's also possible to set content handlers on a per-location basis.
4122 If the
4123 <link doc="../http/ngx_http_core_module.xml">ngx_http_core_module</link>'s
4124 location configuration has <literal>handler</literal> set, this handler is
4125 called as the content handler and content phase handlers are ignored
4126 </listitem>
4127
4128 <listitem>
4129 <literal>NGX_HTTP_LOG_PHASE</literal> is used to perform request logging.
4130 Currently, only the
4131 <link doc="../http/ngx_http_log_module.xml">ngx_http_log_module</link>
4132 registers its handler
4133 at this stage for access logging.
4134 Log phase handlers are called at the very end of request processing, right
4135 before freeing the request
4136 </listitem>
4137
4138 </list>
4139
4140 <para>
4141 Following is the example of a preaccess phase handler.
4142 </para>
4143
4144 <programlisting>
4145 static ngx_http_module_t ngx_http_foo_module_ctx = {
4146 NULL, /* preconfiguration */
4147 ngx_http_foo_init, /* postconfiguration */
4148
4149 NULL, /* create main configuration */
4150 NULL, /* init main configuration */
4151
4152 NULL, /* create server configuration */
4153 NULL, /* merge server configuration */
4154
4155 NULL, /* create location configuration */
4156 NULL /* merge location configuration */
4157 };
4158
4159
4160 static ngx_int_t
4161 ngx_http_foo_handler(ngx_http_request_t *r)
4162 {
4163 ngx_str_t *ua;
4164
4165 ua = r->headers_in->user_agent;
4166
4167 if (ua == NULL) {
4168 return NGX_DECLINED;
4169 }
4170
4171 /* reject requests with "User-Agent: foo" */
4172 if (ua->value.len == 3 &amp;&amp; ngx_strncmp(ua->value.data, "foo", 3) == 0) {
4173 return NGX_HTTP_FORBIDDEN;
4174 }
4175
4176 return NGX_DECLINED;
4177 }
4178
4179
4180 static ngx_int_t
4181 ngx_http_foo_init(ngx_conf_t *cf)
4182 {
4183 ngx_http_handler_pt *h;
4184 ngx_http_core_main_conf_t *cmcf;
4185
4186 cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module);
4187
4188 h = ngx_array_push(&amp;cmcf->phases[NGX_HTTP_PREACCESS_PHASE].handlers);
4189 if (h == NULL) {
4190 return NGX_ERROR;
4191 }
4192
4193 *h = ngx_http_foo_handler;
4194
4195 return NGX_OK;
4196 }
4197 </programlisting>
4198
4199 <para>
4200 Phase handlers are expected to return specific codes:
4201 </para>
4202
4203 <list type="bullet">
4204
4205 <listitem>
4206 <literal>NGX_OK</literal> - proceed to the next phase
4207 </listitem>
4208
4209 <listitem>
4210 <literal>NGX_DECLINED</literal> - proceed to the next handler of the current
4211 phase.
4212 If current handler is the last in current phase, move to the next phase
4213 </listitem>
4214
4215 <listitem>
4216 <literal>NGX_AGAIN, NGX_DONE</literal> - suspend phase handling until some
4217 future event.
4218 This can be for example asynchronous I/O operation or just a delay.
4219 It is supposed, that phase handling will be resumed later by calling
4220 <literal>ngx_http_core_run_phases()</literal>
4221 </listitem>
4222
4223 <listitem>
4224 Any other value returned by the phase handler is treated as a request
4225 finalization code, in particular, HTTP response code.
4226 The request is finalized with the code provided
4227 </listitem>
4228
4229 </list>
4230
4231 <para>
4232 Some phases treat return codes in a slightly different way.
4233 At content phase, any return code other that <literal>NGX_DECLINED</literal>
4234 is considered a finalization code.
4235 As for the location content handlers, any return from them is considered a
4236 finalization code.
4237 At access phase, in
4238 <link doc="../http/ngx_http_core_module.xml" id="satisfy">satisfy any</link>
4239 mode, returning a code other
4240 than <literal>NGX_OK, NGX_DECLINED, NGX_AGAIN, NGX_DONE</literal> is considered
4241 a denial.
4242 If none of future access handlers allow access or deny with a new
4243 code, the denial code will become the finalization code.
4244 </para>
4245
4246 </section>
4247
4248 </section>
4249
4250
3390 </article> 4251 </article>