"""quixote.publish

Logic for publishing modules and objects on the Web.
"""

__revision__ = "$Id: publish.py,v 1.99 2001/10/09 21:38:15 gward Exp $"

import sys, os, traceback, cStringIO
import time, types, socket, re

from quixote import errors, fcgi
from quixote.http_request import HTTPRequest
from quixote.http_response import HTTPResponse


def _get_module (name):
    """Get a module object by name."""
    __import__(name)
    module = sys.modules[name]
    return module
    
# Error message to dispay when DISPLAY_EXCEPTIONS in config file is not
# true.  Note that SERVER_ADMIN must be fetched from the environment and
# plugged in here -- we can't do it now because the environment isn't
# really setup for us yet if running as a FastCGI script.
INTERNAL_ERROR_MESSAGE = """\
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html>
<head><title>Internal Server Error</title></head>
<body>
<h1>Internal Server Error</h1>
<p>An internal error occurred while handling your request.</p>

<p>Please contact the server administrator (%s) and inform them of
the time the error occurred, and anything you might have done to
trigger the error.</p>

<p>If you are the server administrator, more information may be
available in either the server's error log or Quixote's error
log.</p>
</body>
</html>
"""

class Publisher:
    """
    The core of Quixote and of any Quixote application.  This class is
    responsible for converting each HTTP request into a search of
    Python's package namespace and, ultimately, a call of a Python
    function/ethod/callable object.

    Each invocation of a driver script should have one Publisher
    instance that lives for as long as the driver script itself.  Eg. if
    your driver script is plain CGI, each Publisher instance will handle
    exactly one HTTP request; if you have a FastCGI driver, then each
    Publisher will handle every HTTP request handed to that driver
    script process.

    Instance attributes:
      root_namespace : module | instance | class
        the Python namespace that will be searched for objects to
        fulfill each HTTP request
      exit_now : boolean
        used for internal state management.  If true, the loop in
        publish_cgi() will terminate at the end of the current request.
      access_log : file
        file to which every access will be logged; set by
        setup_logs() (None if no access log)
      error_log : file
        file to which application errors (exceptions caught by Quixote,
        as well as anything printed to stderr by application code) will
        be logged; set by setup_logs().  Set to sys.stderr if no
        ERROR_LOG setting in the application config file.
      config : Config
        holds all configuration info for this application.  If the
        application doesn't have a config file, uses the default values
        from the quixote.config module.
    """

    def __init__ (self, root_namespace, config=None):
        from quixote.config import Config
        global _publisher

        if _publisher is not None:
            raise RuntimeError, "only one instance of Publisher allowed"
        _publisher = self

        if type(root_namespace) is types.StringType:
            self.root_namespace = _get_module(root_namespace)
        else:
            # Should probably check that root_namespace is really a
            # namespace, ie. a module, class, or instance -- but it's
            # tricky to know if something is really a class or instance
            # (because of ExtensionClass), and who knows what other
            # namespaces are lurking out there in the world?
            self.root_namespace = root_namespace

        self.exit_now = 0
        self.access_log = None
        self.error_log = sys.stderr     # possibly overridden in setup_logs()

        # Initialize default config object with all the default values from
        # the config variables at the top of the config module, ie. if
        # DEBUG_LOG is set to "/var/log/quxiote-debug.log", then
        # config.DEBUG_LOG will also be "/var/log/quixote-debug.log".  If
        # application FCGI/CGI scripts need to override any of these
        # defaults, they can do so by direct manipulation of the config
        # object, or by reading a config file:
        #   app.read_config("myapp.conf")
        if config is None:
            self.config = Config()
        else:
            self.set_config(config)

    def configure (self, **kwargs):
        self.config.set_from_dict(kwargs)

    def read_config (self, filename):
        self.config.read_file(filename)

    def set_config (self, config):
        from quixote.config import Config
        if not isinstance(config, Config):
            raise TypeError, "'config' must be a Config instance"
        self.config = config

    def setup_logs (self):
        """
        Open all log files specified in the config file, and reassign
        sys.stdout to go to the debug log.  If no debug log was
        specified, sys.stdout goes to /dev/null.
        """

        if self.config.debug_log is None:
            # If no debug log file is configured, debugging output goes
            # to the bit-bucket.
            sys.stdout = open('/dev/null', 'w')
        else:
            sys.stdout = open(self.config.debug_log, 'a', 1)

        if self.config.access_log is not None:
            try:
                self.access_log = open(self.config.access_log, 'a', 1)
            except IOError, exc:
                sys.stderr.write("error opening access log %s: %s\n" 
                                 % (`self.config.access_log`, exc.strerror))

        if self.config.error_log is not None:
            try:
                self.error_log = open(self.config.error_log, 'a', 1)
                sys.stderr = self.error_log
            except IOError, exc:
                # leave self.error_log as it was, most likely sys.stderr
                sys.stderr.write("error opening error log %s: %s\n"
                                 % (`self.config.error_log`, exc.strerror))

    def shutdown_logs (self):
        """
        Close log files and restore sys.stdout and sys.stderr to their
        original values.
        """
        if sys.stdout is sys.__stdout__:
            raise RuntimeError, "'setup_logs()' never called"
        sys.stdout.close()
        sys.stdout = sys.__stdout__
        self.access_log.close()
        if self.error_log is not sys.__stderr__:
            self.error_log.close()
            sys.stderr = sys.__stderr__

    def debug (self, msg):
        """
        
        Print a debugging message to the real stderr, ie. the file-like
        object that was sys.stderr when this request started.  What
        happens to this error message depends on your HTTP server; with
        Apache, it will wind up in Apache's error log.

        This is for debugging Quixote itself.  If you're not hacking on
        Quixote, just use "print" for debugging output.

        Note that the ERROR_LOG config variable has no effect here,
        since it's only used for application errors.
        """
        
        # DEBUG_LOG controls where *stdout* goes, but debug messages
        # handled by this function go to *stderr*.  That's because
        # DEBUG_LOG is for debugging Quixote applications, and this
        # function is for debugging Quixote itself.  In other words, if
        # you're hacking on a Quixote app, just set DEBUG_LOG and print
        # your debug messages to stdout.
        from time import time, ctime

        # This is a bogus way to format date/time, but it's what Apache uses in
        # its error_log -- yechh.
        timestamp = ctime(time())
        stderr = sys.__stderr__
        stderr.write("[%s] [quixote %d] %s\n" % (timestamp, os.getpid(), msg))


    def parse_request (self, stdin, env):
        """Parse the request information and return a HTTPRequest object.
        """
        global _request

        self.start_time = time.time()
        request = HTTPRequest(stdin, env)
        _request = request
        request.process_inputs()
        return request

    def start_request (self, request):
        """Called at the start of each request.  Overridden by
        SessionPublisher to handle session details.
        """
        pass

    def log_request (self, request):
        """Log a request in the access_log file.
        """
        if self.access_log is not None:
            if request.session:
                user = request.session.user or "-"
            else:
                user = "-"
            now = time.time()
            seconds = now - self.start_time
            now = time.strftime('%Y-%m-%d %H:%M:%S',
                                time.localtime(time.time()))

            env = request.environ
            method = env.get('REQUEST_METHOD')

            # Under Apache, REQUEST_URI == SCRIPT_NAME + PATH_INFO.
            # Not everyone uses Apache, so we have to stick to
            # environment variables in the CGI spec.  Note that this
            # relies on PATH_INFO under IIS being fixed by HTTPRequest,
            # because IIS gets it wrong.
            request_uri = env.get('SCRIPT_NAME') + env.get('PATH_INFO')
            proto = env.get('SERVER_PROTOCOL')

            self.access_log.write('%s %s %s %d "%s %s %s" %s %0.2fsec\n' %
                                   (request.environ.get('REMOTE_ADDR'),
                                    str(user),
                                    now,
                                    os.getpid(),
                                    method,
                                    request_uri,
                                    proto,
                                    request.response.status_code,
                                    seconds
                                   ) )


    def finish_successful_request (self, request):
        """Called at the end of a successful request.  Overridden by
        SessionPublisher to handle session details."""
        pass

    def finish_interrupted_request (self, request, exc):
        """
        Called at the end of an interrupted request.  Requests are
        interrupted by raising a PublishError exception.  This method
        should return a string object which will be used as the result
        of the request.
        """
        # Throw away the existing response object and start a new one
        # for the error document we're going to create here.
        request.response = HTTPResponse()

        # Test if the exception formats itself.
        msg = exc.format(request)
        if msg is not None:
            return msg

        # No, use a standard format.
        return self.format_error(request, exc)

    def format_error (self, request, exc):
        if isinstance(exc, errors.TraversalError):
            request.response.set_status(404) # resource not found
            return self.format_traversal_error(request, exc)
        elif isinstance(exc, errors.QueryError):
            request.response.set_status(400)
            return self.format_query_error(request, exc)
        elif isinstance(exc, errors.AccessError):
            request.response.set_status(403) # forbidden
            return self.format_access_error(request, exc)
        elif isinstance(exc, errors.SessionError):
            request.response.set_status(400)
            return self.format_session_error(request, exc)
        else:
            raise RuntimeError, "unknown publish exception %s" % `exc`

    def format_query_error (self, request, exc):
        """
        Format a response after a QueryError exception.  Applications
        may wish to subclass this method.
        """
        request.response.set_header("Content-Type", "text/plain")
        return str(exc)

    def format_traversal_error (self, request, exc):
        """
        Format a response after a TraversalError exception.
        Applications may wish to subclass this method.
        """
        from cgi import escape
        page = """\
        <html>
          <head><title>Error: Not Found</title></head>
          <body>%s</body>
        </html>
        """
        msg = 'The requested link "%s" was not found' % exc.path
        
        if self.config.secure_errors:
            msg += ": %s" % exc.public_msg
        else:
            msg += ": %s" % exc.private_msg
        return page % escape(msg)

    def format_access_error (self, request, exc):
        """
        Format a response after a AccessError exception.  Applications
        may wish to subclass this method.
        """
        request.response.set_header("Content-Type", "text/plain")
        return str(exc)

    def format_session_error (self, request, exc):
        # Wait till preparing the error page to revoke the session
        # cookie because we have a new response object at this point.
        # If we called revoke_session_cookie() from the code that raises
        # SessionError, it would have no effect, because it would only
        # put the "Set-cookie" header into the response that is thrown
        # away when we raise this exception.
        from quixote.session import get_session_manager
        get_session_manager().revoke_session_cookie(request)

        request.response.set_header("Content-Type", "text/plain")
        request.response.set_status(400, exc.msg)
        return str(exc)
        

    def format_internal_error (self, request, error_message):
        """
        Format a response after a non-PublishError exception.
        Applications may wish to subclass this method but they should do
        so carefully.  The application could be broken badly when this
        method is called.  This probably best to keep the formatting
        simple.
        """
        if self.config.display_exceptions:
            request.response.set_header("Content-Type", "text/plain")
            return error_message
        else:
            request.response.set_header("Content-Type", "text/html")
            admin = os.environ.get('SERVER_ADMIN',
                                   "<i>email address unknown</i>")
            return INTERNAL_ERROR_MESSAGE % admin

    def finish_failed_request (self, request):
        """
        Called at the end of an failed request.  Any exception (other
        than PublishError) causes a request to fail.  This method should
        return a string object which will be used as the result of the
        request.
        """
        # build new response to be safe
        original_response = request.response
        request.response = HTTPResponse()
        #self.debug("caught an error (%s), reporting it." %
        #           sys.exc_info()[1])

        (exc_type, exc_value, tb) = sys.exc_info()
        error_summary = traceback.format_exception_only(exc_type, exc_value)
        error_summary = error_summary[0][0:-1] # de-listify and strip newline
        error_file = cStringIO.StringIO()

        #self.debug("report_error: exception = %s: %s" % (exc_type, exc_value))

        # record the time of the error
        now = time.localtime(time.time())
        error_file.write('Error at time: %s\n' %
                         time.strftime('%Y-%m-%d %H:%M:%S', now) )
        # format the traceback
        error_file.write('Traceback\n'
                         '=========\n')
        traceback.print_exception(exc_type, exc_value, tb, file=error_file)
        # include request and response dumps
        error_file.write('\nRequest\n'
                           '=======\n')
        error_file.write(request.dump())
        error_file.write('\nOriginal Response\n'
                           '=================\n')
        original_response.write(error_file)
        error_file.write('='*65 + '\n')

        error_msg = error_file.getvalue()
        self.error_log.write(error_msg)
        if request.session is not None:
            request.session.dump(file=self.error_log)

        if self.config.error_email:
            self.mail_error(error_msg, error_summary)

        request.response.set_status(500)
        return self.format_internal_error(request, error_msg)
        
    def mail_error (self, msg, error_summary):
        """Send an email notifying someone of a traceback."""

        cmd = "/usr/lib/sendmail '%s'" % self.config.error_email
        pipe = os.popen(cmd, 'w')
        pipe.write('Subject: Quixote Traceback (%s)\n' % error_summary)
        pipe.write('From: Quixote on %s <%s>\n' % (socket.gethostname(),
                                                   self.config.error_email))
        pipe.write('To: %s\n' % self.config.error_email)
        pipe.write('\n')
        pipe.write(msg)
        pipe.close()

    def get_component (self, container, component, path, request):
        """Get one component of a path from a namespace.
        """
        # First security check: if the container doesn't even have an
        # _q_exports list, fail now: all Quixote-traversable namespaces
        # (modules, packages, instances) must have an export list!
        if not hasattr(container, '_q_exports'):
            raise errors.TraversalError("Resource not found", 
                "%s has no _q_exports list" % repr(container))

        # Second security check: call _q_access function if it's present.
        if hasattr(container, '_q_access'):
            # will raise AccessError if access failed
            container._q_access(request)
            
        # Third security check: make sure the current name component is
        # in the export list or is _q_index.
        if (component == "_q_index") or (component in container._q_exports):
            is_module = type(container) is types.ModuleType
            has_component = hasattr(container, component)
            if is_module and not has_component:
                # get next module
                mod_name = container.__name__ + '.' + component
                # If we get an ImportError here we don't catch it.  It means
                # that either someone exported something that doesn't exist or
                # an exception was raised from deeping in the code.  A
                # traceback should be generated in either case.
                object = _get_module(mod_name)

            elif has_component:
                object = getattr(container, component)

            else: 
                # not a module, doesn't have 'component'
                raise errors.TraversalError("Resource not found",
                    "object %s has no attribute '%s'" % (`container`, component))
        else:
            # Component is not in exports list.  Check if namespace provides a
            # '_q_getname()' function, which translates an arbitrary string
            # into an object that we continue traversing.  This is very handy;
            # it lets you put user-space objects into your URL-space,
            # eliminating the need for digging ID strings out of a query, or
            # checking PATHINFO after Quixote's done with it.  But it is a
            # compromise to security: it opens up the traversal algorithm to
            # arbitrary names not listed in _q_exports!
            if hasattr(container, "_q_getname"):
                object = container._q_getname(request, component)
            else:
                raise errors.TraversalError("Resource not found",
                    ("%s not in _q_exports list for %s" %
                     (repr(component), container)))
        
        return object

    _slash_pat = re.compile("//*")

    def traverse_url (self, path, request):
        """traverse_url(path : string, request : HTTPRequest) -> object : any

        Perform traversal based on the provided path, starting at the root
        object.  It returns the script name and path info values for
        the arrived-at object, along with the object itself.

        It's expected that the final object is something callable like a
        function or a method; intermediate objects along the way will
        usually be packages or modules.

        To prevent crackers from writing URLs that traverse private
        objects, every package, module, or object along the way must have
        a _q_exports attribute containing a list of publicly visible
        names.  Not having a _q_exports attribute is an error, though
        having _q_exports be an empty list is OK (though useless).  If a
        component of the path isn't in _q_exports, that also produces an
        error.
        """
        
        # If someone accesses a Quixote driver script without a trailing
        # slash, we'll wind up here with an empty path.  This won't
        # work; relative references in the page generated by the root
        # namespace's _q_index() will be off.  Fix it by redirecting the
        # user to the right URL; when the client follows the redirect,
        # we'll wind up here again with path == '/'.
        if (not path and self.config.fix_trailing_slash):
            request.redirect(request.environ['SCRIPT_NAME'] + '/' ,
                             permanent=1)
            return

        # replace repeated slashes with a single slash
        if path.find("//") != -1:
            path = self._slash_pat.sub("/", path)

        # split path apart; /foo/bar/baz  -> ['foo', 'bar', 'baz']
        #                   /foo/bar/     -> ['foo', 'bar', '']
        path_components = path[1:].split('/')

        # Traverse starting at the root
        object = self.root_namespace

        # Loop over the components of the path
        for component in path_components:
            if component == "":
                # "/q/foo/" == "/q/foo/_q_index"
                component = "_q_index"
            object = self.get_component(object, component, path, request)

        if not callable(object):
            # We went through all the components of the path and ended up at
            # something which isn't callable, like a module or an instance
            # without a __call__ method.
            if path[-1] != '/':
                if not request.form and self.config.fix_trailing_slash:
                    # This is for the convenience of users who type in paths.
                    # Repair the path and redirect.  This should not happen for
                    # URLs within the site.
                    path = "%s/%s/" % (self.config.url_prefix,
                                       "/".join(path_components))
                    request.redirect(path, permanent=1)
                    return

                else:
                    # Automatic redirects disabled or there is form data.  If
                    # there is form data then the programmer is using the
                    # wrong path.  A redirect won't work if the form data came
                    # from a POST anyhow.
                    raise errors.TraversalError("missing trailing slash?",
                                                path=path)
            else:
                raise errors.TraversalError("Resource not found",
                                            "uncallable object %s" % `object`,
                                            path)

        # Determine the script name and path info
        script_name = "/".join([self.config.url_prefix] + path_components)
        os.environ['SCRIPT_NAME'] = script_name
        os.environ['PATH_INFO'] = '' # we always traverse the entire path

        return object

    def try_publish (self, request, path):
        """try_publish(request : HTTPRequest, path : string) -> string
        
        The master method that does all the work for a single request.  Uses
        traverse_url() to get a callable object.  The object is called and
        the output is returned.  Exceptions are handled by the caller. 
        """

        self.start_request(request)

        # Traverse package to a (hopefully-) callable object
        object = self.traverse_url(path, request)

        # None means no output -- traverse_url() just issued a redirect.
        if object is None:
            return None

        # Anything else must be a callable object...
        if not callable(object):
            raise RuntimeError, "object not callable: %s" % repr(object)

        # ...so call it.
        try:
            output = object(request)
        except SystemExit:
            output = "SystemExit exception caught, shutting down"
            self.debug(output)
            self.exit_now = 1

        if output is None:
            raise RuntimeError, 'callable %s returned None' % repr(object)

        # The callable ran OK, commit any changes to the session
        self.finish_successful_request(request)

        return output

    _gzip_header = ("\037\213" # magic
                    "\010" # compression method
                    "\000" # flags
                    "\000\000\000\000" # time, who cares?
                    "\002"
                    "\377")

    def compress_output (self, request, output):
        import zlib, struct

        encoding = request.get_encoding(["gzip", "x-gzip"])
        n = len(output)
        if n > 200 and encoding:
            co = zlib.compressobj(6, zlib.DEFLATED, -zlib.MAX_WBITS,
                                  zlib.DEF_MEM_LEVEL, 0)
            chunks = [self._gzip_header,
                      co.compress(output),
                      co.flush(),
                      struct.pack("<ll", zlib.crc32(output), len(output))]
            output = "".join(chunks)
            #self.debug("gzip (original size %d, ratio %.1f)" % 
            #           (n, float(n)/len(output)))
            request.response.set_header("Content-Encoding", encoding)
        return output

    def publish (self, stdin, stdout, stderr):
        """publish(stdin : file, stdout : file, stderr : file)

        Process a single request.  The try_publish() method will be called
        to do the work and exceptions will be handled here.
        """

        request = self.parse_request(stdin, os.environ)

        try:
            output = self.try_publish(request, os.environ.get('PATH_INFO', ''))

        except errors.PublishError, exc:
            # Exit the publishing loop and return a result right away.
            output = self.finish_interrupted_request(request, exc)

        except:
            # some other exception, generate error messages to the logs, etc.
            output = self.finish_failed_request(request)

        self.log_request(request)

        if output and self.config.compress_pages:
            output = self.compress_output(request, str(output))

        # Output results from Response object
        if output:
            request.response.set_body(output)
        request.response.write(stdout)

    def publish_cgi (self):
        """publish_cgi() -> None

        Entry point from CGI and FCGI scripts; it will repeatedly do the
        publish() function until there are no more requests (only once for
        CGI scripts).
        """

        while fcgi.isFCGI() and not self.exit_now:
            f = fcgi.FCGI()
            os.environ = f.env
            self.publish(f.inp, f.out, f.err)
            f.Finish()
            if self.config.run_once:
                break


