New buildstep_inspect plugin

Signed-off-by: Tim Waugh <twaugh@redhat.com>

Author: twaugh

README.md

@@ -47,3 +47,29 @@ to each inspector function specified in `inspector_funk`.
 
 The `plugins` argument is a list, so one can specify multiple plugins to 
 inspect.
+
+For inspecting the workflow state at the build-step phase, the
+`build_inspect.py` plugin is provided. This can be told whether to
+succeed or fail by passing arguments as appropriate when it is
+declared in the buildstep plugins section. A failing declaration would
+be:
+
+```json
+{
+    "name": "buildstep_inspect",
+    "args": {
+        "fail_reason": "insufficient memory"
+    }
+}
+```
+
+A succeeding declaration would be:
+
+```json
+{
+    "name": "buildstep_inspect",
+    "args": {
+        "image_id": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    }
+}
+```

buildstep_inspect.py

@@ -0,0 +1,60 @@
+"""
+Copyright (c) 2017 Red Hat, Inc
+All rights reserved.
+
+This software may be modified and distributed under the terms
+of the BSD license. See the LICENSE file for details.
+"""
+
+from __future__ import unicode_literals
+from __future__ import print_function
+
+from atomic_reactor.plugin import BuildStepPlugin
+from atomic_reactor.build import BuildResult
+
+
+class BuildStepInspectPlugin(BuildStepPlugin):
+    """
+    Log the inputs to the build-step plugin
+    """
+
+    key = 'buildstep_inspect'
+    is_allowed_to_fail = True
+
+    def __init__(self, tasker, workflow, fail_reason=None, image_id=None):
+        """
+        """
+        super(BuildStepInspectPlugin, self).__init__(tasker, workflow)
+
+        logs = [
+            "Step 1 : FROM sha256:<...>",
+            "---> <...>",
+            "Step 2 : CMD /bin/bash",
+            "---> Running in <...>",
+            "---> <...>",
+            "Removing intermediate container <...>",
+        ]
+
+        if image_id is not None:
+            final_line = "Successfully built {}".format(image_id)
+        else:
+            final_line = "Build failed"
+
+        logs.append(final_line)
+        self.build_result = BuildResult(logs=logs,
+                                        fail_reason=fail_reason,
+                                        image_id=image_id)
+
+    def run(self):
+        """
+        Run plugin, logging self.workflow.builder information
+        """
+
+        for line in [
+                "Build directory: {}".format(self.workflow.builder.df_dir),
+                "Dockerfile path: {}".format(self.workflow.builder.df_path),
+                "Image to build: {}".format(self.workflow.builder.image),
+                ]:
+            self.log.info(line)
+
+        return self.build_result