github.com/nycdavid/zeus@v0.0.0-20201208104106-9ba439429e03/docs/overview.md (about)

     1  # Zeus Overview
     2  
     3  Zeus is composed of three components:
     4  
     5  1. [The Master Process](../go/zeusmaster). This is written in Go, and coordinates all the other processes. It connects Clients to Slaves and handles reloading when files change.
     6  
     7  2. [Clients](../go/zeusclient). 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.
     8  
     9  3. [Slaves/Commands](../rubygem). 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. Though the Master and Client are completely language-agnostic, currently ruby is the only language for which a Slave shim exists.
    10  
    11  If you've read Tony Hoare's (or C.A.R. Hoare's) "Communicating Sequential Processes", [`csp.pdf`](http://www.usingcsp.com/cspbook.pdf) might be a bit helpful in addition to this document. I haven't studied the math enough for it to be fully correct, but it gets some of the point across.
    12  
    13  See: [`terminology.md`](terminology.md)
    14  
    15  ## Master Process
    16  
    17  ### Logical Modules
    18  
    19  1. Config
    20  
    21  2. ClientHandler
    22  
    23  3. FileMonitor
    24  
    25  4. SlaveMonitor
    26  
    27  ![arch.png](arch.png)
    28  
    29  The Master process revolves around the [`ProcessTree`](../go/processtree/processtree.go) -- 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.
    30  
    31  ### 1. Config
    32  
    33  This component reads the configuration file on initialization, and constructs the initial `ProcessTree` for the rest of the application to use.
    34  
    35  * [`config.go`](../go/config/config.go)
    36  * [`zeus.json`](../examples/zeus.json)
    37  
    38  ### 2. ClientHandler
    39  
    40  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.
    41  
    42  * [`clienthandler.go`](../go/clienthandler/clienthandler.go)
    43  
    44  ### 3. FileMonitor
    45  
    46  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.
    47  
    48  * [`filemonitor.go`](../go/filemonitor/filemonitor.go)
    49  * [`fsevents/main.m`](../ext/fsevents/main.m)
    50  
    51  ### 4. SlaveMonitor
    52  
    53  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.
    54  
    55  * [`slavemonitor.go`](../go/processtree/slavemonitor.go)
    56  * [`slavenode.go`](../go/processtree/slavenode.go)
    57  * [`master_slave_handshake.md`](master_slave_handshake.md)
    58  
    59  ## Client Process
    60  
    61  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.
    62  
    63  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.
    64  
    65  A handler is set up for SIGWINCH, again to forward it to the remote process, and keep both window sizes in sync.
    66  
    67  When the remote process exits, it reports its exit status, which the client process then exits with.
    68  
    69  * [`zeusclient.go`](../go/zeusclient/zeusclient.go)
    70  * [`client_master_handshake.md`](client_master_handshake.md)
    71  
    72  ## Slave/Command Processes
    73  
    74  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.
    75  
    76  * [`zeus.rb`](../rubygem/lib/zeus.rb)
    77  * [`zeus/rails.rb`](../rubygem/lib/zeus/rails.rb)
    78  
    79  ## Contributing to Zeus
    80  
    81  See the handy contribution guide at [`docs/contributing.md`](../contributing.md).
    82