Revision: 89
Author: matt
Date: 2006-08-16 04:09:12 +0000 (Wed, 16 Aug 2006)
Log Message:
-----------
Lots of luvverly plugin docs
Modified Paths:
--------------
trunk/plugins/cachecache
trunk/plugins/demo/doc_viewer
trunk/plugins/demo/serve_xslt
trunk/plugins/dir_to_xml
trunk/plugins/error_xml
trunk/plugins/request_log
trunk/plugins/serve_cgi
trunk/plugins/serve_file
trunk/plugins/stats
Modified: trunk/plugins/cachecache
===================================================================
--- trunk/plugins/cachecache 2006-08-16 03:40:24 UTC (rev 88)
+++ trunk/plugins/cachecache 2006-08-16 04:09:12 UTC (rev 89)
@@ -1,5 +1,60 @@
#!/usr/bin/perl -w
+=head1 NAME
+
+cachecache - a plugin that provides a cache API using the Cache::Cache module
+
+=head1 SYNOPSIS
+
+in axkit.conf:
+
+ Plugin cachecache
+ # mandatory:
+ CacheModule File
+ # optional:
+ CacheSize 10000
+ CacheNamespace wibble
+ CacheExpiresIn 300
+
+in your plugin:
+
+ my $cache = $self->cache();
+
+=head1 DESCRIPTION
+
+This module provides every plugin with a C<< $self->cache() >> method to access
+a cache. This could be used for storing database output, LDAP results, Session
+data, or just about any scalar.
+
+=head1 USAGE
+
+Please see L<Cache::Cache> for the API of the C<$cache> object returned. The
+construction of the cache object is done for you using the parameters specified
+in the config file.
+
+=head1 CONFIG
+
+=head2 CacheModule ( File | Memory | SharedMemory )
+
+Configures which cache module to use. The SharedMemory module doesn't make much
+sense since AxKit2 is a single process, so just use C<File> or C<Memory>.
+
+=head2 CacheSize NNN
+
+If specified, will try to use the "SizeAware" versions of the cache modules and
+specify the cache size as given (in bytes, according to the Cache::Cache docs).
+
+=head2 CacheNamespace STRING
+
+Will use a cache under the given namespace. This provides a way to separate
your
+caches on a per-application basis.
+
+=head2 CacheExpiresIn NNN
+
+Number of seconds before objects in the cache expire.
+
+=cut
+
sub init {
my $self = shift;
@@ -70,4 +125,4 @@
$self->log(LOGDEBUG, "Get cache $cachemodule with args: ", join(', ',
@args));
return $cachemodule->new([EMAIL PROTECTED]);
-}
\ No newline at end of file
+}
Modified: trunk/plugins/demo/doc_viewer
===================================================================
--- trunk/plugins/demo/doc_viewer 2006-08-16 03:40:24 UTC (rev 88)
+++ trunk/plugins/demo/doc_viewer 2006-08-16 04:09:12 UTC (rev 89)
@@ -1,5 +1,22 @@
#!/usr/bin/perl -w
+=head1 NAME
+
+doc_viewer - A pod viewer for the local AxKit2 docs
+
+=head1 SYNOPSIS
+
+ <Location /docs>
+ Plugin doc_viewer
+ </Location>
+
+=head1 DESCRIPTION
+
+This plugin uses Pod::SAX to turn the local POD docs into XML for rendering in
+the browser.
+
+=cut
+
use Pod::SAX;
use XML::LibXML::SAX::Builder;
Modified: trunk/plugins/demo/serve_xslt
===================================================================
--- trunk/plugins/demo/serve_xslt 2006-08-16 03:40:24 UTC (rev 88)
+++ trunk/plugins/demo/serve_xslt 2006-08-16 04:09:12 UTC (rev 89)
@@ -33,7 +33,6 @@
$self->log(LOGDEBUG, "Does ", $self->client->headers_in->filename, " match
$match?");
return DECLINED unless $self->client->headers_in->filename =~ /$match/;
-
my $stylefile = $self->xslt_stylesheet($self->config);
my $out = $input->transform(map XSLT($_), @$stylefile);
Modified: trunk/plugins/dir_to_xml
===================================================================
--- trunk/plugins/dir_to_xml 2006-08-16 03:40:24 UTC (rev 88)
+++ trunk/plugins/dir_to_xml 2006-08-16 04:09:12 UTC (rev 89)
@@ -1,5 +1,45 @@
#!/usr/bin/perl -w
+=head1 NAME
+
+dir_to_xml - Convert a directory request to XML
+
+=head1 SYNOPSIS
+
+ Plugin dir_to_xml
+ # optional
+ DirExternalEncoding iso-8859-1
+
+=head1 DESCRIPTION
+
+This module turns a directory request into XML so that other plugins can
+process the directory in the same way as other XML inputs.
+
+=head1 FORMAT
+
+The following is an example of the XML format to expect from this plugin:
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <filelist xmlns="http://axkit.org/2002/filelist";>
+ <directory size="4096" atime="1077320634" mtime="1077312841"
ctime="1077312841" readable="1" executable="1">.</directory>
+ <directory size="4096" atime="1077316522" mtime="1076743711"
ctime="1076743711" readable="1" executable="1">..</directory>
+ <file size="0" atime="1076770889" mtime="1076770889" ctime="1076770889"
readable="1">index.xml</file>
+ <directory size="4096" atime="1076954718" mtime="1076774280"
ctime="1076774280" readable="1" executable="1">images</directory>
+ <file size="580626" atime="1077319951" mtime="1076774007"
ctime="1076774007" readable="1">link-4.1a.tar.gz</file>
+ <file size="708" atime="1077319951" mtime="1076774018" ctime="1076774018"
readable="1" executable="1">Bender.pl</file>
+ </filelist>
+
+=head1 CONFIG
+
+=head2 DirExternalEncoding STRING
+
+File systems aren't consistent with what encodings they use to represent
+accented filenames or filenames in non-ascii encodings. In order to cope with
+these sorts of filenames you need to specify an encoding. The filenames will
+then be converted to unicode using the perl Encode module.
+
+=cut
+
use File::Spec::Functions qw(catfile);
use Encode;
Modified: trunk/plugins/error_xml
===================================================================
--- trunk/plugins/error_xml 2006-08-16 03:40:24 UTC (rev 88)
+++ trunk/plugins/error_xml 2006-08-16 04:09:12 UTC (rev 89)
@@ -1,5 +1,67 @@
#!/usr/bin/perl -w
+=head1 NAME
+
+error_xml - Convert 500 errors to XML and process through XSLT
+
+=head1 SYNOPSIS
+
+ Plugin error_xml
+ ErrorStylesheet /path/to/error.xsl
+ # optional
+ StackTrace On
+
+=head1 DESCRIPTION
+
+This plugin turns AxKit exceptions into XML structures to be transformed via
+XSLT and output to the browser. Simply specify an F<error.xsl> to transform
+with, or use the one provided with AxKit (in F<demo/error.xsl>).
+
+If you wish to include a full stack trace, add the config as listed below.
+
+Note: This plugin does add some overhead so it is suggested to only use it in
+development.
+
+=head1 FORMAT
+
+The error XML is in the following format:
+
+ <?xml version="1.0"?>
+ <error>
+ <file>./plugins/foosle</file>
+ <msg>Can't locate object method "foobar" via package
+ "AxKit2::Plugin::foosle" at ./plugins/foosle line 37.
+ </msg>
+ <stack_trace>
+ <bt level="0">
+ <package>AxKit2::Plugin::foosle</package>
+ <file>./plugins/foosle</file>
+ <line>37</line>
+ <subroutine>AxKit2::Plugin::error_xml::__ANON__(...)</subroutine>
+ </bt>
+ <bt level="1">
+ <package>AxKit2::Plugin</package>
+ <file>lib/AxKit2/Plugin.pm</file>
+ <line>35</line>
+ <subroutine>AxKit2::Plugin::foosle::hook_xmlresponse(...)</subroutine>
+ </bt>
+ ...
+ </stacktrace>
+ </error>
+
+=head1 CONFIG
+
+=head2 ErrorStylesheet STRING
+
+An XSLT stylesheet to use for transforming the error XML to HTML.
+
+=head2 StackTrace ( On | Off | 1 | 0 | Yes | No )
+
+Takes a boolean value (to the extreme!) to determine whether to include a
+stack trace in the output or not.
+
+=cut
+
sub init {
my $self = shift;
Modified: trunk/plugins/request_log
===================================================================
--- trunk/plugins/request_log 2006-08-16 03:40:24 UTC (rev 88)
+++ trunk/plugins/request_log 2006-08-16 04:09:12 UTC (rev 89)
@@ -1,5 +1,31 @@
#!/usr/bin/perl -w
+=head1 NAME
+
+request_log - Creates a request log in combined log format
+
+=head1 SYNOPSIS
+
+ Plugin request_log
+ LogFile /path/to/logfile
+
+=head1 DESCRIPTION
+
+This plugin attempts to emulate the standard apache combined log format of:
+
+ "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""
+
+Which most log parsers can cope with by default.
+
+=head1 CONFIG
+
+=head2 LogFile STRING
+
+Specifies a log file to write to. Doesn't do any log file rotation or anything
+fancy like that. Patches welcome obviously ;-)
+
+=cut
+
sub init {
my $self = shift;
Modified: trunk/plugins/serve_cgi
===================================================================
--- trunk/plugins/serve_cgi 2006-08-16 03:40:24 UTC (rev 88)
+++ trunk/plugins/serve_cgi 2006-08-16 04:09:12 UTC (rev 89)
@@ -2,42 +2,25 @@
=head1 NAME
-serve_cgi - serve up CGI scripts where appropriate
+serve_cgi - AxKit2 can do CGIs too!
-=head2 INFO
+=head1 SYNOPSIS
-Connection: close
-Date: Wed, 26 Jul 2006 20:38:41 GMT
-Server: Apache/1.3.33 (Unix) AxKit/1.7 mod_perl/1.29
-Content-Type: text/plain
-Client-Date: Wed, 26 Jul 2006 20:38:41 GMT
-Client-Peer: 127.0.0.1:80
-Client-Response-Num: 1
-Client-Transfer-Encoding: chunked
+ Plugin serve_cgi
+ CGI_Match \.(cgi|pl)$
-DOCUMENT_ROOT="/usr/local/apache/htdocs"
-GATEWAY_INTERFACE="CGI/1.1"
-HTTP_CONNECTION="TE, close"
-HTTP_HOST="localhost"
-HTTP_TE="deflate,gzip;q=0.3"
-HTTP_USER_AGENT="lwp-request/2.06"
-LD_LIBRARY_PATH="/usr/local/lib"
-PATH="/usr/lib/courier-imap/bin:/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin:/home/matt/bin"
-QUERY_STRING=""
-REMOTE_ADDR="127.0.0.1"
-REMOTE_PORT="46554"
-REQUEST_METHOD="GET"
-REQUEST_URI="/cgi-bin/printenv"
-SCRIPT_FILENAME="/usr/local/apache/cgi-bin/printenv"
-SCRIPT_NAME="/cgi-bin/printenv"
-SERVER_ADDR="127.0.0.1"
-SERVER_ADMIN="[EMAIL PROTECTED]"
-SERVER_NAME="www.sergeant.org"
-SERVER_PORT="80"
-SERVER_PROTOCOL="HTTP/1.1"
-SERVER_SIGNATURE="<ADDRESS>Apache/1.3.33 Server at www.sergeant.org Port
80</ADDRESS>\n"
-SERVER_SOFTWARE="Apache/1.3.33 (Unix) AxKit/1.7 mod_perl/1.29"
+=head1 DESCRIPTION
+This plugin makes running CGI scripts from AxKit2 possible. These get run in
the
+traditional CGI manner of forking off, so beware that they won't perform very
+well.
+
+=head1 CONFIG
+
+=head2 CGI_Match REGEXP
+
+Specify a perl regexp for files to run as CGIs. Files must also be executable.
+
=cut
sub init {
Modified: trunk/plugins/serve_file
===================================================================
--- trunk/plugins/serve_file 2006-08-16 03:40:24 UTC (rev 88)
+++ trunk/plugins/serve_file 2006-08-16 04:09:12 UTC (rev 89)
@@ -1,6 +1,30 @@
#!/usr/bin/perl -w
+=head1 NAME
+serve_file - Plugin for serving raw files
+
+=head1 SYNOPSIS
+
+ Plugin serve_file
+
+=head1 DESCRIPTION
+
+This plugin turns AxKit2 into a normal every-day httpd. Yay!
+
+Most httpds need to serve plain files. Things like favicon.ico and robots.txt
+that any sane web server would be lost without. So just load this plugin after
+all the others, and if your other plugins DECLINE to deliver the content, this
+kind little plugin will happily deliver your file without making any changes
+to it whatsoever. Ain't that nice?
+
+=head1 CONFIG
+
+None.
+
+=cut
+
+
sub hook_response {
my ($self, $hd) = @_;
Modified: trunk/plugins/stats
===================================================================
--- trunk/plugins/stats 2006-08-16 03:40:24 UTC (rev 88)
+++ trunk/plugins/stats 2006-08-16 04:09:12 UTC (rev 89)
@@ -1,5 +1,51 @@
#!/usr/bin/perl -w
+=head1 NAME
+
+stats - Default statistics plugin for the console.
+
+=head1 SYNOPSIS
+
+ ConsolePort 18000
+ Plugin stats
+
+Then:
+
+ $ telnet localhost 18000
+ > stats
+
+=head1 DESCRIPTION
+
+This module provides statistics on the server since it was last restarted.
+
+The following stats are provided:
+
+=over 4
+
+=item Uptime
+
+=item Total requests
+
+(this really counts responses - it doesn't count when the client disconnects
+before a response can be made)
+
+=item Total OK requests
+
+=item Errors
+
+=item Delivery Rate (i.e. reqs/sec)
+
+=back
+
+Note that this module isn't 'free' - it does have a minor effect on the time
+it takes to process a request.
+
+=head1 CONFIG
+
+No config.
+
+=cut
+
use Time::HiRes qw(time);
our $START_TIME = time;
@@ -11,7 +57,7 @@
my $class = shift;
my $uptime = $class->uptime;
my ($rate, $unit) = $class->delivery_rate;
- return sprintf(" Uptime: %0.2f sec\n".
+ return sprintf(" Uptime: %s\n".
" Total Requests: % 10d\n".
" OK Requests: % 10d\n".
" Errors: % 10d\n".
@@ -37,13 +83,38 @@
}
sub uptime {
- return (time() - $START_TIME);
+ my $ut = (time() - $START_TIME);
+ if ($ut > 120) {
+ my $mins = $ut / 60;
+ my $secs = $ut % 60;
+ if ($mins < 60) {
+ $ut = sprintf("%dm %0.2fs", $mins, $secs);
+ }
+ else {
+ my $hours = $mins / 60;
+ $mins = $mins % 60;
+ if ($hours < 24) {
+ $ut = sprintf("%dh %dm %0.2fs", $hours, $mins, $secs);
+ }
+ else {
+ my $days = $hours / 24;
+ $hours = $hours % 24;
+ $ut = sprintf("%dd %dh %dm %0.2fs", $days, $hours, $mins,
$secs)
+;
+ }
+ }
+ }
+ else {
+ $ut = sprintf("%0.2fs", $ut);
+ }
+
+ return $ut;
}
sub delivery_rate {
my $class = shift;
my $unit = 'sec';
- my $per_sec = ($REQS / $class->uptime());
+ my $per_sec = ($REQS / (time() - $START_TIME));
if ($per_sec > 1) {
return ($per_sec, $unit);
}
