Permalink
Browse files

Improved documentation a bit

  • Loading branch information...
1 parent 3634ec9 commit 47b2640a37e4e6308805e1d3e99b3230001ffc19 @burke committed Sep 6, 2012
View
@@ -0,0 +1,61 @@
+# Zeus Overview
+
+Zeus is composed of three components:
+
+1. The Master Process. This is written in Go, and coordinates all the other processes. It connects Clients to Slaves and handles reloading when files change.
+
+2. Clients. The Client is also written in Go. It sends a command to the Master, and has its streams wired up to a Command process, to make it appear to be running locally.
+
+3. Slaves/Commands. These are the target application. A small shim, written in the target language, manages the communication between the application and the Master process, and boots the application in phases.
+
+See: [`terminology.md`](terminology.md)
+
+## Master Process
+
+### Logical Modules
+
+1. Config
+
+2. ClientHandler
+
+3. FileMonitor
+
+4. SlaveMonitor
+
+![arch.png](arch.png)
+
+The Master process revolves around the `ProcessTree` -- the core data structure that maintains most of the state of the application. Each module performs most of its communication with other modules through interactions with the Tree.
+
+### 1. Config
+
+This component reads the configuration file on initialization, and constructs the initial `ProcessTree` for the rest of the application to use.
+
+### 2. ClientHandler
+
+The `ClientHandler` listens on a socket for incoming requests from Client processes, and negotiates connections to running Slave processes. It is responsible for interactions with the client for its entire life-cycle.
+
+### 3. FileMonitor
+
+The `FileMonitor`'s job is to restart slaves when one of their dependencies has changed. Slaves are expected to report back with a list of files they have loaded. The `FileMonitor` listens for these messages and registers them with an external process that watches the filesystem for changes. When the external process reports a change, the `FileMonitor` restarts any slaves that have loaded that file.
+
+### 4. SlaveMonitor
+
+This component is responsible for communication with the target-language shim to manage booting and forking of application phase slaves. It constantly attempts to keep all slaves booted, restarting them when they are killed or die.
+
+See also: [`master_slave_handshake.md`](master_slave_handshake.md)
+
+## Client Process
+
+The client process is mostly about terminal configuration. It opens a PTY, sets it to raw mode (so that 'fancy' commands behave as if they were running locally), and passes the slave side of the PTY to the Master process.
+
+The client then sets up handlers to write STDIN to the PTY, and write the PTY's output to STDOUT. STDIN is scanned for certain escape codes (`^C`, `^\`, and `^Z`), which are sent as signals to the remote process to mimic the behaviour of a local process.
+
+A handler is set up for SIGWINCH, again to forward it to the remote process, and keep both window sizes in sync.
+
+When the remote process exits, it reports its exit status, which the client process then exits with.
+
+See also: [`client_master_handshake.md`](client_master_handshake.md)
+
+## Slave/Command Processes
+
+The Slave processes boot the actual application, and run commands. See [`master_slave_handshake.md`](master_slave_handshake.md), and the ruby implementation in the `rubygem` directory.
View
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -16,8 +16,7 @@
The Master always has a UNIX domain server listening at a known socket path.
-The Client connects to this server and sends a string indicating the command to run
-and any arguments to run with (ie. the ARGV). See message_format.md for more info.
+The Client connects to this server and sends a string indicating the command to run and any arguments to run with (ie. the ARGV). See message_format.md for more info.
#### 2. Terminal IO (Client -> Master)
@@ -43,15 +42,15 @@ The Client is now connected to the Command process.
#### 7. Exit status (Command -> Master)
-When the command terminates, it must send its exit code to the master. This is normally
-easiest to implement as a wrapper process that does the setsid, then forks the command
-and `waitpid`s on it.
+When the command terminates, it must send its exit code to the master. This is normally easiest to implement as a wrapper process that does the setsid, then forks the command and `waitpid`s on it.
-The form of this message is `{{code}}\n`, eg: `1\n`.
+The form of this message is `{{code}}`, eg: `1`.
#### 8. Exit status (Master -> Client)
Finally, the Master forwards the exit status to the Client. The command cycle is now complete.
-The form of this message is `{{code}}\n`, eg: `1\n`.
+The form of this message is `{{code}}`, eg: `1`.
+
+See [`message_format.md`](message_format.md) for more information on messages.
@@ -1,51 +0,0 @@
-# Overview of the Master Process
-
-The Master process all revolves around a single core data structure -- the `ProcessTree`.
-
-The `ProcessTree` represents a tree of all the processes that should exist when
-the application is fully booted. Each process is represented by a node. A node
-knows about:
-
-* the pid of the currently-running process (if booted);
-
-* the identifier as specified in the config file;
-
-* The action;
-
-* a list of pointers to child nodes;
-
-* A list of pointers to a different kind of node representing a command; and
-
-* A list of features this node requires that its parent does not.
-
-The command nodes contain:
-
-* the command name (identifier);
-
-* A list of aliases; and
-
-* The action.
-
-There are four main components to the Master process software. Each of these components is largely interested in working with the ProcessTree.
-
-### 1. Config
-
-This component reads the configuration file on initialization, and constructs the ProcessTree (empty of any pids, since everything remains unbooted for now).
-
-### 2. Slave Monitor
-
-This component is responsible for constantly attempting to boot any unbooted nodes in the ProcessTree. It is responsible for understanding
-that child nodes must be started by issuing commands to their parents in the tree, and it is responsible for listening for messages about
-dead child processes, and restarting those processes (after killing their orphaned children).
-
-### 3. Client Handler
-
-This component is responsible for listening for connections from Clients (see docs/terminology if this seems confusing).
-When a connection is received, this module issues a command to the Slave responsible for executing the requested Command,
-and negotiates the socket pairing. It is also responsible to returning the command process exit status to the client.
-
-### 4. File Monitor
-
-The file monitor is responsible for listening to messages from slaves indicating features loaded, and inserting them in the process tree.
-Additionally, it must interface with fsevents/inotify to watch for changes in these files, and kill processes (and all their children)
-when a file that has been loaded is changed.
@@ -2,8 +2,7 @@
There are a number of different types of messages passed between Master and Slave processes.
-In the interest of simplifying Slave libraries, messages are sent as single packets over a UNIX datagram socket,
-with a single-letter prefix, followed by a colon, indicating the message type.
+In the interest of simplifying Slave libraries, messages are sent as single packets over a UNIX datagram socket, with a single-letter prefix, followed by a colon, indicating the message type.
the parenthesesized values after each title are the message code, and the handling module.
@@ -1,39 +0,0 @@
-# Slave Monitor Overview
-
-The Slave Monitor is responsible for keeping each process in the process tree running.
-It is responsible for the initial boot of all processes, and then subsequent maintenance,
-by detecting when processes die, and restarting them.
-
-### Messages Handled
-
-* Pid & Identifier
-* Action
-* Action Response
-* Spawn Slave
-* Dead Child
-
-## Components
-
-The Slave Monitor has a few primary concerns:
-
-* Booting a Slave
-* Knowing when to boot a Slave
-
-A slave should be booted when it is not running, but its parent is (or it is
-the root state).
-
-When a Slave has terminated, all of its children should be killed immediately,
-with SIGKILL.
-
-Booting a slave involves forking a process, negotiating sockets, pid, action,
-and result. After this is done, the slave is ready.
-
-The major problem is how to communicate this information about process states.
-
-When a slave is booted, we can publish its identifer on a channel. A goroutine
-will listen on this channel, look up all its child nodes, and start booting them.
-
-When a slave dies, it will also be published on a channel. A goroutine will pull
-the entry off the channel, kill all its children, and initiate rebooting.
-
-

0 comments on commit 47b2640

Please sign in to comment.