Documentation

Index

Constants

const Forever = -1 * time.Second

Forever is a location TTL that is infinite.


const Never = 0 * time.Second

Never is a location TTL that is effectively zero.


const ProfCPUFileName = "pprof_cpu"

Variables

var EndOfTime = time.Unix(1<<62, 0)

EndOfTime is not actually the end of time, but it is a long time from now.

If you are wondering, this value is in the year 146138514283.


Functions

func BenchSystem

func BenchSystem(name string) (*System, *Context)

BenchSystem makes a System that might be appropriate for benchmarks.

Verbosity is 'NOTHING'. Based on 'ExampleSystem'.

func ExampleSystem

func ExampleSystem(name string) (*System, *Context)

func GetRuntimes

func GetRuntimes(ctx *Context) (map[string]interface{}, error)

GetRuntimes get a list of current the System's runtime data.

func GetStorage

func GetStorage(ctx *Context, storageType string, storageConfig interface{}) (Storage, error)

GetStorage attempts to create a Storage.

See '../storage/' for some implementations.

Possible storage types:

"none": This Storage doesn't remember anything.
"mem": In-memory-only storage.  Never writes to disk.
"bolt": BoltDB Storage.  'storageConfig' should be a filename.
"dynamodb": DynamoDB Storage. 'storageConfig' should be
   REGION:TABLE_NAME:CONSISTENT_READS, where CONSISTENT_READS is
   either 'true' or 'false'.

func ParseLocationTTL

func ParseLocationTTL(ttl string) (time.Duration, error)

ParseLocationTTL tries to parse a duration.

"never" parses to 'Never' and "forever" parses to 'Forever'. Otherwise you should provide a duration in 'time.Duration' syntax.

func ServiceAvailable

func ServiceAvailable(ctx *Context, url string, timeout time.Duration) bool

ServiceAvailable checks to see if what's at 'url' is accessible and at least semi-functional.

The URL should include the full path (ideally to a health check).

func SystemForTest

func SystemForTest(name string) (*System, *Context)

Types

type CachedLocation

type CachedLocation struct {
	sync.Mutex
	Expires time.Time
	Pending bool
	*Location
}

CachedLocation mostly provides a mutex associated with the target location.

That mutex allows use to block only on this specific location when opening it. That's way better than having a system-wide lock held when opening each location because opening a location could take a long time.

func (*CachedLocation) Get

func (cl *CachedLocation) Get(ctx *Context, sys *System, name string, checkExists bool) (*Location, error)

Get returns the location after opening it once.

type CachedLocations

type CachedLocations struct {
	sync.Mutex
	// contains filtered or unexported fields
}

CachedLocations is just that: a location cache keyed by name.

We have this struct in part to have a mutex dedicated to this state.

func NewCachedLocations

func NewCachedLocations(ctx *Context) *CachedLocations

func (*CachedLocations) Count

func (cl *CachedLocations) Count() int

func (*CachedLocations) Open

func (cls *CachedLocations) Open(ctx *Context, sys *System, name string, check bool) (*Location, error)

Open gets a location from the cache after first creating it.

This function the top-level location cache API, and it uses 'CachedLocations.Get()' to do the real work.

TTL can be 'Never', 'Forever', or anything in between.

func (*CachedLocations) Release

func (cls *CachedLocations) Release(ctx *Context, sys *System, name string) error

Release checks whether the location has expired and, if so, closes it.

type GroupControls

type GroupControls map[string]*Control

GroupControls maps a group to a 'core.Control'.

Used to be called 'LocControls'

type LocToGroup

type LocToGroup func(string) string

LocToGroup maps a location name to a group name.

Used to be called 'GroupMap'.

type System

type System struct {
	sync.Mutex

	*CachedLocations
	ProfCPUFile *os.File
	// contains filtered or unexported fields
}

System is a location container.

A System is responsible for loading locations and directing API requests to then.

func NewSystem

func NewSystem(ctx *Context, conf SystemConfig, cont SystemControl, cron cron.Cronner) (*System, error)

NewSystem does about what you'd think.

func SimpleSystem

func SimpleSystem(ctx *Context) *System

SimpleSystem ia a basic system with 'FOREVER' TTL and 'DefaultVerbosity' Verbosity.

func (*System) AddFact

func (sys *System) AddFact(ctx *Context, location string, id string, fact string) (string, error)

AddFact add a fact to the given location. Returns the ID for the fact.

func (*System) AddFactJS

func (sys *System) AddFactJS(ctx *Context, location string, id string, fact string) map[string]interface{}

func (*System) AddRule

func (sys *System) AddRule(ctx *Context, location string, id string, rule string) (string, error)

