Merge branch 'develop'

Author: ethanhann

docs-src/configuration.md

@@ -13,7 +13,8 @@ Configuration is accomplished by modifying the appsettings.json file that comes
       "UseCompression": false,
       "PrimaryQueueConsumers":  16,
       "SecondaryQueueConsumers": 4,
-      "QueueName": "InEngine:Queue",
+      "QueueDriver": "redis",
+      "QueueName": "InEngineQueue",
       "RedisHost": "localhost",
       "RedisPort": 6379,
       "RedisDb": 0,
@@ -39,6 +40,7 @@ Configuration is accomplished by modifying the appsettings.json file that comes
 | UseCompression            | bool      | A situation performance optimization that compresses queued messages. |
 | PrimaryQueueConsumers     | string    | The number of consumers to schedule for the secondary queue.          |
 | SecondaryQueueConsumers   | string    | The number of consumers to schedule for the secondary queue.          |
+| QueueDriver               | string    | The driver to use to interact with a queue data store.                |
 | QueueName                 | string    | The base name of the queue, used to form the Redis Queue keys.        |
 | RedisHost                 | string    | The Redis hostname to connect to.                                     |
 | RedisPort                 | integer   | Redis's port.                                                         |

docs-src/index.md

@@ -1,22 +1,20 @@
-InEngine.NET allows commands to be [queued](queuing), [scheduled](scheduling), and run directly.
+InEngine.NET is a plugin-based software application that allows commands to be [queued](queuing), [scheduled](scheduling), and run directly.
 
 ## How does it work?
 
 InEngine.NET uses a plugin system to dynamically load .NET assemblies and execute code. 
 It also has a built-in command for launching external non-.NET programs.
 
