CAB/Server/HTTP/Handler.pm untested

filter: Statementstmt 0.0% 0 / 85 Branchbran 0.0% 0 / 40 Conditioncond 0.0% 0 / 25 MC/DCmcdc 0.0% 0 / 16 Subroutinesub 0.0% 0 / 20 Podpod 0.0% 0 / 15 totaltotal 0.0% 0 / 201 CC 21 SCAR 31.4
CC
21
Cov
0%
response
56.0
dumpResponse
42.0
fqClass
30.0
CRAP 23.1
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__