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