summaryrefslogtreecommitdiffstats
path: root/keystone-moon/keystone/common/cache/core.py
blob: 306587b317b72585adf476348c7914780368c173 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
# Copyright 2013 Metacloud
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.

"""Keystone Caching Layer Implementation."""

import dogpile.cache
from dogpile.cache import proxy
from dogpile.cache import util
from oslo_config import cfg
from oslo_log import log
from oslo_utils import importutils

from keystone import exception
from keystone.i18n import _, _LE


CONF = cfg.CONF
LOG = log.getLogger(__name__)

make_region = dogpile.cache.make_region

dogpile.cache.register_backend(
    'keystone.common.cache.noop',
    'keystone.common.cache.backends.noop',
    'NoopCacheBackend')

dogpile.cache.register_backend(
    'keystone.cache.mongo',
    'keystone.common.cache.backends.mongo',
    'MongoCacheBackend')

dogpile.cache.register_backend(
    'keystone.cache.memcache_pool',
    'keystone.common.cache.backends.memcache_pool',
    'PooledMemcachedBackend')


class DebugProxy(proxy.ProxyBackend):
    """Extra Logging ProxyBackend."""
    # NOTE(morganfainberg): Pass all key/values through repr to ensure we have
    # a clean description of the information.  Without use of repr, it might
    # be possible to run into encode/decode error(s). For logging/debugging
    # purposes encode/decode is irrelevant and we should be looking at the
    # data exactly as it stands.

    def get(self, key):
        value = self.proxied.get(key)
        LOG.debug('CACHE_GET: Key: "%(key)r" Value: "%(value)r"',
                  {'key': key, 'value': value})
        return value

    def get_multi(self, keys):
        values = self.proxied.get_multi(keys)
        LOG.debug('CACHE_GET_MULTI: "%(keys)r" Values: "%(values)r"',
                  {'keys': keys, 'values': values})
        return values

    def set(self, key, value):
        LOG.debug('CACHE_SET: Key: "%(key)r" Value: "%(value)r"',
                  {'key': key, 'value': value})
        return self.proxied.set(key, value)

    def set_multi(self, keys):
        LOG.debug('CACHE_SET_MULTI: "%r"', keys)
        self.proxied.set_multi(keys)

    def delete(self, key):
        self.proxied.delete(key)
        LOG.debug('CACHE_DELETE: "%r"', key)

    def delete_multi(self, keys):
        LOG.debug('CACHE_DELETE_MULTI: "%r"', keys)
        self.proxied.delete_multi(keys)


def build_cache_config():
    """Build the cache region dictionary configuration.

    :returns: dict
    """
    prefix = CONF.cache.config_prefix
    conf_dict = {}
    conf_dict['%s.backend' % prefix] = CONF.cache.backend
    conf_dict['%s.expiration_time' % prefix] = CONF.cache.expiration_time
    for argument in CONF.cache.backend_argument:
        try:
            (argname, argvalue) = argument.split(':', 1)
        except ValueError:
            msg = _LE('Unable to build cache config-key. Expected format '
                      '"<argname>:<value>". Skipping unknown format: %s')
            LOG.error(msg, argument)
            continue

        arg_key = '.'.join([prefix, 'arguments', argname])
        conf_dict[arg_key] = argvalue

        LOG.debug('Keystone Cache Config: %s', conf_dict)
    # NOTE(yorik-sar): these arguments will be used for memcache-related
    # backends. Use setdefault for url to support old-style setting through
    # backend_argument=url:127.0.0.1:11211
    conf_dict.setdefault('%s.arguments.url' % prefix,
                         CONF.cache.memcache_servers)
    for arg in ('dead_retry', 'socket_timeout', 'pool_maxsize',
                'pool_unused_timeout', 'pool_connection_get_timeout'):
        value = getattr(CONF.cache, 'memcache_' + arg)
        conf_dict['%s.arguments.%s' % (prefix, arg)] = value

    return conf_dict


def configure_cache_region(region):
    """Configure a cache region.

    :param region: optional CacheRegion object, if not provided a new region
                   will be instantiated
    :raises: exception.ValidationError
    :returns: dogpile.cache.CacheRegion
    """
    if not isinstance(region, dogpile.cache.CacheRegion):
        raise exception.ValidationError(
            _('region not type dogpile.cache.CacheRegion'))

    if not region.is_configured:
        # NOTE(morganfainberg): this is how you tell if a region is configured.
        # There is a request logged with dogpile.cache upstream to make this
        # easier / less ugly.

        config_dict = build_cache_config()
        region.configure_from_config(config_dict,
                                     '%s.' % CONF.cache.config_prefix)

        if CONF.cache.debug_cache_backend:
            region.wrap(DebugProxy)

        # NOTE(morganfainberg): if the backend requests the use of a
        # key_mangler, we should respect that key_mangler function.  If a
        # key_mangler is not defined by the backend, use the sha1_mangle_key
        # mangler provided by dogpile.cache. This ensures we always use a fixed
        # size cache-key.
        if region.key_mangler is None:
            region.key_mangler = util.sha1_mangle_key

        for class_path in CONF.cache.proxies:
            # NOTE(morganfainberg): if we have any proxy wrappers, we should
            # ensure they are added to the cache region's backend.  Since
            # configure_from_config doesn't handle the wrap argument, we need
            # to manually add the Proxies. For information on how the
            # ProxyBackends work, see the dogpile.cache documents on
            # "changing-backend-behavior"
            cls = importutils.import_class(class_path)
            LOG.debug("Adding cache-proxy '%s' to backend.", class_path)
            region.wrap(cls)

    return region


