mod_cache.h revision 0e4d28ac2522b8cca425f5f5f668ded49bb5c7ed
842ae4bd224140319ae7feec1872b93dfd491143fielding/* Licensed to the Apache Software Foundation (ASF) under one or more
842ae4bd224140319ae7feec1872b93dfd491143fielding * contributor license agreements. See the NOTICE file distributed with
842ae4bd224140319ae7feec1872b93dfd491143fielding * this work for additional information regarding copyright ownership.
842ae4bd224140319ae7feec1872b93dfd491143fielding * The ASF licenses this file to You under the Apache License, Version 2.0
842ae4bd224140319ae7feec1872b93dfd491143fielding * (the "License"); you may not use this file except in compliance with
842ae4bd224140319ae7feec1872b93dfd491143fielding * the License. You may obtain a copy of the License at
2d2eda71267231c2526be701fe655db125852c1ffielding *
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * http://www.apache.org/licenses/LICENSE-2.0
2d2eda71267231c2526be701fe655db125852c1ffielding *
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * Unless required by applicable law or agreed to in writing, software
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * distributed under the License is distributed on an "AS IS" BASIS,
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * See the License for the specific language governing permissions and
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd * limitations under the License.
2d2eda71267231c2526be701fe655db125852c1ffielding */
2d2eda71267231c2526be701fe655db125852c1ffielding
759f4a24d09e28c4eaca9f97311b497fc15cb5c7ben/**
0432a26b69eedfb9ca5f34fba590236378a24851ben * @file mod_cache.h
0432a26b69eedfb9ca5f34fba590236378a24851ben * @brief Main include file for the Apache Transparent Cache
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh *
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh * @defgroup MOD_CACHE mod_cache
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh * @ingroup APACHE_MODS
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh * @{
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh */
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh#ifndef MOD_CACHE_H
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh#define MOD_CACHE_H
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh#include "httpd.h"
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh#include "apr_date.h"
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh#include "apr_optional.h"
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh#include "apr_hooks.h"
2d2eda71267231c2526be701fe655db125852c1ffielding
2d2eda71267231c2526be701fe655db125852c1ffielding#include "cache_common.h"
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh/* Create a set of CACHE_DECLARE(type), CACHE_DECLARE_NONSTD(type) and
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh * CACHE_DECLARE_DATA with appropriate export and import tags for the platform
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb */
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb#if !defined(WIN32)
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb#define CACHE_DECLARE(type) type
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb#define CACHE_DECLARE_NONSTD(type) type
2d2eda71267231c2526be701fe655db125852c1ffielding#define CACHE_DECLARE_DATA
30c289e6bc6d28d210b21edd800ab2cfc78a8381wrowe#elif defined(CACHE_DECLARE_STATIC)
cccd31fa4a72fe23cc3249c06db181b274a55a69gstein#define CACHE_DECLARE(type) type __stdcall
cccd31fa4a72fe23cc3249c06db181b274a55a69gstein#define CACHE_DECLARE_NONSTD(type) type
cd39d2139743ca0ef899953c6496dcf99e9c791atrawick#define CACHE_DECLARE_DATA
cccd31fa4a72fe23cc3249c06db181b274a55a69gstein#elif defined(CACHE_DECLARE_EXPORT)
a261b81a1044c0e2ea3f21cf9b7019297bad16aajorton#define CACHE_DECLARE(type) __declspec(dllexport) type __stdcall
b627048681b27fe30f979ba471b523be3a6a22adrbb#define CACHE_DECLARE_NONSTD(type) __declspec(dllexport) type
cccd31fa4a72fe23cc3249c06db181b274a55a69gstein#define CACHE_DECLARE_DATA __declspec(dllexport)
cccd31fa4a72fe23cc3249c06db181b274a55a69gstein#else
44c46ef733836b32585d135d2d90856e7cfd9929rbb#define CACHE_DECLARE(type) __declspec(dllimport) type __stdcall
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb#define CACHE_DECLARE_NONSTD(type) __declspec(dllimport) type
e6cc28a5eb3371ba0c38e941855e71ff0054f50erbb#define CACHE_DECLARE_DATA __declspec(dllimport)
d9039a9aaeaa1359c1147af66c09aeac56ae3ee0pquerna#endif
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb
9cfc48b742c224c1fbc2c26a4119a3266192c7d2wrowe/* cache info information */
9cfc48b742c224c1fbc2c26a4119a3266192c7d2wrowetypedef struct cache_info cache_info;
ef5650b61a8e35f3cc93ec07e73efc17ea329894jortonstruct cache_info {
7c7372abe2484e7fcf81937b93496d1246e5b816gstein /**
a261b81a1044c0e2ea3f21cf9b7019297bad16aajorton * the original time corresponding to the 'Date:' header of the request
a261b81a1044c0e2ea3f21cf9b7019297bad16aajorton * served
a261b81a1044c0e2ea3f21cf9b7019297bad16aajorton */
a261b81a1044c0e2ea3f21cf9b7019297bad16aajorton apr_time_t date;
d71fd7cd9c4815d0647425f21ba3a803919a9148jorton /** a time when the cached entity is due to expire */
7c7372abe2484e7fcf81937b93496d1246e5b816gstein apr_time_t expire;
7c7372abe2484e7fcf81937b93496d1246e5b816gstein /** r->request_time from the same request */
7c7372abe2484e7fcf81937b93496d1246e5b816gstein apr_time_t request_time;
7c7372abe2484e7fcf81937b93496d1246e5b816gstein /** apr_time_now() at the time the entity was actually cached */
7c7372abe2484e7fcf81937b93496d1246e5b816gstein apr_time_t response_time;
2d2eda71267231c2526be701fe655db125852c1ffielding /**
2d2eda71267231c2526be701fe655db125852c1ffielding * HTTP status code of the cached entity. Though not necessarily the
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh * status code finally issued to the request.
2d2eda71267231c2526be701fe655db125852c1ffielding */
2d2eda71267231c2526be701fe655db125852c1ffielding int status;
2d2eda71267231c2526be701fe655db125852c1ffielding /* cached cache-control */
2d2eda71267231c2526be701fe655db125852c1ffielding cache_control_t control;
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh};
2d2eda71267231c2526be701fe655db125852c1ffielding
2d2eda71267231c2526be701fe655db125852c1ffielding/* cache handle information */
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianhtypedef struct cache_object cache_object_t;
2d2eda71267231c2526be701fe655db125852c1ffieldingstruct cache_object {
2e123e8beedc9f921448c113e2d6823a92fd5261fielding const char *key;
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh cache_object_t *next;
2d2eda71267231c2526be701fe655db125852c1ffielding cache_info info;
dd5cbadf2df719db2f3c769d03ec847da25854e6bnicholes /* Opaque portion (specific to the implementation) of the cache object */
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh void *vobj;
dd5cbadf2df719db2f3c769d03ec847da25854e6bnicholes};
2d2eda71267231c2526be701fe655db125852c1ffielding
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianhtypedef struct cache_handle cache_handle_t;
2d2eda71267231c2526be701fe655db125852c1ffieldingstruct cache_handle {
2d2eda71267231c2526be701fe655db125852c1ffielding cache_object_t *cache_obj;
2d2eda71267231c2526be701fe655db125852c1ffielding apr_table_t *req_hdrs; /* cached request headers */
2d2eda71267231c2526be701fe655db125852c1ffielding apr_table_t *resp_hdrs; /* cached response headers */
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb};
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb#define CACHE_PROVIDER_GROUP "cache"
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb
72a4ef8eac1adef882246c5bfb9b8bbd82d613c4coartypedef struct {
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb int (*remove_entity) (cache_handle_t *h);
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb apr_status_t (*store_headers)(cache_handle_t *h, request_rec *r, cache_info *i);
b0f20a4a26bcfa85724b1c2e5ec6a077f12ef44crbb apr_status_t (*store_body)(cache_handle_t *h, request_rec *r, apr_bucket_brigade *in,
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh apr_bucket_brigade *out);
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh apr_status_t (*recall_headers) (cache_handle_t *h, request_rec *r);
2d2eda71267231c2526be701fe655db125852c1ffielding apr_status_t (*recall_body) (cache_handle_t *h, apr_pool_t *p, apr_bucket_brigade *bb);
2d2eda71267231c2526be701fe655db125852c1ffielding int (*create_entity) (cache_handle_t *h, request_rec *r,
2d2eda71267231c2526be701fe655db125852c1ffielding const char *urlkey, apr_off_t len, apr_bucket_brigade *bb);
2d2eda71267231c2526be701fe655db125852c1ffielding int (*open_entity) (cache_handle_t *h, request_rec *r,
2d2eda71267231c2526be701fe655db125852c1ffielding const char *urlkey);
2d2eda71267231c2526be701fe655db125852c1ffielding int (*remove_url) (cache_handle_t *h, request_rec *r);
2d2eda71267231c2526be701fe655db125852c1ffielding apr_status_t (*commit_entity)(cache_handle_t *h, request_rec *r);
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh apr_status_t (*invalidate_entity)(cache_handle_t *h, request_rec *r);
2d2eda71267231c2526be701fe655db125852c1ffielding} cache_provider;
2d2eda71267231c2526be701fe655db125852c1ffielding
2d2eda71267231c2526be701fe655db125852c1ffieldingtypedef enum {
2d2eda71267231c2526be701fe655db125852c1ffielding AP_CACHE_HIT,
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh AP_CACHE_REVALIDATE,
2d2eda71267231c2526be701fe655db125852c1ffielding AP_CACHE_MISS,
a77c6787a1ea7dd88cb6cf8e4ad968b235af2a20jorton AP_CACHE_INVALIDATE
2d2eda71267231c2526be701fe655db125852c1ffielding} ap_cache_status_e;
2d2eda71267231c2526be701fe655db125852c1ffielding
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh#define AP_CACHE_HIT_ENV "cache-hit"
2d2eda71267231c2526be701fe655db125852c1ffielding#define AP_CACHE_REVALIDATE_ENV "cache-revalidate"
2d2eda71267231c2526be701fe655db125852c1ffielding#define AP_CACHE_MISS_ENV "cache-miss"
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh#define AP_CACHE_INVALIDATE_ENV "cache-invalidate"
2d2eda71267231c2526be701fe655db125852c1ffielding#define AP_CACHE_STATUS_ENV "cache-status"
2d2eda71267231c2526be701fe655db125852c1ffielding
2d2eda71267231c2526be701fe655db125852c1ffielding
2d2eda71267231c2526be701fe655db125852c1ffielding/* cache_util.c */
2d2eda71267231c2526be701fe655db125852c1ffielding/* do a HTTP/1.1 age calculation */
2d2eda71267231c2526be701fe655db125852c1ffieldingCACHE_DECLARE(apr_time_t) ap_cache_current_age(cache_info *info, const apr_time_t age_value,
2d2eda71267231c2526be701fe655db125852c1ffielding apr_time_t now);
2d2eda71267231c2526be701fe655db125852c1ffielding
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianhCACHE_DECLARE(apr_time_t) ap_cache_hex2usec(const char *x);
2d2eda71267231c2526be701fe655db125852c1ffieldingCACHE_DECLARE(void) ap_cache_usec2hex(apr_time_t j, char *y);
2d2eda71267231c2526be701fe655db125852c1ffieldingCACHE_DECLARE(char *) ap_cache_generate_name(apr_pool_t *p, int dirlevels,
2d2eda71267231c2526be701fe655db125852c1ffielding int dirlength,
2d2eda71267231c2526be701fe655db125852c1ffielding const char *name);
2d2eda71267231c2526be701fe655db125852c1ffieldingCACHE_DECLARE(int) ap_cache_liststr(apr_pool_t *p, const char *list,
2d2eda71267231c2526be701fe655db125852c1ffielding const char *key, char **val);
2d2eda71267231c2526be701fe655db125852c1ffieldingCACHE_DECLARE(const char *)ap_cache_tokstr(apr_pool_t *p, const char *list, const char **str);
2d2eda71267231c2526be701fe655db125852c1ffielding
2d2eda71267231c2526be701fe655db125852c1ffielding/* Create a new table consisting of those elements from an
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh * headers table that are allowed to be stored in a cache.
2d2eda71267231c2526be701fe655db125852c1ffielding */
2d2eda71267231c2526be701fe655db125852c1ffieldingCACHE_DECLARE(apr_table_t *)ap_cache_cacheable_headers(apr_pool_t *pool,
2d2eda71267231c2526be701fe655db125852c1ffielding apr_table_t *t,
2d2eda71267231c2526be701fe655db125852c1ffielding server_rec *s);
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh
2d2eda71267231c2526be701fe655db125852c1ffielding/* Create a new table consisting of those elements from an input
2d2eda71267231c2526be701fe655db125852c1ffielding * headers table that are allowed to be stored in a cache.
2d2eda71267231c2526be701fe655db125852c1ffielding */
2d2eda71267231c2526be701fe655db125852c1ffieldingCACHE_DECLARE(apr_table_t *)ap_cache_cacheable_headers_in(request_rec *r);
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh
2d2eda71267231c2526be701fe655db125852c1ffielding/* Create a new table consisting of those elements from an output
dbbf1b4183ae16353011a5269b37899f02b97d81gregames * headers table that are allowed to be stored in a cache;
2d2eda71267231c2526be701fe655db125852c1ffielding * ensure there is a content type and capture any errors.
2d2eda71267231c2526be701fe655db125852c1ffielding */
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianhCACHE_DECLARE(apr_table_t *)ap_cache_cacheable_headers_out(request_rec *r);
2d2eda71267231c2526be701fe655db125852c1ffielding
e44e11f9fece12c783f18d033923bfc0d6b4289aake/**
2d2eda71267231c2526be701fe655db125852c1ffielding * Parse the Cache-Control and Pragma headers in one go, marking
2d2eda71267231c2526be701fe655db125852c1ffielding * which tokens appear within the header. Populate the structure
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh * passed in.
2d2eda71267231c2526be701fe655db125852c1ffielding */
ee1af2aeb57527f33baa4737aa431e4aef997855rbowenint ap_cache_control(request_rec *r, cache_control_t *cc, const char *cc_header,
2d2eda71267231c2526be701fe655db125852c1ffielding const char *pragma_header, apr_table_t *headers);
2d2eda71267231c2526be701fe655db125852c1ffielding
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh
2d2eda71267231c2526be701fe655db125852c1ffielding/* hooks */
2d2eda71267231c2526be701fe655db125852c1ffielding
2d2eda71267231c2526be701fe655db125852c1ffielding/**
2d2eda71267231c2526be701fe655db125852c1ffielding * Cache status hook.
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh * This hook is called as soon as the cache has made a decision as to whether
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh * an entity should be served from cache (hit), should be served from cache
2d2eda71267231c2526be701fe655db125852c1ffielding * after a successful validation (revalidate), or served from the backend
2d2eda71267231c2526be701fe655db125852c1ffielding * and potentially cached (miss).
2d2eda71267231c2526be701fe655db125852c1ffielding *
2d2eda71267231c2526be701fe655db125852c1ffielding * A basic implementation of this hook exists in mod_cache which writes this
2d2eda71267231c2526be701fe655db125852c1ffielding * information to the subprocess environment, and optionally to request
2d2eda71267231c2526be701fe655db125852c1ffielding * headers. Further implementations may add hooks as appropriate to perform
2d2eda71267231c2526be701fe655db125852c1ffielding * more advanced processing, or to store statistics about the cache behaviour.
2d2eda71267231c2526be701fe655db125852c1ffielding */
2d2eda71267231c2526be701fe655db125852c1ffieldingAPR_DECLARE_EXTERNAL_HOOK(cache, CACHE, int, cache_status, (cache_handle_t *h,
2d2eda71267231c2526be701fe655db125852c1ffielding request_rec *r, apr_table_t *headers, ap_cache_status_e status,
2d2eda71267231c2526be701fe655db125852c1ffielding const char *reason))
2d2eda71267231c2526be701fe655db125852c1ffielding
2d2eda71267231c2526be701fe655db125852c1ffieldingAPR_DECLARE_OPTIONAL_FN(apr_status_t,
2d2eda71267231c2526be701fe655db125852c1ffielding ap_cache_generate_key,
2d2eda71267231c2526be701fe655db125852c1ffielding (request_rec *r, apr_pool_t*p, const char **key));
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh
2d2eda71267231c2526be701fe655db125852c1ffielding#endif /*MOD_CACHE_H*/
2d2eda71267231c2526be701fe655db125852c1ffielding/** @} */
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh