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

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI05-delivery/trunk/lib/python/delivery/server.py@1187
Revision 1187, 4.9 KB checked in by spascoe, 13 years ago (diff)

Auto-generated documentation included for the python-server interface.

Some file clean up prior to alpha. Fixed some confusion between authentication
and authorisation in the API.

The embedded client test case is disabled because it doesn't work :-(.

Line 
1"""
2Start a bbftp server process and define python callbacks for authentication and authorisation.
3
4Interface to the BBftp server.
5
6@copyright Copyright (C) 2006 CCLRC & NERC
7@license This software may be distributed under the terms of the Q Public Licence, version 1.0 or later.
8
9@author Stephen Pascoe
10"""
11
12import bbftpd
13
14def start(authHandler, args):
15    """Start the bbftp server.
16
17    The server performs a fork() during initialisation, the child process remains in
18    the server's main loop and the parent returns from this function.  The server process
19    calls authHandler.authorise() on each connection to do authentication/authorisation.
20
21    @note because the server process forks, authHandler will not see any changes to the python
22        interpreter following the call to start().
23
24    @param authHandler an instance of AuthHandler.
25    @param args a list of command line arguments.
26    @return the PID of the server process.
27    """
28   
29    return bbftpd.run(authHandler, args)
30
31
32class AuthenticationFailure(Exception):
33    """Signals authentication failed.
34    """
35    pass
36
37class AuthorisationFailure(Exception):
38    """Signals authorisation failed.
39    """
40    pass
41
42
43
44class AuthHandler(object):
45    """Abstract base class for implementing authentication.
46
47    Subclasses should implement the authorise() method to authenticate clients connecting to
48    the server.  An AuthHandler object is passed to start() when initialising the server.
49    """
50   
51    def send(self, buffer):
52        """Send a message to the client during authorisation.
53
54        This method must only be used from within self.authorise() which has been called
55        from the bbftp server process started by start().
56
57        @param buffer a string containing the message to send.
58        """
59   
60        return bbftpd.send(buffer)
61
62    def recv(self):
63        """Receive a message from the client during authorisation.
64
65        This method must only be used from within self.authorise() which has been called
66        from the bbftp server process started by start().
67
68        @return a string containing the message received.
69        """
70
71        return bbftpd.recv()
72
73    def authenticate(self):
74        """Authenticate a connection.
75
76        This function should be overridden in subclasses to implement authentication using
77        the method calls self.send() and send.recv().  It is called by the bbftp server process
78        created using the start() function.
79
80        @note because the server process forks on each connection, calls to authorise() will
81            see the state of the python interpreter as it was when start() was called.
82
83        @return an AuthzHandler instance if authentication succeeds.  Any false value is considered
84            an authorisation failure.
85        @raise AuthorisationFailure the preferred way of signaling authorisation failure to
86            the bbftp server process.
87        """
88
89        raise NotImplementedError
90
91
92class AuthzHandler(object):
93    """Abstract base class for implementing authorisation.
94
95    @ivar username: the client's username.  This attribute must be set before an instance of AuthzHandler
96        is returned to the bbftp server process by AuthHandler.authenticate().
97       
98    """
99
100    def authzControl(self, msgcode, transferoption, path):
101        """Authorise a control command.
102
103        @param msgcode the command type.
104        @param transferoption extra options specified in the command.
105        @param path the file or directory to which the command applies.
106        @return bool for success or failure.
107        """
108
109        raise NotImplementedError
110
111    def authzRetr(self, path):
112        """Authorise a retrieve request.
113
114        @param path the file being retrieved.
115        @return bool for success or failure.
116        """
117
118        raise NotImplementedError
119
120    def authzStore(self, path):
121        """Authorise a store request.
122
123        @param path the destination file.
124        @return bool for success or failure.
125        """
126
127        raise NotImplementedError
128   
129
130#--------------------------------------------------------------------------------------------------------------
131
132class BasicClientAuthHandler(AuthHandler):
133    """
134    This class makes communicating with the stand alone bbftp client slightly easier.
135    Mainly for use during testing.
136    """
137
138    def recvCStr(self):
139        """Receive a message from the client which may contain \\0 characters indicating message end.
140
141        The message is truncated to the first \\0 character.
142
143        @return a string containing the message received.
144        """
145
146        msg = self.recv()
147        # Trim to first '\0'
148        x = msg.find('\0')
149        if x:
150            msg = msg[:x]
151
152        return msg
153
154
155
156class LiberalAuthzHandler(AuthzHandler):
157    """Allow everything.
158    """
159
160    def __init__(self, username):
161        self.username = username
162
163    def authzControl(self, m, t, p):
164        return True;
165
166    def authzRetr(self, p):
167        return True;
168
169    def authzStore(self, p):
170        return True;
171   
Note: See TracBrowser for help on using the repository browser.