Merge lp:~rconradharris/glance/cached-images-middleware into lp:~hudson-openstack/glance/trunk

[Jay Pipes]

New local filesystem image cache with REST managment API

Additional changes include:

    * Added glance-reaper binary
    * Moved invalid cache entry reaping from glance-pruner to glance-reaper
    * Added stalled image detection and reaping
    * Added incomplete image listing (shows which images are currently being fetched)
    * Added percent progress to incomplete image listing and invalid image listing (useful when looking for failure trends)
    * Added ability to reap-invalid and reap-stalled directly from glance command. Helpful for testing and recovering from failures immediately (w/o having to wait for cron to kick off glance-reaper)
    * Renamed glance cache management commands. Now all start with 'cache-' and they better mirror the naming of 'image' commands
    * Fixed bug where print_help didn't have access to parser to print usage

[Ed Leafe (ed-leafe)]

Haven't gone through all the code, but I noticed several places where str(e) is used. Since error strings can be localized, it is reasonable to expect non-ASCII characters to appear in them. Either unicode(e) or "%s" % e should be used instead.

[Ed Leafe (ed-leafe)]

Another observation:
In the open() method of the ImageCache class, you test for the presence of 'r' or 'w' in the mode param. This means that any mode that contains either of the two characters is valid, and if it contains both, then 'w' is assumed. Should this be more discriminating? e.g.:

mode = mode[0].lower()
if mode == 'w':
    ...
elif mode == 'r':
    ....
else:
    raise ...

[Rick Harris (rconradharris)]

Thanks for the comments, Ed.

> Haven't gone through all the code, but I noticed several places where str(e)
> is used. Since error strings can be localized, it is reasonable to expect
> non-ASCII characters to appear in them. Either unicode(e) or "%s" % e should
> be used instead.

Looking around, I see a few other places where we do `str(e)` as well. I'm
hesitant to fix those at the moment (perhaps those should be a cleanup patch?),
but in this case, I don't see anything wrong with using one of the forms
you've suggested.

Look for a fix shortly.

> In the open() method of the ImageCache class, you test for the presence of 'r' or 'w' in the mode param. This means that any mode that contains either of the two characters is valid, and if it contains both, then 'w' is assumed. Should this be more discriminating? e.g.:

Nice catch, if the file was opened for `rw`, it would correctly call the
`_open_write` handler, but it wouldn't bump the hit-count.

`rw` mode isn't really used (nor should it since image-data is immutable), so,
I think it's safe to "tighten" up the switch statement to be something like:

    if mode == 'r': do_read
    elif mode == 'w': do_write
    else: raise not supported

[Jay Pipes (jaypipes)]

Awesome work, Rick. Looking forward to getting this into trunk...

Tiny nits:

1161 + logger.debug("image cache HIT, retrieving image '%s'"
1162 + " from cache" % id)

There are a couple places where you're doing the above. Should really be:

logger.debug("image cache HIT, retrieving image '%s' from cache", id)

Note the use of args to debug() instead of % interpolation...

1569 + def _delete_file(path):
1570 + if os.path.exists(path):
1571 + logger.debug("deleting image cache file '%s'", path)
1572 + os.unlink(path)

Might want to add an else: block there and log the error if trying to delete a non-existing image. This might be useful for identifying if any race conditions are occurring...

Finally, it would be good to add some documentation for the cache and its management API. I'm OK with doing this documentation in a follow-up bug in D4.

-jay

review: Needs Fixing

[Ed Leafe (ed-leafe)]

> Looking around, I see a few other places where we do `str(e)` as well.

Heh, this isn't the first time I've made a comment like this about OS code. :)

[Jay Pipes (jaypipes)]

> > Looking around, I see a few other places where we do `str(e)` as well.
>
> Heh, this isn't the first time I've made a comment like this about OS code. :)

FYI, I told Rick we can do a separate refactoring patch around this. I've logged a bug about it for tracking purposes: https://bugs.launchpad.net/glance/+bug/816077

-jay

[Rick Harris (rconradharris)]

Ed:

Per Jay's comments, going to hold of on the `str(e)` issue.

Fixed the loose file mode handling.

Jay:

> Note the use of args to debug() instead of % interpolation...

Fixed.

> Might want to add an else: block there and log the error if trying to delete a non-existing image.
> This might be useful for identifying if any race conditions are occurring...

Good call, fixed.

> Finally, it would be good to add some documentation for the cache and its management API. I'm OK with doing this documentation in a follow-up bug in D4.

Agreed.

[Jay Pipes (jaypipes)]

Rock and roll.

review: Approve

[Ed Leafe (ed-leafe)]

Jay:
> FYI, I told Rick we can do a separate refactoring patch around this.
> I've logged a bug about it for tracking purposes:
> https://bugs.launchpad.net/glance/+bug/816077

Cool; probably a better way to handle this.

Rick:
> Fixed the loose file mode handling.

Looks good. Finally got a chance to look over the rest of the code, and it looks good, too.

review: Approve

[Brian Waldon (bcwaldon)]

1) The decision was made to implement the caching layer as an extension, so in the future it will be easy to replace it with an external service. An optional middleware is a good way to accomplish this without tarnishing the rest of our API code, but I'm curious why we didn't take a similar approach with the command-line utility? Wouldn't it make sense to separate that out (possibly into a separate binary) so it can be completely removed later on? I always thought the cli tool (bin/glance) was analogous to the user-facing API, and caching commands shouldn't live there.

2) The API looks much better, but I think reap_invalid and reap_stalled still need to be changed. Would DELETE with a status query param suffice?

DELETE /cached_images?status=invalid
DELETE /cached_images?status=incomplete

3) Can the responsibilities assumed by cache-reaper and cache-pruner be consolidated into a single file?

review: Needs Information

[Rick Harris (rconradharris)]

> 1) The decision was made to implement the caching layer as an extension, so in
> the future it will be easy to replace it with an external service. An optional
> middleware is a good way to accomplish this without tarnishing the rest of our
> API code, but I'm curious why we didn't take a similar approach with the
> command-line utility? Wouldn't it make sense to separate that out (possibly
> into a separate binary) so it can be completely removed later on? I always
> thought the cli tool (bin/glance) was analogous to the user-facing API, and
> caching commands shouldn't live there.

Interesting point. There is some precedent already in Nova to having the CLI
tool also handle admin-only functionality (in Nova, scheduled backups are
kicked off by the novaclient tool).

I followed the same model for glance-caching. As to whether this is the right
approach, I'm not sure. It's convenient to have a single binary for working
with glance, but I can see the benefit of having it split out, too.

Either way, I think we should probably get an ML discussion going where we can
discuss this not just for Glance, but also for Nova as well. Whatever we come
up with could be addressed in a follow-on patch.

> 2) The API looks much better, but I think reap_invalid and reap_stalled still
> need to be changed. Would DELETE with a status query param suffice?
>
> DELETE /cached_images?status=invalid DELETE /cached_images?status=incomplete

Fixed.

> 3) Can the responsibilities assumed by cache-reaper and cache-pruner be
> consolidated into a single file?

I see pruning (part of normal operation) and reaping (recovering from error
cases) as different functionality. I'd prefer to keep them as separate
binaries, with separate source files, and their own log files.

(Aside: we should expect lots of output in the pruning.log; however, if we're
seeing lots of output in reaping.log, we have some bugs we need to hammer
out).

[Brian Waldon (bcwaldon)]

> > 1) The decision was made to implement the caching layer as an extension, so
> in
> > the future it will be easy to replace it with an external service. An
> optional
> > middleware is a good way to accomplish this without tarnishing the rest of
> our
> > API code, but I'm curious why we didn't take a similar approach with the
> > command-line utility? Wouldn't it make sense to separate that out (possibly
> > into a separate binary) so it can be completely removed later on? I always
> > thought the cli tool (bin/glance) was analogous to the user-facing API, and
> > caching commands shouldn't live there.
>
> Interesting point. There is some precedent already in Nova to having the CLI
> tool also handle admin-only functionality (in Nova, scheduled backups are
> kicked off by the novaclient tool).

Well this isn't an admin-only feature, it is supposed to be an 'extension'. I still see those as different things. Keep in mind that novaclient is not being developed under the Nova project within OpenStack, either.

> I followed the same model for glance-caching. As to whether this is the right
> approach, I'm not sure. It's convenient to have a single binary for working
> with glance, but I can see the benefit of having it split out, too.
>
> Either way, I think we should probably get an ML discussion going where we can
> discuss this not just for Glance, but also for Nova as well. Whatever we come
> up with could be addressed in a follow-on patch.

I agree with a future decision here.

> > 3) Can the responsibilities assumed by cache-reaper and cache-pruner be
> > consolidated into a single file?
>
> I see pruning (part of normal operation) and reaping (recovering from error
> cases) as different functionality. I'd prefer to keep them as separate
> binaries, with separate source files, and their own log files.

I still see pruning/reaping as the same thing, just with two different names. They both remove images from the cache based on a set of criteria.

[Jay Pipes (jaypipes)]

Brian, I see both of your concerns as things that can possibly be addressed in future patches. Would you be OK with seeing this patch go through?

[Brian Waldon (bcwaldon)]

Certainly :)

review: Approve