AddRule adds a rule to the given location. Returns the ID for the rule.

func (*System) ClearLocation

func (sys *System) ClearLocation(ctx *Context, location string) error

ClearLocation should (!) clear all the state for the given location.

func (*System) ClearLocationStats

func (sys *System) ClearLocationStats(ctx *Context, location string) error

ClearLocationStats clears stats for the given location.

func (*System) ClearStats

func (sys *System) ClearStats(ctx *Context) error

ClearStats clear the System's stats.

func (*System) Close

func (sys *System) Close(ctx *Context) error

Close should shut down things.

Currently this method just calls 'storage.Close()', which itself might not really do anything (depending on the Storage, of course).

func (*System) CloseLocation

func (sys *System) CloseLocation(ctx *Context, loc string) error

CloseLocation currently does nothing.

func (*System) Control

func (s *System) Control() *SystemControl

Control atomically gets the System's controls.

func (*System) CreateLocation

func (sys *System) CreateLocation(ctx *Context, location string) (bool, error)

CreateLocation exists solely to mark a location as created.

func (*System) DeleteLocation

func (sys *System) DeleteLocation(ctx *Context, location string) error

DeleteLocation should (!) clear all the state for the given location.

func (*System) EnableRule

func (sys *System) EnableRule(ctx *Context, location string, id string, enable bool) error

EnableRule enables or disables a rule.

func (*System) GetCachedLocations

func (sys *System) GetCachedLocations(ctx *Context) []string

GetCachedLocations gets the set of cached locations.

Gets the System's mutex.

func (*System) GetFact

func (sys *System) GetFact(ctx *Context, location string, id string) (js string, err error)

GetFact returns JSON representation of a fact from the given location.

func (*System) GetLastUpdatedMem

func (sys *System) GetLastUpdatedMem(ctx *Context, location string) (string, error)

GetLastUpdatedMem reports what this system thinks the location's last updated timestamp is.

Does not query DynamoDB to find out. Just returns what is currently known in memory.

func (*System) GetLocation

func (sys *System) GetLocation(ctx *Context, name string) (*Location, error)

GetLocation implements core.LocationProvider.

Just calls 'findLocation(,,false)'.

func (*System) GetLocationStats

func (sys *System) GetLocationStats(ctx *Context, location string) (*ServiceStats, error)

GetLocationStats returns ServiceStats for the given location.

func (*System) GetParents

func (sys *System) GetParents(ctx *Context, location string) ([]string, error)

GetParents gets the location's parents (if any).

func (*System) GetProfileBlock

func (sys *System) GetProfileBlock(ctx *Context) (string, error)

GetProfileBlock returns pprof block.

func (*System) GetProfileCPU

func (sys *System) GetProfileCPU(ctx *Context, stop bool) (prof []byte, err error)

GetProfileCPU gets/stops pprof cpu.

func (*System) GetProfileMem

func (sys *System) GetProfileMem(ctx *Context) (string, error)

GetProfileMem returns pprof mem.

func (*System) GetRule

func (sys *System) GetRule(ctx *Context, location string, id string) (js string, err error)

GetRule returns JSON representation of a rule from the given location.

func (*System) GetSize

func (sys *System) GetSize(ctx *Context, location string) (int, error)

GetSize returns the number of facts (including rules) stored in the given location.

func (*System) GetStats

func (sys *System) GetStats(ctx *Context) (*ServiceStats, error)

GetStats get a clean copy of the System's current stats.

func (*System) ListRules

func (sys *System) ListRules(ctx *Context, location string, includeInherited bool) ([]string, error)

ListRules returns all rules (JSON) stored in the given location.

func (*System) LocControl

func (s *System) LocControl(ctx *Context, loc string) *Control

LocControl gets a location controls.

A location's controls originate with the System's controls, which have a 'DefaultLocControl' that's used if 'LocToGroup' together with 'GroupControls' don't provide the required controls.

func (*System) LogLoop

func (sys *System) LogLoop(level LogLevel, ctx *Context, scope string, interval time.Duration, iterations int)

LogLoop starts a loop that logs sys.stats at the given interval.

If iterations is negative, the loop is endless. Otherwise the loop terminates after the specified number of iteratins.

func (*System) OpenLocation

func (sys *System) OpenLocation(ctx *Context, name string, checkExists bool) (*Location, error)

OpenLocation wraps 'newLocation' to check for existence (optionally).

func (*System) PeekStorage

func (sys *System) PeekStorage(ctx *Context) (Storage, error)

PeekStorage is an unholy API to expose underlying storage.

Used by 'service' for testing purposes.

