/* Copyright 2000-2006 The Apache Software Foundation or its licensors, as
 * applicable.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

Mod-Cache-Requester
-------------------

Contents
--------
This document covers following topics for mod-cache-requester.

1. Concept
2. Implementation
3. Compilation
4. Configuration.


1. Concept
----------
a.) Every time a page expires, it is removed from the cache and thus next request would require server to re-generate the cached page.

b.) this module keeps track of all popular pages and re-requests them before they are removed from the cache so that server 'refreshes' those pages.

c.) Execution flow.
	a. request is received by te mod-cache quick handler.
	b. if page is 'soon-to-expire' then quick-handler lets mod-cache-requester know about this page and it continues processing the request.
	c. if page is already there in queue of mod-cache-requester, its priority is incremented by one. if not, then this page is inserted in the queue.
	d. mod-cache-requester pops the highest priority page from queue and re-requests (in a seperate thread) that page, 
	   with the note indicating that this page is coming from the mod-cache-requester so it should not be served from cache. 
	   rather quick handler should add save filter for this request.
	e. mod-cache-requester receives data which it throws away as the objective of this request - to reload page in cache - is already achieved.

	f. if no pending request is available in the queue of mod-cache-requester then all threads go to sleep.

2. Implementation
-----------------
a.) a new provider is added in mod_cache.h (cache_req_provider) which provides an interface (notify-cache-requester) to notify about soon-to-expire pages.
    This provider would allow us to change/add implementation of mod-cache-requester without affecting mod_cache.

b.) mod-cache-requester implements a cache-req-provider.

c.) mod_cache_requester.h implements key data structures. (again it would allow us to add/change the implementation of re-requesting technique. keeping all these data structures in mod_cache_requester.c would not let us have this flexibility)

d.) mod-cache-requester uses libcurl(function make_curl_request) to make the re-request the documents. and it adds a note in input headers indicating that this page is being requested by mod-cache-requester. So server does return cached page and it reloads the page. for security reasons, 

3. Compilation
--------------
a.) copy mod_cache_requester[.h/.c], config.m4 in the cache modules.

b.) apply mod_cache.h.patch and mod_cache.c.patches.

c.) config.m4 should detect the required libraries automatically, if now please follow below instructions.
	while compiling and linking this module, provide libcurl path. http://curl.haxx.se/libcurl/using/
		a. curl-config --cflags command returns list of all files to be  included in CFLAGS
		b. curl-config --libs command returns list of all libraries to e incuded in LDFLAGS 

4. Configuration
----------------
a.) This is a sub-module of a mod_cache

b.) it provides following directives.
	a. CacheRequesterThreads: Number of threads those run in background and keep re-requesting popular pages.
	b. CacheRequesterMaxQueueSize: Maximum size of the expiring pages waiting page queue.
	c. CacheRequesterSoonToExpireTime: (In Seconds) when expiring time of a page is equal or less than CacheRequesterSoonToExpireTime, 
	then such page would be inserted into the queue whose elements are going to be re-requested.
	d. CacheRequesterSecretCode: This string value is used by libcurl request as an input-header. This would be used to authenticate requests created by mod-cache-requester.

c.) Sample config file is shown below.
# I have set CacheRequesterSoonToExpireTime too high just to make most of the pages in the cache be considered as soon-to-be-expired!

LoadModule cache_module modules/mod_cache.so
LoadModule disk_cache_module modules/mod_disk_cache.so
LoadModule mem_cache_module modules/mod_mem_cache.so
LoadModule cache_requester_module modules/mod_cache_requester.so

<IfModule mod_cache.c>
	CacheIgnoreCacheControl On
	<IfModule mod_mem_cache.c>
		CacheEnable mem /
		MCacheSize 4096
		MCacheMaxObjectCount 100
		MCacheMinObjectSize 1
		MCacheMaxObjectSize 2048
	</IfModule>

	<IfModule mod_cache_requester.c>
		CacheRequesterThreads 2
		CacheRequesterMaxQueueSize 10
		CacheRequesterSoonToExpireTime 1000000
		CacheRequesterSecretCode ABCDEF
	</IfModule>
</IfModule>