Overview: Nest

Dargon.Nest is our application distribution system. Features include automated deployment, installation, and error reporting.

Key Concepts

Eggs represent standalone packages. For example, modifications are eggs. Eggs may be executed by the Nest Exeggutor. Eggs are spawned and instances are referred to as hatchlings. Individual C# projects are somewhat equatable to executable eggs.

Bundles represent collections of tightly-coupled eggs. Think of bundles as logical dependency-level releases. For example, the nest bundle contains nestd, nest-host, and nest-spawner, explained later. Eggs within bundles have full names defined as {bundle-name}/{egg-name} e.g. nest/nest-host. Standalone C# solutions are somewhat equatable to bundles.

Deployments represent collections of bundles. Think of deployments as application releases. For example, the dargon-client deployment contains core, client, trinket, and nest.

Eggs, Bundles, and Deployments all contain VERSION files, which are formatted semver-style; that is, in major.minor.patch-prerelease format. They also contain REMOTE files, which indicate their patching servers.

Nest Applications

Executable eggs deploy a file named {egg-name}.dll or {egg-name.exe} which export a public class implementing NestApplication.

public interface NestApplication {
   NestResult Start(HatchlingParameters parameters);
   NestResult Shutdown(ShutdownReason reason);
}

Executable eggs may leverage Dargon.Services to communicate with nestd in order to enumerate, spawn, and kill other eggs via the ExeggutorService.

Core Application Loop

Installation

1. User downloads and executes nest-spawner, our installer.
2. nest-spawner creates nest directory and downloads application packages.
3. nest-spawner fetches init package and places it in deployment directory.
4. nest-spawner registers init/init.exe to run at startup.
5. nest-spawner executes init/init.exe.

Startup Loop

1. init/init.exe is executed.
   a. Moves change from stage to bundles.
   b. Clears temp directory.
   c. Compacts log directories. d. Starts bundles/nest/nestd.exe.
2. bundles/nest/nestd.exe is executed.
   a. Iterates through bundles, processing their init.json scripts.
   b. Iterates through restart signals (see below).

init.json scripts and restart signals may trigger further operations, such as spawning hatchlings.

Spawning Hatchlings

1. nest/nestd.exe is the parent process of all hatchlings.
2. nest/nest-host.exe handles loading all hatchlings, instantiating their NestApplication implementations, and invoking Start(HatchlingParameters).

Restart Signals

Upon shutdown, nestd sends a shutdown signal to hosted hatchlings. The shutdown signal includes a ShutdownReason. Hatchlings may call host.SetRestartToken(HatchlingParameters hatchlingParameters) where hatchlingParameters contains the parameters to restart the egg.

Installation Layout

The below installation layout is copied from Dargon.Nest/InstallationLayout.txt

root
:- deployments
:  '- dargon-client
:     :- CHANNEL                    stable
:     :- REMOTE                     https://packages.dargon.io
:     :- VERSION                    0.0.0
:     :- LOCK
:     :- bundles
:     :  :- client
:     :  :  :- init.json
:     :  :  :- REMOTE
:     :  :  :- VERSION
:     :  :  :- cored
:     :  :  :- dargon-cli
:     :  :  '- dargon-client
:     :  '- nest  
:     :     :- REMOTE
:     :     :- VERSION
:     :     :- nest
:     :     :- nestd
:     :     :  :- nestd.exe
:     :     :  '- NEST_INIT
:     :     '- nest-host
:     :        '- nest-host.exe
:     :- cache
:     :  :- 3d72a9ce
:     :  '- b45a81f1
:     :- config
:     :  :- client
:     :  :  '- system-state.json
:     :  '- nest
:     :     '- system-state.json
:     :- init
:     :  :- init.exe
:     :  :- FILELIST
:     :  :- REMOTE
:     :  '- VERSION
:     :- logs
:     :  :- client
:     :  :  '- cored.log
:     :  '- nest
:     :     '- nestd.log
:     :- restart
:     :  '- trinket-10382
:     :- stage
:     :  '- client
:     :     '- cored
:     :        '- NEST_READY
:     '- temp
:        '- a9fe3452
:           '- cored
'- stage
   '- dargon-client