gitweb/lib - Cache captured output (using get/set)
authorJakub Narebski <jnareb@gmail.com>
Sun, 5 Dec 2010 20:48:51 +0000 (5 21:48 +0100)
committerJakub Narebski <jnareb@gmail.com>
Sun, 5 Dec 2010 20:48:51 +0000 (5 21:48 +0100)
Add GitwebCache::CacheOutput package, which contains cache_output
subroutine.  The cache_output gets data from cache and prints it, or
captures output of provided subroutine (code reference), saves it to
cache and prints it.  It currently uses Cache::Cache compatibile (get,
set) interface to cache.  The capture_stop currently simply runs
$capture->capture_stop().

Capturing output is done using GitwebCache::Capture::Simple compatibile
capture (->new(), ->capture($code)) passed as one of parameters; the
default solution is to use GitwebCache::Capture::Simple.

Gitweb would use cache_output to get page from cache, or to generate
page and save it to cache.  The capture_stop would be used in die_error
subroutine, because error pages would not be cached.

It is assumed that data is saved to cache _converted_, and should
therefore be read from cache and printed to STDOUT in ':raw' (binary)
mode.

Add t9505/test_cache_output.pl test, run as external test in
t9505-gitweb-cache.  It checks that cache_output behaves correctly,
namely that it saves and restores action output in cache, and that it
prints generated output or cached output, depending on whether there
exist data in cache.  This test requires Capture::Tiny to be installed
(because GitwebCache::Capture::Simple dosn't support recursive
capturing).

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
gitweb/lib/GitwebCache/CacheOutput.pm [new file with mode: 0644]
t/t9505-gitweb-cache.sh [new file with mode: 0755]
t/t9505/test_cache_output.pl [new file with mode: 0755]