# Publisher singleton, one of these per process
_publisher = None

# The current request being processed.
_request = None

def get_publisher():
    global _publisher
    return _publisher

def get_request():
    global _request
    return _request

def get_session():
    global _request
    return _request.session

def get_user():
    global _request
    session = _request.session
    if session is None:
        return None
    else:
        return session.user

class SessionPublisher (Publisher):
    
    def __init__ (self, root_namespace):
        Publisher.__init__(self, root_namespace)
        self.session_mgr = None

    def set_session_manager (self, session_mgr):
        from quixote.session import set_session_manager
        set_session_manager(session_mgr)
        self.session_mgr = session_mgr

    def start_request (self, request):
        # Get the session object and stick it onto the request
        request.session = self.session_mgr.get_session(request)
        request.session.start_request(request)

    def finish_successful_request (self, request):
        if request.session is not None:
            request.session.finish_request(request)
            self.session_mgr.maintain_session(request, request.session)
        self.session_mgr.commit()

    def finish_interrupted_request (self, request, exc):
        output = Publisher.finish_interrupted_request(self, request, exc)

        # commit the current transaction so that any changes to the
        # session objects are saved and are visible on the next HTTP
        # hit.  Remember, AccessError is a subclass of PublishError,
        # so this code will be run for both typos in the URL and for
        # the user not being logged in.
        #
        # The assumption here is that the UI code won't make changes
        # to the core database before checking permissions and raising
        # a PublishError; if you must do this (though it's hard to see
        # why this would be necessary), you'll have to abort the
        # current transaction, make your session changes, and then
        # raise the PublishError.
        # 
        # XXX We should really be able to commit session changes and
        # database changes separately, but that requires ZODB
        # incantations that we currently don't know.
        self.session_mgr.commit()

        return output

    def finish_failed_request (self, request):
        self.session_mgr.abort()
        return Publisher.finish_failed_request(self, request)

