The purpose of this document is to help hackers find their way into the Mojo Nation broker source code. This document is doomed to be incomplete and flawed, but it will hopefully be better than nothing. This is a living document, so please ask questions, suggest changes, post patches, etc. The most up-to-date version of this file can always be found in CVS on SourceForge, and is browse-able over the web via this link. (You have click on the latest version number to get the document.)
There are two components of the Mojo Nation broker which are in place in a running system on a user's computer.
A diagram here would be nice!
The mojohttpd listens on a port (port 4004 by default) on the local network interface. It acts as a normal http server, handling requests from the users browser. The user can point their browser directly at the mojohttpd (for example, by opening URL "http://localhost:4004/broker"). The mojohttpd interprets certain URLs (for example "http://localhost:4004/broker/search_query?ctype=Audio" as commands for the Mojo Broker. It invokes the Mojo Broker through the Broker's Python API to satisfy each command. The mojohttpd also formats the results of each command and displays the results to the user by returning an HTML page on the HTTP connection.
The Broker is a Python module running in the same Python interpreter as the mojohttpd. The broker performs all of the computation and it communicates with other Mojo Brokers over the network in order to satisfy each user request.
The interface between the web browser and the proxy is the standard web proxy interface.
Note: this proven to be one of the most difficult parts of the whole system for end-users to install and configure, and it would be great if someone would hack an "automatically configure your web proxy" installer for Mojo Nation.
See AsyncMojoProxy for the proxy, which uses asychronous I/O.
The interface between the Mojo Proxy and the mojohttpd is straight HTTP.
Note: actually, there is also this whole issue of encryption/authentication between browser, proxy, and mojohttpd which I have ignored. Perhaps someone should edit this document and describe how it works.
See mojohttpd for the interface to mojohttpd.
The interface between the mojohttpd and the Broker is a set of Python functions.
There are many utility modules used by mojohttpd (e.g. mojosixbit') which provide simple, mostly stateless, functions, but only two modules that provide access to the complex, distributed functions of the Mojo Nation network. Those are contentlib which provides methods to query content trackers and to publish metadata to content trackers, and Archive which provides methods to 0 Nejucomo: please fix this; Only a couple of sentences are needed at this point.. Anyway, until nejucomo updates this, be aware that UserCommand seems to host the very important publishing functions, as well as maybe (?) parts of the content tracking and downloading functions.
The interface between one Broker and another is a "Mojo Transaction" over the Internet.
One Broker, acting as server, initiates the transaction by making a call to its "MojoTransaction" Python module. The other Broker, acting as server, handles the transaction by running one of her "handler" methods. See MojoTransaction for the Python interfaces for clients and servers to initiate and service transactions. See BlockServerEGTP for an example. See OurMessages for the formats of all of the messages used in the current protocols.
There are several layers of abstraction in the core of the Mojo Broker.
The highest layer is "business logic", which enables a Python hacker to easily configure prices, preferences among competing suppliers, and similar things. See accompanying document Writing Business Logic.
The next highest layer is "application level" code, which includes functions that publish and retrieve blocks, inform and query content trackers, publish and retrieve contact info (that is: the public key and communication strategies for a Broker), etc. A common theme in "application level" code is that it uses `MojoTransaction.initiate()' to perform transactions with other brokers over the network.
The next highest layer is the "Mojo Transaction layer", the interface to which is MojoTransaction.
Below the Mojo Transaction layer are a few more layers, to do cryptography, communications, etc. These will be described more later, especially if people start asking specific questions. The guts of the lower layers can be found in MojoTransaction (lots of functionality is in the file), Conversation, CommsHandler and its subclasses CryptoCommsHandler and TCPCommsHandler, and mesgen.