envato/medusa — pull request #13 by elseano (2014-06-10 03:04:43+00:00)
Title: Clean up responsibilities and add tests

This PR was originally just around adding tests to Master, but as I delved further into the quest, a new domain design emerged.

**Overlords**
The central intelligence within the Medusa system, the Overlord commands Keepers to run tests and collates results for any attached listeners.

**Keeper**
A Keeper claims a dungeon (which is provided by the Overlord). Keepers run on the same machine as the Overlord, and interface with the minion's union situated on a remote machine to run tests.

**Minion**
A minion runs around a Dungeon, doing any work required.

**Union**
The Union manages the Minion's workload, ensuring the nasty Keepers can't overload them with work. The Keeper - Union pair represents the communication between the controlling machine and a testing node, with the Union running on the machine remote to the Keeper's machine.

**UnionApprovedWorkspace**
Gives minions a forked process in which they can run their tasks, so they don't stomp on each others toes.

**Dungeon**
An area on a testing node dedicated to running tests. A dungeon is claimed by a Keeper and cannot run tests for any other Keeper while claimed. When a dungeon is created, it has a size, which dictates how many minions can be run.

**Labyrinth**
The labyrinth provides access to any number of dungeons running on a machine. The Overlord - Labyrinth pair is responsible for the initial discovery of any available testing nodes (with the help of DungeonDiscovery).

Interactions:

On the testing node (optional):

1. Labyrinth is created on a specific port.
2. Dungeons are added to the labyrinth, which can be claimed by a keeper.

On the developers or CI agent's machine:

1. An overlord is created and seeded with the files to run.
2. Keepers are added to the overlord, which indicate how many parellel processes should be run.
3. The overlord then instructs keepers to claim dungeons at a list of labyrinth addresses.
4. As dungeons are claimed, they are built according to the Overlord's project.
5. Once a dungeon is built, it fills itself to capacity with minions, and creates a Union which is returned to the keeper.
6. The overlord then sends work to keepers as each dungeon union permits.
7. As a minion completes their work file (assisted by the relevant Drivers), work progress is reported back through the Union, Keeper and Overlord, which then is forwarded to any listeners attached to the Overlord.
8. Once testing is complete, the Keepers abandon their dungeon, causing the collapse of the Union and the inevitable death of the minions represented.

**Usage**

A simple `medusa spec` will create a local labyrinth, and delegate work to it.

`medusa labyrinth localhost:18100` will create a labyrinth on the local machine on port 18100. Other machines can then use that labyrinth to execute specs by running `medusa -c localhost:18100 spec`. Additional labyrinths can be specified with additional `-c` options on the command line.