diff --git a/gitweb/lib/GitwebCache/CacheOutput.pm b/gitweb/lib/GitwebCache/CacheOutput.pm
new file mode 100644 (file)
index 0000000..458e314
--- /dev/null
@@ -0,0 +1,90 @@
+# gitweb - simple web interface to track changes in git repositories
+#
+# (C) 2010, Jakub Narebski <jnareb@gmail.com>
+# (C) 2006, John 'Warthog9' Hawley <warthog19@eaglescrag.net>
+#
+# This program is licensed under the GPLv2
+
+#
+# Capturing and caching (gitweb) output
+#
+
+# Capture output, save it in cache and print it, or retrieve it from
+# cache and print it.
+
+package GitwebCache::CacheOutput;
+
+use strict;
+use warnings;
+
+use Exporter qw(import);
+our @EXPORT      = qw(cache_output capture_stop);
+our %EXPORT_TAGS = (all => [ @EXPORT ]);
+
+# cache_output($cache, $capture, $key, $action_code);
+#
+# Attempts to get $key from $cache; if successful, prints the value.
+# Otherwise, calls $action_code, capture its output using $capture,
+# and use the captured output as the new value for $key in $cache,
+# then print captured output.
+#
+# It is assumed that captured data is already converted and it is
+# in ':raw' format (and thus restored in ':raw' from cache)
+
+# default capture class (engine), if none provided
+our $DEFAULT_CAPTURE_CLASS = 'GitwebCache::Capture::Simple';
+sub cache_output {
+       my ($cache, $capture, $key, $code) = @_;
+
+       $capture = setup_capture($capture);
+
+       # check if data is in the cache
+       my $data = $cache->get($key);
+
+       # capture and cache output, if there was nothing in the cache
+       if (!defined $data) {
+               $data = $capture->capture($code);
+               $cache->set($key, $data) if defined $data;
+       }
+
+       # print cached data
+       if (defined $data) {
+               binmode STDOUT, ':raw';
+               print $data;
+       }
+
+       return $data;
+}
+
+# capture_stop($cache, $capture);
+#
+# Stops capturing output; to be used in die_error, so that error pages
+# are not cached (not captured and cached).
+sub capture_stop {
+       my ($cache, $capture) = @_;
+
+       if (defined $capture) {
+               return $capture->capture_stop();
+       }
+       return;
+}
+
+# ......................................................................
+# helper subroutines
+
+# setup capture engine
+sub setup_capture {
+       my $capture = shift;
+
+       $capture ||= $DEFAULT_CAPTURE_CLASS;
+       if (!ref($capture)) {
+               eval "require $capture;" or die $@;
+               $capture = $capture->new();
+       }
+
+       return $capture;
+}
+
+1;
+__END__
+# end of package GitwebCache::CacheOutput
diff --git a/t/t9505-gitweb-cache.sh b/t/t9505-gitweb-cache.sh
new file mode 100755 (executable)
index 0000000..181577f
--- /dev/null
@@ -0,0 +1,39 @@
+#!/bin/sh
+#
+# Copyright (c) 2010 Jakub Narebski
+#
+
+test_description='gitweb cache
+
+This test checks GitwebCache::CacheOutput Perl module that is
+responsible for capturing and caching gitweb output.'
+
+# for now we are running only cache interface tests
+. ./test-lib.sh
+
+# this test is present in gitweb-lib.sh
+if ! test_have_prereq PERL; then
+       skip_all='perl not available, skipping test'
+       test_done
+fi
+
+"$PERL_PATH" -MTest::More -e 0 >/dev/null 2>&1 || {
+       skip_all='perl module Test::More unavailable, skipping test'
+       test_done
+}
+
+"$PERL_PATH" -MCapture::Tiny -e 0 >/dev/null 2>&1 || {
+       skip_all='perl module Capture::Tiny unavailable, skipping test'
+       test_done
+}
+
+# ----------------------------------------------------------------------
+
+# The external test will outputs its own plan
+test_external_has_tap=1
+
+test_external \
+       'GitwebCache::CacheOutput Perl API (in gitweb/lib/)' \
+       "$PERL_PATH" "$TEST_DIRECTORY"/t9505/test_cache_output.pl
+
+test_done
diff --git a/t/t9505/test_cache_output.pl b/t/t9505/test_cache_output.pl
new file mode 100755 (executable)
index 0000000..167bb36
--- /dev/null
@@ -0,0 +1,86 @@
+#!/usr/bin/perl
+use lib (split(/:/, $ENV{GITPERLLIB}));
+
+use warnings;
+use strict;
+
+use Test::More;
+use Capture::Tiny qw(capture);
+
+# test source version
+use lib $ENV{GITWEBLIBDIR} || "$ENV{GIT_BUILD_DIR}/gitweb/lib";
+
+# ....................................................................
+
+# prototypes must be known at compile time, otherwise they do not work
+BEGIN { use_ok('GitwebCache::CacheOutput'); }
+
+require_ok('GitwebCache::SimpleFileCache');
+require_ok('GitwebCache::Capture::Simple');
+
+diag("Using lib '$INC[0]'");
+diag("Testing '$INC{'GitwebCache/CacheOutput.pm'}'");
+diag("Testing '$INC{'GitwebCache/SimpleFileCache.pm'}'");
+diag("Testing '$INC{'GitwebCache/Capture/Simple.pm'}'");
+
+
+# Test setting up $cache and $capture
+my $cache   = new_ok('GitwebCache::SimpleFileCache' => [], 'The $cache  ');
+my $capture = new_ok('GitwebCache::Capture::Simple' => [], 'The $capture');
+
+# ......................................................................
+
+# Prepare for testing cache_output
+my $key = 'Key';
+my $action_output = <<'EOF';
+# This is data to be cached and shown
+EOF
+my $cached_output = <<"EOF";
+$action_output# (version recovered from cache)
+EOF
+sub action {
+       print $action_output;
+}
+
+my $no_capture_output = <<"EOF";
+$action_output# (no capture)
+EOF
+sub no_capture {
+       capture_stop($cache, $capture);
+       print $no_capture_output;
+}
+
+# Catch output printed by cache_fetch
+# (only for 'print <sth>' and 'printf <sth>')
+sub capture_output_of_cache_output {
+       my $code = shift;
+
+       my ($stdout, $stderr) = capture {
+               cache_output($cache, $capture, $key, $code);
+       };
+       print STDERR $stderr;
+       return $stdout;
+}
+
+# clean state
+$cache->set_expires_in(-1);
+$cache->remove($key);
+my $test_data;
+
+# first time (if there is no cache) generates cache entry
+$test_data = capture_output_of_cache_output(\&action);
+is($test_data, $action_output,        'action output is printed (generated)');
+is($cache->get($key), $action_output, 'action output is saved in cache (generated)');
+
+# second time (if cache is set/valid) reads from cache
+$cache->set($key, $cached_output);
+$test_data = capture_output_of_cache_output(\&action);
+is($test_data, $cached_output,        'action output is printed (from cache)');
+
+# test using capture_stop
+$cache->remove($key);
+$test_data = capture_output_of_cache_output(\&no_capture);
+is($test_data, $no_capture_output,    'no_capture output is printed (generated)');
+ok(! $cache->get($key),               'no_capture output is not captured and not cached');
+
+done_testing();