general/lastmodified2

   1 # Blosxom Plugin: lastmodified2
   2 # Author(s): Frank Hecker <hecker@hecker.org>
   3 # (based on work by Bob Schumaker <cobblers@pobox.com>)
   4 # Version: 0.10
   5 # Documentation: See the bottom of this file or type: perldoc lastmodified2
   6
   7 package lastmodified2;
   8
   9 use strict;
  10
  11 use HTTP::Date;
  12 use Data::Dumper;
  13 use POSIX qw! strftime !;
  14
  15 # Use the Digest:MD5 module if available, the older MD5 module if not.
  16
  17 my $use_digest;
  18 my $use_just_md5;
  19
  20 BEGIN {
  21     if (eval "require Digest::MD5") {
  22         Digest::MD5->import();
  23         $use_digest = 1;
  24     }
  25     elsif (eval "require MD5") {
  26         MD5->import();
  27         $use_just_md5 = 1;
  28     }
  29 }
  30
  31 # --- Package variables -----
  32
  33 my $current_time = time();              # Use consistent value of current time.
  34 my $last_modified_time = 0;
  35 my $etag = "";
  36 my $md5_digest = "";
  37 my %validator;
  38
  39 # --- Output variables -----
  40
  41 our $latest_rfc822 = '';
  42 our $latest_iso8601 = '';
  43
  44 our $others_rfc822 = '';
  45 our $others_iso8601 = '';
  46
  47 our $now_rfc822 = '';
  48 our $now_iso8601 = '';
  49
  50 our $story_rfc822 = '';
  51 our $story_iso8601 = '';
  52
  53 # --- Configurable variables -----
  54
  55 my $generate_etag = 1;                  # generate ETag header?
  56
  57 my $generate_mod = 1;                   # generate Last-modified header?
  58
  59 my $strong = 0;                         # do strong validation?
  60
  61 my $val_cache = "validator.cache";      # where to cache last-modified values
  62                                         # and MD5 digests (in state directory)
  63
  64 my $generate_expires = 0;               # generate Expires header?
  65
  66 my $generate_cache = 0;                 # generate Cache-control header?
  67
  68 my $freshness_time = 3000;              # number of seconds pages are fresh
  69                                         # (0 = do not cache, max is 1 year)
  70
  71 my $generate_length = 1;                # generate Content-length header?
  72
  73 my $use_others = 0;                     # consult %others for weak validation
  74                                         # (DEPRECATED)
  75
  76 my $export_dates = 1;                   # set $latest_rfc822, etc., for
  77                                         # compatibility with lastmodified
  78
  79 my $debug = 0;                          # set > 0 for debug output
  80
  81 # --------------------------------
  82
  83
  84 # Do any initial processing, and decide whether to activate the plugin.
  85
  86 sub start {
  87     warn "lastmodified2: start\n" if $debug > 1;
  88
  89     # Don't activate this plugin if we are doing static page generation.
  90
  91     return 0 if $blosxom::static_or_dynamic eq 'static';
  92
  93     # If we can't do MD5 then we don't do strong validation.
  94
  95     if ($strong && !($use_digest || $use_just_md5)) {
  96         $strong = 0;
  97
  98         warn "lastmodified2: MD5 not available, forcing weak validation\n"
  99             if $debug > 0;
 100     }
 101
 102     # Limit freshness time to maximum of one year, must be non-negative.
 103
 104     $freshness_time > 365*24*3600 and $freshness_time = 365*24*3600;
 105     $freshness_time < 0 and $freshness_time = 0;
 106
 107     if ($debug > 1) {
 108         warn "lastmodified2: \$generate_etag = $generate_etag\n";
 109         warn "lastmodified2: \$generate_mod = $generate_mod\n";
 110         warn "lastmodified2: \$strong = $strong\n";
 111         warn "lastmodified2: \$generate_cache = $generate_cache\n";
 112         warn "lastmodified2: \$generate_expires = $generate_expires\n";
 113         warn "lastmodified2: \$freshness_time = $freshness_time\n";
 114         warn "lastmodified2: \$generate_length = $generate_length\n";
 115     }
 116
 117     # If we are using Last-modified as a strong validator then read
 118     # in the cached last-modified values and MD5 digests.
 119
 120     if ($generate_mod && $strong &&
 121         open CACHE, "<$blosxom::plugin_state_dir/$val_cache" ) {
 122
 123         warn "lastmodified2: loading cached validators\n" if $debug > 0;
 124
 125         my $index = join '', <CACHE>;
 126         close CACHE;
 127
 128         my $VAR1;
 129         $index =~ m!\$VAR1 = \{!
 130             and eval($index) and !$@ and %validator = %$VAR1;
 131     }
 132
 133     # Convert current time to RFC 822 and ISO 8601 formats for others' use.
 134
 135     if ($export_dates && $current_time) {
 136         $now_rfc822 = HTTP::Date::time2str($current_time);
 137         $now_iso8601 = iso8601($current_time);
 138     }
 139
 140     return 1;
 141 }
 142
 143
 144 # We check the list of entries to be displayed and determine the modification
 145 # time of the most recent entry.
 146
 147 sub filter {
 148     my ($pkg, $files, $others) = @_;
 149
 150     warn "lastmodified2: filter\n" if $debug > 1;
 151
 152     # We can skip all this unless we're doing weak validation and/or we're
 153     # setting the *_rfc822 and *_iso8601 variables for others to use.
 154
 155     return 1 unless $export_dates ||
 156         (($generate_etag || $generate_mod) && !$strong);
 157
 158     # Find the latest date/time modified for the entries to be displayed.
 159
 160     $last_modified_time = 0;
 161     for (values %$files) {
 162         $_ > $last_modified_time and $last_modified_time = $_;
 163     }
 164
 165     warn "lastmodified2: \$last_modified_time = " .
 166         $last_modified_time . " (entries)\n" if $debug > 0;
 167
 168     # Convert last modified time to RFC 822 and ISO 8601 formats for others.
 169
 170     if ($export_dates && $last_modified_time) {
 171         $latest_rfc822 = HTTP::Date::time2str($last_modified_time);
 172         $latest_iso8601 = iso8601($last_modified_time);
 173     }
 174
 175     # Optionally look at other files as well (DEPRECATED).
 176
 177     if ($use_others) {
 178         my $others_last_modified_time = 0;
 179         for (values %$others) {
 180             $_ > $others_last_modified_time
 181                 and $others_last_modified_time = $_;
 182         }
 183
 184         if ($export_dates && $others_last_modified_time) {
 185             $others_rfc822 = HTTP::Date::time2str($others_last_modified_time);
 186             $others_iso8601 = iso8601($others_last_modified_time);
 187         }
 188
 189         warn "lastmodified2: \$others_last_modified_time = " .
 190             $others_last_modified_time . " (others)\n" if $debug > 0;
 191
 192         $others_last_modified_time > $last_modified_time
 193             and $last_modified_time = $others_last_modified_time;
 194     }
 195
 196     # If we're doing weak validation then create an etag based on the latest
 197     # date/time modified and mark it as weak (i.e., by prefixing it with 'W/').
 198
 199     if ($generate_etag && !$strong) {
 200         $etag = 'W/"' . $last_modified_time . '"';
 201
 202         warn "lastmodified2: \$etag = $etag\n" if $debug > 0;
 203     }
 204
 205     return 1;
 206 }
 207
 208
 209 # Skip story processing and generate configured headers now on a conditional
 210 # GET request for which we don't need to return a full response.
 211
 212 sub skip {
 213     warn "lastmodified2: skip\n" if $debug > 1;
 214
 215     # If we are doing strong validation then we can't skip story processing
 216     # because we need all output in order to generate the proper etag and/or
 217     # last-modified value.
 218
 219     return 0 unless ($generate_etag || $generate_mod) && !$strong;
 220
 221     # Otherwise we can check here whether we can send a 304 or not.
 222
 223     my $send_304 = check_for_304();
 224
 225     # If we don't need to return a full response on a conditional GET then
 226     # set the HTTP status to 304 and generate headers as configured.
 227     # (We have to do this here because the last subroutine won't be executed
 228     # if we skip story processing.)
 229
 230     add_headers($send_304) if $send_304;
 231
 232     return $send_304;
 233 }
 234
 235
 236 # Set variables with story date/time in RFC 822 and ISO 8601 formats.
 237
 238 sub story {
 239     my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
 240
 241     warn "lastmodified2: story (\$path = $path, \$filename = $filename)\n"
 242         if $debug > 1;
 243
 244     if ($export_dates) {
 245         $path ||= "";
 246
 247         my $timestamp =
 248             $blosxom::files{"$blosxom::datadir$path/$filename.$blosxom::file_extension"};
 249
 250         warn "lastmodified2: \$timestamp = $timestamp\n" if $debug > 0;
 251
 252         $story_rfc822 = $timestamp ? HTTP::Date::time2str($timestamp) : '';
 253         $story_iso8601 = $timestamp ? iso8601($timestamp) : '';
 254     }
 255
 256     return 1;
 257 }
 258
 259
 260 # Do conditional GET checks if we couldn't do them before (i.e., we are
 261 # doing strong validation and couldn't skip story processing) and output
 262 # any configured headers plus a 304 status if appropriate.
 263
 264 sub last {
 265     warn "lastmodified2: last\n" if $debug > 1;
 266
 267     # If some other plugin has set the HTTP status to a non-OK value then we
 268     # don't attempt to do anything here, since it would probably be wrong.
 269
 270     return 1 if $blosxom::header->{'Status'} &&
 271         $blosxom::header->{'Status'} !~ m!^200 !;
 272
 273     # If we are using ETag and/or Last-modified as a strong validator then
 274     # we generate an entity tag from the MD5 message digest of the complete
 275     # output. (We use the base-64 representation if possible because it is
 276     # more compact than hex and hence saves a few bytes of bandwidth.)
 277
 278     if (($generate_etag || $generate_mod) && $strong) {
 279         $md5_digest =
 280             $use_digest ? Digest::MD5::md5_base64($blosxom::output)
 281                         : MD5->hex_hash($blosxom::output);
 282         $etag = '"' . $md5_digest . '"';
 283
 284         warn "lastmodified2: \$etag = $etag\n" if $debug > 0;
 285     }
 286
 287     # If we are using Last-modified as a strong validator then we look up
 288     # the cached MD5 digest for this URI, compare it to the current digest,
 289     # and use the cached last-modified value if they match. Otherwise we set
 290     # the last-modified value to just prior to the current time.
 291
 292     my $cache_tag = cache_tag();
 293     my $update_cache = 0;
 294
 295     if ($generate_mod && $strong) {
 296         if ($validator{$cache_tag} &&
 297             $md5_digest eq $validator{$cache_tag}{'md5'}) {
 298             $last_modified_time = $validator{$cache_tag}{'last-modified'};
 299         } else {
 300             $last_modified_time = $current_time - 5;
 301             $validator{$cache_tag}{'last-modified'} = $last_modified_time;
 302             $validator{$cache_tag}{'md5'} = $md5_digest;
 303             $update_cache = 1;
 304         }
 305
 306         warn "lastmodified2: \$last_modified_time = $last_modified_time\n"
 307             if $debug > 0;
 308
 309     }
 310
 311     # Do conditional GET checks and output configured headers plus status.
 312
 313     my $send_304 = check_for_304();
 314     add_headers($send_304);
 315
 316     # Update the validator cache if we need to. To minimize race conditions
 317     # we write the cache as a temporary file and then rename it.
 318
 319     if ($update_cache) {
 320         warn "lastmodified2: updating validator cache\n" if $debug > 0;
 321
 322         my $tmp_cache = "$val_cache-$$-$current_time";
 323
 324         if (open CACHE, ">$blosxom::plugin_state_dir/$tmp_cache") {
 325             print CACHE Dumper \%validator;
 326             close CACHE;
 327
 328             warn "lastmodified2: renaming $tmp_cache to $val_cache\n"
 329                 if $debug > 1;
 330
 331             rename("$blosxom::plugin_state_dir/$tmp_cache",
 332                    "$blosxom::plugin_state_dir/$val_cache")
 333                 or warn "couldn't rename $blosxom::plugin_state_dir/$tmp_cache: $!\n";
 334         } else {
 335             warn "couldn't > $blosxom::plugin_state_dir/$tmp_cache: $!\n";
 336         }
 337     }
 338
 339     1;
 340 }
 341
 342
 343 # Check If-none-match and/or If-modified-since headers and return true if
 344 # we can send a 304 (not modified) response instead of a normal response.
 345
 346 sub check_for_304 {
 347     my $etag_send_304 = 0;
 348     my $mod_send_304 = 0;
 349     my $etag_request = 0;
 350     my $mod_request = 0;
 351     my $send_304 = 0;
 352
 353     warn "lastmodified2: check_for_304\n" if $debug > 1;
 354
 355     # For a conditional GET using the If-none-match header, compare the
 356     # ETag value(s) in the header with the ETag value generated for the page,
 357     # set $etag_send_304 true if we don't need to send a full response,
 358     # and note that an etag value was included in the request.
 359
 360     if ($ENV{'HTTP_IF_NONE_MATCH'}) {
 361         $etag_request = 1;
 362         if ($generate_etag) {
 363             my @inm_etags = split '\s*,\s*', $ENV{'HTTP_IF_NONE_MATCH'};
 364
 365             if ($debug > 0) {
 366                 for (@inm_etags) {
 367                     warn "lastmodified2: \$inm_etag = |" . $_ . "|\n";
 368                 }
 369             }
 370
 371             for (@inm_etags) {
 372                 $etag eq $_ and $etag_send_304 = 1 and last;
 373             }
 374         }
 375     }
 376
 377     # For a conditional GET using the If-modified-since header, compare the
 378     # time in the header with the time any entry on the page was last modified,
 379     # set $mod_send_304 true if we don't need to send a full response, and
 380     # also note that a last-modified value was included in the request.
 381
 382     if ($ENV{'HTTP_IF_MODIFIED_SINCE'}) {
 383         $mod_request = 1;
 384         if ($generate_mod) {
 385             my $ims_time =
 386                 HTTP::Date::str2time($ENV{'HTTP_IF_MODIFIED_SINCE'});
 387
 388             warn "lastmodified2: \$ims_time = " . $ims_time . "\n"
 389                 if $debug > 0;
 390
 391             $mod_send_304 = 1 if $last_modified_time <= $ims_time;
 392         }
 393     }
 394
 395     # If the request includes both If-none-match and If-modified-since then
 396     # we don't send a 304 response unless both tests agree it should be sent,
 397     # per section 13.3.4 of the HTTP 1.1 specification.
 398
 399     if ($etag_request && $mod_request) {
 400         $send_304 = $etag_send_304 && $mod_send_304;
 401     } else {
 402         $send_304 = $etag_send_304 || $mod_send_304;
 403     }
 404
 405     warn "lastmodified2: \$send_304 = " . $send_304 .
 406             " \$etag_send_304 = " . $etag_send_304 .
 407             " \$mod_send_304 = " . $mod_send_304 . "\n"
 408         if $debug > 0;
 409
 410     return $send_304;
 411 }
 412
 413
 414 # Set status and add additional header(s) depending on the type of response.
 415
 416 sub add_headers {
 417     my ($send_304) = @_;
 418
 419     warn "lastmodified2: add_headers (\$send_304 = $send_304)\n"
 420         if $debug > 1;
 421
 422     # Set HTTP status and truncate output if we are sending a 304 response.
 423
 424     if ($send_304) {
 425         $blosxom::header->{'Status'} = "304 Not Modified";
 426         $blosxom::output = "";
 427
 428         warn "lastmodified2: Status: " .
 429             $blosxom::header->{'Status'} . "\n" if $debug > 0;
 430     }
 431
 432     # For the rules on what headers to generate for a 304 response, see
 433     # section 10.3.5 of the HTTP 1.1 protocol specification.
 434
 435     # Last-modified is not returned on a 304 response.
 436
 437     if ($generate_mod && !$send_304) {
 438         $blosxom::header->{'Last-modified'} =
 439             HTTP::Date::time2str($last_modified_time);
 440
 441         warn "lastmodified2: Last-modified: " .
 442             $blosxom::header->{'Last-modified'} . "\n" if $debug > 0;
 443     }
 444
 445     # If we send ETag on a 200 response then we send it on a 304 as well.
 446
 447     if ($generate_etag) {
 448         $blosxom::header->{'ETag'} = $etag;
 449
 450         warn "lastmodified2: ETag: " .
 451             $blosxom::header->{'ETag'} . "\n" if $debug > 0;
 452     }
 453
 454     # We send Expires for a 304 since its value is updated for each request.
 455
 456     if ($generate_expires) {
 457         $blosxom::header->{'Expires'} = $freshness_time ?
 458             HTTP::Date::time2str($current_time + $freshness_time) :
 459             HTTP::Date::time2str($current_time - 60);
 460
 461         warn "lastmodified2: Expires: " .
 462             $blosxom::header->{'Expires'} . "\n" if $debug > 0;
 463     }
 464
 465     # We send Cache-control for a 304 response for consistency with Expires.
 466
 467     if ($generate_cache) {
 468         $blosxom::header->{'Cache-control'} =
 469             $freshness_time ? "max-age=" . $freshness_time
 470                             : "no-cache";
 471
 472         warn "lastmodified2: Cache-control: " .
 473             $blosxom::header->{'Cache-control'} . "\n" if $debug > 0;
 474     }
 475
 476     # Content-length is not returned on a 304 response.
 477
 478     if ($generate_length && !$send_304) {
 479         $blosxom::header->{'Content-length'} = length($blosxom::output);
 480
 481         warn "lastmodified2: Content-length: " .
 482             $blosxom::header->{'Content-length'} . "\n" if $debug > 0;
 483     }
 484 }
 485
 486
 487 # Generate a tag to look up the cached last-modified value and MD5 digest
 488 # for this URI.
 489
 490 sub cache_tag {
 491     # Start with the original URI from the request.
 492
 493     my $tag = $ENV{REQUEST_URI} || "";
 494
 495     # Add an "/index.flavour" for uniqueness unless it's already present.
 496
 497     unless ($tag =~ m!/index\.!) {
 498         $tag .= '/' unless ($tag =~ m!/$!);
 499         $tag .= "index.$blosxom::flavour";
 500     }
 501
 502     return $tag;
 503 }
 504
 505
 506 # Convert time to ISO 8601 format (including time zone offset).
 507 # (Format is YYYY-MM-DDThh:mm:ssTZD per http://www.w3.org/TR/NOTE-datetime)
 508
 509 sub iso8601 {
 510     my ($timestamp) = @_;
 511     my $tz_offset = strftime("%z", localtime());
 512     $tz_offset = substr($tz_offset, 0, 3) . ":" . substr($tz_offset, 3, 5);
 513     return strftime("%Y-%m-%dT%T", localtime($timestamp)) . $tz_offset;
 514 }
 515
 516
 517 1;
 518
 519 __END__
 520
 521 =head1 NAME
 522
 523 Blosxom Plug-in: lastmodified2
 524
 525 =head1 SYNOPSIS
 526
 527 Enables caching and validation of dynamically-generated Blosxom pages
 528 by generating C<ETag>, C<Last-modified>, C<Cache-control>, and/or
 529 C<Expires> HTTP headers in the response and responding appropriately
 530 to an C<If-none-match> and/or C<If-modified-since> header in the
 531 request. Also generates a C<Content-length> header to support HTTP 1.0
 532 persistent connections.
 533
 534 =head1 VERSION
 535
 536 0.10
 537
 538 =head1 AUTHOR
 539
 540 Frank Hecker <hecker@hecker.org>, http://www.hecker.org/ (based on
 541 work by Bob Schumaker, <cobblers@pobox.com>, http://www.cobblers.net/blog/)
 542
 543 =head1 DESCRIPTION
 544
 545 This plugin enables caching and validation of dynamically-generated
 546 Blosxom pages by web browsers, web proxies, feed aggregators, and
 547 other clients by generating various cache-related HTTP headers in the
 548 response and supporting conditional GET requests, as described
 549 below. This can reduce excess network traffic and server load caused
 550 by requests for RSS or Atom feeds or for web pages for popular entries
 551 or categories.
 552
 553 =head1 INSTALLATION AND CONFIGURATION
 554
 555 Copy this plugin into your Blosxom plugin directory. You should not
 556 normally need to rename the plugin; however see the discussion below.
 557
 558 Configurable variables specify how the plugin handles validation
 559 (C<$generate_etag>, C<$generate_mod>, and C<$strong>), caching
 560 (C<$generate_cache>, C<$generate_expires>, and C<$freshness_time>) and
 561 whether or not to generate any other recommended headers
 562 (C<$generate_length>). The plugin supports the variable C<$use_others>
 563 as used in the lastmodified plugin; however use of this is deprecated
 564 (use strong validation instead). The variable C<$export_dates>
 565 specifies whether to export date/time variables C<$latest_rfc822>,
 566 etc., for compatibility with the lastmodified plugin.
 567
 568 You can set the variable C<$debug> to 1 or greater to produce
 569 additional information useful in debugging the operation of the
 570 plugin; the debug output is sent to your web server's error log.
 571
 572 This plugin supplies C<filter>, C<skip>, and C<last> subroutines. It
 573 needs to run after any other plugin whose C<filter> subroutine changes
 574 the list of entries included in the response; otherwise the
 575 C<Last-modified> date may be computed incorrectly. It needs to run
 576 after any other plugin whose C<skip> subroutine does redirection
 577 (e.g., the canonicaluri plugin) or otherwise conditionally sets the
 578 HTTP status to any value other than 200. Finally, this plugin needs to
 579 run after any other plugin whose C<last> subroutine changes the output
 580 for the page; otherwise the C<Content-length> value (and the C<ETag>
 581 and C<Last-modified> values, if you are using strong validation) may
 582 be computed incorrectly. If you are encountering problems in any of
 583 these regards then you can force the plugin to run after other plugins
 584 by renaming it to, e.g., 99lastmodified2.
 585
 586 =head1 SEE ALSO
 587
 588 Blosxom Home/Docs/Licensing: http://blosxom.sourceforge.net/
 589
 590 Blosxom Plugin Docs: http://blosxom.sourceforge.net/documentation/users/plugins.html
 591
 592 lastmodified plugin: http://www.cobblers.net/blog/dev/blosxom/
 593
 594 more on the lastmodified2 plugin: http://www.hecker.org/blosxom/lastmodified2
 595
 596 =head1 BUGS
 597
 598 None known; please send bug reports and feedback to the Blosxom
 599 development mailing list <blosxom-devel@lists.sourceforge.net>.
 600
 601 =head1 AUTHOR
 602
 603 Frank Hecker <hecker@hecker.org> http://www.hecker.org/
 604
 605 Based on the original lastmodified plugin by Bob Schumaker
 606 <cobblers@pobox.com> http://www.cobblers.net/blog
 607
 608 This plugin is now maintained by the Blosxom Sourceforge Team,
 609 <blosxom-devel@lists.sourceforge.net>.
 610
 611 =head1 LICENSE
 612
 613 This source code is submitted to the public domain.  Feel free to use
 614 and modify it.  If you like, a comment in your modified source
 615 attributing credit to myself, Bob Schumaker, and any other
 616 contributors for our work would be appreciated.
 617
 618 THIS SOFTWARE IS PROVIDED AS IS AND WITHOUT ANY WARRANTY OF ANY KIND.
 619 USE AT YOUR OWN RISK!