Trader Client Description

The Trader Client works on several layers. At the top layer is the User Interface, this is a separate thread that handles everything that the Trader wants to do such as downloading files, making Offers, etc. At the lowest level is the Command layer, handling all input from other Traders, the WhereHouse Server, etc. Anything below this level is considered network layer, and beyond the reach of the Trader Client.

Making a Request

When a Trader clicks “Download Request” the User Interface creates a Download object and sets it running. This Download object inserts Download Data Block commands in to a Download Stream, sends Commands to the WhereHouse Server to request Data Blocks. This Download Stream is intelligently managed by the Trader Client so that it does not flood the WhereHouse Server with requests. The Download Stream has a thread that monitors the number of active requests at the Server and the amount of available bandwidth, as bandwidth becomes available so the Download Stream will send instructions to the Command layer to retrieve data.

Downloading an Offer requires that the Trader Client look in its database of Offers, retrieve the number of blocks that make up that Offer, and place an appropriate number of Request Data Block commands in to the Download Stream. An entry is added to the User Interface to signify that the Trade has been queued, this Trade may be removed from the queue at any time. To do this the Trader Client must clean up the Download Stream, close any active Transfers for that Trade and inform the WhereHouse Server to purge all Request Data Block commands from it’s own queue. The Trader Client expects an “OK” response from this purge command.

When the WhereHouse Server responds to a Request Data Block command it will send the Trader Client a Request Data Block ID, an Trader IP Address, a Cache Block ID and an MD5 checksum. To retrieve the Data Block the Trader Client must connect to the supplied IP address, send a Request Cache Block command along with the Request Data Block ID and the Cache Block ID. It will receive a Response Code of one of the following:
a) OK – the Response Code also contains a single Data Block (4KB of data) as a parameter
b) Request Data Block ID Invalid/Expired – the request is invalid or expired
c) Cache Block ID Invalid – a Cache Block was asked for that does not exist
d) Trader IP Invalid – the incoming trader’s IP address does not match the expected IP address

Once the transfer of data is complete the Trader Client should disconnect from the other Trader.

Once the Data Block is transferred the Trader Client should disconnect from the other Trader and the connection closed. The Trader Client should calculate a 128-bit MD5 checksum for the 4KB of data to ensure it’s integrity. This calculated checksum is compared against that supplied by the WhereHouse Server when the Request Data Block command was responded too. If they match then the data is good and can be placed on the hard drive for later shuffling. If the checksum is bad then the Data Block must be thrown away and a Request Data Block command for that Data Block placed in to the Download Stream again.

The Trader Client at the end of the MD5 calculation should send a Complete Data Block command to the WhereHouse Server that indicates whether the MD5 matches. If the Trader Client failed to receive all of the data, or if the connection was prematurely terminated, or if the Trader’s request for a Data Block was refused for any reason, or was unable to connect, the Trader Client should inform the WhereHouse Server with appropriate parameters. Three of the parameters that are sent to the WhereHouse Server with this Complete Data Block command are the Request Data Block ID, the Trader IP Address, and the Cache Block ID that the Trader Client originally received. The Server will use these items to monitor the network. Another parameter is how long the transfer took from when the Request Cache Block command was sent to the other Trader to when the connection was closed, in milliseconds. This is used by the Server to handle network statistics and Fair Trading parameters for each Trader.

The reason to use this mechanism is to prevent Traders just making a single request to the WhereHouse Server for a data block and then constantly connecting to another Trader to retrieve all Data Blocks from that location.

Request Data Block command (to server)
Request Cache Block command (to another Trader)
Request Data Block ID
Trader IP Address
Cache Block ID
Data Block (item)
Cache Block (item)