Stable Ruby API for bolt

[adreyer]

Use Case

Currently people are leveraging BoltSpec::Run as a ruby API into bolt. Since it was designed for testing it does not provide as much flexibility as is desired.

Proposal

The core of this API will be BoltEngine class that users instantiate which exposes methods for core bolt functionality. Standardizing the API of a handful of Bolt objects and allowing users to inject their own implementations will allow further extensibility.

BoltEngine

The BoltEngine is the center of the Bolt API. At this point a BoltEngine instance is not capable of handling concurrent commands and due to the unsafe global state in puppet different instances are thread safe. To avoid limitations around objects bound to a puppet compiler the interface with these methods will be data rather then the corresponding plan language ruby objects(Result/ResultSet/Target etc) Initializer

• Executor A configured executor instance
• Inventory A primed inventory instance
• Config a loaded instance configuration.

initialize(Executor, Inventory, config)

Methods

These methods align with most of the CLI commands bolt exposes.

• run_task(name, targets, params, options)
• run_plan(plan_name, params, options)
• run_command(command, targets, options)
• run_script(script_name, targets, args, options)
• upload_file(file_name, dest, targets, options)
• list_tasks(options)
• task_details(name, options)
• list_plans(options)
• plan_details(name, options)
• subscribe(Outputter)
• apply(targets, file:, code:, **options) This one is slightly more complicated.

API Classes

These classes will have a stabilized API allowing consumers to replace them with their own implementations.

Executor

This handles those components of the plan language that have side effects: remote execution and event reporting.

Inventory

The inventory stores information about all targets. It's stateful and may be updated during plan execution.

Outputter

This is an event handler multiple different handlers can be subscribed to the events of a single engine instance.

PuppetDBClient

Helpers/Factories

To make it easier to use for the most common use case helper methods to load a BoltEngine with the most common implementations will be exposed.

from_project(path)

Create a bolt engine loading context automatically from the Project Directory. This is what the CLI does and probably what reusabolt needs to do.

from_data(data)

In cases where there is no on disk configuration only a directory of modules use the from_data helper to enable BoltSpec like behavior