modules/cache/mod_cache.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file mod_cache.h
  19  * @brief Main include file for the Apache Transparent Cache
  20  *
  21  * @defgroup MOD_CACHE mod_cache
  22  * @ingroup  APACHE_MODS
  23  * @{
  24  */
  25
  26 #ifndef MOD_CACHE_H
  27 #define MOD_CACHE_H
  28
  29 #include "apr_hooks.h"
  30 #include "apr.h"
  31 #include "apr_lib.h"
  32 #include "apr_strings.h"
  33 #include "apr_buckets.h"
  34 #include "apr_md5.h"
  35 #include "apr_pools.h"
  36 #include "apr_strings.h"
  37 #include "apr_optional.h"
  38 #define APR_WANT_STRFUNC
  39 #include "apr_want.h"
  40
  41 #include "httpd.h"
  42 #include "http_config.h"
  43 #include "ap_config.h"
  44 #include "http_core.h"
  45 #include "http_protocol.h"
  46 #include "http_request.h"
  47 #include "http_vhost.h"
  48 #include "http_main.h"
  49 #include "http_log.h"
  50 #include "http_connection.h"
  51 #include "util_filter.h"
  52 #include "apr_date.h"
  53 #include "apr_uri.h"
  54
  55 #ifdef HAVE_NETDB_H
  56 #include <netdb.h>
  57 #endif
  58
  59 #ifdef HAVE_SYS_SOCKET_H
  60 #include <sys/socket.h>
  61 #endif
  62
  63 #ifdef HAVE_NETINET_IN_H
  64 #include <netinet/in.h>
  65 #endif
  66
  67 #ifdef HAVE_ARPA_INET_H
  68 #include <arpa/inet.h>
  69 #endif
  70
  71 #include "apr_atomic.h"
  72
  73 #ifndef MAX
  74 #define MAX(a,b)                ((a) > (b) ? (a) : (b))
  75 #endif
  76 #ifndef MIN
  77 #define MIN(a,b)                ((a) < (b) ? (a) : (b))
  78 #endif
  79
  80 #define MSEC_ONE_DAY    ((apr_time_t)(86400*APR_USEC_PER_SEC)) /* one day, in microseconds */
  81 #define MSEC_ONE_HR     ((apr_time_t)(3600*APR_USEC_PER_SEC))  /* one hour, in microseconds */
  82 #define MSEC_ONE_MIN    ((apr_time_t)(60*APR_USEC_PER_SEC))    /* one minute, in microseconds */
  83 #define MSEC_ONE_SEC    ((apr_time_t)(APR_USEC_PER_SEC))       /* one second, in microseconds */
  84 #define DEFAULT_CACHE_MAXEXPIRE MSEC_ONE_DAY
  85 #define DEFAULT_CACHE_MINEXPIRE 0
  86 #define DEFAULT_CACHE_EXPIRE    MSEC_ONE_HR
  87 #define DEFAULT_CACHE_LMFACTOR  (0.1)
  88
  89 /* Create a set of CACHE_DECLARE(type), CACHE_DECLARE_NONSTD(type) and
  90  * CACHE_DECLARE_DATA with appropriate export and import tags for the platform
  91  */
  92 #if !defined(WIN32)
  93 #define CACHE_DECLARE(type)            type
  94 #define CACHE_DECLARE_NONSTD(type)     type
  95 #define CACHE_DECLARE_DATA
  96 #elif defined(CACHE_DECLARE_STATIC)
  97 #define CACHE_DECLARE(type)            type __stdcall
  98 #define CACHE_DECLARE_NONSTD(type)     type
  99 #define CACHE_DECLARE_DATA
 100 #elif defined(CACHE_DECLARE_EXPORT)
 101 #define CACHE_DECLARE(type)            __declspec(dllexport) type __stdcall
 102 #define CACHE_DECLARE_NONSTD(type)     __declspec(dllexport) type
 103 #define CACHE_DECLARE_DATA             __declspec(dllexport)
 104 #else
 105 #define CACHE_DECLARE(type)            __declspec(dllimport) type __stdcall
 106 #define CACHE_DECLARE_NONSTD(type)     __declspec(dllimport) type
 107 #define CACHE_DECLARE_DATA             __declspec(dllimport)
 108 #endif
 109
 110 struct cache_enable {
 111     apr_uri_t url;
 112     const char *type;
 113     apr_size_t pathlen;
 114 };
 115
 116 struct cache_disable {
 117     apr_uri_t url;
 118     apr_size_t pathlen;
 119 };
 120
 121 /* static information about the local cache */
 122 typedef struct {
 123     apr_array_header_t *cacheenable;    /* URLs to cache */
 124     apr_array_header_t *cachedisable;   /* URLs not to cache */
 125     /* Maximum time to keep cached files in msecs */
 126     apr_time_t maxex;
 127     int maxex_set;
 128     /* default time to keep cached file in msecs */
 129     apr_time_t defex;
 130     int defex_set;
 131     /* factor for estimating expires date */
 132     double factor;
 133     int factor_set;
 134     /** ignore the last-modified header when deciding to cache this request */
 135     int no_last_mod_ignore_set;
 136     int no_last_mod_ignore;
 137     /** ignore client's requests for uncached responses */
 138     int ignorecachecontrol;
 139     int ignorecachecontrol_set;
 140     /** ignore Cache-Control: private header from server */
 141     int store_private;
 142     int store_private_set;
 143     /** ignore Cache-Control: no-store header from client or server */
 144     int store_nostore;
 145     int store_nostore_set;
 146     /** store the headers that should not be stored in the cache */
 147     apr_array_header_t *ignore_headers;
 148     /* flag if CacheIgnoreHeader has been set */
 149     #define CACHE_IGNORE_HEADERS_SET   1
 150     #define CACHE_IGNORE_HEADERS_UNSET 0
 151     int ignore_headers_set;
 152     /* Minimum time to keep cached files in msecs */
 153     apr_time_t minex;
 154     int minex_set;
 155     /** ignore query-string when caching */
 156     int ignorequerystring;
 157     int ignorequerystring_set;
 158 } cache_server_conf;
 159
 160 /* cache info information */
 161 typedef struct cache_info cache_info;
 162 struct cache_info {
 163     /**
 164      * HTTP status code of the cached entity. Though not neccessarily the
 165      * status code finally issued to the request.
 166      */
 167     int status;
 168     /**
 169      * the original time corresponding to the 'Date:' header of the request
 170      * served
 171      */
 172     apr_time_t date;
 173     /** a time when the cached entity is due to expire */
 174     apr_time_t expire;
 175     /** r->request_time from the same request */
 176     apr_time_t request_time;
 177     /** apr_time_now() at the time the entity was acutally cached */
 178     apr_time_t response_time;
 179 };
 180
 181 /* cache handle information */
 182
 183 /* XXX TODO On the next structure change/MMN bump,
 184  * count must become an apr_off_t, representing
 185  * the potential size of disk cached objects.
 186  * Then dig for
 187  * "XXX Bad Temporary Cast - see cache_object_t notes"
 188  */
 189 typedef struct cache_object cache_object_t;
 190 struct cache_object {
 191     const char *key;
 192     cache_object_t *next;
 193     cache_info info;
 194     /* Opaque portion (specific to the implementation) of the cache object */
 195     void *vobj;
 196     /* FIXME: These are only required for mod_mem_cache. */
 197     apr_size_t count;   /* Number of body bytes written to the cache so far */
 198     int complete;
 199     apr_uint32_t refcount;  /* refcount and bit flag to cleanup object */
 200 };
 201
 202 typedef struct cache_handle cache_handle_t;
 203 struct cache_handle {
 204     cache_object_t *cache_obj;
 205     apr_table_t *req_hdrs;        /* cached request headers */
 206     apr_table_t *resp_hdrs;       /* cached response headers */
 207 };
 208
 209 #define CACHE_PROVIDER_GROUP "cache"
 210
 211 typedef struct {
 212     int (*remove_entity) (cache_handle_t *h);
 213     apr_status_t (*store_headers)(cache_handle_t *h, request_rec *r, cache_info *i);
 214     apr_status_t (*store_body)(cache_handle_t *h, request_rec *r, apr_bucket_brigade *b);
 215     apr_status_t (*recall_headers) (cache_handle_t *h, request_rec *r);
 216     apr_status_t (*recall_body) (cache_handle_t *h, apr_pool_t *p, apr_bucket_brigade *bb);
 217     int (*create_entity) (cache_handle_t *h, request_rec *r,
 218                            const char *urlkey, apr_off_t len);
 219     int (*open_entity) (cache_handle_t *h, request_rec *r,
 220                            const char *urlkey);
 221     int (*remove_url) (cache_handle_t *h, apr_pool_t *p);
 222 } cache_provider;
 223
 224 /* A linked-list of authn providers. */
 225 typedef struct cache_provider_list cache_provider_list;
 226
 227 struct cache_provider_list {
 228     const char *provider_name;
 229     const cache_provider *provider;
 230     cache_provider_list *next;
 231 };
 232
 233 /* per request cache information */
 234 typedef struct {
 235     cache_provider_list *providers;     /* possible cache providers */
 236     const cache_provider *provider;     /* current cache provider */
 237     const char *provider_name;          /* current cache provider name */
 238     int fresh;                          /* is the entitey fresh? */
 239     cache_handle_t *handle;             /* current cache handle */
 240     cache_handle_t *stale_handle;       /* stale cache handle */
 241     apr_table_t *stale_headers;         /* original request headers. */
 242     int in_checked;                     /* CACHE_SAVE must cache the entity */
 243     int block_response;                 /* CACHE_SAVE must block response. */
 244     apr_bucket_brigade *saved_brigade;  /* copy of partial response */
 245     apr_off_t saved_size;               /* length of saved_brigade */
 246     apr_time_t exp;                     /* expiration */
 247     apr_time_t lastmod;                 /* last-modified time */
 248     cache_info *info;                   /* current cache info */
 249     ap_filter_t *remove_url_filter;     /* Enable us to remove the filter */
 250     char *key;                          /* The cache key created for this
 251                                          * request
 252                                          */
 253 } cache_request_rec;
 254
 255
 256 /* cache_util.c */
 257 /* do a HTTP/1.1 age calculation */
 258 CACHE_DECLARE(apr_time_t) ap_cache_current_age(cache_info *info, const apr_time_t age_value,
 259                                                apr_time_t now);
 260
 261 /**
 262  * Check the freshness of the cache object per RFC2616 section 13.2 (Expiration Model)
 263  * @param h cache_handle_t
 264  * @param r request_rec
 265  * @return 0 ==> cache object is stale, 1 ==> cache object is fresh
 266  */
 267 CACHE_DECLARE(int) ap_cache_check_freshness(cache_handle_t *h, request_rec *r);
 268
 269 /**
 270  * Merge in cached headers into the response
 271  * @param h cache_handle_t
 272  * @param r request_rec
 273  * @param preserve_orig If 1, the values in r->headers_out are preserved.
 274  *        Otherwise, they are overwritten by the cached value.
 275  */
 276 CACHE_DECLARE(void) ap_cache_accept_headers(cache_handle_t *h, request_rec *r,
 277                                             int preserve_orig);
 278
 279 CACHE_DECLARE(apr_time_t) ap_cache_hex2usec(const char *x);
 280 CACHE_DECLARE(void) ap_cache_usec2hex(apr_time_t j, char *y);
 281 CACHE_DECLARE(char *) ap_cache_generate_name(apr_pool_t *p, int dirlevels,
 282                                              int dirlength,
 283                                              const char *name);
 284 CACHE_DECLARE(cache_provider_list *)ap_cache_get_providers(request_rec *r, cache_server_conf *conf, apr_uri_t uri);
 285 CACHE_DECLARE(int) ap_cache_liststr(apr_pool_t *p, const char *list,
 286                                     const char *key, char **val);
 287 CACHE_DECLARE(const char *)ap_cache_tokstr(apr_pool_t *p, const char *list, const char **str);
 288
 289 /* Create a new table consisting of those elements from an
 290  * headers table that are allowed to be stored in a cache.
 291  */
 292 CACHE_DECLARE(apr_table_t *)ap_cache_cacheable_headers(apr_pool_t *pool,
 293                                                         apr_table_t *t,
 294                                                         server_rec *s);
 295
 296 /* Create a new table consisting of those elements from an input
 297  * headers table that are allowed to be stored in a cache.
 298  */
 299 CACHE_DECLARE(apr_table_t *)ap_cache_cacheable_headers_in(request_rec *r);
 300
 301 /* Create a new table consisting of those elements from an output
 302  * headers table that are allowed to be stored in a cache;
 303  * ensure there is a content type and capture any errors.
 304  */
 305 CACHE_DECLARE(apr_table_t *)ap_cache_cacheable_headers_out(request_rec *r);
 306
 307 /* Legacy call - functionally equivalent to ap_cache_cacheable_headers.
 308  * @deprecated @see ap_cache_cacheable_headers
 309  */
 310 CACHE_DECLARE(apr_table_t *)ap_cache_cacheable_hdrs_out(apr_pool_t *pool,
 311                                                         apr_table_t *t,
 312                                                         server_rec *s);
 313
 314 /**
 315  * cache_storage.c
 316  */
 317 int cache_remove_url(cache_request_rec *cache, apr_pool_t *p);
 318 int cache_create_entity(request_rec *r, apr_off_t size);
 319 int cache_select(request_rec *r);
 320 apr_status_t cache_generate_key_default( request_rec *r, apr_pool_t*p, char**key );
 321 /**
 322  * create a key for the cache based on the request record
 323  * this is the 'default' version, which can be overridden by a default function
 324  */
 325 const char* cache_create_key( request_rec*r );
 326
 327 /*
 328 apr_status_t cache_store_entity_headers(cache_handle_t *h, request_rec *r, cache_info *info);
 329 apr_status_t cache_store_entity_body(cache_handle_t *h, request_rec *r, apr_bucket_brigade *bb);
 330
 331 apr_status_t cache_recall_entity_headers(cache_handle_t *h, request_rec *r);
 332 apr_status_t cache_recall_entity_body(cache_handle_t *h, apr_pool_t *p, apr_bucket_brigade *bb);
 333 */
 334
 335 /* hooks */
 336
 337 APR_DECLARE_OPTIONAL_FN(apr_status_t,
 338                         ap_cache_generate_key,
 339                         (request_rec *r, apr_pool_t*p, char**key ));
 340
 341
 342 #endif /*MOD_CACHE_H*/
 343 /** @} */