Mercurial > hg > nginx-site
comparison xml/en/docs/dev/development_guide.xml @ 1929:7f290929b32d
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 && 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(&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> |