Plugins: Test harness, test fixture, docs, and local-type example

.rubocop.yml

@@ -4,7 +4,7 @@ AllCops:
   - Gemfile
   - Rakefile
   - 'test/**/*'
-  - 'examples/**/*'
+  - 'examples/plugins/train-*/test/**/*'
   - 'vendor/**/*'
 Documentation:
   Enabled: false

Gemfile

@@ -25,7 +25,7 @@ group :test do
   # (Gem::Specification.find_by_path('train-gem-fixture') will return nil)
   # but it's close enough to show the gempath handler can find a plugin
   # See test/unit/
-  gem 'train-gem-fixture', path: 'test/fixtures/gempath/gems'
+  gem 'train-test-fixture', path: 'test/fixtures/plugins/train-test-fixture'
 end
 
 group :integration do

docs/plugins.md

@@ -0,0 +1,79 @@
+# Train Plugins
+
+## Introducing Plugins
+
+Train plugins are a way to add new transports and platform detection to Train.
+
+If you are familiar with InSpec plugins, be forewarned; the two plugin systems are not similar.
+
+### Why Plugins?
+
+#### Benefits of plugins
+
+Plugins address two main needs that the Chef InSpec Engineering team encountered in 2017-2018.
+
+* Passionate contributors parties can develop and release new Train transports at their own pace, without gating by Chef engineers.
+* Reduction of dependency bloat within Train.  For example, since only the AWS transport need the aws-sdk, we can move the gem dependency into the plugin gem, and out of train itself.
+
+#### Future of existing Transports
+
+The Chef InSpec Engineering team currently (October 2018) plans to migrate most existing Train transports into plugins.  For example, AWS, Azure, and GCP are all excellent candidates for migration to plugin status.  The team commits to keeping SSH, WinRM, and Local transports in Train core.  All other transports may be migrated.
+
+In the near-term, InSpec will carry a gemspec dependency on the migrated plugins.  This will continue a smooth experience for users relying on (for example) Azure.
+
+## Managing Plugins
+
+### Installing and Managing Train Plugins as an InSpec User
+
+InSpec has a command-line plugin management interface, which is used for managing both InSpec plugins and Train plugins.  For example, to install `train-aws`, simply run:
+
+```bash
+$ inspec plugin install train-aws
+```
+
+The management facility can install, update, and remove plugins, including their dependencies.
+
+### Installing Train Plugins outside of InSpec
+
+If you need a train plugin installed, and `inspec plugin` is not available to you, you can install a train plugin like any other gem.  Just be sure to use the `gem` binary that comes with the application you wish to extend.  For example, to add a Train Plugin to a ChefDK installation, use:
+
+```bash
+$ chef exec gem install train-something
+```
+
+### Finding Train plugins
+
+Train plugins can be found by running:
+
+```bash
+$ inspec plugin search train-
+```
+
+If you are not an InSpec user, you may also perform a rubygems search.
+
+## Developing Train Plugins for the Train Plugin API v1
+
+Train plugins are gems.  Their names always start with 'train-'.
+
+You can use the example plugin at [the Train github project](https://github.com/inspec/train/tree/master/examples/train-local-rot13) as a starting point.
+
+### The Entry Point
+
+As with any Gem library, you should create a file with the name of your plugin, which loads the remaining files you need.  Some plugins place them in 1 file, but it is cleaner to place them in 4: a version file, then transport, connection and platform files.
+
+### The Transport File
+
+In this file, you should define a class that inherits from `Train.plugin(1)`.  The class returned will be `Train::Plugins::Transport` or a descendant.  This superclass provides DSL methods for you to configure your plugin.
+
+#### name
+
+Required. Use the `name` call to register your plugin.  Pass a String, which should have the 'train-' portion removed.
+
+#### option
+
+
+
+### The Connection
+
+### Platform Detection
+

examples/plugins/train-local-rot13/Gemfile

@@ -0,0 +1,20 @@
+# encoding: utf-8
+source 'https://rubygems.org'
+
+# This is Gemfile, which is used by bundler
+# to ensure a coherent set of gems is installed.
+# This file lists dependencies needed when outside
+# of a gem (the gemspec lists deps for gem deployment)
+
+# Bundler should refer to the gemspec for any dependencies.
+gemspec
+
+# Remaining group is only used for development.
+group :development do
+  gem 'bundler'
+  gem 'byebug'
+  gem 'inspec', '>= 2.2.112' # We need InSpec for the test harness while developing.
+  gem 'minitest'
+  gem 'rake'
+  gem 'rubocop', '= 0.49.1' # Need to keep in sync with main InSpec project, so config files will work
+end

examples/plugins/train-local-rot13/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2018 Chef Software Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

examples/plugins/train-local-rot13/README.md

@@ -0,0 +1,72 @@
+# Example Train Plugin - train-local-rot13
+
+This plugin is provided as a teaching example for building a Train plugin.  Train plugins allow you to connect to remote systems or APIs, so that other tools such as InSpec or Chef Workstation can talk over the connection.
+
+train-local-rot13's functionality is simple: it acts as a local transport (targeting the local machine), but it applies the [rot13](https://en.wikipedia.org/wiki/ROT13) trivial cypher transformation on the contents of each file it reads, and on the stdout of ever command it executes.
+
+Please note that ROT13 is an incredibly weak cypher, and can be broken by most elementary school students.  Do not use this plugin for security purposes.
+
+## Relationship between InSpec and Train
+
+Train itself has no CLI, nor a sophisticated test harness.  InSpec does have such facilities, so installing Train plugins will require an InSpec installation.  You do not need to use or understand InSpec.
+
+Train plugins may be developed without an InSpec installation.
+
+## To Install this as a User
+
+You will need InSpec v2.3 or later.
+
+If you just want to use this (not learn how to write a plugin), you can so by simply running:
+
+```
+$ inspec plugin install train-local-rot13
+```
+
+You can then run:
+
+```
+$ inspec detect -t local-rot13://
+== Platform Details
+
+Name:      local-rot13
+Families:  unix, os, windows, os
+Release:   0.1.0
+Arch:      example
+
+$ inspec shell -t local-rot13:// -c 'command("echo hello")'
+uryyb
+```
+
+## Features of This Example Kit
+
+This example plugin is a full-fledged plugin example, with everything a real-world, industrial grade plugin would have, including:
+
+* an implementation of a Train plugin, using the Train Plugin V1 API, including
+  * a Transport
+  * a Connection
+  * Platform configuration
+* documentation (you are reading it now)
+* tests, at the unit and functional level
+* a .gemspec, for packaging and publishing it as a gem
+* a Gemfile, for managing its dependencies
+* a Rakefile, for running development tasks
+* Rubocop linting support for using the base Train project rubocop.yml (See Rakefile)
+
+You are encouraged to use this plugin as a starting point for real plugins.
+
+## Development of a Plugin
+
+[Plugin Development](https://github.com/inspec/train/blob/master/docs/dev/plugins.md) is documented on the `train` project on GitHub.  Additionally, this example
+plugin has extensive comments explaining what is happening, and why.
+
+### A Tour of the Plugin
+
+One nice circuit of the plugin might be:
+ * look at the gemspec, to see what the plugin thinks it does
+ * look at the functional tests, to see the plugin proving it does what it says
+ * look at the unit tests, to see how the plugin claims it is internally structured
+ * look at the Rakefile, to see how to interact with the project
+ * look at lib/train-local-rot13.rb, the entry point which InSpec will always load if the plugin is installed
+ * look at lib/train-local-rot13/transport.rb, the plugin "backbone"
+ * look at lib/train-local-rot13/connection.rb, the plugin implementation
+ * look at lib/train-local-rot13/platform.rb, OS plform support declaration

examples/plugins/train-local-rot13/Rakefile

@@ -0,0 +1,41 @@
+# A Rakefile defines tasks to help maintain your project.
+# Rake provides several task templates that are useful.
+
+#------------------------------------------------------------------#
+#                    Test Runner Tasks
+#------------------------------------------------------------------#
+
+# This task template will make a task named 'test', and run
+# the tests that it finds.
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs.push 'lib'
+  t.test_files = FileList[
+    'test/unit/*_test.rb',
+    'test/integration/*_test.rb',
+    'test/function/*_test.rb',
+  ]
+  t.verbose = true
+  # Ideally, we'd run tests with warnings enabled,
+  # but the dependent gems have many warnings. As this
+  # is an example, let's disable them so the testing
+  # experience is cleaner.
+  t.warning = false
+end
+
+#------------------------------------------------------------------#
+#                    Code Style Tasks
+#------------------------------------------------------------------#
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new(:lint) do |t|
+  # Choices of rubocop rules to enforce are deeply personal.
+  # Here, we set things up so that your plugin will use the Bundler-installed
+  # train gem's copy of the Train project's rubocop.yml file (which
+  # is indeed packaged with the train gem).
+  require 'train/globals'
+  train_rubocop_yml = File.join(Train.src_root, '.rubocop.yml')
+
+  t.options = ['--display-cop-names', '--config', train_rubocop_yml]
+end

examples/plugins/train-local-rot13/lib/train-local-rot13.rb

@@ -0,0 +1,21 @@
+# This file is known as the "entry point."
+# This is the file Train will try to load if it
+# thinks your plugin is needed.
+
+# The *only* thing this file should do is setup the
+# load path, then load plugin files.
+
+# Next two lines simply add the path of the gem to the load path.
+# This is not needed when being loaded as a gem; but when doing
+# plugin development, you may need it.  Either way, it's harmless.
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+# It's traditonal to keep your gem version in a separate file, so CI can find it easier.
+require 'train-local-rot13/version'
+
+# A train plugin has three components: Transport, Connection, and Platform.
+# Transport acts as the glue.
+require 'train-local-rot13/transport'
+require 'train-local-rot13/platform'
+require 'train-local-rot13/connection'

examples/plugins/train-local-rot13/lib/train-local-rot13/connection.rb

@@ -0,0 +1,84 @@
+# Connection definition file for an example Train plugin.
+
+# Most of the work of a Train plugin happens in this file.
+# Connections derive from Train::Plugins::Transport::BaseConnection,
+# and provide a variety of services.  Later generations of the plugin
+# API will likely separate out these responsibilities, but for now,
+# some of the responsibilities include:
+# * authentication to the target
+# * platform / release /family detection
+# * caching
+# * filesystem access
+# * remote command execution
+# * API execution
+# * marshalling to / from JSON
+# You don't have to worry about most of this.
+
+# Push platform detection out to a mixin, as it tends
+# to develop at a different cadence than the rest
+require 'train-local-rot13/platform'
+
+# This is a support library for our file content meddling
+require 'train-local-rot13/file_content_rotator'
+
+# This is a support library for our command meddling
+require 'mixlib/shellout'
+require 'ostruct'
+
+module TrainPlugins
+  module LocalRot13
+    # You must inherit from BaseConnection.
+    class Connection < Train::Plugins::Transport::BaseConnection
+      # We've placed platform detection in a separate module; pull it in here.
+      include TrainPlugins::LocalRot13::Platform
+
+      def initialize(options)
+        # 'options' here is a hash, Symbol-keyed,
+        # of what Train.target_config decided to do with the URI that it was
+        # passed by `inspec -t` (or however the application gathered target information)
+        # Some plugins might use this moment to capture credentials from the URI,
+        # and the configure an underlying SDK accordingly.
+        # You might also take a moment to manipulate the options.
+        # Have a look at the Local, SSH, and AWS transports for ideas about what
+        # you can do with the options.
+
+        # Regardless, let the BaseConnection have a chance to configure itself.
+        super(options)
+
+        # If you need to attempt a connection to a remote system, or verify your
+        # credentials, now is a good time.
+      end
+
+      # If you are writing a local-style connection, implement this to return true.
+      def local?
+        true
+      end
+
+      # Filesystem access.
+      # If your plugin is for an API, don't implement this.
+      # If your plugin supports reading files, you'll need to implement this.
+      def file_via_connection(path)
+        train_file = Train::File::Local::Unix.new(self, path)
+        # But then we wrap the return in a class that meddles with the content.
+        FileContentRotator.new(train_file)
+      end
+
+      # Command execution.
+      # If your plugin is for an API, don't implement this.
+      # If your plugin supports executing commands, you'll need to implement this.
+      def run_command_via_connection(cmd)
+        # Run the command.
+        run_result = Mixlib::ShellOut.new(cmd)
+        run_result.run_command
+
+        # Wrap the results in a structure that Train expects...
+        OpenStruct.new(
+          # And meddle with the stdout along the way.
+          stdout: Rot13.rotate(run_result.stdout),
+          stderr: run_result.stderr,
+          exit_status: run_result.exitstatus,
+        )
+      end
+    end
+  end
+end

examples/plugins/train-local-rot13/lib/train-local-rot13/file_content_rotator.rb

@@ -0,0 +1,26 @@
+# Here's our helper class for the file object.  This is just some
+# silliness specific to the task of applying rot13 to the file content.
+
+require 'rot13'
+
+module TrainPlugins
+  module LocalRot13
+    class FileContentRotator
+      # The FileContentRotator has-a Train::File
+      def initialize(train_file)
+        @train_file = train_file
+      end
+
+      # We implement content ourselves, rotating the contents of the file
+      def content
+        Rot13.rotate(@train_file.content)
+      end
+
+      # Everything else, we delegate to the Train::File object.
+      # This is not a safe or efficient implementation.
+      def method_missing(meth, *args, &block) # rubocop: disable Style/MethodMissing
+        @train_file.send(meth, *args, &block)
+      end
+    end
+  end
+end