If you are going to use this module to cache location responses out of the box, try [[HttpSRCacheModule]] with this module to achieve that.

If you are going to use this module to cache location responses out of the box, try [[HttpSRCacheModule]] with this module to achieve that.

−

When used in conjunction with [[HttpLuaModule]], it is recommended to use the [http://github.com/agentzh/lua-resty-memcached lua-resty-memcached] library instead of this one, since the former is more memory-friendly.

+

When used in conjunction with [[HttpLuaModule]], it is recommended to use the [http://github.com/agentzh/lua-resty-memcached lua-resty-memcached] library instead of this one, since the former is more flexible and more memory-efficient.

# GET /bar?cmd=get&key=cat# GET /bar?cmd=set&key=dog&val=animal&flags=1234&exptime=2# GET /bar?cmd=delete&key=dog# GET /bar?cmd=flush_alllocation /bar {set$memc_cmd$arg_cmd;set$memc_key$arg_key;set$memc_value$arg_val;set$memc_flags$arg_flags;# defaults to 0set$memc_exptime$arg_exptime;# defaults to 0
memc_cmds_allowed get set add delete flush_all;
memc_pass 127.0.0.1:11211;}

Memcached commands supported

The memcached storage commands set, add, replace, prepend, and append uses the $memc_key as the key, $memc_exptime as the expiration time (or delay) (defaults to 0), $memc_flags as the flags (defaults to 0), to build the corresponding memcached queries.

If $memc_value is not defined at all, then the request body will be used as the value of the $memc_value except for the incr and decr commands. Note that if $memc_value is defined as an empty string (""), that empty string will still be used as the value as is.

The following memcached commands have been implemented and tested (with their parameters marked by corresponding
nginx variables defined by this module):

get $memc_key

Returns 200 OK with the value put into the response body if the key is found, or 404 Not Found otherwise. The flags number will be set into the $memc_flags variable so it's often desired to put that info into the response headers by means of the standard add_header directive.

It returns 502 for ERROR, CLIENT_ERROR, or SERVER_ERROR.

set $memc_key $memc_flags $memc_exptime $memc_value

To use the request body as the memcached value, just avoid setting the $memc_value variable:

For Developers

The memached response parsers were generated by Ragel. If you want to
regenerate the parser's C file, i.e., src/ngx_http_memc_response.c, use the following command from the root of the memc module's source tree:

$ ragel -G2 src/ngx_http_memc_response.rl

Compatibility

The following versions of Nginx should work with this module:

1.2.x (last tested: 1.2.1)

1.1.x (last tested: 1.1.5)

1.0.x (last tested: 1.0.10)

0.9.x (last tested: 0.9.4)

0.8.x (last tested: 0.8.54)

0.7.x >= 0.7.46 (last tested: 0.7.68)

It's worth mentioning that some 0.7.x versions older than 0.7.46 might also work, but I can't easily test them because the test suite makes extensive use of the echo module's echo_location directive, which requires at least nginx 0.7.46 :)

Earlier versions of Nginx like 0.6.x and 0.5.x will not work.

If you find that any particular version of Nginx above 0.7.46 does not work with this module, please consider reporting a bug.

Because a single nginx server (by default, localhost:1984) is used across all the test scripts (.t files), it's meaningless to run the test suite in parallel by specifying -jN when invoking the prove utility.

You should also keep a memcached server listening on the 11211 port at localhost before running the test suite.

Some parts of the test suite requires modules rewrite and echo to be enabled as well when building Nginx.

TODO

add support for the memcached commands cas, gets and stats $memc_value.

add support for the noreply option.

Getting involved

You'll be very welcomed to submit patches to the author or just ask for a commit bit to the source repository on GitHub.

Author

Yichun "agentzh" Zhang (章亦春) <agentzh@gmail.com>

This wiki page is also maintained by the author himself, and everybody is encouraged to improve this page as well.

Copyright & License

The code base is borrowed directly from the standard memcached module in the Nginx 0.8.28 core. This part of code is copyrighted by Igor Sysoev.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.