earthworm

"benevolent virus propagation" for team file sharing

Network Protocols

Network communication between machines is handled using HTTP. Each machine runs its own HTTP server listening on port 13370 (not the standard HTTP port 80). The HTTP server listens for various requests made by clients and responds to them appropriately.

Clients decide for themselves which port(s) they want to make requests from. In our Earthworm software, those ports are automatically decided by the Python HTTP request library.


Getting a file list

To retrieve a remote machine's dropbox file list containing MD5 hashes, last modified times, and file names, send the following to the remote server on port 13370:


Request type: GET
Request path: /
Headers: (none needed)

The response is a HTTP 200 (OK) response with a plain text list of the files on the remote machine. Each file is on a new line (\r\n delimited). Each line contains a file's MD5 hash, last modified date in UTC (Universal Coordinated Time), and file path, all tab-delimited. An example is: 

d1cf36299c8e74378962f3e06a7de5a9   2008-12-03T16:32:07Z   readme.txt
70d0da5c86754fd9e7bf5391957f6a52   2008-12-03T02:38:46Z   test.txt

Note that you can use a web browser to view the file list by pointing it to http://serverAddress:13370/, since web browsers make GET requests to addresses typed into their address bars.


Retrieving files

To retrieve a file /fileName.ext from a remote machine, send the following request to the server on port 13370:


Request type: GET
Request path: /fileName.ext
Headers: (none needed)

If the file is on the remote machine, the response is a HTTP 200 (OK) response with the file as the response body. Note that you can use a web browser to view or download the file by pointing it to http://serverAddress:13370/fileName.ext, since web browsers make GET requests to addresses typed into their address bars.

If the file does not exist, the response is a HTTP 404 (Not Found) response.


Requesting a file grab

Say two people, Alex and Bryn, are running Earthworm. Alex adds two files to his dropbox, "file1.ext" and "file2.ext", and he wants to ask Bryn to get the new files from him. Alex sends a file grab request to Bryn's machine on port 13370, asking that Bryn retrieve the files from his machine:


Request type: POST
Request path: /
Headers:
X-EarthwormFT-GrabFiles
file1.ext
file2.ext

Note that the files in the X-EarthwormFT-GrabFiles header are delimited by \r\n.

Bryn's machine, upon receiving the grab request, will send a HTTP 200 (OK) response to Alex, then retrieve files one-by-one from Alex's machine using the method described in the "Retrieving files" section above, assuming his machine is running the Earthworm server.


Requesting a file delete

Say two people, Alex and Bryn, are running Earthworm. Alex deletes two files from his dropbox, "file1.ext" and "file2.ext", and he wants to ask Bryn to delete the files from her machine as well. Alex sends a file delete request to Bryn's machine on the port 13370:

Request type: POST
Request path: /
Headers:
X-EarthwormFT-DeleteFiles
file1.ext
file2.ext

Note that the files in the X-EarthwormFT-DeleteFiles header are delimited by \r\n.

Bryn's machine, upon receiving the delete request, will send a HTTP 200 (OK) response to Alex, then delete the appropriate files from her machine.


Last modified by Eric Hwang on 2008-12-16


Earthworm was created for ENGR 3410 (Computer Architecture) at Olin College of Engineering in Needham, Massachusetts.


Team Earthworm is: Leslie Gerhat, Eric Hwang, Katarina Miller, Raghu Rangan, and Garrett Rodrigues (Class of 2010).