# shellac

`shellac` is a suite of software which aims to provides OS-level 
process control for the Elixir language. The software is composed of two
sub-projects which coordinate to accomplish this goal:

- `lacca`: an Elixir process control library, implemented as
  an OTP application which can be included in a `mix` project.

- `resin`: a Rust binary which acts as a companion to the `lacca`
  OTP application. This binary provides process control and 
  supervision, it also multiplexes the process's open file descriptors
  onto the single BEAM port.


## Build Instructions

You will need an Elixir toolchain (`mix`) and a Rust toolchain (`cargo`) to
properly build this project. From the project directory run the following
commands:

1. `mix deps.get` -- download dependencies

2. `mix deps.compile` -- compile dependences

3. `mix compile` -- compiles `lacca` to the `_build/` directory.

4. NOTE: the compile step will run `cargo build` on the `resin/` directory.
   The artifacts from this build will be placed in `priv/resin/` which must
   be deployed with the `lacca` OTP application.


Since this project builds native code (a Rust executable), you will need to
build this OTP application / release on the target platform. If you need to
change how the `resind` executable is built you can modify the `Makefile`
in this project directory.


## Protocol Versioning

The `lacca` and `resin` programs *do not* follow standard semantic versioning
guideliens. Please read the following to understand how the project's versions
are controlled. *The developer's suggest pinning both a major AND minor version*
when using build tools which expect semantic versioning. i.e: pin to
"\~> 1.3.0" rather than "\~> 1.3" in your build tool. This would allow the patch
version to change, but not the major or minor version.

The version number consits of `protocol`, `library`, and `patch` components.
Their significance to the project is as follows:

- `protocol` will whenever the protocol between `lacca` and `resin` are
  changed in non-backwards compatible ways. Newer major versions of `resin` 
  will work with older versions of `lacca`, but not vice versa.

- `minor` will be changed to reflect *breaking changes* to the program's API.
  - Such changes for `lacca` might include:
    - Removed functions
    - Change of non-optional arguments to a function
    - Change in return value from a function

  - Such changes to `resin` might include:
    - Command line options renamed or removed
    - Change in interpretation of command line arguments

- `patch` will be changed when backwards-compatible changes are introduced
  to either the protocol, library, or daemon.

NOTE: `v0` of the protocol is considered unstable. For best results 
you should always build and deploy the `v0` programs together.

## Protocol Format

`shellac` v0 packets are sent on the wire as follows:

- (n) 		two bytes identifying packet length
- (data)	packet specific data (n bytes, CBOR encoded)

### Packet Types

Packet types are as follows:

**TBD**

1. Start Process 	(exec: string, args: [string]])
2. Stop Process 	()
3. DataOut 			(ty: (Stdout | Stderr), buf: [u8])
5. DataIn 			(buf: [u8])

### Future Additions

- POSIX signal support?
- windows support?
- Standard stream redirection?
- Buffered input mode?

## Lacca Design

When the `lacca` application starts it will kick off a supervision
process. To start an OS-level process `lacca` will perform the
following initialization sequence:

- Start a child BEAM process w/ the given command line.

- Open a port to a `resin` daemon in `:binary` mode.

- Handshake w/ the `resin` daemon to verify matching protocol versions.

- Pass the initialization arguments to the `resin` daemon.

- Enter a message loop awaiting messages from the port, as well
  as messages from other peers in the Erlang VM.


## TODO

- resin: general clean up of error handling
  - what to do with errors if stdout goes away?
  - logging facilities?

- resin: signal handling architecture
  - need more generalized support for sending processes different kinds of
    signals, not just calling `Child::kill()`
  - wtf do we do on Windows land?

- resin: restructure as state machine?
  - there are bits of the server process state which don't exist until the
    inferior process is running. it would be nice if this was encoded in the
    type system as some kind of FSM so I can stop unwrapping Option<..>
    everywhere.

- resin: multi proc support
  - Should one daemon be able to handle multiple inferior processes?
    I think this is what `erlexec` does but I'm not sure.

- lacca: explore stdout/stderr space
  - with streams how do we signal EOF?
  - what if user wants to stream by line?
  - should we send messages to interested processes instead of a
    buffer that is read-once? (`flush()` destroys the contents of the
    buffer...)

- packaging (hex.pm): how do we distribute both halves effectively?
  distribute source and call `cargo` from Mix?