def get_should_cache_fn(section):
    """Build a function that returns a config section's caching status.

    For any given driver in keystone that has caching capabilities, a boolean
    config option for that driver's section (e.g. ``token``) should exist and
    default to ``True``.  This function will use that value to tell the caching
    decorator if caching for that driver is enabled.  To properly use this
    with the decorator, pass this function the configuration section and assign
    the result to a variable.  Pass the new variable to the caching decorator
    as the named argument ``should_cache_fn``.  e.g.::

        from keystone.common import cache

        SHOULD_CACHE = cache.get_should_cache_fn('token')

        @cache.on_arguments(should_cache_fn=SHOULD_CACHE)
        def function(arg1, arg2):
            ...

    :param section: name of the configuration section to examine
    :type section: string
    :returns: function reference
    """
    def should_cache(value):
        if not CONF.cache.enabled:
            return False
        conf_group = getattr(CONF, section)
        return getattr(conf_group, 'caching', True)
    return should_cache


def get_expiration_time_fn(section):
    """Build a function that returns a config section's expiration time status.

    For any given driver in keystone that has caching capabilities, an int
    config option called ``cache_time`` for that driver's section
    (e.g. ``token``) should exist and typically default to ``None``. This
    function will use that value to tell the caching decorator of the TTL
    override for caching the resulting objects. If the value of the config
    option is ``None`` the default value provided in the
    ``[cache] expiration_time`` option will be used by the decorator. The
    default may be set to something other than ``None`` in cases where the
    caching TTL should not be tied to the global default(s) (e.g.
    revocation_list changes very infrequently and can be cached for >1h by
    default).

    To properly use this with the decorator, pass this function the
    configuration section and assign the result to a variable. Pass the new
    variable to the caching decorator as the named argument
    ``expiration_time``.  e.g.::

        from keystone.common import cache

        EXPIRATION_TIME = cache.get_expiration_time_fn('token')

        @cache.on_arguments(expiration_time=EXPIRATION_TIME)
        def function(arg1, arg2):
            ...

    :param section: name of the configuration section to examine
    :type section: string
    :rtype: function reference
    """
    def get_expiration_time():
        conf_group = getattr(CONF, section)
        return getattr(conf_group, 'cache_time', None)
    return get_expiration_time


def key_generate_to_str(s):
    # NOTE(morganfainberg): Since we need to stringify all arguments, attempt
    # to stringify and handle the Unicode error explicitly as needed.
    try:
        return str(s)
    except UnicodeEncodeError:
        return s.encode('utf-8')


def function_key_generator(namespace, fn, to_str=key_generate_to_str):
    # NOTE(morganfainberg): This wraps dogpile.cache's default
    # function_key_generator to change the default to_str mechanism.
    return util.function_key_generator(namespace, fn, to_str=to_str)


REGION = dogpile.cache.make_region(
    function_key_generator=function_key_generator)
on_arguments = REGION.cache_on_arguments


def get_memoization_decorator(section, expiration_section=None):
    """Build a function based on the `on_arguments` decorator for the section.

    For any given driver in Keystone that has caching capabilities, a
    pair of functions is required to properly determine the status of the
    caching capabilities (a toggle to indicate caching is enabled and any
    override of the default TTL for cached data). This function will return
    an object that has the memoization decorator ``on_arguments``
    pre-configured for the driver.

    Example usage::

        from keystone.common import cache

        MEMOIZE = cache.get_memoization_decorator(section='token')

        @MEMOIZE
        def function(arg1, arg2):
            ...


        ALTERNATE_MEMOIZE = cache.get_memoization_decorator(
            section='token', expiration_section='revoke')

        @ALTERNATE_MEMOIZE
        def function2(arg1, arg2):
            ...

    :param section: name of the configuration section to examine
    :type section: string
    :param expiration_section: name of the configuration section to examine
                               for the expiration option. This will fall back
                               to using ``section`` if the value is unspecified
                               or ``None``
    :type expiration_section: string
    :rtype: function reference
    """
    if expiration_section is None:
        expiration_section = section
    should_cache = get_should_cache_fn(section)
    expiration_time = get_expiration_time_fn(expiration_section)

    memoize = REGION.cache_on_arguments(should_cache_fn=should_cache,
                                        expiration_time=expiration_time)

    # Make sure the actual "should_cache" and "expiration_time" methods are
    # available. This is potentially interesting/useful to pre-seed cache
    # values.
    memoize.should_cache = should_cache
    memoize.get_expiration_time = expiration_time

    return memoize