Skip to content

Commit fa2da58

Browse files
agentzhagentzh
committed
updated docs to reflect recent changes.
1 parent 6ba9beb commit fa2da58

File tree

3 files changed

+250
-53
lines changed

3 files changed

+250
-53
lines changed

‎README

Lines changed: 86 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@ Status
99
This module is production ready.
1010

1111
Version
12-
This document describes srcache-nginx-module v0.13rc2
13-
(<https://github.com/agentzh/srcache-nginx-module/tags>) released on 15
14-
October 2011.
12+
This document describes srcache-nginx-module v0.13rc6
13+
(<https://github.com/agentzh/srcache-nginx-module/tags>) released on 16
14+
March 2012.
1515

1616
Synopsis
1717
upstream my_memcached {
@@ -64,6 +64,28 @@ Synopsis
6464
# or even static files on the disk
6565
}
6666

67+
map $request_method $skip_fetch {
68+
default 0;
69+
POST 1;
70+
PUT 1;
71+
}
72+
73+
server {
74+
listen 8080;
75+
76+
location /api/ {
77+
set $key "$uri?$args";
78+
79+
srcache_fetch GET /memc $key;
80+
srcache_store PUT /memc $key;
81+
82+
srcache_methods GET PUT POST;
83+
srcache_fetch_skip $skip_fetch;
84+
85+
# proxy_pass/drizzle_pass/content_by_lua/echo/...
86+
}
87+
}
88+
6789
Description
6890
This module provides a transparent caching layer for arbitrary nginx
6991
locations (like those use an upstream or even serve static disk files).
@@ -81,7 +103,7 @@ Description
81103
security reasons.
82104

83105
Subrequest caching
84-
For subrequests, we explicitly disallow the use of this module because
106+
For *subrequests*, we explicitly disallow the use of this module because
85107
it's too difficult to get right. There used to be an implementation but
86108
it was buggy and I finally gave up fixing it and abandoned it.
87109

@@ -205,7 +227,7 @@ Directives
205227

206228
context: *http, server, location, location if*
207229

208-
phase: *post access*
230+
phase: *post-access*
209231

210232
This directive registers an access phase handler that will issue an
211233
Nginx subrequest to lookup the cache.
@@ -230,7 +252,7 @@ Directives
230252

231253
context: *http, server, location, location if*
232254

233-
phase: *post access*
255+
phase: *post-access*
234256

235257
The "<flag>" argument supports nginx variables. When this argument's
236258
value is not empty *and* not equal to 0, then the fetching process will
@@ -258,14 +280,25 @@ Directives
258280
}
259281
where [[HttpLuaModule]] is used to calculate the value of the C<$skip> variable at the (earlier) rewrite phase. Similarly, the C<$key> variable can be computed by Lua using the L<set_by_lua|HttpLuaModule/"set_by_lua"> or L<rewrite_by_lua|HttpLuaModule/"rewrite_by_lua"> directive too.
260282

283+
The standard map directive can also be used to compute the value of the
284+
$skip variable used in the sample above:
285+
286+
map $cookie_foo $skip {
287+
default 0;
288+
bar 1;
289+
}
290+
291+
but your map statement should be put into the "http" config block in
292+
your "nginx.conf" file though.
293+
261294
srcache_store
262295
syntax: *srcache_store <method> <uri> <args>?*
263296

264297
default: *no*
265298

266299
context: *http, server, location, location if*
267300

268-
phase: *output filter*
301+
phase: *output-filter*
269302

270303
This directive registers an output filter handler that will issue an
271304
Nginx subrequest to save the response of the current main request into a
@@ -309,6 +342,8 @@ Directives
309342

310343
context: *http, server, location, location if*
311344

345+
phase: *output-header-filter*
346+
312347
When the response body length is exceeding this size, this module will
313348
not try to store the response body into the cache using the subrequest
314349
template that is specified in srcache_store.
@@ -326,7 +361,7 @@ Directives
326361

327362
context: *http, server, location, location if*
328363

329-
phase: *output filter*
364+
phase: *output-header-filter*
330365

331366
The "<flag>" argument supports Nginx variables. When this argument's
332367
value is not empty *and* not equal to 0, then the storing process will
@@ -350,7 +385,7 @@ Directives
350385

351386
context: *http, server, location, location if*
352387

353-
phase: *output filter*
388+
phase: *output-header-filter*
354389

355390
This directive controls what responses to store to the cache according
356391
to their status code.
@@ -375,7 +410,7 @@ Directives
375410

376411
context: *http, server, location, location if*
377412

378-
phase: *output filter*
413+
phase: *output-header-filter*
379414

380415
This directive controles the header buffer when serializing response
381416
headers for srcache_store. The default size is the page size, usually
@@ -394,7 +429,7 @@ Directives
394429

395430
context: *http, server, location, location if*
396431

397-
phase: *output filter*
432+
phase: *output-header-filter*
398433

399434
By default, this module caches all the response headers except the
400435
following ones:
@@ -436,7 +471,7 @@ Directives
436471

437472
context: *http, server, location, location if*
438473

439-
phase: *output filter*
474+
phase: *output-header-filter*
440475

441476
By default, this module caches all the response headers except the
442477
following ones:
@@ -479,7 +514,7 @@ Directives
479514

480515
context: *http, server, location*
481516

482-
phase: *output filter*
517+
phase: *post-access, output-header-filter*
483518

484519
This directive specifies HTTP request methods that are considered by
485520
either srcache_fetch or srcache_store. HTTP request methods not listed
@@ -498,7 +533,7 @@ Directives
498533

499534
context: *http, server, location, location if*
500535

501-
phase: *output filter*
536+
phase: *output-header-filter*
502537

503538
When this directive is turned "off" (which is the default), non-empty
504539
"Content-Encoding" response header will cause srcache_store skip storing
@@ -526,6 +561,8 @@ Directives
526561

527562
context: *http, server, location*
528563

564+
phase: *post-access, output-header-filter*
565+
529566
When this directive is turned "on", the request headers "Cache-Control"
530567
and "Pragma" will be honored by this module in the following ways:
531568

@@ -550,6 +587,8 @@ Directives
550587

551588
context: *http, server, location*
552589

590+
phase: *output-header-filter*
591+
553592
When this directive is turned "on", the response headers "Cache-Control"
554593
and "Expires" will be honored by this module in the following ways:
555594

@@ -577,7 +616,7 @@ Directives
577616

578617
context: *http, server, location*
579618

580-
phase: *output filter*
619+
phase: *output-header-filter*
581620

582621
Turning this directive on will force responses with the header
583622
"Cache-Control: no-store" to be stored into the cache when
@@ -593,7 +632,7 @@ Directives
593632

594633
context: *http, server, location*
595634

596-
phase: *output filter*
635+
phase: *output-header-filter*
597636

598637
Turning this directive on will force responses with the header
599638
"Cache-Control: no-cache" to be stored into the cache when
@@ -609,7 +648,7 @@ Directives
609648

610649
context: *http, server, location*
611650

612-
phase: *output filter*
651+
phase: *output-header-filter*
613652

614653
Turning this directive on will force responses with the header
615654
"Cache-Control: private" to be stored into the cache when
@@ -625,7 +664,7 @@ Directives
625664

626665
context: *http, server, location, location if*
627666

628-
phase: *output filter*
667+
phase: *output-header-filter*
629668

630669
This directive controls the default expiration time period that is
631670
allowed for the $srcache_expire variable value when neither
@@ -650,7 +689,7 @@ Directives
650689

651690
context: *http, server, location, location if*
652691

653-
phase: *output filter*
692+
phase: *output-header-filter*
654693

655694
This directive controls the maximal expiration time period that is
656695
allowed for the $srcache_expire variable value. This setting takes
@@ -714,6 +753,34 @@ Caveats
714753

715754
proxy_set_header Accept-Encoding "";
716755

756+
* Do *not* use [[HttpRewriteModule]]'s if directive in the same
757+
location as this module's, because "if is evil". Instead, use
758+
[[HttpMapModule]] or [[HttpLuaModule]] combined with this module's
759+
srcache_store_skip and/or srcache_fetch_skip directives. For
760+
example:
761+
762+
map $request_method $skip_fetch {
763+
default 0;
764+
POST 1;
765+
PUT 1;
766+
}
767+
768+
server {
769+
listen 8080;
770+
771+
location /api/ {
772+
set $key "$uri?$args";
773+
774+
srcache_fetch GET /memc $key;
775+
srcache_store PUT /memc $key;
776+
777+
srcache_methods GET PUT POST;
778+
srcache_fetch_skip $skip_fetch;
779+
780+
# proxy_pass/drizzle_pass/content_by_lua/echo/...
781+
}
782+
}
783+
717784
Installation
718785
It's recommended to install this module as well as the Nginx core and
719786
many other goodies via the ngx_openresty bundle

0 commit comments

Comments
 (0)