app

Documentation

Overview

Package app provides app context and extensions: hooks and plugins.

Index

• Variables
• func LoadConfig(ctx Context) (config.Config, error)
• type BlockTime
• type Context
  • func Defaults() Context
• type Hooks
• type Instrument
• type Plugins
• type TimerInstrument
  • func NewTimerInstrument() *TimerInstrument
  • func (in *TimerInstrument) Report() []BlockTime
  • func (in *TimerInstrument) Start(block string)
  • func (in *TimerInstrument) Stop(block string)

Variables

var NopInstrument nopInstrment

NopInstrument is a no-op Instrument. When query profile sampling is less than 100% (< 1.0), NopInstrument is used in api.go to blackhole skipped measurements.

var Now func() time.Time = time.Now

Functions

func LoadConfig

func LoadConfig(ctx Context) (config.Config, error)

Types

type BlockTime

type BlockTime struct {
	Block string        // block name
	Level uint          // call stack
	Calls uint          // number of calls
	Time  time.Duration // total time spent in block (all calls)
}

BlockTime represents the time profile for one code block.

type Context

type Context struct {
	ConfigFile string
	Config     config.Config

	EntityStore     entity.Store
	EntityValidator entity.Validator
	CDCStore        cdc.Store
	ChangesServer   changestream.Server
	StreamerFactory changestream.StreamerFactory
	MetricsStore    metrics.Store
	MetricsFactory  metrics.Factory
	SystemMetrics   metrics.Metrics
	Auth            auth.Manager

	// 3rd-party extensions, all optional
	Hooks   Hooks
	Plugins Plugins
}

Context represents the config, core service singletons, and 3rd-party extensions. There is one immutable context shared by many packages, created in Server.Boot, called api.appCtx.

func Defaults

func Defaults() Context

Defaults returns a Context with default (built-in) hooks and plugins. The default context is not sufficient to run Etre, but it provides the starting point for user customization by overriding the defaults.

After customizing the default context, it is used to boot the server (see server package) which loads the configs and creates the core service singleton.

type Hooks

type Hooks struct {
	// LoadConfig loads the Etre config. The default hook loads the config from
	// a file. This hook overrides the default. Etre fails to start if it returns
	// an error.
	LoadConfig func(Context) (config.Config, error)

	// RunAPI runs the Etre API. It should block until the API is stopped by
	// a call to StopAPI. If this hook is provided, it is called instead of api.Run().
	// If you provide this hook, you need to provide StopAPI as well.
	RunAPI func() error

	// StopAPI stops running the Etre API. It is called after RunAPI when
	// Etre is shutting down, and it should cause RunAPI to return.
	// If you provide this hook, you need to provide RunAPI as well.
	StopAPI func() error
}

Hooks allow users to modify system behavior at certain points. All hooks are optional; the defaults are sufficient to run Etre. For example, the LoadConfig hook allows the user to load and parse the config file, completely overriding the built-in code.

type Instrument

type Instrument interface {
	// Start code block timer. Blocks can be nested (e.g. foo calls bar) and called
	// multiple times (e.g. calling foo in a for loop). Block names must be unique
	// within the query being instrumented. Be sure to call Stop for each block.
	Start(block string)

	// Stop code block timer previously started by calling Start.
	Stop(block string)

	// Report all unique code block calls.
	Report() []BlockTime
}

Instrument records and reports query profile times. Use one instrument per query. Instruments are not safe for multiple goroutines.

type Plugins

type Plugins struct {
	Auth auth.Plugin
}

Plugins allow users to provide custom components. All plugins are optional; the defaults are sufficient to run Etre. Whereas hooks are single, specific calls, plugins are complete components with more extensive functionality defined by an interface. A user plugin, if provided, must implement the interface completely. For example, the Auth plugin allows the user to provide a complete and custom system of authentication and authorization.

type TimerInstrument

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

TimerInstrument is the real Instrument. When a query meets the sampling rate in api.go, a TimerInstrument is created to record and report its times (profile).

func NewTimerInstrument

func NewTimerInstrument() *TimerInstrument

func (*TimerInstrument) Report

func (in *TimerInstrument) Report() []BlockTime

func (*TimerInstrument) Start

func (in *TimerInstrument) Start(block string)

func (*TimerInstrument) Stop

func (in *TimerInstrument) Stop(block string)