← Back to branch summary

~azzar1/unity/add-show-desktop-key

« back to all changes in this revision

Viewing changes to doc/dev/architecture.rst

  • Committer: David Coles
  • Date: 2009-11-27 06:11:18 UTC
  • mto: This revision was merged to the branch mainline in revision 1322.
  • Revision ID: coles.david@gmail.com-20091127061118-32rlhggn2fd6c27f
Chat protocol documentation and some stuff on Console.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/dev/architecture.rst
126
126
than the real memory used. For this reason :const:`RLIMIT_AS` is currently set 
127
127
very large.
128
128
 
129
 
Console
130
 
=======
 
129
Python Console
 
130
==============
 
131
 
 
132
IVLE provides a web based programming console, exposing similar features to 
 
133
Python's command line console. It is built around python script 
 
134
:file:`services/python-console` which opens up a socket to which `JSON`_ 
 
135
encoded chat requests can be made. A new console is typically from launched on 
 
136
demand by the web client to the HTTP API, which in turn calls the wrapper 
 
137
class :class:`ivle.console.Console` to start a new console in the user's jail.
 
138
 
 
139
.. _JSON: http://json.org
 
140
 
 
141
User Management Server
 
142
======================
 
143
 
 
144
.. TODO: Write!
 
145
 
 
146
Chat Protocol
 
147
=============
 
148
 
 
149
*Chat* is our JSON_-based client/server communication protocol used in 
 
150
communicating to `Python Console`_ processes and `User Management Server`_.  
 
151
Since it is JSON-based it can be called from either Python or JavaScript.
 
152
 
 
153
Protocol
 
154
--------
 
155
The protocol is a fairly simple client/server based one consisting of a single 
 
156
JSON object. Before communication starts a shared secret :const:`MAGIC` must 
 
157
be  known by both parties. The shared secret is then used to form a 
 
158
'keyed-Hash Message Authentication Code' to ensure that the content is valid 
 
159
and not been modified in transit.
 
160
 
 
161
The client request takes the following form::
 
162
 
 
163
    {
 
164
        "content": DATA,
 
165
        "digest": HASH
 
166
    }
 
167
 
 
168
where :const:`DATA` is any valid JSON value and :const:`HASH` is an string 
 
169
containing the MD5 hash of the :const:`DATA` appended to :const:`MAGIC` and 
 
170
then hex encoded.
 
171
 
 
172
The server will respond with a JSON value corresponding to the request.
 
173
If an error occurs then a special JSON object will be returned of the 
 
174
following form::
 
175
 
 
176
    {
 
177
        "type": NAME,
 
178
        "value": VALUE,
 
179
        "traceback": TRACEBACK
 
180
    }
 
181
 
 
182
where :const:`NAME` is a JSON string of the exception type (such as 
 
183
'AttributeError'), :const:`VALUE` is the string value associated with the 
 
184
exception and :const:`TRACEBACK` is a string of the traceback generated by the 
 
185
server's exception handler.
 
186
 
 
187
See :file:`ivle/chat.py` for details.
 
188
 
131
189
 
132
190
Version Control
133
191
===============