granicus.if.org Git - apache/blob - 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 "httpd.h"
  30 #include "apr_date.h"
  31 #include "apr_optional.h"
  32 #include "apr_hooks.h"
  33
  34 /* Create a set of CACHE_DECLARE(type), CACHE_DECLARE_NONSTD(type) and
  35  * CACHE_DECLARE_DATA with appropriate export and import tags for the platform
  36  */
  37 #if !defined(WIN32)
  38 #define CACHE_DECLARE(type)            type
  39 #define CACHE_DECLARE_NONSTD(type)     type
  40 #define CACHE_DECLARE_DATA
  41 #elif defined(CACHE_DECLARE_STATIC)
  42 #define CACHE_DECLARE(type)            type __stdcall
  43 #define CACHE_DECLARE_NONSTD(type)     type
  44 #define CACHE_DECLARE_DATA
  45 #elif defined(CACHE_DECLARE_EXPORT)
  46 #define CACHE_DECLARE(type)            __declspec(dllexport) type __stdcall
  47 #define CACHE_DECLARE_NONSTD(type)     __declspec(dllexport) type
  48 #define CACHE_DECLARE_DATA             __declspec(dllexport)
  49 #else
  50 #define CACHE_DECLARE(type)            __declspec(dllimport) type __stdcall
  51 #define CACHE_DECLARE_NONSTD(type)     __declspec(dllimport) type
  52 #define CACHE_DECLARE_DATA             __declspec(dllimport)
  53 #endif
  54
  55 /* a cache control header breakdown */
  56 typedef struct cache_control cache_control_t;
  57 struct cache_control {
  58     unsigned int parsed:1;
  59     unsigned int cache_control:1;
  60     unsigned int pragma:1;
  61     unsigned int no_cache:1;
  62     unsigned int no_cache_header:1; /* no cache by header match */
  63     unsigned int no_store:1;
  64     unsigned int max_age:1;
  65     unsigned int max_stale:1;
  66     unsigned int min_fresh:1;
  67     unsigned int no_transform:1;
  68     unsigned int only_if_cached:1;
  69     unsigned int public:1;
  70     unsigned int private:1;
  71     unsigned int private_header:1; /* private by header match */
  72     unsigned int must_revalidate:1;
  73     unsigned int proxy_revalidate:1;
  74     unsigned int s_maxage:1;
  75     apr_int64_t max_age_value; /* if positive, then set */
  76     apr_int64_t max_stale_value; /* if positive, then set */
  77     apr_int64_t min_fresh_value; /* if positive, then set */
  78     apr_int64_t s_maxage_value; /* if positive, then set */
  79 };
  80
  81 /* cache info information */
  82 typedef struct cache_info cache_info;
  83 struct cache_info {
  84     /**
  85      * the original time corresponding to the 'Date:' header of the request
  86      * served
  87      */
  88     apr_time_t date;
  89     /** a time when the cached entity is due to expire */
  90     apr_time_t expire;
  91     /** r->request_time from the same request */
  92     apr_time_t request_time;
  93     /** apr_time_now() at the time the entity was acutally cached */
  94     apr_time_t response_time;
  95     /**
  96      * HTTP status code of the cached entity. Though not necessarily the
  97      * status code finally issued to the request.
  98      */
  99     int status;
 100     /* cached cache-control */
 101     cache_control_t control;
 102 };
 103
 104 /* cache handle information */
 105 typedef struct cache_object cache_object_t;
 106 struct cache_object {
 107     const char *key;
 108     cache_object_t *next;
 109     cache_info info;
 110     /* Opaque portion (specific to the implementation) of the cache object */
 111     void *vobj;
 112 };
 113
 114 typedef struct cache_handle cache_handle_t;
 115 struct cache_handle {
 116     cache_object_t *cache_obj;
 117     apr_table_t *req_hdrs;        /* cached request headers */
 118     apr_table_t *resp_hdrs;       /* cached response headers */
 119 };
 120
 121 #define CACHE_PROVIDER_GROUP "cache"
 122
 123 typedef struct {
 124     int (*remove_entity) (cache_handle_t *h);
 125     apr_status_t (*store_headers)(cache_handle_t *h, request_rec *r, cache_info *i);
 126     apr_status_t (*store_body)(cache_handle_t *h, request_rec *r, apr_bucket_brigade *in,
 127                            apr_bucket_brigade *out);
 128     apr_status_t (*recall_headers) (cache_handle_t *h, request_rec *r);
 129     apr_status_t (*recall_body) (cache_handle_t *h, apr_pool_t *p, apr_bucket_brigade *bb);
 130     int (*create_entity) (cache_handle_t *h, request_rec *r,
 131                            const char *urlkey, apr_off_t len, apr_bucket_brigade *bb);
 132     int (*open_entity) (cache_handle_t *h, request_rec *r,
 133                            const char *urlkey);
 134     int (*remove_url) (cache_handle_t *h, request_rec *r);
 135     apr_status_t (*commit_entity)(cache_handle_t *h, request_rec *r);
 136 } cache_provider;
 137
 138 typedef enum {
 139     AP_CACHE_HIT,
 140     AP_CACHE_REVALIDATE,
 141     AP_CACHE_MISS
 142 } ap_cache_status_e;
 143
 144 #define AP_CACHE_HIT_ENV "cache-hit"
 145 #define AP_CACHE_REVALIDATE_ENV "cache-revalidate"
 146 #define AP_CACHE_MISS_ENV "cache-miss"
 147 #define AP_CACHE_STATUS_ENV "cache-status"
 148
 149
 150 /* cache_util.c */
 151 /* do a HTTP/1.1 age calculation */
 152 CACHE_DECLARE(apr_time_t) ap_cache_current_age(cache_info *info, const apr_time_t age_value,
 153                                                apr_time_t now);
 154
 155 CACHE_DECLARE(apr_time_t) ap_cache_hex2usec(const char *x);
 156 CACHE_DECLARE(void) ap_cache_usec2hex(apr_time_t j, char *y);
 157 CACHE_DECLARE(char *) ap_cache_generate_name(apr_pool_t *p, int dirlevels,
 158                                              int dirlength,
 159                                              const char *name);
 160 CACHE_DECLARE(int) ap_cache_liststr(apr_pool_t *p, const char *list,
 161                                     const char *key, char **val);
 162 CACHE_DECLARE(const char *)ap_cache_tokstr(apr_pool_t *p, const char *list, const char **str);
 163
 164 /* Create a new table consisting of those elements from an
 165  * headers table that are allowed to be stored in a cache.
 166  */
 167 CACHE_DECLARE(apr_table_t *)ap_cache_cacheable_headers(apr_pool_t *pool,
 168                                                         apr_table_t *t,
 169                                                         server_rec *s);
 170
 171 /* Create a new table consisting of those elements from an input
 172  * headers table that are allowed to be stored in a cache.
 173  */
 174 CACHE_DECLARE(apr_table_t *)ap_cache_cacheable_headers_in(request_rec *r);
 175
 176 /* Create a new table consisting of those elements from an output
 177  * headers table that are allowed to be stored in a cache;
 178  * ensure there is a content type and capture any errors.
 179  */
 180 CACHE_DECLARE(apr_table_t *)ap_cache_cacheable_headers_out(request_rec *r);
 181
 182 /**
 183  * Parse the Cache-Control and Pragma headers in one go, marking
 184  * which tokens appear within the header. Populate the structure
 185  * passed in.
 186  */
 187 int ap_cache_control(request_rec *r, cache_control_t *cc, const char *cc_header,
 188         const char *pragma_header, apr_table_t *headers);
 189
 190
 191 /* hooks */
 192
 193 /**
 194  * Cache status hook.
 195  * This hook is called as soon as the cache has made a decision as to whether
 196  * an entity should be served from cache (hit), should be served from cache
 197  * after a successful validation (revalidate), or served from the backend
 198  * and potentially cached (miss).
 199  *
 200  * A basic implementation of this hook exists in mod_cache which writes this
 201  * information to the subprocess environment, and optionally to request
 202  * headers. Further implementations may add hooks as appropriate to perform
 203  * more advanced processing, or to store statistics about the cache behaviour.
 204  */
 205 APR_DECLARE_EXTERNAL_HOOK(cache, CACHE, int, cache_status, (cache_handle_t *h,
 206                 request_rec *r, apr_table_t *headers, ap_cache_status_e status,
 207                 const char *reason))
 208
 209 APR_DECLARE_OPTIONAL_FN(apr_status_t,
 210                         ap_cache_generate_key,
 211                         (request_rec *r, apr_pool_t*p, const char **key));
 212
 213
 214 #endif /*MOD_CACHE_H*/
 215 /** @} */