#!/usr/bin/env python # # Copyright 2007 Google Inc. # # 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. # """A memcache viewer and editor UI. Memcache associates a key with a value and an integer flag. The Go API maps keys to strings and lets the user control the flag. Java, PHP and Python map keys to an arbitrary type and uses the flag to indicate the type information. Java, PHP and Python map types in inconsistent ways, see: - google/appengine/api/memcache/__init__.py - google/appengine/api/memcache/MemcacheSerialization.java - google/appengine/runtime/MemcacheUtils.php """ import datetime import logging import urllib from google.appengine.api import apiproxy_stub_map from google.appengine.api import memcache from google.appengine.api.memcache import memcache_service_pb from google.appengine.tools.devappserver2.admin import admin_request_handler class StringValueConverter(object): memcache_type = memcache.TYPE_STR placeholder = 'hello world!' can_edit = True friendly_type_name = 'String' @staticmethod def to_display(cache_value): """Convert a memcache string into a displayable representation. Make a memcache string into a text string that can be displayed or edited. While called a string, it is technically just an array of bytes. Because we do not know what encoding the bytes are (and possibly they are not an encoded text string - for example they could be an MD5 hash) we display in string-escaped form. Args: cache_value: an array of bytes Returns: A unicode string that represents the sequence of bytes and can be roundtripped back to the sequence of bytes. """ # As we don't know what encoding the bytes are, we string escape so any # byte sequence is legal ASCII. Once we have a legal ASCII byte sequence # we can safely convert to a unicode/text string. return cache_value.encode('string-escape').decode('ascii') @staticmethod def to_cache(display_value): """Convert a displayable representation to a memcache string. Take a displayable/editable text string and convert into a memcache string. As a memcache string is technically an array of bytes, we only allow characters from the ASCII range and require all other bytes to be indicated via string escape. (because if we see the Unicode character Yen sign (U+00A5) we don't know if they want the byte 0xA5 or the UTF-8 two byte sequence 0xC2 0xA5). Args: display_value: a text (i.e. unicode string) using only ASCII characters; non-ASCII characters must be represented string escapes. Returns: An array of bytes. Raises: UnicodeEncodeError: a non-ASCII character is part of the input. """ # Since we don't know how they want their Unicode encoded, this will raise # an exception (which will be displayed nicely) if they include non-ASCII. return display_value.encode('ascii').decode('string-escape') class UnicodeValueConverter(object): memcache_type = memcache.TYPE_UNICODE # Hello world in Japanese. placeholder = u'\u3053\u3093\u306b\u3061\u306f\u4e16\u754c' can_edit = True friendly_type_name = 'Unicode String' @staticmethod def to_display(cache_value): return cache_value.decode('utf-8') @staticmethod def to_cache(display_value): return display_value.encode('utf-8') class BooleanValueConverter(object): memcache_type = memcache.TYPE_BOOL placeholder = 'true' can_edit = True friendly_type_name = 'Boolean' @staticmethod def to_display(cache_value): if cache_value == '0': return 'false' elif cache_value == '1': return 'true' else: raise ValueError('unexpected boolean %r' % cache_value) @staticmethod def to_cache(display_value): if display_value.lower() in ('false', 'no', 'off', '0'): return '0' elif display_value.lower() in ('true', 'yes', 'on', '1'): return '1' raise ValueError( 'invalid literal for boolean: %s (must be "true" or "false")' % display_value) class IntValueConverter(object): memcache_type = memcache.TYPE_INT placeholder = '42' can_edit = True friendly_type_name = 'Integer' @staticmethod def to_display(cache_value): return str(cache_value) @staticmethod def to_cache(display_value): return str(int(display_value)) class OtherValueConverter(object): memcache_type = None placeholder = None can_edit = False friendly_type_name = 'Unknown Type' @staticmethod def to_display(cache_value): return repr(cache_value)[1:-1] @staticmethod def to_cache(display_value): raise NotImplementedError('cannot to a memcache value of unknown type') class MemcacheViewerRequestHandler(admin_request_handler.AdminRequestHandler): CONVERTERS = [StringValueConverter, UnicodeValueConverter, BooleanValueConverter, IntValueConverter, OtherValueConverter] MEMCACHE_TYPE_TO_CONVERTER = {c.memcache_type: c for c in CONVERTERS if c.memcache_type is not None} FRIENDLY_TYPE_NAME_TO_CONVERTER = {c.friendly_type_name: c for c in CONVERTERS} def _get_memcache_value_and_flags(self, key): """Return a 2-tuple containing a memcache value and its flags.""" request = memcache_service_pb.MemcacheGetRequest() response = memcache_service_pb.MemcacheGetResponse() request.add_key(key) apiproxy_stub_map.MakeSyncCall('memcache', 'Get', request, response) assert response.item_size() < 2 if response.item_size() == 0: return None, None else: return response.item(0).value(), response.item(0).flags() def _set_memcache_value(self, key, value, flags): """Store a value in memcache.""" request = memcache_service_pb.MemcacheSetRequest() response = memcache_service_pb.MemcacheSetResponse() item = request.add_item() item.set_key(key) item.set_value(value) item.set_flags(flags) apiproxy_stub_map.MakeSyncCall('memcache', 'Set', request, response) return (response.set_status(0) == memcache_service_pb.MemcacheSetResponse.STORED) def get(self): """Show template and prepare stats and/or key+value to display/edit.""" values = {'request': self.request, 'message': self.request.get('message')} edit = self.request.get('edit') key = self.request.get('key') if edit: # Show the form to edit/create the value. key = edit values['show_stats'] = False values['show_value'] = False values['show_valueform'] = True values['types'] = [type_value.friendly_type_name for type_value in self.CONVERTERS if type_value.can_edit] elif key: # A key was given, show it's value on the stats page. values['show_stats'] = True values['show_value'] = True values['show_valueform'] = False else: # Plain stats display + key lookup form. values['show_stats'] = True values['show_valueform'] = False values['show_value'] = False if key: values['key'] = key memcache_value, memcache_flags = self._get_memcache_value_and_flags(key) if memcache_value is not None: converter = self.MEMCACHE_TYPE_TO_CONVERTER.get(memcache_flags, OtherValueConverter) try: values['value'] = converter.to_display(memcache_value) except ValueError: # This exception is possible in the case where the value was set by # Go, which allows for arbitrary user-assigned flag values. logging.exception('Could not convert %s value %s', converter.friendly_type_name, memcache_value) converter = OtherValueConverter values['value'] = converter.to_display(memcache_value) values['type'] = converter.friendly_type_name values['writable'] = converter.can_edit values['key_exists'] = True values['value_placeholder'] = converter.placeholder else: values['writable'] = True values['key_exists'] = False if values['show_stats']: memcache_stats = memcache.get_stats() if not memcache_stats: # No stats means no memcache usage. memcache_stats = {'hits': 0, 'misses': 0, 'byte_hits': 0, 'items': 0, 'bytes': 0, 'oldest_item_age': 0} values['stats'] = memcache_stats try: hitratio = memcache_stats['hits'] * 100 / (memcache_stats['hits'] + memcache_stats['misses']) except ZeroDivisionError: hitratio = 0 values['hitratio'] = hitratio # TODO: oldest_item_age should be formatted in a more useful # way. delta_t = datetime.timedelta(seconds=memcache_stats['oldest_item_age']) values['oldest_item_age'] = datetime.datetime.now() - delta_t self.response.write(self.render('memcache_viewer.html', values)) def _urlencode(self, query): """Encode a dictionary into a URL query string. In contrast to urllib this encodes unicode characters as UTF8. Args: query: Dictionary of key/value pairs. Returns: String. """ return '&'.join('%s=%s' % (urllib.quote_plus(k.encode('utf8')), urllib.quote_plus(v.encode('utf8'))) for k, v in query.iteritems()) def post(self): """Handle modifying actions and/or redirect to GET page.""" next_param = {} if self.request.get('action:flush'): if memcache.flush_all(): next_param['message'] = 'Cache flushed, all keys dropped.' else: next_param['message'] = 'Flushing the cache failed. Please try again.' elif self.request.get('action:display'): next_param['key'] = self.request.get('key') elif self.request.get('action:edit'): next_param['edit'] = self.request.get('key') elif self.request.get('action:delete'): key = self.request.get('key') result = memcache.delete(key) if result == memcache.DELETE_NETWORK_FAILURE: next_param['message'] = ('ERROR: Network failure, key "%s" not deleted.' % key) elif result == memcache.DELETE_ITEM_MISSING: next_param['message'] = 'Key "%s" not in cache.' % key elif result == memcache.DELETE_SUCCESSFUL: next_param['message'] = 'Key "%s" deleted.' % key else: next_param['message'] = ('Unknown return value. Key "%s" might still ' 'exist.' % key) elif self.request.get('action:save'): key = self.request.get('key') value = self.request.get('value') type_ = self.request.get('type') next_param['key'] = key converter = self.FRIENDLY_TYPE_NAME_TO_CONVERTER[type_] try: memcache_value = converter.to_cache(value) except ValueError as e: next_param['message'] = 'ERROR: Failed to save key "%s": %s.' % (key, e) else: if self._set_memcache_value(key, memcache_value, converter.memcache_type): next_param['message'] = 'Key "%s" saved.' % key else: next_param['message'] = 'ERROR: Failed to save key "%s".' % key elif self.request.get('action:cancel'): next_param['key'] = self.request.get('key') else: next_param['message'] = 'Unknown action.' next = self.request.path_url if next_param: next = '%s?%s' % (next, self._urlencode(next_param)) self.redirect(next)