Preventing Multiple Server Calls

  The initial idea for Image::Delivery was due to some problems with
  the design of CVS Monitor (L<http://ali.as/devel/cvsmonitor/), an advanced
  but extremely resource-hungry MVC CGI application. Many of the CVS Monitor
  views have a single large graph on them, which involves a second call to the
  server that starts just before the previous call ends. Generating the graph
  took minimal extra effort, but the overhead of starting another process and
  loading another 100meg of data creates a double whammy hit to the server.
  
  What would be ideal would be to generate both at once and have the browser
  get the image without a CGI hit.

The solution to this problem, and the primary mechanism that Image::Delivery implements could be called "Static Delivery via Cached Disk", but is best demonstrated with the diagram outlined in General Structure below.

Use Case 2: Thumbnails

  One problem with thumbnailing is the vast number that need to be generated.
  When done on demand, if generated by the image request, you will have large
  numbers of processes working. The normal solution is to pre-generate the
  thumbnails, potentially polluting image directories.

Image::Delivery stores all images in one central cache, so that the original images are unaffected.

General Structure

    Image Provider
      |
      |BLOB + TransformPath
      |
     \1/
    Image::Delivery
      |           \
      |            |
      |            |
     \2/           |
  Hard Disk        |
  /5\     |        |URI
   |      |        |
   |      |        |
   |     \6/       |
  Web Server       | 
   /4\    |       /
    |     |gzip  /
     \    |     / 
      \  \7/  \3/
      Web Browser

1) Image Data pulled from Object/Provider

An Object, or a Provider that accesses the data from outside the API, generates or obtains the image data and various metadata that describes the image data.

2) Image Written to File-System

Image::Delivery writes the image to the filesystem with a specific file name

3) URI sent to Browser in HTML

Image::Delivery determines the matching URI that points to the location of the written file, and provides it to be used in an "img" tag in the generated HTML page.

4) Web Browser Requests Image

Having received the HTML, the browser requests the image from the web server.

5) Web Server Finds Image File

The web server receives the image request and finds the file that was written at step 2)

6) Web Server Retrieves Image File

Web server reads the file like any other plain file

7) Web Server Sends File to Browser

Web server sends the file off to the browser

Digest::TransformPath

To handle this, we utilise (or SHOULD utilise) Digest::TransformPath to help identify the images, with a 10 digit digest built into the filename.

Might as Well Cache Them

Image::Delivery Naming Scheme

The basic path format is:

  $ROOT/Object.id/checksum.type

Object.id

When an object is updated, it may have any number of Image fields, which may each have any number of scaled/rotated/morphed/derived images. When a source object is updated, some or all of these need to be cleared.

checksum

The checksum calculated from the TransformPath does not describe any of the data, only the data source and modifications to it. This means that it is possible to cheaply test if the image for a particular transform has already been created, without having to access any of the data in the actual images.

type

Because we accept image data in a variety of formats, its not possible to know what image type any given image should be. So when testing we simply check the lot until we find one.

Generally, rather than test 10-15 types, the Provider will inform us of the types to expect. :)

Operation Profile

- Intrinsicaly supports all major image types

- No pre-generation of images, generates everything on-the-fly

- Image names are secure and can't be predicted

- All images for any page are processed in one process hit

- Cache checking is extremely quick

- Never touches image source data when not filling the cache

- Handles many images. Storage extendable to support thousands to millions of individual images

- Multiple hosts can work with the same Image cache

- Images can be delivered by a different web server to the application

Setting up the URI <-> path mapping

You should also make sure that whatever process will be running will have write permissions to the appropriate directory.

For starters, we would suggest creating the cache directory just under the root of a website, at "$ROOT/cache", which will be linked to "http://yourwebsite.com/cache/".

This will let you create your HTML::Location.

  # Set up the location of the cache
  my $Location = HTML::Location->new(
      "$ROOT/cache",
      "http://yourwebsite.com/cache"
      );

This gives you the absolute minimum Image::Delivery itself needs to get rolling. With a location to manage, you can then start to fire images at it, and it will store them and hand you back a HTML::Location for the actual file.

  # Create the Image::Delivery object
  my $Delivery = Image::Delivery->new(
        Location => $Location,
        );

However, the tricky bit is probably setting up your Provider class. Although the abstract class implements much of the details and defaults for you, you are probably still going to need to do some work to tie the two together.

new %params

Location

The required Location parameter

Location

filename $TransformPath | $Provider

This is the method most likely to be overloaded, so enable a different naming scheme.

exists $TransformPath | $Provider

Returns the HTML::Location of the image if it exists, false if it does not exist, or "undef" on error.

get $TransformPath | $Provider

Returns a reference to a SCALAR containing the image data if the image exists. Returns "undef" if the image does not exist, or some other error occurs.

set $Provider

Returns the HTML::Location of the stored image on success, or "undef" on error.

clear $TransformPath

Returns true if the image was removed, or did not exist. Returns "undef" on error.