~azzar1/unity/add-show-desktop-key : revision 15

1

IVLE - System Architecture

2

==========================

3

4

Author: Matt Giuca

5

Date: 10/12/2007

6

7

This document describes the high-level system architecture of IVLE,

8

specifically with respect to the "pluggable clients" interface.

9

10

Users and authorization

11

-----------------------

12

13

We need some way to authenticate users and store information about a logged-in

14

user. Whether they are stored in a database local to our system remains to be

15

seen.

16

17

Importantly, we need some way to send user information to the clients. This is

18

discussed in the "pluggable clients" section.

19

20

Pluggable clients

21

-----------------

22

23

The IVLE system is largely just a collection of various components, called

24

"clients", such as the file browser, text editor, console, tutorial sheets,

25

etc.

26

27

The architecture provides a common interface in which clients can be plugged

28

in.

29

30

Firstly, we want all HTML pages on the site to be generated with a common

31

header. The easiest way to do this is to write our own Python handler which

32

is common to the entire application (this replaces the standard handlers such

33

as Publisher).

34

35

This top-level handler handles all authentication issues (for instance,

36

checking the session to see if a user is logged in properly and if not,

37

redirecting to the login page). It then outputs the header, and calls the

38

appropriate client based on the URL.

39

40

Before the handler outputs a HTML header, it needs to consult the client to

41

see what the MIME type is of the page being requested. For instance, many

42

requested files will output JSON instead of HTML. Therefore part of the client

43

interface will be a mime type declaration. The handler queries this first,

44

completes the HTTP headers, and then proceeds to write an XHTML heading

45

section iff the mime type is appropriate for HTML content.

46

47

Clients *must* supply the correct MIME type as the handler is allowed to make

48

such inferences based on the MIME type. (For example, returning JSON content

49

with a mime type of "text/html" is bad because the handler will then write an

50

HTML header section).

51

52

### Plugin interface ###

53

54

The top-level handler will keep a Python file (or a text, JSON, etc file)

55

containing a list of valid clients. This is a dictionary mapping clients'

56

internal names (the top-level directories, as described below in "URLs" and

57

the "planned clients") to some other date about the clients (such as a

58

friendly name to display in the tabs, and a boolean as to whether or not to

59

display the client in the tabs).

60

61

Part of the HTML header which the handler generates is a set of tabs linking

62

to all of the clients in this list.

63

64

Each client will be located physically in a directory "clients", in a

65

subdirectory of the client's name. (eg. the console is located in

66

"clients/console"). There *must* be a file in this directory called

67

**client.py**. This file is called by the handler for most requests.

68

69

**Discussion**: We want the handler to handle many requests (such as for CSS,

70

JavaScript and image files) directly, simply loading a file from an absolute

71

location and serving it. Is it OK to simply have a list of file extensions

72

which will automatically be served without going into the client interface?

73

(eg. .js, .css, .jpg, etc). If so, can we let the webserver do this without

74

even bothering our main handler?

75

76

The remainder of this discussion ignores the possibility of such "unhandled"

77

files, assuming they have been served up and not passed to the client.

78

79

Inside client.py, there is a fixed interface which all clients must follow.

80

Firstly, there is a set of information which the handler must pass to the

81

client in numerous calls - such as username, URL, and nicely split up parts of

82

the URL such as the path, the GET variables, and also the POST data, as well

83

as mod_python's low-level Request object.

84

This information is encapsulated into an object and passed as a single

85

argument to the client handling functions.

86

87

Note that as stated above, the handler may need to insert HTML contents into

88

the output stream. Instead of having two separate function calls (a call to

89

find the mime type and a call to get content), we'll simply provide a wrapper

90

object to the client where the client can make callbacks to.

91

92

To this end, the client receives an object containing all of the information,

93

as well as an object with some methods to call. The handler passes this to a

94

function in client.py, `handle`. The callback object contains the following

95

methods:

96

97

* set_mime_type(string) - Sets the output mime type. May be called any number

98

of times (including 0, will default to HTML), but may not be called after

99

any calls to `write`.

100

* set_status(string) - Sets the HTTP response status. The string is a numeric

101

code followed by a description, for example "404 File Not Found". May not be

102

called after any calls to `write`.

103

* set_location(string) - Sets the Location field of the HTTP response to a new

104

URL. For use with 300-level HTTP response codes. May not be called after any

105

calls to `write`.

106

* write(string) - Writes raw data to the output.

107

108

Note that this is very similar to the CGI interface, but much higher level (we

109

have functions to call instead of writing strings, and we send the GET and

110

POST data in a packaged object instead of environment variables and stdin).

111

112

Note that, as with CGI, there is a "cutoff point" during the processing

113

(immediately when the first call to `write` is made) - in which the response

114

headers are written to the server. It is during this point that the handler

115

also writes the HTML header if the mime type is appropriate.

116

117

URLs

118

----

119

120

It would be good if we had full control of URLs and were able to make them

121

"nice" at all times. The criteria for "nice" URLs are as follows:

122

123

* The paths in the URLs reflect a sensible hierarchy of where you are in the

124

program at the current time.

125

* The URLs do not contain any file extensions for the pages (no .html or

126

.py), although linked files such as CSS, JavaScript and image files should

127

have appropriate file extensions.

128

* The URLs do not contain unnecessary garbage arguments, and preferably no GET

129

arguments at all (for instance, the file browser will specify the path to

130

browse in the actual URL path, not the GET arguments.

131

* The URL does not contain the student's login name. This is implicit in the

132

browser session. (This requirement allows for us to link to URLs in

133

documentation which will work for any student).

134

135

The top-level directory given in the URL determines the client which the

136

handler will pass off to. For instance,

137

138

http://www.example.com/ivle/console

139

140

Since IVLE is located at `http://www.example.com/ivle`, it will consider the

141

"top-level directory" to be "console", and therefore will call the client

142

"console".

143

144

The file browser's client name will be "home". This is a bit of a trick to

145

allow the file browser URLs to be completely natural. eg:

146

147

http://www.example.com/ivle/home/151/proj1/

148

149

In this instance, the handler will see the top-level directory as "home", and

150

will therefore link to the file browser client. The file browser client will

151

then receive the additional arguments passed to it in some way, which in this

152

case are "/151/proj1/". The file browser will know where students directories

153

are stored (maybe "/home/students/") and also know the name of the student

154

from the session information, and will therefore be able to navigate to

155

"/home/students/jbloggs/151/proj1/".

156

157

Planned Clients

158

---------------

159

160

### File Browser ###

161

162

Top-level directory: `home`

163

164

### Text Editor ###

165

166

Top-level directory: `edit`

167

168

### Console ###

169

170

Top-level directory: `console`

171

172

### Tutorial Pages ###

173

174

Top-level directory: `tutorial`

175