plugin

Documentation

Overview

Package plugin provides functionality that is not available with just iterators and entries. Splitting these out into their own, independent (except what's provided in pkg) packages means that they can be omitted in favor of a smaller build size if the functionality isn't needed. This likely won't result in shorter initial compile times, since the dependencies are still listed in the root level go.mod.

"Source" functions should take input and return an iterator.Iterator and potentially an error, and operate asynchronously. Sources should close any resources, like file handles or channels, and stop the associated goroutine when they have reached the end of their input.

"Sink" functions should take an iterator.Iterator - and optionally other parameters - and operate synchronously (the user may decide to call a Sink function in a goroutine). Sink functions should use iterator.Drain on an iterator if they encounter an error to prevent upstream blocking.

A plugin is anything that implements the Plugin interface. A Plugin is expected to register its source and sink functions when its Plugin.Register method is called, and may perform cleanup operations in Plugin.Stopping. Arbitrary logic may be added around these events as needed. If Plugin.Register is not called, then neither will Plugin.Closing.

Current Plugins:
- file provides source and sink for files, including tail support.
- store provides SQLite source and sink.

More will be added as time allows.

Index

• Variables
• type Plugin
• type Registration
  • func NewRegistration() *Registration
  • func (r *Registration) AllDocs() string
  • func (r *Registration) DocumentSink(qualifier, class, doc string)
  • func (r *Registration) DocumentSource(qualifier, class, doc string)
  • func (r *Registration) RegisterSink(qualifier, class string, sink SinkFunc)
  • func (r *Registration) RegisterSource(qualifier, class string, src SourceFunc)
  • func (r *Registration) Sink(qualifier, class string) (SinkFunc, string, bool)
  • func (r *Registration) Source(qualifier, class string) (SourceFunc, string, bool)
• type SinkFunc
• type SourceFunc

Variables

var (
	ErrArgs = errors.New("argument error")
)

Types

type Plugin

type Plugin interface {
	// ID should return a unique identifier for this plugin.
	ID() string
	// Register is called to allow registration of source and sink functions.
	Register(*Registration)
	// Stopping is called after all source and sink operations, when the nomlog session is shutting down.
	Stopping() error
}

Plugin represents the operations expected of a source/sink plugin.

type Registration

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

Registration is a collection of SourceFunc and SinkFunc to be used by other components.

func NewRegistration

func NewRegistration() *Registration

func (*Registration) AllDocs

func (r *Registration) AllDocs() string

AllDocs will return a string containing all the documentation for all loaded plugins. The listing will include sources, then sinks, in alphabetical order by qualifier and class.

func (*Registration) DocumentSink

func (r *Registration) DocumentSink(qualifier, class, doc string)

DocumentSink is used to document a provided plugin sink. It's recommended to provide usage information in this documentation.

func (*Registration) DocumentSource

func (r *Registration) DocumentSource(qualifier, class, doc string)

DocumentSource is used to document a provided plugin source. It's recommended to provide usage information in this documentation.

func (*Registration) RegisterSink

func (r *Registration) RegisterSink(qualifier, class string, sink SinkFunc)

RegisterSink is called by Plugin.Register to provide a sink for use in DSL scripts.

func (*Registration) RegisterSource

func (r *Registration) RegisterSource(qualifier, class string, src SourceFunc)

RegisterSource is called by Plugin.Register to provide a source for use in DSL scripts.

func (*Registration) Sink

func (r *Registration) Sink(qualifier, class string) (SinkFunc, string, bool)

Sink retrieves a sink known to this Registration. It returns the SinkFunc if it exists, documentation, and a bool indicating whether the qualifier and class pair matches a known sink.

func (*Registration) Source

func (r *Registration) Source(qualifier, class string) (SourceFunc, string, bool)

Source retrieves a source known to this Registration. It returns the SourceFunc if it exists, documentation, and a bool indicating whether the qualifier and class pair matches a known source.

type SinkFunc

type SinkFunc = func(ctx context.Context, src iterator.Iterator, args ...*dsl.Arg) error

SinkFunc is a function that consumes an iterator.Iterator and 0 or more dsl.Arg.

type SourceFunc

type SourceFunc = func(ctx context.Context, args ...*dsl.Arg) (iterator.Iterator, error)

SourceFunc is a function that takes 0 or more dsl.Arg to produce an iterator.Iterator.