1"""Base classes for server/gateway implementations""" 2 3from .util import FileWrapper, guess_scheme, is_hop_by_hop 4from .headers import Headers 5 6import sys, os, time 7 8__all__ = [ 9 'BaseHandler', 'SimpleHandler', 'BaseCGIHandler', 'CGIHandler', 10 'IISCGIHandler', 'read_environ' 11] 12 13# Weekday and month names for HTTP date/time formatting; always English! 14_weekdayname = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] 15_monthname = [None, # Dummy so we can use 1-based month numbers 16 "Jan", "Feb", "Mar", "Apr", "May", "Jun", 17 "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] 18 19def format_date_time(timestamp): 20 year, month, day, hh, mm, ss, wd, y, z = time.gmtime(timestamp) 21 return "%s, %02d %3s %4d %02d:%02d:%02d GMT" % ( 22 _weekdayname[wd], day, _monthname[month], year, hh, mm, ss 23 ) 24 25_is_request = { 26 'SCRIPT_NAME', 'PATH_INFO', 'QUERY_STRING', 'REQUEST_METHOD', 'AUTH_TYPE', 27 'CONTENT_TYPE', 'CONTENT_LENGTH', 'HTTPS', 'REMOTE_USER', 'REMOTE_IDENT', 28}.__contains__ 29 30def _needs_transcode(k): 31 return _is_request(k) or k.startswith('HTTP_') or k.startswith('SSL_') \ 32 or (k.startswith('REDIRECT_') and _needs_transcode(k[9:])) 33 34def read_environ(): 35 """Read environment, fixing HTTP variables""" 36 enc = sys.getfilesystemencoding() 37 esc = 'surrogateescape' 38 try: 39 ''.encode('utf-8', esc) 40 except LookupError: 41 esc = 'replace' 42 environ = {} 43 44 # Take the basic environment from native-unicode os.environ. Attempt to 45 # fix up the variables that come from the HTTP request to compensate for 46 # the bytes->unicode decoding step that will already have taken place. 47 for k, v in os.environ.items(): 48 if _needs_transcode(k): 49 50 # On win32, the os.environ is natively Unicode. Different servers 51 # decode the request bytes using different encodings. 52 if sys.platform == 'win32': 53 software = os.environ.get('SERVER_SOFTWARE', '').lower() 54 55 # On IIS, the HTTP request will be decoded as UTF-8 as long 56 # as the input is a valid UTF-8 sequence. Otherwise it is 57 # decoded using the system code page (mbcs), with no way to 58 # detect this has happened. Because UTF-8 is the more likely 59 # encoding, and mbcs is inherently unreliable (an mbcs string 60 # that happens to be valid UTF-8 will not be decoded as mbcs) 61 # always recreate the original bytes as UTF-8. 62 if software.startswith('microsoft-iis/'): 63 v = v.encode('utf-8').decode('iso-8859-1') 64 65 # Apache mod_cgi writes bytes-as-unicode (as if ISO-8859-1) direct 66 # to the Unicode environ. No modification needed. 67 elif software.startswith('apache/'): 68 pass 69 70 # Python 3's http.server.CGIHTTPRequestHandler decodes 71 # using the urllib.unquote default of UTF-8, amongst other 72 # issues. 73 elif ( 74 software.startswith('simplehttp/') 75 and 'python/3' in software 76 ): 77 v = v.encode('utf-8').decode('iso-8859-1') 78 79 # For other servers, guess that they have written bytes to 80 # the environ using stdio byte-oriented interfaces, ending up 81 # with the system code page. 82 else: 83 v = v.encode(enc, 'replace').decode('iso-8859-1') 84 85 # Recover bytes from unicode environ, using surrogate escapes 86 # where available (Python 3.1+). 87 else: 88 v = v.encode(enc, esc).decode('iso-8859-1') 89 90 environ[k] = v 91 return environ 92 93 94class BaseHandler: 95 """Manage the invocation of a WSGI application""" 96 97 # Configuration parameters; can override per-subclass or per-instance 98 wsgi_version = (1,0) 99 wsgi_multithread = True 100 wsgi_multiprocess = True 101 wsgi_run_once = False 102 103 origin_server = True # We are transmitting direct to client 104 http_version = "1.0" # Version that should be used for response 105 server_software = None # String name of server software, if any 106 107 # os_environ is used to supply configuration from the OS environment: 108 # by default it's a copy of 'os.environ' as of import time, but you can 109 # override this in e.g. your __init__ method. 110 os_environ= read_environ() 111 112 # Collaborator classes 113 wsgi_file_wrapper = FileWrapper # set to None to disable 114 headers_class = Headers # must be a Headers-like class 115 116 # Error handling (also per-subclass or per-instance) 117 traceback_limit = None # Print entire traceback to self.get_stderr() 118 error_status = "500 Internal Server Error" 119 error_headers = [('Content-Type','text/plain')] 120 error_body = b"A server error occurred. Please contact the administrator." 121 122 # State variables (don't mess with these) 123 status = result = None 124 headers_sent = False 125 headers = None 126 bytes_sent = 0 127 128 def run(self, application): 129 """Invoke the application""" 130 # Note to self: don't move the close()! Asynchronous servers shouldn't 131 # call close() from finish_response(), so if you close() anywhere but 132 # the double-error branch here, you'll break asynchronous servers by 133 # prematurely closing. Async servers must return from 'run()' without 134 # closing if there might still be output to iterate over. 135 try: 136 self.setup_environ() 137 self.result = application(self.environ, self.start_response) 138 self.finish_response() 139 except (ConnectionAbortedError, BrokenPipeError, ConnectionResetError): 140 # We expect the client to close the connection abruptly from time 141 # to time. 142 return 143 except: 144 try: 145 self.handle_error() 146 except: 147 # If we get an error handling an error, just give up already! 148 self.close() 149 raise # ...and let the actual server figure it out. 150 151 152 def setup_environ(self): 153 """Set up the environment for one request""" 154 155 env = self.environ = self.os_environ.copy() 156 self.add_cgi_vars() 157 158 env['wsgi.input'] = self.get_stdin() 159 env['wsgi.errors'] = self.get_stderr() 160 env['wsgi.version'] = self.wsgi_version 161 env['wsgi.run_once'] = self.wsgi_run_once 162 env['wsgi.url_scheme'] = self.get_scheme() 163 env['wsgi.multithread'] = self.wsgi_multithread 164 env['wsgi.multiprocess'] = self.wsgi_multiprocess 165 166 if self.wsgi_file_wrapper is not None: 167 env['wsgi.file_wrapper'] = self.wsgi_file_wrapper 168 169 if self.origin_server and self.server_software: 170 env.setdefault('SERVER_SOFTWARE',self.server_software) 171 172 173 def finish_response(self): 174 """Send any iterable data, then close self and the iterable 175 176 Subclasses intended for use in asynchronous servers will 177 want to redefine this method, such that it sets up callbacks 178 in the event loop to iterate over the data, and to call 179 'self.close()' once the response is finished. 180 """ 181 try: 182 if not self.result_is_file() or not self.sendfile(): 183 for data in self.result: 184 self.write(data) 185 self.finish_content() 186 except: 187 # Call close() on the iterable returned by the WSGI application 188 # in case of an exception. 189 if hasattr(self.result, 'close'): 190 self.result.close() 191 raise 192 else: 193 # We only call close() when no exception is raised, because it 194 # will set status, result, headers, and environ fields to None. 195 # See bpo-29183 for more details. 196 self.close() 197 198 199 def get_scheme(self): 200 """Return the URL scheme being used""" 201 return guess_scheme(self.environ) 202 203 204 def set_content_length(self): 205 """Compute Content-Length or switch to chunked encoding if possible""" 206 try: 207 blocks = len(self.result) 208 except (TypeError,AttributeError,NotImplementedError): 209 pass 210 else: 211 if blocks==1: 212 self.headers['Content-Length'] = str(self.bytes_sent) 213 return 214 # XXX Try for chunked encoding if origin server and client is 1.1 215 216 217 def cleanup_headers(self): 218 """Make any necessary header changes or defaults 219 220 Subclasses can extend this to add other defaults. 221 """ 222 if 'Content-Length' not in self.headers: 223 self.set_content_length() 224 225 def start_response(self, status, headers,exc_info=None): 226 """'start_response()' callable as specified by PEP 3333""" 227 228 if exc_info: 229 try: 230 if self.headers_sent: 231 # Re-raise original exception if headers sent 232 raise exc_info[0](exc_info[1]).with_traceback(exc_info[2]) 233 finally: 234 exc_info = None # avoid dangling circular ref 235 elif self.headers is not None: 236 raise AssertionError("Headers already set!") 237 238 self.status = status 239 self.headers = self.headers_class(headers) 240 status = self._convert_string_type(status, "Status") 241 assert len(status)>=4,"Status must be at least 4 characters" 242 assert status[:3].isdigit(), "Status message must begin w/3-digit code" 243 assert status[3]==" ", "Status message must have a space after code" 244 245 if __debug__: 246 for name, val in headers: 247 name = self._convert_string_type(name, "Header name") 248 val = self._convert_string_type(val, "Header value") 249 assert not is_hop_by_hop(name),\ 250 f"Hop-by-hop header, '{name}: {val}', not allowed" 251 252 return self.write 253 254 def _convert_string_type(self, value, title): 255 """Convert/check value type.""" 256 if type(value) is str: 257 return value 258 raise AssertionError( 259 "{0} must be of type str (got {1})".format(title, repr(value)) 260 ) 261 262 def send_preamble(self): 263 """Transmit version/status/date/server, via self._write()""" 264 if self.origin_server: 265 if self.client_is_modern(): 266 self._write(('HTTP/%s %s\r\n' % (self.http_version,self.status)).encode('iso-8859-1')) 267 if 'Date' not in self.headers: 268 self._write( 269 ('Date: %s\r\n' % format_date_time(time.time())).encode('iso-8859-1') 270 ) 271 if self.server_software and 'Server' not in self.headers: 272 self._write(('Server: %s\r\n' % self.server_software).encode('iso-8859-1')) 273 else: 274 self._write(('Status: %s\r\n' % self.status).encode('iso-8859-1')) 275 276 def write(self, data): 277 """'write()' callable as specified by PEP 3333""" 278 279 assert type(data) is bytes, \ 280 "write() argument must be a bytes instance" 281 282 if not self.status: 283 raise AssertionError("write() before start_response()") 284 285 elif not self.headers_sent: 286 # Before the first output, send the stored headers 287 self.bytes_sent = len(data) # make sure we know content-length 288 self.send_headers() 289 else: 290 self.bytes_sent += len(data) 291 292 # XXX check Content-Length and truncate if too many bytes written? 293 self._write(data) 294 self._flush() 295 296 297 def sendfile(self): 298 """Platform-specific file transmission 299 300 Override this method in subclasses to support platform-specific 301 file transmission. It is only called if the application's 302 return iterable ('self.result') is an instance of 303 'self.wsgi_file_wrapper'. 304 305 This method should return a true value if it was able to actually 306 transmit the wrapped file-like object using a platform-specific 307 approach. It should return a false value if normal iteration 308 should be used instead. An exception can be raised to indicate 309 that transmission was attempted, but failed. 310 311 NOTE: this method should call 'self.send_headers()' if 312 'self.headers_sent' is false and it is going to attempt direct 313 transmission of the file. 314 """ 315 return False # No platform-specific transmission by default 316 317 318 def finish_content(self): 319 """Ensure headers and content have both been sent""" 320 if not self.headers_sent: 321 # Only zero Content-Length if not set by the application (so 322 # that HEAD requests can be satisfied properly, see #3839) 323 self.headers.setdefault('Content-Length', "0") 324 self.send_headers() 325 else: 326 pass # XXX check if content-length was too short? 327 328 def close(self): 329 """Close the iterable (if needed) and reset all instance vars 330 331 Subclasses may want to also drop the client connection. 332 """ 333 try: 334 if hasattr(self.result,'close'): 335 self.result.close() 336 finally: 337 self.result = self.headers = self.status = self.environ = None 338 self.bytes_sent = 0; self.headers_sent = False 339 340 341 def send_headers(self): 342 """Transmit headers to the client, via self._write()""" 343 self.cleanup_headers() 344 self.headers_sent = True 345 if not self.origin_server or self.client_is_modern(): 346 self.send_preamble() 347 self._write(bytes(self.headers)) 348 349 350 def result_is_file(self): 351 """True if 'self.result' is an instance of 'self.wsgi_file_wrapper'""" 352 wrapper = self.wsgi_file_wrapper 353 return wrapper is not None and isinstance(self.result,wrapper) 354 355 356 def client_is_modern(self): 357 """True if client can accept status and headers""" 358 return self.environ['SERVER_PROTOCOL'].upper() != 'HTTP/0.9' 359 360 361 def log_exception(self,exc_info): 362 """Log the 'exc_info' tuple in the server log 363 364 Subclasses may override to retarget the output or change its format. 365 """ 366 try: 367 from traceback import print_exception 368 stderr = self.get_stderr() 369 print_exception( 370 exc_info[0], exc_info[1], exc_info[2], 371 self.traceback_limit, stderr 372 ) 373 stderr.flush() 374 finally: 375 exc_info = None 376 377 def handle_error(self): 378 """Log current error, and send error output to client if possible""" 379 self.log_exception(sys.exc_info()) 380 if not self.headers_sent: 381 self.result = self.error_output(self.environ, self.start_response) 382 self.finish_response() 383 # XXX else: attempt advanced recovery techniques for HTML or text? 384 385 def error_output(self, environ, start_response): 386 """WSGI mini-app to create error output 387 388 By default, this just uses the 'error_status', 'error_headers', 389 and 'error_body' attributes to generate an output page. It can 390 be overridden in a subclass to dynamically generate diagnostics, 391 choose an appropriate message for the user's preferred language, etc. 392 393 Note, however, that it's not recommended from a security perspective to 394 spit out diagnostics to any old user; ideally, you should have to do 395 something special to enable diagnostic output, which is why we don't 396 include any here! 397 """ 398 start_response(self.error_status,self.error_headers[:],sys.exc_info()) 399 return [self.error_body] 400 401 402 # Pure abstract methods; *must* be overridden in subclasses 403 404 def _write(self,data): 405 """Override in subclass to buffer data for send to client 406 407 It's okay if this method actually transmits the data; BaseHandler 408 just separates write and flush operations for greater efficiency 409 when the underlying system actually has such a distinction. 410 """ 411 raise NotImplementedError 412 413 def _flush(self): 414 """Override in subclass to force sending of recent '_write()' calls 415 416 It's okay if this method is a no-op (i.e., if '_write()' actually 417 sends the data. 418 """ 419 raise NotImplementedError 420 421 def get_stdin(self): 422 """Override in subclass to return suitable 'wsgi.input'""" 423 raise NotImplementedError 424 425 def get_stderr(self): 426 """Override in subclass to return suitable 'wsgi.errors'""" 427 raise NotImplementedError 428 429 def add_cgi_vars(self): 430 """Override in subclass to insert CGI variables in 'self.environ'""" 431 raise NotImplementedError 432 433 434class SimpleHandler(BaseHandler): 435 """Handler that's just initialized with streams, environment, etc. 436 437 This handler subclass is intended for synchronous HTTP/1.0 origin servers, 438 and handles sending the entire response output, given the correct inputs. 439 440 Usage:: 441 442 handler = SimpleHandler( 443 inp,out,err,env, multithread=False, multiprocess=True 444 ) 445 handler.run(app)""" 446 447 def __init__(self,stdin,stdout,stderr,environ, 448 multithread=True, multiprocess=False 449 ): 450 self.stdin = stdin 451 self.stdout = stdout 452 self.stderr = stderr 453 self.base_env = environ 454 self.wsgi_multithread = multithread 455 self.wsgi_multiprocess = multiprocess 456 457 def get_stdin(self): 458 return self.stdin 459 460 def get_stderr(self): 461 return self.stderr 462 463 def add_cgi_vars(self): 464 self.environ.update(self.base_env) 465 466 def _write(self,data): 467 result = self.stdout.write(data) 468 if result is None or result == len(data): 469 return 470 from warnings import warn 471 warn("SimpleHandler.stdout.write() should not do partial writes", 472 DeprecationWarning) 473 while True: 474 data = data[result:] 475 if not data: 476 break 477 result = self.stdout.write(data) 478 479 def _flush(self): 480 self.stdout.flush() 481 self._flush = self.stdout.flush 482 483 484class BaseCGIHandler(SimpleHandler): 485 486 """CGI-like systems using input/output/error streams and environ mapping 487 488 Usage:: 489 490 handler = BaseCGIHandler(inp,out,err,env) 491 handler.run(app) 492 493 This handler class is useful for gateway protocols like ReadyExec and 494 FastCGI, that have usable input/output/error streams and an environment 495 mapping. It's also the base class for CGIHandler, which just uses 496 sys.stdin, os.environ, and so on. 497 498 The constructor also takes keyword arguments 'multithread' and 499 'multiprocess' (defaulting to 'True' and 'False' respectively) to control 500 the configuration sent to the application. It sets 'origin_server' to 501 False (to enable CGI-like output), and assumes that 'wsgi.run_once' is 502 False. 503 """ 504 505 origin_server = False 506 507 508class CGIHandler(BaseCGIHandler): 509 510 """CGI-based invocation via sys.stdin/stdout/stderr and os.environ 511 512 Usage:: 513 514 CGIHandler().run(app) 515 516 The difference between this class and BaseCGIHandler is that it always 517 uses 'wsgi.run_once' of 'True', 'wsgi.multithread' of 'False', and 518 'wsgi.multiprocess' of 'True'. It does not take any initialization 519 parameters, but always uses 'sys.stdin', 'os.environ', and friends. 520 521 If you need to override any of these parameters, use BaseCGIHandler 522 instead. 523 """ 524 525 wsgi_run_once = True 526 # Do not allow os.environ to leak between requests in Google App Engine 527 # and other multi-run CGI use cases. This is not easily testable. 528 # See http://bugs.python.org/issue7250 529 os_environ = {} 530 531 def __init__(self): 532 BaseCGIHandler.__init__( 533 self, sys.stdin.buffer, sys.stdout.buffer, sys.stderr, 534 read_environ(), multithread=False, multiprocess=True 535 ) 536 537 538class IISCGIHandler(BaseCGIHandler): 539 """CGI-based invocation with workaround for IIS path bug 540 541 This handler should be used in preference to CGIHandler when deploying on 542 Microsoft IIS without having set the config allowPathInfo option (IIS>=7) 543 or metabase allowPathInfoForScriptMappings (IIS<7). 544 """ 545 wsgi_run_once = True 546 os_environ = {} 547 548 # By default, IIS gives a PATH_INFO that duplicates the SCRIPT_NAME at 549 # the front, causing problems for WSGI applications that wish to implement 550 # routing. This handler strips any such duplicated path. 551 552 # IIS can be configured to pass the correct PATH_INFO, but this causes 553 # another bug where PATH_TRANSLATED is wrong. Luckily this variable is 554 # rarely used and is not guaranteed by WSGI. On IIS<7, though, the 555 # setting can only be made on a vhost level, affecting all other script 556 # mappings, many of which break when exposed to the PATH_TRANSLATED bug. 557 # For this reason IIS<7 is almost never deployed with the fix. (Even IIS7 558 # rarely uses it because there is still no UI for it.) 559 560 # There is no way for CGI code to tell whether the option was set, so a 561 # separate handler class is provided. 562 def __init__(self): 563 environ= read_environ() 564 path = environ.get('PATH_INFO', '') 565 script = environ.get('SCRIPT_NAME', '') 566 if (path+'/').startswith(script+'/'): 567 environ['PATH_INFO'] = path[len(script):] 568 BaseCGIHandler.__init__( 569 self, sys.stdin.buffer, sys.stdout.buffer, sys.stderr, 570 environ, multithread=False, multiprocess=True 571 ) 572