Ubuntu Manpage: CGI::Compress::Gzip - CGI with automatically compressed output

Provided by: libcgi-compress-gzip-perl_1.03-2_all

NAME

       CGI::Compress::Gzip - CGI with automatically compressed output

LICENSE

       Copyright 2006-2007 Clotho Advanced Media, Inc., <cpan@clotho.com>

       Copyright 2007-2008 Chris Dolan <cdolan@cpan.org>

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

SYNOPSIS

          use CGI::Compress::Gzip;

          my $cgi = new CGI::Compress::Gzip;
          print $cgi->header();
          print "<html> ...";

       See the CAVEATS section below!

DESCRIPTION

CGI::Compress::Gzip extends the CGI module to auto-detect whether the client browser wants
compressed output and, if so and if the script chooses HTML output, apply gzip compression
on any content header for STDOUT. This module is intended to be a drop-in replacement for
CGI.pm.

Apache mod_perl users may wish to consider the Apache::Compress or Apache::GzipChain
modules, which allow more transparent output compression than this module can provide.
However, as of this writing those modules are more aggressive about compressing,
regardless of Content-Type.

Headers
At the time that a header is requested, CGI::Compress::Gzip checks the
HTTP_ACCEPT_ENCODING environment variable (passed by Apache). If this variable includes
the flag "gzip" and the outgoing mime-type is "text/*", then gzipped output is preferred.
[the default mime-type selection of text/* can be changed by subclassing -- see below]
The header is altered to add the "Content-Encoding: gzip" flag which indicates that
compression is turned on.

Naturally, it is crucial that the CGI application output nothing before the header is
printed. If this is violated, things will go badly.

Compression
When the header is created, this module sets up a new filehandle to accept data. STDOUT
is redirected through that filehandle. The new filehandle passes data verbatim until it
detects the end of the CGI header. At that time, it switches over to Gzip output for the
remainder of the CGI run.

Note that the Zlib library on which this code is ultimately based requires a fileno for
the output filehandle. Where the output filehandle is faked (i.e. in mod_perl), we
instead use in-memory compression. This is more wasteful of RAM, but it is the only
solution I've found (and it is one shared by the Apache::* compression modules).

Debugging note: if you set $CGI::Compress::Gzip::global_give_reason to a true value, then
this module will add an HTTP header entry called X-non-gzip-reason with an explanation of
why it chose not to gzip the output stream.

Buffering
The Zlib library introduces latencies. In some cases, this module may delay output until
the CGI object is garbage collected, presumably at the end of the program. This buffering
can be detrimental to long-lived programs which are supposed to have incremental output,
causing browser timeouts. To compensate, compression is automatically disabled when
autoflush (i.e. the $| variable) is set to true. Future versions may try to enable
autoflushing on the Zlib filehandles, if possible [Help wanted].

CLASS METHODS

       $pkg->new([CGI ARGS])
           Create a new object.  This resets the environment before creating a CGI.pm object.
           This should not be called more than once per script run!  All arguments are passed to
           the parent class.

       $pkg->useCompression($boolean)
       $self->useCompression($boolean)
           This can be used as a class method or an instance method.  The former is included for
           backward compatibility, and is NOT recommended.  As a class method, this changes the
           default value.  As an instance method it affects only the specified instance.

           Turn compression on/off for the target.  If turned on, compression will be used only
           if the prerequisite compression libraries are available and if the client browser
           requests compression.

           Defaults to on.

INSTANCE METHODS

       $self->useFileHandle($filehandle)
           Manually set the output filehandle.  Because of limitations of Zlib, this MUST be a
           real filehandle (with valid results from fileno()) and not a pseudo filehandle like
           IO::String.

           If this is not set, STDOUT is used.

       $self->isCompressibleType($content_type)
           Given a MIME type (with possible charset attached), return a boolean indicating if
           this media type is a good candidate for compression.  This implementation is simply:

               return $type =~ /^text\//;

           Subclasses may wish to override this method to apply different criteria.

       $self->header([HEADER ARGS])
           Overrides the "header()" method in CGI.

           Return a CGI header with the compression flags set properly.  Returns an empty string
           is a header has already been printed.

           This method engages the Gzip output by fiddling with the default output filehandle.
           All subsequent output via usual Perl print() will be automatically gzipped except for
           this header (which must go out as plain text).

           Any arguments will be passed on to CGI::header.  This method should NOT be called if
           you don't want your header or STDOUT to be fiddled with.

       $self->DESTROY()
           Override the CGI destructor so we can close the Gzip output stream, if there is one
           open.

CAVEATS

   Apache::Registry
       Under Apache::Registry, global variables may not go out of scope in time.  This may causes
       timing bugs, since this module makes use of the DESTROY() method.  To avoid this issue,
       make sure your CGI object is stored in a scoped variable.

          # BROKEN CODE
          use CGI::Compress::Gzip;
          $q = CGI::Compress::Gzip->new;
          print $q->header;
          print "Hello, world\n";

          # WORKAROUND CODE
          use CGI::Compress::Gzip;
          do {
            my $q = CGI::Compress::Gzip->new;
            print $q->header;
            print "Hello, world\n";
          }

   Filehandles
       This module works by changing the default filehandle.  It does not change STDOUT at all.
       As a consequence, your programs should call "print" without a filehandle argument.

          # BROKEN CODE
          use CGI::Compress::Gzip;
          my $q = CGI::Compress::Gzip->new;
          print STDOUT $q->header;
          print STDOUT "Hello, world\n";

          # WORKAROUND CODE
          use CGI::Compress::Gzip;
          my $q = CGI::Compress::Gzip->new;
          print $q->header;
          print "Hello, world\n";

       Future versions may steal away STDOUT and replace it with the compression filehandle, but
       that seemed too risky for this version.

   Header Munging
       When sending compressed output, the HTTP headers must remain uncompressed.  So, this
       module goes to great effort to keep the headers and body separate.  That has led to
       CGI::header() emulation code that is a little brittle.  Most potential problems arise
       because STDOUT gets tweaked as soon as header() is called.

       If you use the CGI.pm header() API as specified in CGI.pm, then all should go well.  But
       if you do anything unusual, this module may break.  For example:

          # BROKEN CODE
          use CGI::Compress::Gzip;
          my $q = CGI::Compress::Gzip->new;
          print "Set-Cookie: foo=bar\n" . $q->header;
          print "Hello, world\n";

          # WORKAROUND 1 (preferred)
          use CGI::Compress::Gzip;
          my $q = CGI::Compress::Gzip->new;
          print $q->header("-Set_Cookie" => "foo=bar");
          print "Hello, world\n";

          # WORKAROUND 2
          use CGI::Compress::Gzip;
          my $q = CGI::Compress::Gzip->new;
          print "Set-Cookie: foo=bar\n";
          print $q->header;
          print "Hello, world\n";

       Future versions could try to parse the header to look for its end rather than insisting
       that the printed version match the version returned by header().  Patches would be very
       welcome.

AUTHOR

       Chris Dolan

       This module was originally developed by me at Clotho Advanced Media Inc.  Now I maintain
       it in my spare time.

ACKNOWLEDGMENTS

       Clotho greatly appreciates the assistance and feedback the community has extended to help
       refine this module.

       Thanks to Rhesa Rozendaal who noticed the -Type omission in v0.17.

       Thanks to Laga Mahesa who did some Windows testing and experimentation.

       Thanks to Slaven Rezic who 1) found several header handling bugs, 2) discovered the
       Apache::Registry and Filehandle caveats, 3) provided a patch incorporated into v0.17, and
       4) persisted with smoke tests that reproduced the envvar problem fixed in v0.23.

       Thanks to Jan Willamowius who found a header handling bug.

       Thanks to Andreas J. Koenig and brian d foy for module naming advice.

HELP WANTED

       If you like this module, please help by testing on Windows or in a "FastCGI" environment,
       since I have neither available for easy testing.

       Personally, I don't use this module much anymore as all of my work is on Catalyst and
       mod_perl now.