-Get started by pulling the latest binaries from the [latest release](https://github.com/InEngine-NET/InEngine.NET/releases) on GitHub.
+Get started by pulling the binaries from the [latest release](https://github.com/InEngine-NET/InEngine.NET/releases) on GitHub.
 
-Then run a [command](commands):
+Then run a command the **echo** command from the core plugin:
 
 ```bash
 inengine.exe -pInEngine.Core echo --text"Hello, world"
 ```
-Or if you\'re a Linux or Mac OS X fan (like me!), use the **inengine** shell script ([Mono](http://www.mono-project.com/download/) required.):
+Or if you're a Linux or Mac OS X fan (like me!), use the **inengine** shell script ([Mono](http://www.mono-project.com/download/) is required):
 
 ```bash
-# or if you\'re a Linux fan like me... 
-
 inengine -pInEngine.Core echo --text"Hello, world"
 ```
 
@@ -32,7 +30,11 @@ Now run a command in a container:
 docker run --rm inengine -pInEngine.Core echo --text"Hello, world"
 ``` 
 
-Want to queue our example echo command to run in (possibly) another server?
+## How does queueing work?
+
+There are a lot of [queuing](queuing) features, but this is the gist...
+
+Want to queue our example echo command to run in the background or possibly on another server?
 
 Use the core plugin's **queue:publish** command:
 
@@ -48,11 +50,11 @@ Use the core plugin's **queue:consume** command of course:
 inengine.exe -pInEngine.Core queue:consume
 ``` 
 
-But what if I want to run some non-.NET code?
+## How do I run non-.NET commands?
 
-Use the core plugin's **proc** command to execute any program you like.
+There is a special **proc** command in the core plugin that allows for the execution of any program you can run at the command line. 
 
-Create a hello world python script called **helloworld.py**:
+For example, create a python script called **helloworld.py** that contains this:
 
 ```python
 print 'Hello, world!'

docs-src/queuing.md

@@ -2,10 +2,22 @@
 
 InEngine.NET's queue functionality allows for commands to be run in the background with a simple publish/consume model. 
 
-## Prerequisites
+## Queue Drivers
 
-Redis is required to use the InEngine.NET queue feature. 
-It can be installed on Ubuntu with this command:
+To make use of queue features, a queue driver must be specified in [appsettings.json](configuration).
+These are the available drivers...
+
+### File
+
+The file driver writes queued messages to the file system. 
+It is useful for testing and development, but probably not suitable for production.
+
+### Redis
+
+Redis is suitable for production use. 
+InEngine.NET utilizes Redis' durable queue features which mean messages will not be lost if InEngine.NET unexpectedly fails. 
+
+Redis can be installed on Ubuntu with this command:
 
 ```bash
 sudo apt-get install redis-server
@@ -19,22 +31,78 @@ sudo service redis start
 
 <div class="alert alert-info">
 It is highly recommended to <a href="https://redis.io/topics/security#authentication-feature">set a password</a> for Redis.
-</div>
+</div> 
+
+### Sync
+
+The sync driver causes the publish command to run a published command synchronously.
+All other queue commands and methods are not supported and will throw an exception if called.
+This driver can be useful for plugin development and testing.
 
 ## Publishing Commands
 
-### From Code
+### With C# Classes
+
+[Commands](commands) can be published programmatically with the **InEngine.Core.Queuing.Queue** class:
+
+```c#
+Queue.Make().Publish(new MyCommand());
+```
+
+Or publish to the secondary queue by passing true to the Make method:
+
+```c#
+Queue.Make(true).Publish(new MyCommand());
+```
+
+!!! note "Do I have to use Queue.Make()?"
+    Queue.Make() is a factory method that autoloads the queue settings from appsettings.json, creates the appropriate queue driver, and returns an instance of Queue.
+    You can create your own Queue object an initialize it if you want.
+    At the very least you can assign the object returned by Queue.Make() to a local variable or load it into a DI container for later use.
+
+### With Lambda Expressions
+
+Lambda expressions, aka anonymous functions, can be queued.
+The disadvantage to queuing lambdas is that the helpful functionality available in **InEngine.Core.AbstractCommand** is not available.  
+
+This is how you queue a lambda:
+
+```c#
+Queue.Make().Publish(() => Console.WriteLine("Hello, world!"));
+```
+
+Here is a neat shortcut for commands without parameters:
+
+```c#
+Queue.Make().Publish(() => Foo.Bar());
+// Can be rewritten as...
+Queue.Make().Publish(Foo.Bar);
+```
+
+### Sequentially In a Chain
+
+Chained commands run in the order specified.
+This is useful for when order matters.
+
+Also, if one command in the chain fails, then subsequent commands are not run at all.
+This affords the opportunity to add additional code that records which command failed, then resuming the command chain where it left off.
 
-[Commands](commands) can be published programmatically with the **InEngine.Core.Queuing.Broker** class:
+Here is a an example of how to chain an imaginary file transfer command together:
 
 ```c#
-Broker.Make().Publish(new MyCommand());
+Subject.Publish(new[] {
+    new MyFileTransfer(filePath1),
+    new MyFileTransfer(filePath2),
+    new MyFileTransfer(filePath3),
+});
 ```
 
-Or publish to the secondary queue:
 
 ```c#
-Broker.Make(true).Publish(new MyCommand());
+Subject.Publish(new List<AbstractCommand>() {
+    new AlwaysSucceed(),
+    new Echo() { VerbatimText = "Hello, world!"},
+});
 ```
 
 ### From the Command Line
@@ -62,17 +130,17 @@ inengine.exe -pInEngine.Core queue:publish --command-plugin=InEngine.Core.dll --
 ## Consuming Commands
 
 ### From Code
-Consuming a command is also accomplished with the Broker class:
+Consuming a command is also accomplished with the Queue class:
 
 ```c#
-Broker.Make().Consume();
+Queue.Make().Consume();
 ```
 
 The make method takes an optional second argument to indicate if the secondary queue should be used instead of the primary queue.
 
 ```c#
 // Uses secondary queue.
-Broker.Make(true).Consume();
+Queue.Make(true).Consume();
 ```
 
 Commands can be consumed from the command line as well with this simple command:
@@ -104,7 +172,7 @@ The **queue:length** command shows a quick summary of pending, in-progress, and
 inengine.exe -pInEngine.Core queue:length
 ```
 
-### Peek at Commands
+### Peek at Queued Commands
 
 The **queue:peek** command allows for queued commands to be inspected:
 

docs-src/scheduling.md

@@ -8,34 +8,45 @@ A job schedule is created by adding a class to your plugin assembly that impleme
 
 ```c#
 using System;
-using Quartz;
 
 namespace MyCommandPlugin
 {
     public class Jobs : IJobs
     {
-        public void Schedule(IScheduler scheduler)
+        public void Schedule(Schedule schedule)
         {
             // Schedule some jobs
         }
     }
 }
 ```
 
-This class is automatically discovered by the InEngine.NET scheduler.
+The InEngine.NET scheduler automatically discovers this class.
 It will call the Jobs.Schedule method with an initialized **InEngine.Scheduling.Schedule** object.
 
 ```c#
 using System;
-using Quartz;
 
 namespace MyCommandPlugin
 {
     public class Jobs : IJobs
     {
         public void Schedule(Schedule schedule)
         {
+            /* 
+             * Run MyCommand every five minutes. 
+             */
             schedule.Job(new MyCommand()).EveryFiveMinutes();
+            
+            /* 
+             * Run a lambda expression every ten minutes. 
+             */
+            schedule.Job(() => Console.WriteLine("Hello, world!")).EveryTenMinutes();
+            
+            /* 
+             * Run a parameterless method every five minutes. 
+             */
+            schedule.Job(() => Foo.Bar).EverySecond();
         }
     }
 }
@@ -219,10 +230,22 @@ sudo supervisorctl reread
 sudo supervisorctl update
 ```
 
-Now, simply start the InEngine Scheduler.
+Now, simply start the scheduler workers with the **supervisorctl** program:
 
 ```bash
 sudo supervisorctl start inengine-scheduler:*
 ```
 
+### In a Container with Docker
+
+Install [Docker](https://www.docker.com/what-docker) first, then pull the **ethanhann/inengine** image:
+
+```bash
+docker pull ethanhann/inengine:latest
+```
+
+Now run the scheduler:
 
+```bash
+docker run --rm inengine -s
+``` 

mkdocs.yml

@@ -8,7 +8,7 @@ copyright: © 2017 - Ethan Hann
 edit_uri: ''
 
 pages:
-- Getting Started: 'index.md'
+- Quickstart: 'index.md'
 - Documentation:
   - commands.md
   - scheduling.md
@@ -26,7 +26,7 @@ theme:
     primary: 'blue'
     accent: 'blue'
   feature:
-    tabs: false
+    tabs: true
 
 markdown_extensions:
   - admonition

src/InEngine.Core.Test/Commands/ChainTest.cs

@@ -0,0 +1,78 @@
+using System.Collections.Generic;
+using BeekmanLabs.UnitTesting;
+using InEngine.Commands;
+using InEngine.Core.Commands;
+using InEngine.Core.Exceptions;
+using Moq;
+using NUnit.Framework;
+using Quartz;
+
+namespace InEngine.Core.Test.Commands
+{
+    [TestFixture]
+    public class ChainTest : TestBase<Chain>
+    {
+        [SetUp]
+        public void Setup()
+        {
+        }
+
+        [Test]
+        public void ShouldRunChainOfCommands()
+        {
+            var mockCommand1 = new Mock<AbstractCommand>();
+            var mockCommand2 = new Mock<AbstractCommand>();
+            var commands = new[] {
+                mockCommand1.Object,
+                mockCommand2.Object,
+            };
+            Subject.Commands = commands;
+
+            Subject.Run();
+
+            mockCommand1.Verify(x => x.Run(), Times.Once());
+            mockCommand2.Verify(x => x.Run(), Times.Once());
+        }
+
+        [Test]
+        public void ShouldRunChainOfCommandsAndFail()
+        {
+            var mockCommand1 = new Mock<AlwaysFail>();
+            var mockCommand2 = new Mock<AlwaysFail>();
+            var alwaysFail = new AlwaysFail();
+            var commands = new[] {
+                mockCommand1.Object,
+                new AlwaysFail(),
+                mockCommand2.Object,
+            };
+            Subject.Commands = commands;
+
+            Assert.That(Subject.Run, Throws.TypeOf<CommandChainFailedException>());
+
+            mockCommand1.Verify(x => x.Run(), Times.Once());
+            mockCommand2.Verify(x => x.Run(), Times.Never());
+        }
+
+        [Test]
+        public void ShouldRunChainOfDifferentCommands()
+        {
+            Subject.Commands = new List<AbstractCommand>() {
+                new AlwaysSucceed(),
+                new Echo() { VerbatimText = "Hello, world!"},
+            };
+
+            Subject.Run();
+        }
+
+        [Test]
+        public void ShouldRunChainOfDifferentCommandsAsAbstractCommand()
+        {
+            Subject.Commands = new[] {
+                new AlwaysSucceed() as AbstractCommand,
+                new Echo() { VerbatimText = "Hello, world!"} as AbstractCommand,
+            };
+
+            Subject.Run();
+        }
+    }
+}

src/InEngine.Core.Test/InEngine.Core.Test.csproj

@@ -28,5 +28,9 @@
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </None>
   </ItemGroup>
+  <ItemGroup>
+    <Folder Include="Scheduling\" />
+    <Folder Include="Commands\" />
+  </ItemGroup>
 </Project>