| 1 | ##-*- Mode: CPerl -*- | ||
| 2 | |||
| 3 | ## File: DTA::CAB::Server::HTTP::Handler.pm | ||
| 4 | ## Author: Bryan Jurish <moocow@cpan.org> | ||
| 5 | ## Description: | ||
| 6 | ## + abstract handler API class for DTA::CAB::Server::HTTP | ||
| 7 | ##====================================================================== | ||
| 8 | |||
| 9 | package DTA::CAB::Server::HTTP::Handler; | ||
| 10 | use HTTP::Status; | ||
| 11 | use DTA::CAB::Logger; | ||
| 12 | use DTA::CAB::Utils qw(:xml); | ||
| 13 | use UNIVERSAL; | ||
| 14 | use strict; | ||
| 15 | |||
| 16 | BEGIN { | ||
| 17 | *isa = \&UNIVERSAL::isa; | ||
| 18 | *can = \&UNIVERSAL::can; | ||
| 19 | } | ||
| 20 | |||
| 21 | our @ISA = qw(DTA::CAB::Logger); | ||
| 22 | |||
| 23 | ##====================================================================== | ||
| 24 | ## API | ||
| 25 | ##====================================================================== | ||
| 26 | |||
| 27 | ## $h = $class_or_obj->new(%options) | ||
| 28 | sub new { | ||
| 29 | my $that = shift; | ||
| 30 | return bless { @_ }, ref($that)||$that; | ||
| 31 | } | ||
| 32 | |||
| 33 | ## $bool = $h->prepare($server,$path) | ||
| 34 | sub prepare { return 1; } | ||
| 35 | |||
| 36 | ## $rsp = $h->run($server, $localPath, $clientConn, $httpRequest) | ||
| 37 | ## + perform local processing | ||
| 38 | ## + should return a HTTP::Response object to pass to the client | ||
| 39 | ## + if the call die()s or returns undef, an error response will be | ||
| 40 | ## sent to the client instead if it the connection is still open | ||
| 41 | ## + this method may return the data to the client itself; if so, | ||
| 42 | ## it should close the client connection ($csock->shutdown(2); $csock->close()) | ||
| 43 | ## and return undef to prevent bogus error messages. | ||
| 44 | sub run { | ||
| 45 | my ($h,$srv,$path,$csock,$hreq) = @_; | ||
| 46 | $h->logdie("run() method not implemented"); | ||
| 47 | } | ||
| 48 | |||
| 49 | ## undef = $h->finish($server, $clientConn) | ||
| 50 | ## + clean up handler state after run() | ||
| 51 | ## + default implementation does nothing | ||
| 52 | sub finish { | ||
| 53 | return; | ||
| 54 | } | ||
| 55 | |||
| 56 | ##====================================================================== | ||
| 57 | ## Generic Utilities | ||
| 58 | |||
| 59 | ## $rsp = $CLASS_OR_OBJECT->response($code=RC_OK, $msg=status_message($code), $hdr, $content) | ||
| 60 | ## + $hdr may be a HTTP::Headers object, an array or hash-ref | ||
| 61 | ## + wrapper for HTTP::Response->new() | ||
| 62 | sub response { | ||
| 63 | my $h = shift; | ||
| 64 | my $code = shift; | ||
| 65 | $code = RC_OK if (!defined($code)); | ||
| 66 | ## | ||
| 67 | my $msg = @_ ? shift : undef; | ||
| 68 | $msg = status_message($code) if (!defined($msg)); | ||
| 69 | ## | ||
| 70 | my $hdr = @_ ? shift : undef; | ||
| 71 | $hdr = [] if (!$hdr); | ||
| 72 | ## | ||
| 73 | return HTTP::Response->new($code,$msg,$hdr) if (!@_); | ||
| 74 | return HTTP::Response->new($code,$msg,$hdr,@_); | ||
| 75 | } | ||
| 76 | |||
| 77 | ## $rsp = $CLASS_OR_OBJECT->headResponse() | ||
| 78 | ## $rsp = $CLASS_OR_OBJECT->headResponse(\@headers) | ||
| 79 | ## #$rsp = $CLASS_OR_OBJECT->headResponse(\%headers) | ||
| 80 | ## $rsp = $CLASS_OR_OBJECT->headResponse($httpHeaders) | ||
| 81 | ## + rudimentary handling for HEAD requests | ||
| 82 | sub headResponse { | ||
| 83 | my ($h,$hdr) = @_; | ||
| 84 | return $h->response(RC_OK,undef,$hdr); | ||
| 85 | } | ||
| 86 | |||
| 87 | ## $rsp = $CLASS_OR_OBJECT->errorResponse() | ||
| 88 | ## $rsp = $CLASS_OR_OBJECT->errorResponse($code) | ||
| 89 | ## $rsp = $CLASS_OR_OBJECT->errorResponse($code, @body) | ||
| 90 | ## + rudimentary error responses; workaround for missing root element in html from HTTP::Daemon::ClientConn::send_error() | ||
| 91 | sub errorResponse { | ||
| 92 | my ($h,$code,@body) = @_; | ||
| 93 | $code //= 500; | ||
| 94 | my $msg = status_message($code); | ||
| 95 | @body = ($msg) if (!@body); | ||
| 96 | my $content =<<EOT; | ||
| 97 | <html> | ||
| 98 | <head><title>$code $msg</title></head> | ||
| 99 | <body> | ||
| 100 | <h1>$code $msg</h1> | ||
| 101 | @body | ||
| 102 | </body> | ||
| 103 | </html> | ||
| 104 | EOT | ||
| 105 | return $h->response($code,$msg,["Content-Type"=>"text/html"],$content); | ||
| 106 | } | ||
| 107 | |||
| 108 | ## $rsp = $CLASS_OR_OBJECT->errorResponseRaw() | ||
| 109 | ## $rsp = $CLASS_OR_OBJECT->errorResponseRaw($code) | ||
| 110 | ## $rsp = $CLASS_OR_OBJECT->errorResponseRaw($code, @body) | ||
| 111 | ## + rudimentary error response for raw (un-escaped) body strings | ||
| 112 | sub errorResponseRaw { | ||
| 113 | my ($h,$code,@body) = @_; | ||
| 114 | return $h->errorResponse($code, "<pre>", xml_escape(join('',@body)), "</pre>"); | ||
| 115 | } | ||
| 116 | |||
| 117 | |||
| 118 | ## undef = $h->cerror($csock, $status=RC_INTERNAL_SERVER_ERROR, @msg) | ||
| 119 | ## + sends an error response and sends it to the client socket | ||
| 120 | ## + also logs the error at level ($c->{logError}||'warn') and shuts down the socket | ||
| 121 | sub cerror { | ||
| 122 | my ($h,$c,$status,@msg) = @_; | ||
| 123 | if (defined($c) && $c->opened) { | ||
| 124 | $status = RC_INTERNAL_SERVER_ERROR if (!defined($status)); | ||
| 125 | my $chost = $c->peerhost(); | ||
| 126 | my $msg = @msg ? xml_escape(join('',@msg)) : status_message($status); | ||
| 127 | $h->vlog(($h->{logError}||'error'), "client=$chost: $msg"); | ||
| 128 | { | ||
| 129 | my $_warn=$^W; | ||
| 130 | $^W=0; | ||
| 131 | #$c->send_error($status, $msg); | ||
| 132 | $c->send_response($h->errorResponseRaw($status, $msg)); | ||
| 133 | $^W=$_warn; | ||
| 134 | } | ||
| 135 | $c->shutdown(2); | ||
| 136 | $c->close(); | ||
| 137 | } | ||
| 138 | return undef; | ||
| 139 | } | ||
| 140 | |||
| 141 | ## $rsp = $h->dumpResponse(\$contentRef, %opts) | ||
| 142 | ## + Create and return a new data-dump response. | ||
| 143 | ## Known %opts: | ||
| 144 | ## ( | ||
| 145 | ## raw => $bool, ##-- return raw data (text/plain) ; defualt=$h->{returnRaw} | ||
| 146 | ## type => $mimetype, ##-- mime type if not raw mode | ||
| 147 | ## charset => $enc, ##-- character set, if not raw mode | ||
| 148 | ## filename => $file, ##-- attachment name, if not raw mode | ||
| 149 | ## ) | ||
| 150 | sub dumpResponse { | ||
| 151 | my ($h,$dataref,%vars) = @_; | ||
| 152 | my $returnRaw = defined($vars{raw}) ? $vars{raw} : $h->{returnRaw}; | ||
| 153 | my $contentType = ($returnRaw || !$vars{type} ? 'text/plain' : $vars{type}); | ||
| 154 | my $charset = $h->sanitizeCharset($vars{charset}); | ||
| 155 | $contentType .= "; charset=$charset" if ($charset && $contentType !~ m|application/octet-stream|); | ||
| 156 | ## | ||
| 157 | my $rsp = $h->response(RC_OK); | ||
| 158 | $rsp->content_type($contentType); | ||
| 159 | $rsp->content_ref($dataref) if (defined($dataref)); | ||
| 160 | $rsp->header('Content-Disposition' => "attachment; filename=\"$vars{filename}\"") if ($vars{filename} && !$returnRaw); | ||
| 161 | return $rsp; | ||
| 162 | } | ||
| 163 | |||
| 164 | ## $charset = $h->sanitizeCharset($charset) | ||
| 165 | ## + maps "UTF8", "UTF-8", etc. to "utf-8" | ||
| 166 | sub sanitizeCharset { | ||
| 167 | my ($that,$charset) = @_; | ||
| 168 | return "utf-8" if ($charset && $charset =~ /^utf\-?8$/i); | ||
| 169 | return $charset; | ||
| 170 | } | ||
| 171 | |||
| 172 | |||
| 173 | ##====================================================================== | ||
| 174 | ## Handler class aliases (for derived classes) | ||
| 175 | ##====================================================================== | ||
| 176 | |||
| 177 | ## %ALIAS = ($aliasName => $className, ...) | ||
| 178 | our (%ALIAS); | ||
| 179 | |||
| 180 | ## undef = DTA::CAB::Server::HTTP::Handler->registerAlias($aliasName=>$fqClassName, ...) | ||
| 181 | sub registerAlias { | ||
| 182 | shift; ##-- ignore class argument | ||
| 183 | my (%alias) = @_; | ||
| 184 | @ALIAS{keys(%alias)} = values(%alias); | ||
| 185 | } | ||
| 186 | |||
| 187 | ## $className_or_undef = DTA::CAB::Server::HTTP::Handler->fqClass($alias_or_class_suffix) | ||
| 188 | sub fqClass { | ||
| 189 | my $alias = $_[1]; ##-- ignore class argument | ||
| 190 | |||
| 191 | ##-- Case 0: $alias wasn't defined in the first place: use empty string | ||
| 192 | $alias = '' if (!defined($alias)); | ||
| 193 | |||
| 194 | ##-- Case 1: $alias is already fully qualified | ||
| 195 | return $alias if (isa($alias,'DTA::CAB::Server::HTTP::Handler')); | ||
| 196 | |||
| 197 | ##-- Case 2: $alias is a registered alias: recurse | ||
| 198 | return $_[0]->fqClass($ALIAS{$alias}) if (defined($ALIAS{$alias}) && $ALIAS{$alias} ne $alias); | ||
| 199 | |||
| 200 | ##-- Case 2: $alias is a valid "DTA::CAB::Server::HTTP::Handler::" suffix | ||
| 201 | return "DTA::CAB::Server::HTTP::Handler::${alias}" if (isa("DTA::CAB::Server::HTTP::Handler::${alias}", 'DTA::CAB::Server::HTTP::Handler')); | ||
| 202 | |||
| 203 | ##-- default: return undef | ||
| 204 | return undef; | ||
| 205 | } | ||
| 206 | |||
| 207 | ##====================================================================== | ||
| 208 | ## Local package aliases | ||
| 209 | ##====================================================================== | ||
| 210 | BEGIN { | ||
| 211 | __PACKAGE__->registerAlias( | ||
| 212 | 'DTA::CAB::Server::HTTP::Handler::base' => __PACKAGE__, | ||
| 213 | 'base' => __PACKAGE__, | ||
| 214 | ); | ||
| 215 | } | ||
| 216 | |||
| 217 | 1; ##-- be happy | ||
| 218 | |||
| 219 | __END__ |