flow

Documentation

Overview

Package flow implements the Flow component graph system. Flow configuration files are parsed from HCL, which contain a listing of components to run.

Components

Each component has a set of arguments (HCL attributes and blocks) and optionally a set of exported fields. Components can reference the arguments or exports of other components using HCL expressions.

See the top-level component package for more information on components, and subpackages for defined components.

Component Health

A component will have various health states during its lifetime:

1. Unknown: The initial health state for new components.
2. Healthy: A healthy component
3. Unhealthy: An unhealthy component.
4. Exited: A component which is no longer running.

Health states are paired with a time for when the health state was generated and a message providing more detail for the health state.

Components can report their own health states. The health state reported by a component is merged with the Flow-level health of that component: an error when evaluating the configuration for a component will always be reported as unhealthy until the next successful evaluation.

Component Evaluation

The process of converting the HCL block associated with a component into the appropriate Go struct is called "component evaluation."

Components are only evaluated after all components they reference have been evaluated; cyclic dependencies are invalid.

If a component updates its Exports at runtime, other components which directly or indirectly reference the updated component will have their Arguments re-evaluated.

The arguments and exports for a component will be left in their last valid state if a component shuts down or is given an invalid config. This prevents a domino effect of a single failed component taking down other components which are otherwise healthy.

Index

• type File
  • func ReadFile(name string, bb []byte) (*File, hcl.Diagnostics)
• type Flow
  • func New(o Options) *Flow
  • func (c *Flow) Close() error
  • func (f *Flow) ConfigHandler() http.HandlerFunc
  • func (f *Flow) GraphHandler() http.HandlerFunc
  • func (c *Flow) LoadFile(f *File) error
• type Options

Types

type File

type File struct {
	Name string    // File name given to ReadFile.
	HCL  *hcl.File // Raw HCL file.

	Logging logging.Options

	// Components holds the list of raw HCL blocks describing components. The
	// Flow controller can interpret this block.
	Components hcl.Blocks
}

File holds the contents of a parsed Flow file.

func ReadFile

func ReadFile(name string, bb []byte) (*File, hcl.Diagnostics)

ReadFile parses the HCL file specified by bb into a File. name should be the name of the file used for reporting errors.

type Flow

type Flow struct {
	// contains filtered or unexported fields
}

Flow is the Flow system.

func New

func New(o Options) *Flow

New creates and starts a new Flow controller. Call Close to stop the controller.

func (*Flow) Close

func (c *Flow) Close() error

Close closes the controller and all running components.

func (*Flow) ConfigHandler

func (f *Flow) ConfigHandler() http.HandlerFunc

ConfigHandler returns an http.HandlerFunc which will render the most recently loaded configuration file as HCL.

func (*Flow) GraphHandler

func (f *Flow) GraphHandler() http.HandlerFunc

GraphHandler returns an http.HandlerFunc which renders the current graph's DAG as an SVG. Graphviz must be installed for this function to work.

func (*Flow) LoadFile

func (c *Flow) LoadFile(f *File) error

LoadFile synchronizes the state of the controller with the current config file. Components in the graph will be marked as unhealthy if there was an error encountered during Load.

The controller will only start running components after Load is called once without any configuration errors.

LoadFile will return an error value of hcl.Diagnostics. hcl.Diagnostics is used to report both warnings and configuration errors.

type Options

type Options struct {
	// Logger for components to use. A no-op logger will be created if this is
	// nil.
	Logger *logging.Logger

	// Directory where components can write data. Components will create
	// subdirectories for component-specific data.
	DataPath string
}

Options holds static options for a flow controller.