=== modified file 'bin/glance'
--- bin/glance	2011-06-28 14:17:58 +0000
+++ bin/glance	2011-07-25 22:03:31 +0000
@@ -22,6 +22,7 @@
 stored in one or more Glance nodes.
 """
 
+import functools
 import optparse
 import os
 import re
@@ -36,15 +37,45 @@
 if os.path.exists(os.path.join(possible_topdir, 'glance', '__init__.py')):
     sys.path.insert(0, possible_topdir)
 
-from glance import client
+from glance import client as glance_client
 from glance import version
 from glance.common import exception
-from glance.common import utils
+from glance.common import utils as common_utils
+from glance import utils
 
 SUCCESS = 0
 FAILURE = 1
 
 
+#TODO(sirp): make more of the actions use this decorator
+def catch_error(action):
+    """Decorator to provide sensible default error handling for actions."""
+    def wrap(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                ret = func(*args, **kwargs)
+                return SUCCESS if ret is None else ret
+            except Exception, e:
+                print "Failed to %s. Got error:" % action
+                pieces = str(e).split('\n')
+                for piece in pieces:
+                    print piece
+                return FAILURE
+
+        return wrapper
+    return wrap
+
+
+def get_percent_done(image):
+    try:
+        pct_done = image['size'] * 100 / int(image['expected_size'])
+    except (ValueError, ZeroDivisionError):
+        # NOTE(sirp): Ignore if expected_size isn't a number, or if it's 0
+        pct_done = "UNKNOWN"
+    return pct_done
+
+
 def get_image_fields_from_args(args):
     """
     Validate the set of arguments passed as field name/value pairs
