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