fnrun

README

fnrun

fnrun is a library that provides utilities for building and executing function runners with isolation.

This library provides an implementation that can be used to interface with CLI applications using the fnrun-proto protocol buffers to stream data over stdin and stdout to the CLI application.

Documentation

Overview

Package fnrun contains utilities for building function runners that execute functions in isolation.

Index

• Variables
• func Env(ctx context.Context) (map[string]string, bool)
• func ReadFrom(r io.Reader, result *Result) error
• func WithEnv(ctx context.Context, env map[string]string) context.Context
• func WriteTo(ctx context.Context, w io.Writer) (int64, error)
• type Input
  • func (input *Input) WriteTo(w io.Writer) (int64, error)
• type Invoker
  • func NewCmdInvoker(cmd *exec.Cmd) (Invoker, error)
• type InvokerFactory
  • func NewCmdInvokerFactory(cmd *exec.Cmd) InvokerFactory
• type InvokerPool
  • func NewInvokerPool(config InvokerPoolConfig) (*InvokerPool, error)
  • func (pool *InvokerPool) Invoke(ctx context.Context, input *Input) (*Result, error)
• type InvokerPoolConfig
• type Result

Variables

var ErrAvailabilityTimeout = errors.New("could not get access to invoker before timeout")

ErrAvailabilityTimeout is an error that indicates that an invoker did not become available within the allow time period.

var ErrMissingTimeout = errors.New("Expected a context with a timeout")

ErrMissingTimeout exists to signal that an code is attempting to call an invoker without specifying a timeout. fnrun assumes that invokers have an associated timeout.

Functions

func Env

func Env(ctx context.Context) (map[string]string, bool)

Env retrieves the environment variables placed on the Invoker's context. The second argument is false if there are no environment variables associated with the context.

func ReadFrom

func ReadFrom(r io.Reader, result *Result) error

ReadFrom reads a Result from the specified reader and populates the specified result.

func WithEnv

func WithEnv(ctx context.Context, env map[string]string) context.Context

WithEnv annotates the context with any environment variables the process should receive.

func WriteTo

func WriteTo(ctx context.Context, w io.Writer) (int64, error)

WriteTo writes the ExecutionContext to the specified writer.

Types

type Input

type Input struct {
	Data []byte
}

Input contains the data that is passed to an invocation.

The data is represented as a byte array to be as generic as possible across many implementations.

func (*Input) WriteTo

func (input *Input) WriteTo(w io.Writer) (int64, error)

WriteTo writes the Input to the specified writer.

type Invoker

type Invoker interface {
	// Invoke triggers a call to the underlying implementation with the specified
	// input and context.
	//
	// The call may time out out subject to the maximum runnable time defined in
	// ctx.
	//
	// If an error is returned, the instance cannot be guaranteed to be invokable
	// again, subject to implementation.
	Invoke(context.Context, *Input) (*Result, error)
}

Invoker represents something that can be called with an input and context and return a result.

It is similar to a function but the underlying implementation may be different.

func NewCmdInvoker

func NewCmdInvoker(cmd *exec.Cmd) (Invoker, error)

NewCmdInvoker creates an object that can invoke the provided exec.Cmd.

This function assumes control of the cmd, and it is the responsibility of the caller to ensure that the cmd is not used after being provided to this function.

This object kills the OS process managed by the provided cmd when an invocation fails, so the object returned from this function should not be reused if a call to Invoke returns an error.

type InvokerFactory

type InvokerFactory interface {
	NewInvoker() (Invoker, error)
}

InvokerFactory represents an object that can create instances of Invokers.

func NewCmdInvokerFactory

func NewCmdInvokerFactory(cmd *exec.Cmd) InvokerFactory

NewCmdInvokerFactory creates a factory that can create new instances of CmdInvoker intances.

The cmd will be cloned for each new instances, which means that multiple calls to the factory can create multiple copies of OS processes.

type InvokerPool

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

InvokerPool represents a pool of Invoker workers that can be used to handle invocation requests.

The pool will attempt to satisfy the requirements specified by the config object, including maintaining a number of invoker instances available to handle invocations; if an Invoker fails, it is discarded and replaced by a new Invoker instance.

func NewInvokerPool

func NewInvokerPool(config InvokerPoolConfig) (*InvokerPool, error)

NewInvokerPool creats a new InvokerPool with the provided configuration.

func (*InvokerPool) Invoke

func (pool *InvokerPool) Invoke(ctx context.Context, input *Input) (*Result, error)

Invoke attempts to use an Invoker in the pool to satisfy the invocation request.

If a worker Invoker is not available within the MaxWaitDuration of the pool configuration, an ErrAvailabilityTimeout error is returned from this function.

type InvokerPoolConfig

type InvokerPoolConfig struct {
	MaxInvokerCount int
	InvokerFactory  InvokerFactory
	MaxWaitDuration time.Duration
	MaxRunnableTime time.Duration
}

InvokerPoolConfig contains the configuration data for an InvokerPool.

type Result

type Result struct {
	Status int
	Data   []byte
	Env    map[string]string
}

Result represents the result of an invocation.

The result includes a status, data, and additional env information.

The status is an int and can represent something meaningful to the code calling Invoke, such as an HTTP status code or an OS process return code.

The data returns is a byte array so as to be as agnostic to the underlying implementation details as possible.

The env should be any environmental data that should be considered important to the return of the code. For example, this could contain HTTP header name/value pairs.