func (*System) ProcessEvent

func (sys *System) ProcessEvent(ctx *Context, location string, event string) (*FindRules, error)

func (*System) Query

func (sys *System) Query(ctx *Context, location string, query string) (*QueryResult, error)

Query runs a query in the given location.

For testing.

func (*System) RemFact

func (sys *System) RemFact(ctx *Context, location string, id string) (string, error)

RemFact remove a fact from the given location. Returns the ID of the removed fact.

func (*System) RemRule

func (sys *System) RemRule(ctx *Context, location string, id string) (string, error)

RemRule removes a rule from the given location. Returns the ID of the removed rule.

func (*System) RetryEventWork

func (sys *System) RetryEventWork(ctx *Context, location string, work *FindRules) error

func (*System) RuleEnabled

func (sys *System) RuleEnabled(ctx *Context, location string, id string) (bool, error)

EnableRule enables or disables a rule.

func (*System) RunJavascript

func (sys *System) RunJavascript(ctx *Context, location string, code string, libraries []string, bs *Bindings, props map[string]interface{}) (interface{}, error)

RunJavascript allows location-specific Javascript testing.

func (*System) RuntimeLogLoop

func (sys *System) RuntimeLogLoop(level LogLevel, ctx *Context, scope string, interval time.Duration, iterations int)

RuntimeLogLoop runs a loop that logs Go runtime stats.

The "scope" parameter is opaque. Might be useful in downstream log/metric processing.

func (*System) SearchFacts

func (sys *System) SearchFacts(ctx *Context, location string, pattern string, includeInherited bool) (*SearchResults, error)

SearchFacts finds facts that match the given pattern (JSON).

func (*System) SearchRules

func (sys *System) SearchRules(ctx *Context, location string, event string, includeInherited bool) (map[string]string, error)

SearchRules finds rules with 'when' patterns that match the given event (JSON).

func (*System) SetControl

func (s *System) SetControl(control SystemControl)

SetControl atomically gets the System's controls.

func (*System) SetParents

func (sys *System) SetParents(ctx *Context, location string, parents []string) (string, error)

SetParents sets the location's parents.

Returns the id of the property (if any).

func (*System) StartProfileCPU

func (sys *System) StartProfileCPU(ctx *Context) error

StartProfileCPU starts pprof cpu.

type SystemConfig

type SystemConfig struct {
	// Type of storage: "dynamodb", "cassandra", "bolt", "memory", or "none"
	Storage string `json:"storage"`

	// How to configure storage.  Examples:
	//
	// For "cassandra", the nodes: []interface{}{"localhost:9042"}
	//   Those ports should talk CQL (for better or worse).
	//
	// For "bolt", the filename: "test"
	//
	StorageConfig interface{}

	// LinearState switches between IndexedState and LinearState.
	//
	// UnindexedState means LinearState.  Maybe I should just say
	// that.
	UnindexedState bool

	// CheckExistence requires that a location is explicitly
	// created before it can be used.
	CheckExistence bool
}

SystemConfig are read-only, boot-time settings for a System.

Once specified, these settings cannot be changed.

func ExampleConfig

func ExampleConfig() *SystemConfig

ExampleConfig just generates a simple config for an in-memory-only System.

type SystemControl

type SystemControl struct {
	// Turn on some timing in various places.
	Timing bool

	// The maximum number of locations that this System will serve.
	MaxLocations int

	// Whether to skip ssh/https insecure keys verification, should only be set true for testing
	InsecureSkipVerify bool

	// LocationTTL is the TTL for cached locations.
	//
	// Often either Forever or Never.
	LocationTTL time.Duration

	// LocToGroup maps a location to a group.
	LocToGroup `json:"-"`

	// GroupControls maps a group to a location control.
	GroupControls

	// DefaultLocationControl is exactly what you think.
	//
	// If LocToGroup and GroupControls don't find a control, we
	// use 'DefaultLocationControl'.
	DefaultLocControl *Control

	// CachedPending will use the location cache to keep pending
	// locations around.
	CachePending bool
}

SystemControl represents ephemeral control options.

These settings are process-specific and not stored. Note that all of these values are simple (not maps or arrays or structs). You can change them (hopefully atomically) at will.

Set and get these controls with 'System.SetControl()' and 'System.Control()'.

Also see core.Control.

func ExampleSystemControl

func ExampleSystemControl() *SystemControl

ExampleSystemControl uses default SystemControl fields, except for Timing, which is turned on.

func OverlayControl

func OverlayControl(js []byte, control SystemControl) (*SystemControl, error)

OverlayControl parses the given JSON as a SystemControl, which is then added to the given control.

Source Files