« back to all changes in this revision
Viewing changes to doc/notes/architecture.txt
- browse files at revision 16
- compare with another revision
- compare with revision 1080.1.15
- download diff
- download tarball
- view history from revision 16
- Committer: mattgiuca
- Date: 2007-12-10 03:01:12 UTC
- Revision ID: svn-v3-trunk0:2b9c9e99-6f39-0410-b283-7f802c844ae2:trunk:16
design notes/architecture.txt: Reworked and added sections following
discussion with Tom Conway.
discussion with Tom Conway.
- files modified:
- doc/notes/architecture.txt
added
removed
doc/notes/architecture.txt
32
32
is common to the entire application (this replaces the standard handlers such
33
33
as Publisher).
34
34
35
This top-level handler handles all authentication issues (for instance,
35
This top-level handler handles all authentication (for instance,
36
36
checking the session to see if a user is logged in properly and if not,
37
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).
38
appropriate client based on the URL. The test of "whether the student is an
39
Informatics student" is considered part of the authentication layer. (So
40
students who are not enrolled in Informatics are treated the same way as a
41
garbage username).
42
43
Note that some clients ("login" and "exec") do not require authentication.
44
This will be one of the properties of the client in the global clients file.
45
46
Note that the handler does *not* perform authorization - that is left up to
47
the clients.
48
49
One special feature of the handler will be the ability to write an XHTML
50
header (which includes the user's name and links to profile page, IVLE logo,
51
and tabs for all the clients). This is important to keep a consistent
52
interface between the clients. This header will be available upon request from
53
the client. It is up to the client to NOT request a header for non-HTML
54
content (or it will be ruined), and also not to request a header when
55
executing student's code (ie. the exec module will never request a header).
51
56
52
57
### Plugin interface ###
53
58
59
64
display the client in the tabs).
60
65
61
66
Part of the HTML header which the handler generates is a set of tabs linking
62
to all of the clients in this list.
67
to all of the clients in this list, or at least the ones with "show in tabs"
68
turned on. Clients such as "exec" and "admin" will not have a tab.
63
69
64
70
Each client will be located physically in a directory "clients", in a
65
71
subdirectory of the client's name. (eg. the console is located in
66
72
"clients/console"). There *must* be a file in this directory called
67
73
**client.py**. This file is called by the handler for most requests.
68
74
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
All requests will go through the handler. Note that there is some media (such
76
as CSS, JavaScript and image files which are directly part of the application
77
itself), which we do not want to pass through the handler. These will be
78
placed in a special top-level directory, which Apache will be told to serve
79
directly. (eg. "/media").
75
80
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.
81
This means that the contents of each client directory is a Python program
82
*only*, and contains no files accessible by the browser. It consists of
83
client.py, plus any Python files imported by client.py (but none of these
84
files will directly serve web content).
78
85
79
86
Inside client.py, there is a fixed interface which all clients must follow.
80
87
Firstly, there is a set of information which the handler must pass to the
96
103
97
104
* set_mime_type(string) - Sets the output mime type. May be called any number
98
105
of times (including 0, will default to HTML), but may not be called after
99
any calls to `write`.
106
any writing has been done.
100
107
* set_status(string) - Sets the HTTP response status. The string is a numeric
101
108
code followed by a description, for example "404 File Not Found". May not be
102
called after any calls to `write`.
109
called after any writing has been done.
103
110
* set_location(string) - Sets the Location field of the HTTP response to a new
104
111
URL. For use with 300-level HTTP response codes. May not be called after any
105
calls to `write`.
112
writing has been done.
113
* write_html_headers() - Writes the general site headers to the output stream.
114
May not be called after any writing has been done.
106
115
* write(string) - Writes raw data to the output.
107
116
108
117
Note that this is very similar to the CGI interface, but much higher level (we
110
119
POST data in a packaged object instead of environment variables and stdin).
111
120
112
121
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.
122
(immediately when the first call to `write` or `write_html_headers` is made) -
123
in which the response headers are written to the server.
124
125
### Application directory hierarchy ###
126
127
Due to the handler, we have a nice property that the application directory
128
hierarchy is completely removed from the apparent hierarchy on the web. This
129
has two opportunities: we can call the applications (in their directory
130
hierarchy) a different name than the URL suggests, and also we can lay out the
131
directory hierarchy with developers interests in mind.
132
133
We capitalise on the first issue by mapping the "action" (url name) of a
134
client to the actual name. (Clients are indexed by url-name so they can
135
be looked up when a URL is requested).
136
137
The proposed application directory hierarchy is:
138
139
/
140
/clients - All clients go in here
141
/clients/myclient - "actual" names of the clients
142
/dispatch - Code files for the top-level dispatch
143
/dispatch.py - Entrypoint for the top-level dispatch
144
/media - Publically viewable files
145
(Note that this directory hierarchy maps onto the web site)
146
/media/myclient - media files specific to each client go in a subdir
147
/media/dispatch - media files for the top-level dispatch
148
/conf - Special .py files which hold configuration info (for the admin to
149
edit, not the programmers).
116
150
117
151
URLs
118
152
----
130
164
browse in the actual URL path, not the GET arguments.
131
165
* The URL does not contain the student's login name. This is implicit in the
132
166
browser session. (This requirement allows for us to link to URLs in
133
documentation which will work for any student).
167
documentation which will work for any student). (Note that URLs may contain
168
other students login names for browsing their work - this is determined by
169
the individual clients).
134
170
135
171
The top-level directory given in the URL determines the client which the
136
172
handler will pass off to. For instance,
139
175
140
176
Since IVLE is located at `http://www.example.com/ivle`, it will consider the
141
177
"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
178
whose action is "console". This may not be the actual name of the client. For
179
example, the "edit" action maps onto the "editor" client, while the "serve"
180
action maps onto the "exec" client. (Perhaps it is best for simplicity if
181
these do in fact correspond).
182
183
For another example, consider the file browser (action name "files"). The URL
184
may have subdirectories after it which indicate the path to explore. This will
185
be detailed in the clients section below. An example of a browse URL is:
186
187
http://www.example.com/ivle/files/jdoe/151/proj1/
188
189
In this instance, the handler will see the top-level directory as "files", and
150
190
will therefore link to the file browser client. The file browser client will
151
191
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/".
192
case are "jdoe/151/proj1/". The file browser client will then handle this path
193
and serve up the correct directory.
194
195
### Relative URLs inside HTML content ###
196
197
It is a requirement that the application can be placed anywhere in a web
198
server's directory hierarchy, not just at the top level. This means HTML
199
should never contain absolute URLs (beginning with, eg, "/browse"). Then it
200
would need to be in the site root.
201
202
To solve the problem of how to generate URLs, one of the fields the handler
203
will pass into the clients (which it will read from a config file somewhere)
204
will be the "site root". This may be "/ivle", for instance. Therefore all
205
absolute URLs generated by the applications must be prepended with the "site
206
root". (In our case the site root will probably be "/", but it's a good
207
feature to have).
208
209
### Student's directory hierarchy, common code ###
210
211
Many clients share the concept of exploring the student's directory hierarchy,
212
as explained above for the browser module. The common code for handling the
213
student id or group name (etc) and authorization will be available as a
214
separate module for all such clients (browser, editor, exec) to use.
156
215
157
216
Planned Clients
158
217
---------------
159
218
160
### File Browser ###
161
162
Top-level directory: `home`
163
164
### Text Editor ###
165
166
Top-level directory: `edit`
219
### File Browser, Text Editor and Executor ###
220
221
Three of the most important clients are the file browser ("browser"), text
222
editor ("editor") and executor ("exec"). These three share a commonality in
223
that they all access the student's directory hierarchy and files. They all
224
share a lot of code in common, and in particular, there is a common
225
server-side handler for file access, directory listings and subversion.
226
227
Firstly, every file and directory is classified into one of the following
228
categories (based on its inferred MIME type and possibly whether it contains
229
invalid Unicode characters):
230
231
1. Directory
232
2. Image
233
3. Audio
234
4. Text file (unless it fits the above, eg, SVG files)
235
5. Any other binary file
236
237
How each of these is handled depends on which of the 3 clients is accessing
238
the file.
239
240
#### File Browser ####
241
242
Name: `browser`
243
Action name: `files`
244
Tab name: "Files"
245
246
1. Directory - Displays a directory listing (this is its primary purpose).
247
2. Image - Displays the image inside the main navigation interface.
248
3. Audio - (non-core) Provides a streaming audio player within the main
249
navigation interface.
250
4. Text file - Redirect to edit.
251
5. Binary file - Provides a download link within the main navigation
252
interface.
253
254
Note that no matter what, using browser will remain within the navigation
255
interface so you will never be "lost" inside a raw image or something. It also
256
will not throw binary files as downloads directly to you.
257
258
Note that the src of the image tag in (2) and the href of the download link in
259
(5) will simply be links to the exec version of the same file.
260
261
File browser will include the Python file which serves up JSON responses to
262
requests for directory hierarchies, and performs SVN and file access commands.
263
This file will be used by the text editor (at least) and possibly exec.
264
265
#### Text Editor ####
266
267
Name: `editor`
268
Action name: `edit`
269
Tab name: "Edit"
270
271
No matter what, editor provides a text area (with advanced editing
272
capabilities and syntax highlighting) for any file, even if it is binary. The
273
only exception is directories, which redirect to browser.
274
275
Note that it will not be possible to click into the editor for a binary file
276
(the browser will not offer an edit link). However, it will still be possible
277
to manually nav there, and then you handle the shock yourself.
278
279
#### Executor ####
280
281
Name: `exec`
282
Action name: `serve`
283
Tab name: (not shown)
284
285
The executor is used to directly serve files out of a student's directory, as
286
if it was a standard web server. (It can be thought of as a little web server
287
inside IVLE). This means that:
288
289
* A whitelist of file types is kept which simply are served up raw. This
290
includes HTML, JavaScript, CSS, all reasonable image and audio formats, etc.
291
* Special "executable" file types (.py, .psp). Exec will call popen on a
292
Python process which loads a mod_python handler, cgihandler or psphandler on
293
the given file.
294
* HTTP errors for banned files.
295
296
**Discussion**: The question remains how exec should handle directories. It
297
*could* redirect to the browser, but this would only be feasible if the user
298
was logged in (exec is available to the public). I would prefer if it acted
299
like a web server, either presenting a basic directory listing (possibly
300
using part of the browser code), or just giving a HTTP 403 Forbidden error.
167
301
168
302
### Console ###
169
303
170
Top-level directory: `console`
304
Name: `console`
305
Action name: `console`
306
Tab name: "Console"
171
307
172
308
### Tutorial Pages ###
173
309
174
Top-level directory: `tutorial`
175
310
Name: `tutorial`
311
Action name: `tutorial`
312
Tab name: "Tutorial"
313
314
### Administration ###
315
316
Name: `admin`
317
Action name: `admin`
318
Tab name: (not shown)
319
320
Client checks authorization for admin status. Tab is not shown so students
321
will not normally know about this (but even if they find it they will be
322
denied access).
323
324
### Login ###
325
326
Name: `login`
327
Action name: `login`
328
Tab name: (not shown)
329
330
Authentication not required. Presents a login box.
331
332
Other similar clients are "logout" (which just immediately logs the current
333
user out and redirects to the main page), and "profile" (user settings).
Loggerhead is a web-based interface for Breezy
Version: 2.0.1