source: TI05-delivery/trunk/lib/python/delivery/server.py @ 1268

"""
Start a bbftp server process and define python callbacks for authentication and authorisation. 

Interface to the BBftp server.

@copyright Copyright (C) 2006 CCLRC & NERC
@license This software may be distributed under the terms of the Q Public Licence, version 1.0 or later.

@author Stephen Pascoe
"""

#!NOTE: Importing bbftpd and bbftpc together is dangerous and will cause stange errors.
import sys
if sys.modules.has_key('delivery.bbftpc'):
    raise ImportError, "delivery.bbftpc extension already loaded.  You cannot use both client and server extensions together"


import bbftpd

class TROPT:
    """Static class containing constants used by bbftp in the transferoption parameter.

    TROPT.X always corresponds to TROPT_X as defined in bbftpd/structures.h.
    Options that aren't likely to be used for the delivery service are not
    included (e.g. TROPT_RFIO).

    @cvar TMP always use temporary name.
    @cvar ACC keep access and modification time.
    @cvar MODE keep mode.
    @cvar DIR create all dirs in path.
    """
    TMP = bbftpd.TROPT_TMP
    ACC = bbftpd.TROPT_ACC
    MODE = bbftpd.TROPT_MODE
    DIR = bbftpd.TROPT_DIR

class MSG:
    """Static class containing message codes used by bbftp.

    MSG.X corresponds to MSG_X or MSG_X_V2 as defined in bbftpd/structures.h.
    Message codes not returned by the auth/authz interface are not included.

    @cvar CHDIR a chdir request.
    @cvar LIST a ls/dir request.
    @cvar MKDIR a mkdir request.
    @cvar RM a rm request.
    @cvar STAT a stat request.
    @cvar DF a statfs request.
    """
    CHDIR = bbftpd.MSG_CHDIR_V2
    LIST = bbftpd.MSG_LIST_V2
    MKDIR = bbftpd.MSG_MKDIR_V2
    RM = bbftpd.MSG_RM
    STAT = bbftpd.MSG_STAT
    DF = bbftpd.MSG_DF
    

#--------------------------------------------------------------------------------------------------------------

def start(authHandler, args):
    """Start the bbftp server.

    The server performs a fork() during initialisation, the child process remains in
    the server's main loop and the parent returns from this function.  The server process
    calls authHandler.authorise() on each connection to do authentication/authorisation.

    @note because the server process forks, authHandler will not see any changes to the python
        interpreter following the call to start().

    @param authHandler an instance of AuthHandler.
    @param args a list of command line arguments.
    @return the PID of the server process.
    """
    
    return bbftpd.run(authHandler, args)


class AuthenticationFailure(Exception):
    """Signals authentication failed.
    """
    pass

class AuthorisationFailure(Exception):
    """Signals authorisation failed.
    """
    pass



class AuthHandler(object):
    """Abstract base class for implementing authentication.

    Subclasses should implement the authorise() method to authenticate clients connecting to
    the server.  An AuthHandler object is passed to start() when initialising the server.
    """
    
    def send(self, buffer):
        """Send a message to the client during authentication

        This method must only be used from within self.authenticate() which has been called
        from the bbftp server process started by start().

        @param buffer a string containing the message to send.
        """
    
        return bbftpd.send(buffer)

    def recv(self):
        """Receive a message from the client during authentication

        This method must only be used from within self.authenticate() which has been called
        from the bbftp server process started by start().

        @return a string containing the message received.
        """

        return bbftpd.recv()

    def authenticate(self):
        """Authenticate a connection.

        This function should be overridden in subclasses to implement authentication using
        the method calls self.send() and send.recv().  It is called by the bbftp server process
        created using the start() function.

        @note because the server process forks on each connection, calls to authorise() will
            see the state of the python interpreter as it was when start() was called.

        @return an AuthzHandler instance if authentication succeeds.  Any false value is considered
            an authorisation failure.
        @raise AuthorisationFailure the preferred way of signaling authorisation failure to
            the bbftp server process.
        """

        raise NotImplementedError


class AuthzHandler(object):
    """Abstract base class for implementing authorisation.

    @ivar username: the client's username.  This attribute must be set before an instance of AuthzHandler
        is returned to the bbftp server process by AuthHandler.authenticate().
        
    """

    def authzControl(self, msgcode, transferoption, path):
        """Authorise a control command.

        @param msgcode the command type.
        @param transferoption extra options specified in the command.
        @param path the file or directory to which the command applies.
        @return bool for success or failure.
        """

        raise NotImplementedError

    def authzRetr(self, path):
        """Authorise a retrieve request.

        @param path the file being retrieved.
        @return bool for success or failure.
        """

        raise NotImplementedError

    def authzStore(self, path):
        """Authorise a store request.

        @param path the destination file.
        @return bool for success or failure.
        """

        raise NotImplementedError
    

#--------------------------------------------------------------------------------------------------------------

class BasicClientAuthHandler(AuthHandler):
    """
    This class makes communicating with the stand alone bbftp client slightly easier.
    Mainly for use during testing.
    """

    def recvCStr(self):
        """Receive a message from the client which may contain \\0 characters indicating message end.

        The message is truncated to the first \\0 character.

        @return a string containing the message received.
        """

        msg = self.recv()
        # Trim to first '\0'
        x = msg.find('\0')
        if x:
            msg = msg[:x]

        return msg



class LiberalAuthzHandler(AuthzHandler):
    """Allow everything.
    """

    def __init__(self, username):
        self.username = username

    def authzControl(self, m, t, p):
        return True;

    def authzRetr(self, p):
        return True;

    def authzStore(self, p):
        return True;