@@ -152,7 +183,7 @@
         return FAILURE
 
     image_meta = {'name': fields.pop('name'),
-                  'is_public': utils.bool_from_string(
+                  'is_public': common_utils.bool_from_string(
                       fields.pop('is_public', False)),
                   'disk_format': fields.pop('disk_format', 'raw'),
                   'container_format': fields.pop('container_format', 'ovf')}
@@ -276,7 +307,7 @@
 
     # Have to handle "boolean" values specially...
     if 'is_public' in fields:
-        image_meta['is_public'] = utils.bool_from_string(
+        image_meta['is_public'] = common_utils.bool_from_string(
             fields.pop('is_public'))
 
     # Add custom attributes, which are all the arguments remaining
@@ -364,40 +395,37 @@
         return FAILURE
 
 
+@catch_error('show index')
 def images_index(options, args):
     """
 %(prog)s index [options]
 
 Returns basic information for all public images
 a Glance server knows about"""
-    c = get_client(options)
-    try:
-        images = c.get_images()
-        if len(images) == 0:
-            print "No public images found."
-            return SUCCESS
-
-        print "Found %d public images..." % len(images)
-        print "%-16s %-30s %-20s %-20s %-14s" % (("ID"),
-                                           ("Name"),
-                                           ("Disk Format"),
-                                           ("Container Format"),
-                                           ("Size"))
-        print ('-' * 16) + " " + ('-' * 30) + " "\
-              + ('-' * 20) + " " + ('-' * 20) + " " + ('-' * 14)
-        for image in images:
-            print "%-16s %-30s %-20s %-20s %14d" % (image['id'],
-                                              image['name'],
-                                              image['disk_format'],
-                                              image['container_format'],
-                                              int(image['size']))
+    client = get_client(options)
+    images = client.get_images()
+    if not images:
+        print "No public images found."
         return SUCCESS
-    except Exception, e:
-        print "Failed to show index. Got error:"
-        pieces = str(e).split('\n')
-        for piece in pieces:
-            print piece
-        return FAILURE
+
+    print "Found %d public images..." % len(images)
+
+    pretty_table = utils.PrettyTable()
+    pretty_table.add_column(16, label="ID")
+    pretty_table.add_column(30, label="Name")
+    pretty_table.add_column(20, label="Disk Format")
+    pretty_table.add_column(20, label="Container Format")
+    pretty_table.add_column(14, label="Size", just="r")
+
+    print pretty_table.make_header()
+
+    for image in images:
+        print pretty_table.make_row(
+            image['id'],
+            image['name'],
+            image['disk_format'],
+            image['container_format'],
+            image['size'])
 
 
 def images_detailed(options, args):
@@ -458,13 +486,256 @@
     return SUCCESS
 
 
+@catch_error('show cached images')
+def cache_index(options, args):
+    """
+%(prog)s cache-index [options]
+
+List all images currently cached"""
+    client = get_client(options)
+    images = client.get_cached_images()
+    if not images:
+        print "No cached images."
+        return SUCCESS
+
+    print "Found %d cached images..." % len(images)
+
+    pretty_table = utils.PrettyTable()
+    pretty_table.add_column(16, label="ID")
+    pretty_table.add_column(30, label="Name")
+    pretty_table.add_column(19, label="Last Accessed (UTC)")
+    # 1 TB takes 13 characters to display: len(str(2**40)) == 13
+    pretty_table.add_column(14, label="Size", just="r")
+    pretty_table.add_column(10, label="Hits", just="r")
+
+    print pretty_table.make_header()
+
+    for image in images:
+        print pretty_table.make_row(
+            image['id'],
+            image['name'],
+            image['last_accessed'],
+            image['size'],
+            image['hits'])
+
+
+@catch_error('show invalid cache images')
+def cache_invalid(options, args):
+    """
+%(prog)s cache-invalid [options]
+
+List current invalid cache images"""
+    client = get_client(options)
+    images = client.get_invalid_cached_images()
+    if not images:
+        print "No invalid cached images."
+        return SUCCESS
+
+    print "Found %d invalid cached images..." % len(images)
+
+    pretty_table = utils.PrettyTable()
+    pretty_table.add_column(16, label="ID")
+    pretty_table.add_column(30, label="Name")
+    pretty_table.add_column(30, label="Error")
+    pretty_table.add_column(19, label="Last Modified (UTC)")
+    # 1 TB takes 13 characters to display: len(str(2**40)) == 13
+    pretty_table.add_column(14, label="Size", just="r")
+    pretty_table.add_column(14, label="Expected Size", just="r")
+    pretty_table.add_column(7, label="% Done", just="r")
+
+    print pretty_table.make_header()
+
+    for image in images:
+        print pretty_table.make_row(
+            image['id'],
+            image['name'],
+            image['error'],
+            image['last_accessed'],
+            image['size'],
+            image['expected_size'],
+            get_percent_done(image))
+
+
+@catch_error('show incomplete cache images')
+def cache_incomplete(options, args):
+    """
+%(prog)s cache-incomplete [options]
+
+List images currently being fetched"""
+    client = get_client(options)
+    images = client.get_incomplete_cached_images()
+    if not images:
+        print "No incomplete cached images."
+        return SUCCESS
+
+    print "Found %d incomplete cached images..." % len(images)
+
+    pretty_table = utils.PrettyTable()
+    pretty_table.add_column(16, label="ID")
+    pretty_table.add_column(30, label="Name")
+    pretty_table.add_column(19, label="Last Modified (UTC)")
+    # 1 TB takes 13 characters to display: len(str(2**40)) == 13
+    pretty_table.add_column(14, label="Size", just="r")
+    pretty_table.add_column(14, label="Expected Size", just="r")
+    pretty_table.add_column(7, label="% Done", just="r")
+
+    print pretty_table.make_header()
+
+    for image in images:
+        print pretty_table.make_row(
+            image['id'],
+            image['name'],
+            image['last_modified'],
+            image['size'],
+            image['expected_size'],
+            get_percent_done(image))
+
+
+@catch_error('purge the specified cached image')
+def cache_purge(options, args):
+    """
+%(prog)s cache-purge [options]
+
+Purges an image from the cache"""
+    try:
+        image_id = args.pop()
+    except IndexError:
+        print "Please specify the ID of the image you wish to purge "
+        print "from the cache as the first argument"
+        return FAILURE
+
+    if not options.force and \
+       not user_confirm("Purge cached image %s?" % (image_id,), default=False):
+        print 'Not purging cached image %s' % (image_id,)
+        return FAILURE
+
+    client = get_client(options)
+    client.purge_cached_image(image_id)
+
+    if options.verbose:
+        print "done"
+
+
+@catch_error('clear all cached images')
+def cache_clear(options, args):
+    """
+%(prog)s cache-clear [options]
+
+Removes all images from the cache"""
+    if not options.force and \
+       not user_confirm("Clear all cached images?", default=False):
+        print 'Not purging any cached images.'
+        return FAILURE
+
+    client = get_client(options)
+    num_purged = client.clear_cached_images()
+
+    if options.verbose:
+        print "Purged %(num_purged)s cached images" % locals()
+
+
+@catch_error('reap invalid images')
+def cache_reap_invalid(options, args):
+    """
+%(prog)s cache-reap-invalid [options]
+
+Reaps any invalid images that were left for
+debugging purposes"""
+    if not options.force and \
+       not user_confirm("Reap all invalid cached images?", default=False):
+        print 'Not reaping any invalid cached images.'
+        return FAILURE
+
+    client = get_client(options)
+    num_reaped = client.reap_invalid_cached_images()
+
+    if options.verbose:
+        print "Reaped %(num_reaped)s invalid cached images" % locals()
+
+
+@catch_error('reap stalled images')
+def cache_reap_stalled(options, args):
+    """
+%(prog)s cache-reap-stalled [options]
+
+Reaps any stalled incomplete images"""
+    if not options.force and \
+       not user_confirm("Reap all stalled cached images?", default=False):
+        print 'Not reaping any stalled cached images.'
+        return FAILURE
+
+    client = get_client(options)
+    num_reaped = client.reap_stalled_cached_images()
+
+    if options.verbose:
+        print "Reaped %(num_reaped)s stalled cached images" % locals()
+
+
+@catch_error('prefetch the specified cached image')
+def cache_prefetch(options, args):
+    """
+%(prog)s cache-prefetch [options]
+
+Pre-fetch an image or list of images into the cache"""
+    image_ids = args
+    if not image_ids:
+        print "Please specify the ID or a list of image IDs of the images "\
+              "you wish to "
+        print "prefetch from the cache as the first argument"
+        return FAILURE
+
+    client = get_client(options)
+    for image_id in image_ids:
+        if options.verbose:
+            print "Prefetching image '%s'" % image_id
+
+        try:
+            client.prefetch_cache_image(image_id)
+        except exception.NotFound:
+            print "No image with ID %s was found" % image_id
+            continue
+
+    if options.verbose:
+        print "done"
+
+
+@catch_error('show prefetching images')
+def cache_prefetching(options, args):
+    """
+%(prog)s cache-prefetching [options]
+
+List images that are being prefetched"""
+    client = get_client(options)
+    images = client.get_prefetching_cache_images()
+    if not images:
+        print "No images being prefetched."
+        return SUCCESS
+
+    print "Found %d images being prefetched..." % len(images)
+
+    pretty_table = utils.PrettyTable()
+    pretty_table.add_column(16, label="ID")
+    pretty_table.add_column(30, label="Name")
+    pretty_table.add_column(19, label="Last Accessed (UTC)")
+    pretty_table.add_column(10, label="Status", just="r")
+
+    print pretty_table.make_header()
+
+    for image in images:
+        print pretty_table.make_row(
+            image['id'],
+            image['name'],
+            image['last_accessed'],
+            image['status'])
+
+
 def get_client(options):
     """
     Returns a new client object to a Glance server
     specified by the --host and --port options
     supplied to the CLI
     """
-    return client.Client(host=options.host,
+    return glance_client.Client(host=options.host,
                          port=options.port)
 
 
@@ -500,28 +771,23 @@
 
     :param parser: The option parser
     """
-    COMMANDS = {'help': print_help,
-                'add': image_add,
-                'update': image_update,
-                'delete': image_delete,
-                'index': images_index,
-                'details': images_detailed,
-                'show': image_show,
-                'clear': images_clear}
-
     if not cli_args:
         cli_args.append('-h')  # Show options in usage output...
 
     (options, args) = parser.parse_args(cli_args)
 
+    # HACK(sirp): Make the parser available to the print_help method
+    # print_help is a command, so it only accepts (options, args); we could
+    # one-off have it take (parser, options, args), however, for now, I think
+    # this little hack will suffice
+    options.__parser = parser
+
     if not args:
         parser.print_usage()
         sys.exit(0)
-    else:
-        command_name = args.pop(0)
-        if command_name not in COMMANDS.keys():
-            sys.exit("Unknown command: %s" % command_name)
-    command = COMMANDS[command_name]
+
+    command_name = args.pop(0)
+    command = lookup_command(parser, command_name)
 
     return (options, command, args)
 
@@ -530,24 +796,50 @@
     """
     Print help specific to a command
     """
-    COMMANDS = {'add': image_add,
-                'update': image_update,
-                'delete': image_delete,
-                'index': images_index,
-                'details': images_detailed,
-                'show': image_show,
-                'clear': images_clear}
-
     if len(args) != 1:
         sys.exit("Please specify a command")
 
-    command = args.pop()
-    if command not in COMMANDS.keys():
+    parser = options.__parser
+    command_name = args.pop()
+    command = lookup_command(parser, command_name)
+
+    print command.__doc__ % {'prog': os.path.basename(sys.argv[0])}
+
+
+def lookup_command(parser, command_name):
+    BASE_COMMANDS = {'help': print_help}
+
+    IMAGE_COMMANDS = {
+                'add': image_add,
+                'update': image_update,
+                'delete': image_delete,
+                'index': images_index,
+                'details': images_detailed,
+                'show': image_show,
+                'clear': images_clear}
+
+    CACHE_COMMANDS = {
+                'cache-index': cache_index,
+                'cache-invalid': cache_invalid,
+                'cache-incomplete': cache_incomplete,
+                'cache-prefetching': cache_prefetching,
+                'cache-prefetch': cache_prefetch,
+                'cache-purge': cache_purge,
+                'cache-clear': cache_clear,
+                'cache-reap-invalid': cache_reap_invalid,
+                'cache-reap-stalled': cache_reap_stalled}
+
+    commands = {}
+    for command_set in (BASE_COMMANDS, IMAGE_COMMANDS, CACHE_COMMANDS):
+        commands.update(command_set)
+
+    try:
+        command = commands[command_name]
+    except KeyError:
         parser.print_usage()
-        if args:
-            sys.exit("Unknown command: %s" % command)
+        sys.exit("Unknown command: %s" % command_name)
 
-    print COMMANDS[command].__doc__ % {'prog': os.path.basename(sys.argv[0])}
+    return command
 
 
 def user_confirm(prompt, default=False):
@@ -596,6 +888,27 @@
 
     clear           Removes all images and metadata from Glance
 
+
+Cache Commands:
+
+    cache-index          List all images currently cached
+
+    cache-invalid        List current invalid cache images
+
+    cache-incomplete     List images currently being fetched
+
+    cache-prefetching    List images that are being prefetched
+
+    cache-prefetch       Pre-fetch an image or list of images into the cache
+
+    cache-purge          Purges an image from the cache
+
+    cache-clear          Removes all images from the cache
+
+    cache-reap-invalid   Reaps any invalid images that were left for
+                         debugging purposes
+
+    cache-reap-stalled   Reaps any stalled incomplete images
 """
 
     oparser = optparse.OptionParser(version='%%prog %s'

=== added file 'bin/glance-cache-prefetcher'
--- bin/glance-cache-prefetcher	1970-01-01 00:00:00 +0000
+++ bin/glance-cache-prefetcher	2011-07-25 22:03:31 +0000
@@ -0,0 +1,65 @@
+#!/usr/bin/env python
+# vim: tabstop=4 shiftwidth=4 softtabstop=4
+
+# Copyright 2010 United States Government as represented by the
+# Administrator of the National Aeronautics and Space Administration.
+# Copyright 2011 OpenStack LLC.
+# All Rights Reserved.
+#
+#    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.
+
+"""
+Glance Image Cache Pre-fetcher
+
+This is meant to be run as a periodic task from cron.
+"""
+
+import optparse
+import os
+import sys
+
+# If ../glance/__init__.py exists, add ../ to Python search path, so that
+# it will override what happens to be installed in /usr/(local/)lib/python...
+possible_topdir = os.path.normpath(os.path.join(os.path.abspath(sys.argv[0]),
+                                   os.pardir,
+                                   os.pardir))
+if os.path.exists(os.path.join(possible_topdir, 'glance', '__init__.py')):
+    sys.path.insert(0, possible_topdir)
+
+from glance import version
+from glance.common import config
+from glance.common import wsgi
+
+
+def create_options(parser):
+    """
+    Sets up the CLI and config-file options that may be
+    parsed and program commands.
+
+    :param parser: The option parser
+    """
+    config.add_common_options(parser)
+    config.add_log_options(parser)
+
+
+if __name__ == '__main__':
+    oparser = optparse.OptionParser(version='%%prog %s'
+                                    % version.version_string())
+    create_options(oparser)
+    (options, args) = config.parse_options(oparser)
+
+    try:
+        conf, app = config.load_paste_app('glance-prefetcher', options, args)
+        app.run()
+    except RuntimeError, e:
+        sys.exit("ERROR: %s" % e)

=== added file 'bin/glance-cache-pruner'
--- bin/glance-cache-pruner	1970-01-01 00:00:00 +0000
+++ bin/glance-cache-pruner	2011-07-25 22:03:31 +0000
@@ -0,0 +1,65 @@
+#!/usr/bin/env python
+# vim: tabstop=4 shiftwidth=4 softtabstop=4
+
+# Copyright 2010 United States Government as represented by the
+# Administrator of the National Aeronautics and Space Administration.
+# Copyright 2011 OpenStack LLC.
+# All Rights Reserved.
+#
+#    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.
+
+"""
+Glance Image Cache Pruner
+
+This is meant to be run as a periodic task, perhaps every half-hour.
+"""
+
+import optparse
+import os
+import sys
+
+# If ../glance/__init__.py exists, add ../ to Python search path, so that
+# it will override what happens to be installed in /usr/(local/)lib/python...
+possible_topdir = os.path.normpath(os.path.join(os.path.abspath(sys.argv[0]),
+                                   os.pardir,
+                                   os.pardir))
+if os.path.exists(os.path.join(possible_topdir, 'glance', '__init__.py')):
+    sys.path.insert(0, possible_topdir)
+
+from glance import version
+from glance.common import config
+from glance.common import wsgi
+
+
+def create_options(parser):
+    """
+    Sets up the CLI and config-file options that may be
+    parsed and program commands.
+
+    :param parser: The option parser
+    """
+    config.add_common_options(parser)
+    config.add_log_options(parser)
+
+
+if __name__ == '__main__':
+    oparser = optparse.OptionParser(version='%%prog %s'
+                                    % version.version_string())
+    create_options(oparser)
+    (options, args) = config.parse_options(oparser)
+
+    try:
+        conf, app = config.load_paste_app('glance-pruner', options, args)
+        app.run()
+    except RuntimeError, e:
+        sys.exit("ERROR: %s" % e)

=== added file 'bin/glance-cache-reaper'
--- bin/glance-cache-reaper	1970-01-01 00:00:00 +0000
+++ bin/glance-cache-reaper	2011-07-25 22:03:31 +0000
@@ -0,0 +1,73 @@
+#!/usr/bin/env python
+# vim: tabstop=4 shiftwidth=4 softtabstop=4
+
+# Copyright 2010 United States Government as represented by the
+# Administrator of the National Aeronautics and Space Administration.
+# Copyright 2011 OpenStack LLC.
+# All Rights Reserved.
+#
+#    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.
+
+"""
+Glance Image Cache Invalid Cache Entry and Stalled Image  Reaper
+
+This is meant to be run as a periodic task from cron.
+
+If something goes wrong while we're caching an image (for example the fetch
+times out, or an exception is raised), we create an 'invalid' entry. These
+entires are left around for debugging purposes. However, after some period of
+time, we want to cleans these up, aka reap them.
+
+Also, if an incomplete image hangs around past the image_cache_stall_timeout
+period, we automatically sweep it up.
+"""
+
+import optparse
+import os
+import sys
+
+# If ../glance/__init__.py exists, add ../ to Python search path, so that
+# it will override what happens to be installed in /usr/(local/)lib/python...
+possible_topdir = os.path.normpath(os.path.join(os.path.abspath(sys.argv[0]),
+                                   os.pardir,
+                                   os.pardir))
+if os.path.exists(os.path.join(possible_topdir, 'glance', '__init__.py')):
+    sys.path.insert(0, possible_topdir)
+
+from glance import version
+from glance.common import config
+from glance.common import wsgi
+
+
+def create_options(parser):
+    """
+    Sets up the CLI and config-file options that may be
+    parsed and program commands.
+
+    :param parser: The option parser
+    """
+    config.add_common_options(parser)
+    config.add_log_options(parser)
+
+
+if __name__ == '__main__':
+    oparser = optparse.OptionParser(version='%%prog %s'
+                                    % version.version_string())
+    create_options(oparser)
+    (options, args) = config.parse_options(oparser)
+
+    try:
+        conf, app = config.load_paste_app('glance-reaper', options, args)
+        app.run()
+    except RuntimeError, e:
+        sys.exit("ERROR: %s" % e)

=== modified file 'etc/glance-api.conf'
--- etc/glance-api.conf	2011-07-23 00:07:38 +0000
+++ etc/glance-api.conf	2011-07-25 22:03:31 +0000
@@ -51,6 +51,16 @@
 # Do we create the container if it does not exist?
 swift_store_create_container_on_put = False
 
+# ============ Image Cache Options ========================
+
+# Directory that the Image Cache writes data to
+# Make sure this is also set in glance-pruner.conf
+image_cache_datadir = /var/lib/glance/image-cache/
+
+# Number of seconds after which we should consider an incomplete image to be
+# stalled and eligible for reaping
+image_cache_stall_timeout = 86400
+
 # ============ Delayed Delete Options =============================
 
 # Turn on/off delayed delete
@@ -59,6 +69,9 @@
 [pipeline:glance-api]
 pipeline = versionnegotiation context apiv1app
 
+# To enable Image Cache Management API replace pipeline with below:
+# pipeline = versionnegotiation imagecache apiv1app
+
 [pipeline:versions]
 pipeline = versionsapp
 
@@ -71,5 +84,8 @@
 [filter:versionnegotiation]
 paste.filter_factory = glance.api.middleware.version_negotiation:filter_factory
 
+[filter:imagecache]
+paste.filter_factory = glance.api.middleware.image_cache:filter_factory
+
 [filter:context]
 paste.filter_factory = glance.common.context:filter_factory

=== added file 'etc/glance-prefetcher.conf'
--- etc/glance-prefetcher.conf	1970-01-01 00:00:00 +0000
+++ etc/glance-prefetcher.conf	2011-07-25 22:03:31 +0000
@@ -0,0 +1,21 @@
+[DEFAULT]
+# Show more verbose log output (sets INFO log level output)
+verbose = True
+
+# Show debugging output in logs (sets DEBUG log level output)
+debug = False
+
+log_file = /var/log/glance/prefetcher.log
+
+# Directory that the Image Cache writes data to
+# Make sure this is also set in glance-api.conf
+image_cache_datadir = /var/lib/glance/image-cache/
+
+# Address to find the registry server
+registry_host = 0.0.0.0
+
+# Port the registry server is listening on
+registry_port = 9191
+
+[app:glance-prefetcher]
+paste.app_factory = glance.image_cache.prefetcher:app_factory

=== added file 'etc/glance-pruner.conf'
--- etc/glance-pruner.conf	1970-01-01 00:00:00 +0000
+++ etc/glance-pruner.conf	2011-07-25 22:03:31 +0000
@@ -0,0 +1,28 @@
+[DEFAULT]
+# Show more verbose log output (sets INFO log level output)
+verbose = True
+
+# Show debugging output in logs (sets DEBUG log level output)
+debug = False
+
+log_file = /var/log/glance/pruner.log
+
+image_cache_max_size_bytes = 1073741824
+
+# Percentage of the cache that should be freed (in addition to the overage)
+# when the cache is pruned
+#
+# A percentage of 0% means we prune only as many files as needed to remain
+# under the cache's max_size. This is space efficient but will lead to
+# constant pruning as the size bounces just-above and just-below the max_size.
+#
+# To mitigate this 'thrashing', you can specify an additional amount of the
+# cache that should be tossed out on each prune.
+image_cache_percent_extra_to_free = 0.20
+
+# Directory that the Image Cache writes data to
+# Make sure this is also set in glance-api.conf
+image_cache_datadir = /var/lib/glance/image-cache/
+
+[app:glance-pruner]
+paste.app_factory = glance.image_cache.pruner:app_factory

=== added file 'etc/glance-reaper.conf'
--- etc/glance-reaper.conf	1970-01-01 00:00:00 +0000
+++ etc/glance-reaper.conf	2011-07-25 22:03:31 +0000
@@ -0,0 +1,29 @@
+[DEFAULT]
+# Show more verbose log output (sets INFO log level output)
+verbose = True
+
+# Show debugging output in logs (sets DEBUG log level output)
+debug = False
+
+log_file = /var/log/glance/reaper.log
+
+# Directory that the Image Cache writes data to
+# Make sure this is also set in glance-api.conf
+image_cache_datadir = /var/lib/glance/image-cache/
+
+# image_cache_invalid_entry_grace_period - seconds
+#
+# If an exception is raised as we're writing to the cache, the cache-entry is
+# deemed invalid and moved to <image_cache_datadir>/invalid so that it can be
+# inspected for debugging purposes. 
+#
+# This is number of seconds to leave these invalid images around before they
+# are elibible to be reaped.
+image_cache_invalid_entry_grace_period = 3600
+
+# Number of seconds after which we should consider an incomplete image to be
+# stalled and eligible for reaping
+image_cache_stall_timeout = 86400
+
+[app:glance-reaper]
+paste.app_factory = glance.image_cache.reaper:app_factory

=== modified file 'glance/api/__init__.py'
--- glance/api/__init__.py	2011-05-05 23:12:21 +0000
+++ glance/api/__init__.py	2011-07-25 22:03:31 +0000
@@ -14,3 +14,50 @@
 #    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 #    License for the specific language governing permissions and limitations
 #    under the License.
+import logging
+import webob.exc
+
+from glance import registry
+from glance.common import exception
+
+
+logger = logging.getLogger('glance.api')
+
+
+class BaseController(object):
+    def get_image_meta_or_404(self, request, id):
+        """
+        Grabs the image metadata for an image with a supplied
+        identifier or raises an HTTPNotFound (404) response
+
+        :param request: The WSGI/Webob Request object
+        :param id: The opaque image identifier
+
+        :raises HTTPNotFound if image does not exist
+        """
+        context = request.context
+        try:
+            return registry.get_image_metadata(self.options, context, id)
+        except exception.NotFound:
+            msg = "Image with identifier %s not found" % id
+            logger.debug(msg)
+            raise webob.exc.HTTPNotFound(
+                    msg, request=request, content_type='text/plain')
+        except exception.NotAuthorized:
+            msg = "Unauthorized image access"
+            logger.debug(msg)
+            raise webob.exc.HTTPForbidden(msg, request=request,
+                                content_type='text/plain')
+
+    def get_active_image_meta_or_404(self, request, id):
+        """
+        Same as get_image_meta_or_404 except that it will raise a 404 if the
+        image isn't 'active'.
+        """
+        image = self.get_image_meta_or_404(request, id)
+        if image['status'] != 'active':
+            msg = "Image %s is not active" % id
+            logger.debug(msg)
+            raise webob.exc.HTTPNotFound(
+                    msg, request=request, content_type='text/plain')
+        return image

=== added file 'glance/api/cached_images.py'
--- glance/api/cached_images.py	1970-01-01 00:00:00 +0000
+++ glance/api/cached_images.py	2011-07-25 22:03:31 +0000
@@ -0,0 +1,105 @@
+# vim: tabstop=4 shiftwidth=4 softtabstop=4
+
+# Copyright 2011 OpenStack LLC.
+# All Rights Reserved.
+#
+#    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.
+
+"""
+Controller for Image Cache Management API
+"""
+
+import httplib
+import json
+
+import webob.dec
+import webob.exc
+
+from glance.common import exception
+from glance.common import wsgi
+from glance import api
+from glance import image_cache
+from glance import registry
+
+
+class Controller(api.BaseController):
+    """
+    A controller that produces information on the Glance API versions.
+    """
+
+    def __init__(self, options):
+        self.options = options
+        self.cache = image_cache.ImageCache(self.options)
+
+    def index(self, req):
+        status = req.str_params.get('status')
+        if status == 'invalid':
+            entries = list(self.cache.invalid_entries())
+        elif status == 'incomplete':
+            entries = list(self.cache.incomplete_entries())
+        elif status == 'prefetching':
+            entries = list(self.cache.prefetch_entries())
+        else:
+            entries = list(self.cache.entries())
+
+        return dict(cached_images=entries)
+
+    def delete(self, req, id):
+        self.cache.purge(id)
+
+    def delete_collection(self, req):
+        """
+        DELETE /cached_images - Clear all active cached images
+        DELETE /cached_images?status=invalid - Reap invalid cached images
+        DELETE /cached_images?status=incomplete - Reap stalled cached images
+        """
+        status = req.str_params.get('status')
+        if status == 'invalid':
+            num_reaped = self.cache.reap_invalid()
+            return dict(num_reaped=num_reaped)
+        elif status == 'incomplete':
+            num_reaped = self.cache.reap_stalled()
+            return dict(num_reaped=num_reaped)
+        else:
+            num_purged = self.cache.clear()
+            return dict(num_purged=num_purged)
+
+    def update(self, req, id):
+        """PUT /cached_images/1 is used to prefetch an image into the cache"""
+        image_meta = self.get_active_image_meta_or_404(req, id)
+        try:
+            self.cache.queue_prefetch(image_meta)
+        except exception.Invalid, e:
+            raise webob.exc.HTTPBadRequest(explanation=str(e))
+
+
+class CachedImageDeserializer(wsgi.JSONRequestDeserializer):
+    pass
+
+
+class CachedImageSerializer(wsgi.JSONResponseSerializer):
+    pass
+
+
+def create_resource(options):
+    """Cached Images resource factory method"""
+    deserializer = CachedImageDeserializer()
+    serializer = CachedImageSerializer()
+    return wsgi.Resource(Controller(options), deserializer, serializer)
+
+
+def app_factory(global_conf, **local_conf):
+    """paste.deploy app factory for creating Cached Images apps"""
+    conf = global_conf.copy()
+    conf.update(local_conf)
+    return Controller(conf)

=== added file 'glance/api/middleware/image_cache.py'
--- glance/api/middleware/image_cache.py	1970-01-01 00:00:00 +0000
+++ glance/api/middleware/image_cache.py	2011-07-25 22:03:31 +0000
@@ -0,0 +1,57 @@
+# vim: tabstop=4 shiftwidth=4 softtabstop=4
+
+# Copyright 2011 OpenStack LLC.
+# All Rights Reserved.
+#
+#    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.
+
+"""
+Image Cache Management API
+"""
+
+import logging
+
+from glance.api import cached_images
+from glance.common import wsgi
+
+logger = logging.getLogger('glance.api.middleware.image_cache')
+
+
+class ImageCacheFilter(wsgi.Middleware):
+    def __init__(self, app, options):
+        super(ImageCacheFilter, self).__init__(app)
+
+        map = app.map
+        resource = cached_images.create_resource(options)
+        map.resource("cached_image", "cached_images",
+                     controller=resource,
+                     collection={'reap_invalid': 'POST',
+                                 'reap_stalled': 'POST'})
+
+        map.connect("/cached_images",
+                    controller=resource,
+                    action="delete_collection",
+                    conditions=dict(method=["DELETE"]))
+
+
+def filter_factory(global_conf, **local_conf):
+    """
+    Factory method for paste.deploy
+    """
+    conf = global_conf.copy()
+    conf.update(local_conf)
+
+    def filter(app):
+        return ImageCacheFilter(app, conf)
+
+    return filter

=== modified file 'glance/api/v1/__init__.py'
--- glance/api/v1/__init__.py	2011-06-27 18:05:29 +0000
+++ glance/api/v1/__init__.py	2011-07-25 22:03:31 +0000
@@ -34,7 +34,7 @@
         mapper = routes.Mapper()
         resource = images.create_resource(options)
         mapper.resource("image", "images", controller=resource,
-                       collection={'detail': 'GET'})
+                        collection={'detail': 'GET'})
         mapper.connect("/", controller=resource, action="index")
         mapper.connect("/images/{id}", controller=resource, action="meta",
                        conditions=dict(method=["HEAD"]))

=== modified file 'glance/api/v1/images.py'
--- glance/api/v1/images.py	2011-07-23 03:38:20 +0000
+++ glance/api/v1/images.py	2011-07-25 22:03:31 +0000
@@ -30,6 +30,8 @@
                        HTTPBadRequest,
                        HTTPForbidden)
 
+from glance import api
+from glance import image_cache
 from glance.common import exception
 from glance.common import wsgi
 from glance.store import (get_from_backend,
@@ -49,8 +51,7 @@
 SUPPORTED_PARAMS = ('limit', 'marker', 'sort_key', 'sort_dir')
 
 
-class Controller(object):
-
+class Controller(api.BaseController):
     """
     WSGI controller for images resource in Glance v1 API
 
@@ -186,18 +187,63 @@
 
         :raises HTTPNotFound if image is not available to user
         """
-        image = self.get_image_meta_or_404(req, id)
-
-        def image_iterator():
-            chunks = get_from_backend(image['location'],
-                                      expected_size=image['size'],
-                                      options=self.options)
-
-            for chunk in chunks:
-                yield chunk
+        image = self.get_active_image_meta_or_404(req, id)
+
+        def get_from_store(image):
+            """Called if caching disabled"""
+            return get_from_backend(image['location'],
+                                    expected_size=image['size'],
+                                    options=self.options)
+
+        def get_from_cache(image, cache):
+            """Called if cache hit"""
+            with cache.open(image, "rb") as cache_file:
+                chunks = utils.chunkiter(cache_file)
+                for chunk in chunks:
+                    yield chunk
+
+        def get_from_store_tee_into_cache(image, cache):
+            """Called if cache miss"""
+            with cache.open(image, "wb") as cache_file:
+                chunks = get_from_store(image)
+                for chunk in chunks:
+                    cache_file.write(chunk)
+                    yield chunk
+
+        cache = image_cache.ImageCache(self.options)
+        if cache.enabled:
+            if cache.hit(id):
+                # hit
+                logger.debug("image cache HIT, retrieving image '%s'"
+                             " from cache", id)
+                image_iterator = get_from_cache(image, cache)
+            else:
+                # miss
+                logger.debug("image cache MISS, retrieving image '%s'"
+                             " from store and tee'ing into cache", id)
+
+                # We only want to tee-into the cache if we're not currently
+                # prefetching an image
+                image_id = image['id']
+                if cache.is_image_currently_prefetching(image_id):
+                    image_iterator = get_from_store(image)
+                else:
+                    # NOTE(sirp): If we're about to download and cache an
+                    # image which is currently in the prefetch queue, just
+                    # delete the queue items since we're caching it anyway
+                    if cache.is_image_queued_for_prefetch(image_id):
+                        cache.delete_queued_prefetch_image(image_id)
+
+                    image_iterator = get_from_store_tee_into_cache(
+                        image, cache)
+        else:
+            # disabled
+            logger.debug("image cache DISABLED, retrieving image '%s'"
+                         " from store", id)
+            image_iterator = get_from_store(image)
 
         return {
-            'image_iterator': image_iterator(),
+            'image_iterator': image_iterator,
             'image_meta': image,
         }
 
@@ -275,12 +321,12 @@
         store = self.get_store_or_400(req, store_name)
 
         image_id = image_meta['id']
-        logger.debug("Setting image %s to status 'saving'" % image_id)
+        logger.debug("Setting image %s to status 'saving'", image_id)
         registry.update_image_metadata(self.options, req.context, image_id,
                                        {'status': 'saving'})
         try:
             logger.debug("Uploading image data for image %(image_id)s "
-                         "to %(store_name)s store" % locals())
+                         "to %(store_name)s store", locals())
             location, size, checksum = store.add(image_meta['id'],
                                                  req.body_file,
                                                  self.options)
@@ -302,7 +348,7 @@
             # from the backend store
             logger.debug("Updating image %(image_id)s data. "
                          "Checksum set to %(checksum)s, size set "
-                         "to %(size)d" % locals())
+                         "to %(size)d", locals())
             registry.update_image_metadata(self.options, req.context,
                                            image_id,
                                            {'checksum': checksum,
@@ -506,30 +552,6 @@
                                          req.context, id)
         registry.delete_image_metadata(self.options, req.context, id)
 
-    def get_image_meta_or_404(self, request, id):
-        """
-        Grabs the image metadata for an image with a supplied
-        identifier or raises an HTTPNotFound (404) response
-
-        :param request: The WSGI/Webob Request object
-        :param id: The opaque image identifier
-
-        :raises HTTPNotFound if image does not exist
-        """
-        try:
-            return registry.get_image_metadata(self.options,
-                                               request.context, id)
-        except exception.NotFound:
-            msg = "Image with identifier %s not found" % id
-            logger.debug(msg)
-            raise HTTPNotFound(msg, request=request,
-                               content_type='text/plain')
-        except exception.NotAuthorized:
-            msg = "Unauthorized image access"
-            logger.debug(msg)
-            raise HTTPForbidden(msg, request=request,
-                                content_type='text/plain')
-
     def get_store_or_400(self, request, store_name):
         """
         Grabs the storage backend for the supplied store name

=== modified file 'glance/client.py'
--- glance/client.py	2011-07-20 22:53:44 +0000
+++ glance/client.py	2011-07-25 22:03:31 +0000
@@ -164,5 +164,120 @@
         self.do_request("DELETE", "/images/%s" % image_id)
         return True
 
+    def get_cached_images(self, **kwargs):
+        """
+        Returns a list of images stored in the image cache.
+
+        :param filters: dictionary of attributes by which the resulting
+                        collection of images should be filtered
+        :param marker: id after which to start the page of images
+        :param limit: maximum number of items to return
+        :param sort_key: results will be ordered by this image attribute
+        :param sort_dir: direction in which to to order results (asc, desc)
+        """
+        params = self._extract_params(kwargs, v1_images.SUPPORTED_PARAMS)
+        res = self.do_request("GET", "/cached_images", params=params)
+        data = json.loads(res.read())['cached_images']
+        return data
+
+    def get_invalid_cached_images(self, **kwargs):
+        """
+        Returns a list of invalid images stored in the image cache.
+
+        :param filters: dictionary of attributes by which the resulting
+                        collection of images should be filtered
+        :param marker: id after which to start the page of images
+        :param limit: maximum number of items to return
+        :param sort_key: results will be ordered by this image attribute
+        :param sort_dir: direction in which to to order results (asc, desc)
+        """
+        params = self._extract_params(kwargs, v1_images.SUPPORTED_PARAMS)
+        params['status'] = 'invalid'
+        res = self.do_request("GET", "/cached_images", params=params)
+        data = json.loads(res.read())['cached_images']
+        return data
+
+    def get_incomplete_cached_images(self, **kwargs):
+        """
+        Returns a list of incomplete images being fetched into cache
+
+        :param filters: dictionary of attributes by which the resulting
+                        collection of images should be filtered
+        :param marker: id after which to start the page of images
+        :param limit: maximum number of items to return
+        :param sort_key: results will be ordered by this image attribute
+        :param sort_dir: direction in which to to order results (asc, desc)
+        """
+        params = self._extract_params(kwargs, v1_images.SUPPORTED_PARAMS)
+        params['status'] = 'incomplete'
+        res = self.do_request("GET", "/cached_images", params=params)
+        data = json.loads(res.read())['cached_images']
+        return data
+
+    def purge_cached_image(self, image_id):
+        """
+        Delete a specified image from the cache
+        """
+        self.do_request("DELETE", "/cached_images/%s" % image_id)
+        return True
+
+    def clear_cached_images(self):
+        """
+        Clear all cached images
+        """
+        res = self.do_request("DELETE", "/cached_images")
+        data = json.loads(res.read())
+        num_purged = data['num_purged']
+        return num_purged
+
+    def reap_invalid_cached_images(self, **kwargs):
+        """
+        Reaps any invalid cached images
+        """
+        params = self._extract_params(kwargs, v1_images.SUPPORTED_PARAMS)
+        params['status'] = 'invalid'
+        res = self.do_request("DELETE", "/cached_images", params=params)
+        data = json.loads(res.read())
+        num_reaped = data['num_reaped']
+        return num_reaped
+
+    def reap_stalled_cached_images(self, **kwargs):
+        """
+        Reaps any stalled cached images
+        """
+        params = self._extract_params(kwargs, v1_images.SUPPORTED_PARAMS)
+        params['status'] = 'incomplete'
+        res = self.do_request("DELETE", "/cached_images", params=params)
+        data = json.loads(res.read())
+        num_reaped = data['num_reaped']
+        return num_reaped
+
+    def prefetch_cache_image(self, image_id):
+        """
+        Pre-fetch a specified image from the cache
+        """
+        res = self.do_request("HEAD", "/images/%s" % image_id)
+        image = utils.get_image_meta_from_headers(res)
+        self.do_request("PUT", "/cached_images/%s" % image_id)
+        return True
+
+    def get_prefetching_cache_images(self, **kwargs):
+        """
+        Returns a list of images which are actively being prefetched or are
+        queued to be prefetched in the future.
+
+        :param filters: dictionary of attributes by which the resulting
+                        collection of images should be filtered
+        :param marker: id after which to start the page of images
+        :param limit: maximum number of items to return
+        :param sort_key: results will be ordered by this image attribute
+        :param sort_dir: direction in which to to order results (asc, desc)
+        """
+        params = self._extract_params(kwargs, v1_images.SUPPORTED_PARAMS)
+        params['status'] = 'prefetching'
+        res = self.do_request("GET", "/cached_images", params=params)
+        data = json.loads(res.read())['cached_images']
+        return data
+
 
 Client = V1Client

=== added directory 'glance/image_cache'
=== added file 'glance/image_cache/__init__.py'
--- glance/image_cache/__init__.py	1970-01-01 00:00:00 +0000
+++ glance/image_cache/__init__.py	2011-07-25 22:03:31 +0000
@@ -0,0 +1,451 @@
+# vim: tabstop=4 shiftwidth=4 softtabstop=4
+
+# Copyright 2011 OpenStack LLC.
+# All Rights Reserved.
+#
+#    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.
+
+"""
+LRU Cache for Image Data
+"""
+from contextlib import contextmanager
+import datetime
+import itertools
+import logging
+import os
+import sys
+import time
+
+from glance.common import config
+from glance.common import exception
+from glance import utils
+
+logger = logging.getLogger('glance.image_cache')
+
+
+class ImageCache(object):
+    """Provides an LRU cache for image data.
+
+    Data is cached on READ not on WRITE; meaning if the cache is enabled, we
+    attempt to read from the cache first, if we don't find the data, we begin
+    streaming the data from the 'store' while simultaneously tee'ing the data
+    into the cache. Subsequent reads will generate cache HITs for this image.
+
+    Assumptions
+    ===========
+
+        1. Cache data directory exists on a filesytem that updates atime on
+           reads ('noatime' should NOT be set)
+
+        2. Cache data directory exists on a filesystem that supports xattrs.
+           This is optional, but highly recommended since it allows us to
+           present ops with useful information pertaining to the cache, like
+           human readable filenames and statistics.
+
+        3. `glance-prune` is scheduled to run as a periodic job via cron. This
+            is needed to run the LRU prune strategy to keep the cache size
+            within the limits set by the config file.
+
+
+    Cache Directory Notes
+    =====================
+
+    The image cache data directory contains the main cache path, where the
+    active cache entries and subdirectories for handling partial downloads
+    and errored-out cache images.
+
+    The layout looks like:
+
+        image-cache/
+            entry1
+            entry2
+            ...
+            incomplete/
+            invalid/
+            prefetch/
+            prefetching/
+    """
+    def __init__(self, options):
+        self.options = options
+        self._make_cache_directory_if_needed()
+
+    def _make_cache_directory_if_needed(self):
+        """Creates main cache directory along with incomplete subdirectory"""
+        if not self.enabled:
+            return
+
+        # NOTE(sirp): making the incomplete_path will have the effect of
+        # creating the main cache path directory as well
+        paths = [self.incomplete_path, self.invalid_path, self.prefetch_path,
+                 self.prefetching_path]
+
+        for path in paths:
+            if os.path.exists(path):
+                continue
+            logger.info("image cache directory doesn't exist, creating '%s'",
+                        path)
+            os.makedirs(path)
+
+    @property
+    def enabled(self):
+        return self.options.get('image_cache_enabled', False)
+
+    @property
+    def path(self):
+        """This is the base path for the image cache"""
+        datadir = self.options['image_cache_datadir']
+        return datadir
+
+    @property
+    def incomplete_path(self):
+        """This provides a temporary place to write our cache entries so that
+        we we're not storing incomplete objects in the cache directly.
+
+        When the file is finished writing to, it is moved from the incomplete
+        path back out into the main cache directory.
+
+        The incomplete_path is a subdirectory of the main cache path to ensure
+        that they both reside on the same filesystem and thus making moves
+        cheap.
+        """
+        return os.path.join(self.path, 'incomplete')
+
+    @property
+    def invalid_path(self):
+        """Place to move corrupted images
+
+        If an exception is raised while we're writing an image to the
+        incomplete_path, we move the incomplete image to here.
+        """
+        return os.path.join(self.path, 'invalid')
+
+    @property
+    def prefetch_path(self):
+        """This contains a list of image ids that should be pre-fetched into
+        the cache
+        """
+        return os.path.join(self.path, 'prefetch')
+
+    @property
+    def prefetching_path(self):
+        """This contains image ids that currently being prefetched"""
+        return os.path.join(self.path, 'prefetching')
+
+    def path_for_image(self, image_id):
+        """This crafts an absolute path to a specific entry"""
+        return os.path.join(self.path, str(image_id))
+
+    def incomplete_path_for_image(self, image_id):
+        """This crafts an absolute path to a specific entry in the incomplete
+        directory
+        """
+        return os.path.join(self.incomplete_path, str(image_id))
+
+    def invalid_path_for_image(self, image_id):
+        """This crafts an absolute path to a specific entry in the invalid
+        directory
+        """
+        return os.path.join(self.invalid_path, str(image_id))
+
+    @contextmanager
+    def open(self, image_meta, mode="rb"):
+        """Open a cache image for reading or writing.
+
+        We have two possible scenarios:
+
+            1. READ: we should attempt to read the file from the cache's
+               main directory
+
+            2. WRITE: we should write to a file under the cache's incomplete
+               directory, and when it's finished, move it out the main cache
+               directory.
+        """
+        if mode == 'wb':
+            with self._open_write(image_meta, mode) as cache_file:
+                yield cache_file
+        elif mode == 'rb':
+            with self._open_read(image_meta, mode) as cache_file:
+                yield cache_file
+        else:
+            # NOTE(sirp): `rw` and `a' modes are not supported since image
+            # data is immutable, we `wb` it once, then `rb` multiple times.
+            raise Exception("mode '%s' not supported" % mode)
+
+    @contextmanager
+    def _open_write(self, image_meta, mode):
+        image_id = image_meta['id']
+        incomplete_path = self.incomplete_path_for_image(image_id)
+
+        def set_xattr(key, value):
+            utils.set_xattr(incomplete_path, key, value)
+
+        def commit():
+            set_xattr('image_name', image_meta['name'])
+            set_xattr('hits', 0)
+
+            final_path = self.path_for_image(image_id)
+            logger.debug("fetch finished, commiting by moving "
+                         "'%(incomplete_path)s' to '%(final_path)s'",
+                         dict(incomplete_path=incomplete_path,
+                              final_path=final_path))
+            os.rename(incomplete_path, final_path)
+
+        def rollback(e):
+            set_xattr('image_name', image_meta['name'])
+            set_xattr('error', str(e))
+
+            invalid_path = self.invalid_path_for_image(image_id)
+            logger.debug("fetch errored, rolling back by moving "
+                         "'%(incomplete_path)s' to '%(invalid_path)s'",
+                         dict(incomplete_path=incomplete_path,
+                              invalid_path=invalid_path))
+            os.rename(incomplete_path, invalid_path)
+
+        try:
+            with open(incomplete_path, mode) as cache_file:
+                set_xattr('expected_size', image_meta['size'])
+                yield cache_file
+        except Exception as e:
+            rollback(e)
+            raise
+        else:
+            commit()
+
+    @contextmanager
+    def _open_read(self, image_meta, mode):
+        image_id = image_meta['id']
+        path = self.path_for_image(image_id)
+        with open(path, mode) as cache_file:
+            yield cache_file
+
+        utils.inc_xattr(path, 'hits')  # bump the hit count
+
+    def hit(self, image_id):
+        return os.path.exists(self.path_for_image(image_id))
+
+    @staticmethod
+    def _delete_file(path):
+        if os.path.exists(path):
+            logger.debug("deleting image cache file '%s'", path)
+            os.unlink(path)
+        else:
+            logger.warn("image cache file '%s' doesn't exist, unable to"
+                        " delete", path)
+
+    def purge(self, image_id):
+        path = self.path_for_image(image_id)
+        self._delete_file(path)
+
+    def clear(self):
+        purged = 0
+        for path in self.get_all_regular_files(self.path):
+            self._delete_file(path)
+            purged += 1
+        return purged
+
+    def is_image_currently_being_written(self, image_id):
+        """Returns true if we're currently downloading an image"""
+        incomplete_path = self.incomplete_path_for_image(image_id)
+        return os.path.exists(incomplete_path)
+
+    def is_currently_prefetching_any_images(self):
+        """True if we are currently prefetching an image.
+
+        We only allow one prefetch to occur at a time.
+        """
+        return len(os.listdir(self.prefetching_path)) > 0
+
+    def is_image_queued_for_prefetch(self, image_id):
+        prefetch_path = os.path.join(self.prefetch_path, str(image_id))
+        return os.path.exists(prefetch_path)
+
+    def is_image_currently_prefetching(self, image_id):
+        prefetching_path = os.path.join(self.prefetching_path, str(image_id))
+        return os.path.exists(prefetching_path)
+
+    def queue_prefetch(self, image_meta):
+        """This adds a image to be prefetched to the queue directory.
+
+        If the image already exists in the queue directory or the
+        prefetching directory, we ignore it.
+        """
+        image_id = image_meta['id']
+
+        if self.hit(image_id):
+            msg = "Skipping prefetch, image '%s' already cached" % image_id
+            logger.warn(msg)
+            raise exception.Invalid(msg)
+
+        if self.is_image_currently_prefetching(image_id):
+            msg = "Skipping prefetch, already prefetching image '%s'"\
+                  % image_id
+            logger.warn(msg)
+            raise exception.Invalid(msg)
+
+        if self.is_image_queued_for_prefetch(image_id):
+            msg = "Skipping prefetch, image '%s' already queued for"\
+                  " prefetching" % image_id
+            logger.warn(msg)
+            raise exception.Invalid(msg)
+
+        prefetch_path = os.path.join(self.prefetch_path, str(image_id))
+
+        # Touch the file to add it to the queue
+        with open(prefetch_path, "w") as f:
+            pass
+
+        utils.set_xattr(prefetch_path, 'image_name', image_meta['name'])
+
+    def delete_queued_prefetch_image(self, image_id):
+        prefetch_path = os.path.join(self.prefetch_path, str(image_id))
+        self._delete_file(prefetch_path)
+
+    def delete_prefetching_image(self, image_id):
+        prefetching_path = os.path.join(self.prefetching_path, str(image_id))
+        self._delete_file(prefetching_path)
+
+    def pop_prefetch_item(self):
+        """This returns the next prefetch job.
+
+        The prefetch directory is treated like a FIFO; so we sort by modified
+        time and pick the oldest.
+        """
+        items = []
+        for path in self.get_all_regular_files(self.prefetch_path):
+            mtime = os.path.getmtime(path)
+            items.append((mtime, path))
+
+        if not items:
+            raise IndexError
+
+        # Sort oldest files to the end of the list
+        items.sort(reverse=True)
+
+        mtime, path = items.pop()
+        image_id = os.path.basename(path)
+        return image_id
+
+    def do_prefetch(self, image_id):
+        """This moves the file from the prefetch queue path to the in-progress
+        prefetching path (so we don't try to prefetch something twice).
+        """
+        prefetch_path = os.path.join(self.prefetch_path, str(image_id))
+        prefetching_path = os.path.join(self.prefetching_path, str(image_id))
+        os.rename(prefetch_path, prefetching_path)
+
+    @staticmethod
+    def get_all_regular_files(basepath):
+        for fname in os.listdir(basepath):
+            path = os.path.join(basepath, fname)
+            if os.path.isfile(path):
+                yield path
+
+    def _base_entries(self, basepath):
+        def iso8601_from_timestamp(timestamp):
+            return datetime.datetime.utcfromtimestamp(timestamp)\
+                                    .isoformat()
+
+        for path in self.get_all_regular_files(basepath):
+            filename = os.path.basename(path)
+            try:
+                image_id = int(filename)
+            except ValueError, TypeError:
+                continue
+
+            entry = {}
+            entry['id'] = image_id
+            entry['path'] = path
+            entry['name'] = utils.get_xattr(path, 'image_name',
+                                            default='UNKNOWN')
+
+            mtime = os.path.getmtime(path)
+            entry['last_modified'] = iso8601_from_timestamp(mtime)
+
+            atime = os.path.getatime(path)
+            entry['last_accessed'] = iso8601_from_timestamp(atime)
+
+            entry['size'] = os.path.getsize(path)
+
+            entry['expected_size'] = utils.get_xattr(
+                    path, 'expected_size', default='UNKNOWN')
+
+            yield entry
+
+    def invalid_entries(self):
+        """Cache info for invalid cached images"""
+        for entry in self._base_entries(self.invalid_path):
+            path = entry['path']
+            entry['error'] = utils.get_xattr(path, 'error', default='UNKNOWN')
+            yield entry
+
+    def incomplete_entries(self):
+        """Cache info for invalid cached images"""
+        for entry in self._base_entries(self.incomplete_path):
+            yield entry
+
+    def prefetch_entries(self):
+        """Cache info for both queued and in-progress prefetch jobs"""
+        both_entries = itertools.chain(
+                        self._base_entries(self.prefetch_path),
+                        self._base_entries(self.prefetching_path))
+
+        for entry in both_entries:
+            path = entry['path']
+            entry['status'] = 'in-progress' if 'prefetching' in path\
+                                            else 'queued'
+            yield entry
+
+    def entries(self):
+        """Cache info for currently cached images"""
+        for entry in self._base_entries(self.path):
+            path = entry['path']
+            entry['hits'] = utils.get_xattr(path, 'hits', default='UNKNOWN')
+            yield entry
+
+    def _reap_old_files(self, dirpath, entry_type, grace=None):
+        """
+        """
+        now = time.time()
+        reaped = 0
+        for path in self.get_all_regular_files(dirpath):
+            mtime = os.path.getmtime(path)
+            age = now - mtime
+            if not grace:
+                logger.debug("No grace period, reaping '%(path)s'"
+                             " immediately", locals())
+                self._delete_file(path)
+                reaped += 1
+            elif age > grace:
+                logger.debug("Cache entry '%(path)s' exceeds grace period, "
+                             "(%(age)i s > %(grace)i s)", locals())
+                self._delete_file(path)
+                reaped += 1
+
+        logger.info("Reaped %(reaped)s %(entry_type)s cache entries",
+                    locals())
+        return reaped
+
+    def reap_invalid(self, grace=None):
+        """Remove any invalid cache entries
+
+        :param grace: Number of seconds to keep an invalid entry around for
+                      debugging purposes. If None, then delete immediately.
+        """
+        return self._reap_old_files(self.invalid_path, 'invalid', grace=grace)
+
+    def reap_stalled(self):
+        """Remove any stalled cache entries"""
+        stall_timeout = int(self.options.get('image_cache_stall_timeout',
+                            86400))
+        return self._reap_old_files(self.incomplete_path, 'stalled',
+                                    grace=stall_timeout)

=== added file 'glance/image_cache/prefetcher.py'
--- glance/image_cache/prefetcher.py	1970-01-01 00:00:00 +0000
+++ glance/image_cache/prefetcher.py	2011-07-25 22:03:31 +0000
@@ -0,0 +1,90 @@
+# vim: tabstop=4 shiftwidth=4 softtabstop=4
+
+# Copyright 2011 OpenStack LLC.
+# All Rights Reserved.
+#
+#    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.
+
+"""
+Prefetches images into the Image Cache
+"""
+import logging
+import os
+import stat
+import time
+
+from glance.common import config
+from glance.common import context
+from glance.image_cache import ImageCache
+from glance import registry
+from glance.store import get_from_backend
+
+
+logger = logging.getLogger('glance.image_cache.prefetcher')
+
+
+class Prefetcher(object):
+    def __init__(self, options):
+        self.options = options
+        self.cache = ImageCache(options)
+
+    def fetch_image_into_cache(self, image_id):
+        ctx = context.RequestContext(is_admin=True, show_deleted=True)
+        image_meta = registry.get_image_metadata(
+                    self.options, ctx, image_id)
+        with self.cache.open(image_meta, "wb") as cache_file:
+            chunks = get_from_backend(image_meta['location'],
+                                      expected_size=image_meta['size'],
+                                      options=self.options)
+            for chunk in chunks:
+                cache_file.write(chunk)
+
+    def run(self):
+        if self.cache.is_currently_prefetching_any_images():
+            logger.debug("Currently prefetching, going back to sleep...")
+            return
+
+        try:
+            image_id = self.cache.pop_prefetch_item()
+        except IndexError:
+            logger.debug("Nothing to prefetch, going back to sleep...")
+            return
+
+        if self.cache.hit(image_id):
+            logger.warn("Image %s is already in the cache, deleting "
+                        "prefetch job and going back to sleep...", image_id)
+            self.cache.delete_queued_prefetch_image(image_id)
+            return
+
+        # NOTE(sirp): if someone is already downloading an image that is in
+        # the prefetch queue, then go ahead and delete that item and try to
+        # prefetch another
+        if self.cache.is_image_currently_being_written(image_id):
+            logger.warn("Image %s is already being cached, deleting "
+                        "prefetch job and going back to sleep...", image_id)
+            self.cache.delete_queued_prefetch_image(image_id)
+            return
+
+        logger.debug("Prefetching '%s'", image_id)
+        self.cache.do_prefetch(image_id)
+
+        try:
+            self.fetch_image_into_cache(image_id)
+        finally:
+            self.cache.delete_prefetching_image(image_id)
+
+
+def app_factory(global_config, **local_conf):
+    conf = global_config.copy()
+    conf.update(local_conf)
+    return Prefetcher(conf)

=== added file 'glance/image_cache/pruner.py'
--- glance/image_cache/pruner.py	1970-01-01 00:00:00 +0000
+++ glance/image_cache/pruner.py	2011-07-25 22:03:31 +0000
@@ -0,0 +1,115 @@
+# vim: tabstop=4 shiftwidth=4 softtabstop=4
+
+# Copyright 2011 OpenStack LLC.
+# All Rights Reserved.
+#
+#    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.
+
+"""
+Prunes the Image Cache
+"""
+import logging
+import os
+import stat
+import time
+
+from glance.common import config
+from glance.image_cache import ImageCache
+
+logger = logging.getLogger('glance.image_cache.pruner')
+
+
+class Pruner(object):
+    def __init__(self, options):
+        self.options = options
+        self.cache = ImageCache(options)
+
+    @property
+    def max_size(self):
+        default = 1 * 1024 * 1024 * 1024  # 1 GB
+        return config.get_option(
+            self.options, 'image_cache_max_size_bytes',
+            type='int', default=default)
+
+    @property
+    def percent_extra_to_free(self):
+        return config.get_option(
+            self.options, 'image_cache_percent_extra_to_free',
+            type='float', default=0.05)
+
+    def run(self):
+        self.prune_cache()
+
+    def prune_cache(self):
+        """Prune the cache using an LRU strategy"""
+
+        # NOTE(sirp): 'Recency' is determined via the filesystem, first using
+        # atime (access time) and falling back to mtime (modified time).
+        #
+        # It has become more common to disable access-time updates by setting
+        # the `noatime` option for the filesystem. `noatime` is NOT compatible
+        # with this method.
+        #
+        # If `noatime` needs to be supported, we will need to persist access
+        # times elsewhere (either as a separate file, in the DB, or as
+        # an xattr).
+        def get_stats():
+            stats = []
+            for path in self.cache.get_all_regular_files(self.cache.path):
+                file_info = os.stat(path)
+                stats.append((file_info[stat.ST_ATIME],  # access time
+                              file_info[stat.ST_MTIME],  # modification time
+                              file_info[stat.ST_SIZE],   # size in bytes
+                              path))                     # absolute path
+            return stats
+
+        def prune_lru(stats, to_free):
+            # Sort older access and modified times to the back
+            stats.sort(reverse=True)
+
+            freed = 0
+            while to_free > 0:
+                atime, mtime, size, path = stats.pop()
+                logger.debug("deleting '%(path)s' to free %(size)d B",
+                             locals())
+                os.unlink(path)
+                to_free -= size
+                freed += size
+
+            return freed
+
+        stats = get_stats()
+
+        # Check for overage
+        cur_size = sum(s[2] for s in stats)
+        max_size = self.max_size
+        logger.debug("cur_size=%(cur_size)d B max_size=%(max_size)d B",
+                     locals())
+        if cur_size <= max_size:
+            logger.debug("cache has free space, skipping prune...")
+            return
+
+        overage = cur_size - max_size
+        extra = max_size * self.percent_extra_to_free
+        to_free = overage + extra
+        logger.debug("overage=%(overage)d B extra=%(extra)d B"
+                     " total=%(to_free)d B", locals())
+
+        freed = prune_lru(stats, to_free)
+        logger.debug("finished pruning, freed %(freed)d bytes", locals())
+
+
+def app_factory(global_config, **local_conf):
+    conf = global_config.copy()
+    conf.update(local_conf)
+    return Pruner(conf)

=== added file 'glance/image_cache/reaper.py'
--- glance/image_cache/reaper.py	1970-01-01 00:00:00 +0000
+++ glance/image_cache/reaper.py	2011-07-25 22:03:31 +0000
@@ -0,0 +1,45 @@
+# vim: tabstop=4 shiftwidth=4 softtabstop=4
+
+# Copyright 2011 OpenStack LLC.
+# All Rights Reserved.
+#
+#    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.
+
+"""
+Reaps any invalid cache entries that exceed the grace period
+"""
+import logging
+
+from glance.image_cache import ImageCache
+
+
+logger = logging.getLogger('glance.image_cache.reaper')
+
+
+class Reaper(object):
+    def __init__(self, options):
+        self.options = options
+        self.cache = ImageCache(options)
+
+    def run(self):
+        invalid_grace = int(self.options.get(
+                            'image_cache_invalid_entry_grace_period',
+                            3600))
+        self.cache.reap_invalid(grace=invalid_grace)
+        self.cache.reap_stalled()
+
+
+def app_factory(global_config, **local_conf):
+    conf = global_config.copy()
+    conf.update(local_conf)
+    return Reaper(conf)

=== modified file 'glance/utils.py'
--- glance/utils.py	2011-06-11 18:18:03 +0000
+++ glance/utils.py	2011-07-25 22:03:31 +0000
@@ -18,6 +18,12 @@
 """
 A few utility routines used throughout Glance
 """
+import errno
+import logging
+
+import xattr
+
+logger = logging.getLogger('glance.utils')
 
 
 def image_meta_to_http_headers(image_meta):
@@ -99,3 +105,158 @@
     :param req:  Webob.Request object
     """
     return req.content_length or 'transfer-encoding' in req.headers
+
+
+def chunkiter(fp, chunk_size=65536):
+    """Return an iterator to a file-like obj which yields fixed size chunks
+
+    :param fp: a file-like object
+    :param chunk_size: maximum size of chunk
+    """
+    while True:
+        chunk = fp.read(chunk_size)
+        if chunk:
+            yield chunk
+        else:
+            break
+
+
+class PrettyTable(object):
+    """Creates an ASCII art table for use in bin/glance
+
+    Example:
+
+        ID  Name              Size         Hits
+        --- ----------------- ------------ -----
+        122 image                       22     0
+    """
+    def __init__(self):
+        self.columns = []
+
+    def add_column(self, width, label="", just='l'):
+        """Add a column to the table
+
+        :param width: number of characters wide the column should be
+        :param label: column heading
+        :param just: justification for the column, 'l' for left,
+                     'r' for right
+        """
+        self.columns.append((width, label, just))
+
+    def make_header(self):
+        label_parts = []
+        break_parts = []
+        for width, label, _ in self.columns:
+            # NOTE(sirp): headers are always left justified
+            label_part = self._clip_and_justify(label, width, 'l')
+            label_parts.append(label_part)
+
+            break_part = '-' * width
+            break_parts.append(break_part)
+
+        label_line = ' '.join(label_parts)
+        break_line = ' '.join(break_parts)
+        return '\n'.join([label_line, break_line])
+
+    def make_row(self, *args):
+        row = args
+        row_parts = []
+        for data, (width, _, just) in zip(row, self.columns):
+            row_part = self._clip_and_justify(data, width, just)
+            row_parts.append(row_part)
+
+        row_line = ' '.join(row_parts)
+        return row_line
+
+    @staticmethod
+    def _clip_and_justify(data, width, just):
+        # clip field to column width
+        clipped_data = str(data)[:width]
+
+        if just == 'r':
+            # right justify
+            justified = clipped_data.rjust(width)
+        else:
+            # left justify
+            justified = clipped_data.ljust(width)
+
+        return justified
+
+
+def _make_namespaced_xattr_key(key, namespace='user'):
+    """Create a fully-qualified xattr-key by including the intended namespace.
+
+    Namespacing differs among OSes[1]:
+
+        FreeBSD: user, system
+        Linux: user, system, trusted, security
+        MacOS X: not needed
+
+    Mac OS X won't break if we include a namespace qualifier, so, for
+    simplicity, we always include it.
+
+    --
+    [1] http://en.wikipedia.org/wiki/Extended_file_attributes
+    """
+    namespaced_key = ".".join([namespace, key])
+    return namespaced_key
+
+
+def get_xattr(path, key, **kwargs):
+    """Return the value for a particular xattr
+
+    If the key doesn't not exist, or xattrs aren't supported by the file
+    system then a KeyError will be raised, that is, unless you specify a
+    default using kwargs.
+    """
+    namespaced_key = _make_namespaced_xattr_key(key)
+    entry_xattr = xattr.xattr(path)
+    try:
+        return entry_xattr[namespaced_key]
+    except KeyError:
+        if 'default' in kwargs:
+            return kwargs['default']
+        else:
+            raise
+
+
+def set_xattr(path, key, value):
+    """Set the value of a specified xattr.
+
+    If xattrs aren't supported by the file-system, we skip setting the value.
+    """
+    namespaced_key = _make_namespaced_xattr_key(key)
+    entry_xattr = xattr.xattr(path)
+    try:
+        entry_xattr.set(namespaced_key, str(value))
+    except IOError as e:
+        if e.errno == errno.EOPNOTSUPP:
+            logger.warn("xattrs not supported, skipping...")
+        else:
+            raise
+
+
+def inc_xattr(path, key, n=1):
+    """Increment the value of an xattr (assuming it is an integer).
+
+    BEWARE, this code *does* have a RACE CONDITION, since the
+    read/update/write sequence is not atomic.
+
+    Since the use-case for this function is collecting stats--not critical--
+    the benefits of simple, lock-free code out-weighs the possibility of an
+    occasional hit not being counted.
+    """
+    try:
+        count = int(get_xattr(path, key))
+    except KeyError:
+        # NOTE(sirp): a KeyError is generated in two cases:
+        # 1) xattrs is not supported by the filesystem
+        # 2) the key is not present on the file
+        #
+        # In either case, just ignore it...
+        pass
+    else:
+        # NOTE(sirp): only try to bump the count if xattrs is supported
+        # and the key is present
+        count += n
+        set_xattr(path, key, str(count))

=== modified file 'setup.py'
--- setup.py	2011-04-15 09:34:17 +0000
+++ setup.py	2011-07-25 22:03:31 +0000
@@ -87,6 +87,9 @@
     ],
     scripts=['bin/glance',
              'bin/glance-api',
+             'bin/glance-cache-prefetcher',
+             'bin/glance-cache-pruner',
+             'bin/glance-cache-reaper',
              'bin/glance-control',
              'bin/glance-manage',
              'bin/glance-registry',

=== modified file 'tools/pip-requires'
--- tools/pip-requires	2011-06-22 14:19:33 +0000
+++ tools/pip-requires	2011-07-25 22:03:31 +0000
@@ -18,3 +18,4 @@
 bzr
 httplib2
 hashlib
+xattr