event

package
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 27, 2021 License: MPL-2.0 Imports: 36 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ServerName    string = "server_name" // ServerName: event source server name
	ServerAddress string = "server_addr" // ServerAddress: event source server address
)

Define a set of common keys and values to use in event payload maps. Having and using a common set will allow operators to more easily define event filters.

View Source 
const (
	OpField          = "op"           // OpField in an event.
	RequestInfoField = "request_info" // RequestInfoField in an event.
	VersionField     = "version"      // VersionField in an event
	DetailsField     = "details"      // Details field in an event.
	HeaderField      = "header"       // HeaderField in an event.
	IdField          = "id"           // IdField in an event.
	CreatedAtField   = "created_at"   // CreatedAtField in an event.
	TypeField        = "type"         // TypeField in an event.

)
View Source 
const (
	ApiRequest auditEventType = "APIRequest" // ApiRequest defines an API request audit event type
)
View Source 
const IdPrefix = "e"
View Source 
const MissingKey = "EXTRA_VALUE_AT_END"

MissingKey defines a key to be used as the "missing key" when ConvertArgs has an odd number of args (it's missing a key in its key/value pairs)

Variables

View Source 
var (
	ErrInvalidParameter = errors.New("invalid parameter")
	ErrMaxRetries       = errors.New("too many retries")
	ErrIo               = errors.New("error during io operation")
	ErrRecordNotFound   = errors.New("record not found")
)

Functions

func ConvertArgs added in v0.5.0 

func ConvertArgs(args ...interface{}) map[string]interface{}

ConvertArgs will convert the key/value pair args to a map. If the args provided are an odd number (they're missing a key in their key/value pairs) then MissingKey is used to the missing key.

func InitSysEventer 

func InitSysEventer(log hclog.Logger, serializationLock *sync.Mutex, serverName string, opt ...Option) error

InitSysEventer provides a mechanism to initialize a "system wide" eventer singleton for Boundary. Support the options of: WithEventer(...) and WithEventerConfig(...)

IMPORTANT: Eventers cannot share file sinks, which likely means that each process should only have one Eventer. In practice this means the process Server (Controller or Worker) and the SysEventer both need a pointer to a single Eventer.

func NewEventerContext 

func NewEventerContext(ctx context.Context, eventer *Eventer) (context.Context, error)

NewEventerContext will return a context containing a value of the provided Eventer

func NewId added in v0.5.0 

func NewId(prefix string) (string, error)

NewId is a bit of a modified NewId has been done to stop a circular dependency with the errors package that is caused by importing boundary/internal/db

func NewRequestInfoContext 

func NewRequestInfoContext(ctx context.Context, info *RequestInfo) (context.Context, error)

NewRequestInfoContext will return a context containing a value for the provided RequestInfo

func TestEnableEventing added in v0.5.0 

func TestEnableEventing(t *testing.T, enable bool)

TestEnableEventing will enable eventing via it's envvar globals.BOUNDARY_DEVELOPER_ENABLE_EVENTS

func TestResetSystEventer 

func TestResetSystEventer(t *testing.T)

TestResetSysEventer will reset event.syseventer to an uninitialized state.

func WriteAudit 

func WriteAudit(ctx context.Context, caller Op, opt ...Option) error

WriteAudit will write an audit event. It will first check the ctx for an eventer, then try event.SysEventer() and if no eventer can be found an error is returned.

At least one and any combination of the supported options may be used: WithRequest, WithResponse, WithAuth, WithId, WithFlush and WithRequestInfo. All other options are ignored.

func WriteError 

func WriteError(ctx context.Context, caller Op, e error, opt ...Option)

WriteError will write an error event. It will first check the ctx for an eventer, then try event.SysEventer() and if no eventer can be found an hclog.Logger will be created and used.

The options WithInfoMsg, WithInfo, WithId and WithRequestInfo are supported and all other options are ignored.

func WriteObservation 

func WriteObservation(ctx context.Context, caller Op, opt ...Option) error

WriteObservation will write an observation event. It will first check the ctx for an eventer, then try event.SysEventer() and if no eventer can be found an error is returned.

At least one and any combination of the supported options may be used: WithHeader, WithDetails, WithId, WithFlush and WithRequestInfo. All other options are ignored.

func WriteSysEvent added in v0.4.0 

func WriteSysEvent(ctx context.Context, caller Op, msg string, args ...interface{})

WriteSysEvent will write a sysevent using the eventer from event.SysEventer() if no eventer can be found an hclog.Logger will be created and used. The args are and optional set of key/value pairs about the event.

This function should never be used when sending events while handling API requests.

Types

type AuditConfig added in v0.6.0 

type AuditConfig struct {
	// FilterOverrides provide an optional a set of overrides for the
	// FilterOperations to be applied to DataClassifications.
	FilterOverrides AuditFilterOperations `hcl:"audit_filter_overrides"`
	// contains filtered or unexported fields
}

AuditConfig defines the configuration required for audit events sinks

func DefaultAuditConfig added in v0.6.0 

func DefaultAuditConfig() *AuditConfig

DefaultAuditConfig specifies a default AuditConfig. The default config will redact both sensitive and secret classifications, so by default a wrapper is not required.

func NewAuditConfig added in v0.6.0 

func NewAuditConfig(opt ...Option) (*AuditConfig, error)

NewAuditConfig creates a new config starting with the DefaultAuditConfig() and applying options. Supported options are: WithWrapper and WithFilterOperations.

func (*AuditConfig) Validate added in v0.6.0 

func (ac *AuditConfig) Validate() error

Validate the AuditConfig

type AuditFilterOperations added in v0.6.0 

type AuditFilterOperations map[DataClassification]FilterOperation

AuditFilterOperation defines a map between DataClassifications and FilterOperations for audit filtering

func DefaultAuditFilterOperations added in v0.6.0 

func DefaultAuditFilterOperations() AuditFilterOperations

DefaultAuditFilterOperations will return a map of the default AuditConfig.AuditFilters

func (AuditFilterOperations) Validate added in v0.6.0 

func (af AuditFilterOperations) Validate() error

Validate the AuditFilterOperation

type Auth 

type Auth struct {
	AuthTokenId string      `json:"auth_token_id" class:"public"`
	UserInfo    *UserInfo   `json:"user_info,omitempty"` // boundary field
	GrantsInfo  *GrantsInfo `json:"grants_info,omitempty"`
	UserEmail   string      `json:"email,omitempty" class:"sensitive"`
	UserName    string      `json:"name,omitempty" class:"sensitive"`
}

type DataClassification added in v0.6.0 

type DataClassification string

DataClassification defines a data classification (public, sensitive, secret, etc) 

const (
	UnknownClassification DataClassification = "unknown"

	// PublicClassification declares a field as public data.  No filter
	// operations are ever performed on public data.
	PublicClassification DataClassification = "public"

	// SensitiveClassification declares a field as sensitive data.  By default,
	// sensitive data is encrypted unless there are AuditConfig.FilterOverrides
	SensitiveClassification DataClassification = "sensitive"

	// SecretClassification declares a field as secret data.  By default,
	// secret data is redacted unless there are AuditConfig.FilterOverrides
	SecretClassification DataClassification = "secret"
)

func (DataClassification) Validate added in v0.6.0 

func (dc DataClassification) Validate() error

Validate the DataClassification

type DeliveryGuarantee 

type DeliveryGuarantee string // DeliveryGuarantee defines the guarantees around delivery of an event type within config

const (
	DefaultDeliveryGuarantee DeliveryGuarantee = ""            // DefaultDeliveryGuarantee will be BestEffort
	Enforced                 DeliveryGuarantee = "enforced"    // Enforced means that a delivery guarantee is enforced
	BestEffort               DeliveryGuarantee = "best-effort" // BestEffort means that a best effort will be made to deliver an event
)

type Eventer 

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

Eventer provides a method to send events to pipelines of sinks

func EventerFromContext 

func EventerFromContext(ctx context.Context) (*Eventer, bool)

EventerFromContext attempts to get the eventer value from the context provided

func NewEventer 

func NewEventer(log hclog.Logger, serializationLock *sync.Mutex, serverName string, c EventerConfig, opt ...Option) (*Eventer, error)

NewEventer creates a new Eventer using the config. Supports options: WithNow, WithSerializationLock, WithBroker, WithAuditWrapper

func SysEventer 

func SysEventer() *Eventer

SysEventer returns the "system wide" eventer for Boundary and can/will return a nil Eventer

func (*Eventer) FlushNodes 

func (e *Eventer) FlushNodes(ctx context.Context) error

FlushNodes will flush any of the eventer's flushable nodes. This needs to be called whenever Boundary is stopping (aka shutting down).

func (*Eventer) Reopen 

func (e *Eventer) Reopen() error

Reopen can used during a SIGHUP to reopen nodes, most importantly the underlying file sinks.

func (*Eventer) StandardLogger added in v0.5.0 

func (e *Eventer) StandardLogger(ctx context.Context, loggerName string, typ Type) (*log.Logger, error)

StandardLogger will create *log.Logger that will emit events through this Logger. This allows packages that require the stdlib log to emit events instead.

func (*Eventer) StandardWriter added in v0.5.0 

func (e *Eventer) StandardWriter(ctx context.Context, typ Type) (io.Writer, error)

StandardWriter will create an io.Writer that will emit events through this io.Writer.

type EventerConfig 

type EventerConfig struct {
	AuditEnabled        bool          `hcl:"audit_enabled"`        // AuditEnabled specifies if audit events should be emitted.
	ObservationsEnabled bool          `hcl:"observations_enabled"` // ObservationsEnabled specifies if observation events should be emitted.
	SysEventsEnabled    bool          `hcl:"sysevents_enabled"`    // SysEventsEnabled specifies if sysevents should be emitted.
	Sinks               []*SinkConfig `hcl:"-"`                    // Sinks are all the configured sinks
}

EventerConfig supplies all the configuration needed to create/config an Eventer.

func DefaultEventerConfig added in v0.5.0 

func DefaultEventerConfig() *EventerConfig

func TestGetEventerConfig added in v0.5.0 

func TestGetEventerConfig(t *testing.T, e *Eventer) EventerConfig

TestGetEventerConfig is a test accessor for the eventer's config

func (*EventerConfig) Validate added in v0.5.0 

func (c *EventerConfig) Validate() error

Validate will Validate the config. A config isn't required to have any sinks to be valid.

type FileSinkTypeConfig added in v0.5.0 

type FileSinkTypeConfig struct {
	Path              string        `hcl:"path"             mapstructure:"path"`             // Path defines the file path for the sink
	FileName          string        `hcl:"file_name"        mapstructure:"file_name"`        // FileName defines the file name for the sink
	RotateBytes       int           `hcl:"rotate_bytes"     mapstructure:"rotate_bytes"`     // RotateBytes defines the number of bytes that should trigger rotation of a FileSink
	RotateDuration    time.Duration `mapstructure:"rotate_duration"`                         // RotateDuration defines how often a FileSink should be rotated
	RotateDurationHCL string        `hcl:"rotate_duration" json:"-"`                         // RotateDurationHCL defines hcl string version of RotateDuration
	RotateMaxFiles    int           `hcl:"rotate_max_files" mapstructure:"rotate_max_files"` // RotateMaxFiles defines how may historical rotated files should be kept for a FileSink
}

FileSinkTypeConfig contains configuration structures for file sink types

type FilterOperation added in v0.6.0 

type FilterOperation string

FilterOperation defines a filter operation (none, redact, encrypt, etc) 

const (
	NoOperation         FilterOperation = ""            // NoOperation specifies no operation.
	UnknownOperation    FilterOperation = "unknown"     // UnknownOperation specifies an unknown operation.
	RedactOperation     FilterOperation = "redact"      // RedactOperation specifies an redaction operation
	EncryptOperation    FilterOperation = "encrypt"     // EncryptOperation specifies an encryption operation.
	HmacSha256Operation FilterOperation = "hmac-sha256" // HmacSha256Operation specifies an hmac-sha256 operation
)

func (FilterOperation) Validate added in v0.6.0 

func (fop FilterOperation) Validate() error

Validate the FilterOperation

type FilterType added in v0.5.0 

type FilterType string

FilterType defines a type for filters (allow or deny) 

const (
	AllowFilter FilterType = "allow" // AllowFilter defines a filter type for "allow"
	DenyFilter  FilterType = "deny"  // DenyFilter defines a filter type for "deny"
)

type GrantsInfo 

type GrantsInfo struct {
	Grants []GrantsPair `json:"grants_pair,omitempty"`
}

type GrantsPair 

type GrantsPair struct {
	Grant   string `json:"grant,omitempty" class:"public"`
	ScopeId string `json:"scope_id,omitempty" class:"public"`
}

type Id 

type Id string

type Op 

type Op string

type Option 

type Option func(*options)

Option - how Options are passed as arguments.

func TestWithAuditSink added in v0.5.0 

func TestWithAuditSink(t *testing.T) Option

TestWithAuditSink is an unexported and a test option

func TestWithBroker added in v0.5.0 

func TestWithBroker(t *testing.T, b broker) Option

TestWithBroker is an unexported and a test option for passing in an optional broker

func TestWithObservationSink added in v0.5.0 

func TestWithObservationSink(t *testing.T) Option

TestWithObservationSink is an unexported and a test option

func WithAllow added in v0.5.0 

func WithAllow(f ...string) Option

WithAllow is an optional set of allow filters

func WithAuditWrapper added in v0.6.0 

func WithAuditWrapper(w wrapping.Wrapper) Option

WithAuditWrapper is an optional wrapper for audit events

func WithAuth 

func WithAuth(a *Auth) Option

WithAuth allows an optional Auth

func WithDeny added in v0.5.0 

func WithDeny(f ...string) Option

WithDeny is an optional set of deny filters

func WithDetails 

func WithDetails(args ...interface{}) Option

WithDetails allows an optional set of key/value pairs about an observation event at the detail level and observation events may have multiple "details"

func WithEventer added in v0.5.0 

func WithEventer(e *Eventer) Option

WithEventer allows an optional eventer

func WithEventerConfig added in v0.5.0 

func WithEventerConfig(c *EventerConfig) Option

WithEventer allows an optional eventer config

func WithFilterOperations added in v0.6.0 

func WithFilterOperations(fop AuditFilterOperations) Option

WithFilterOperations is an optional set of filter operations

func WithFlush 

func WithFlush() Option

WithFlush allows an optional flush option.

func WithHeader 

func WithHeader(args ...interface{}) Option

WithHeader allows an optional set of key/value pairs about an event at the header level and observation events will only have one "header"

func WithId 

func WithId(id string) Option

WithId allows an optional Id

func WithInfo added in v0.5.0 

func WithInfo(args ...interface{}) Option

WithInfo allows an optional info key/value pairs about an error event. If used in conjunction with the WithInfoMsg(...) option, and WithInfoMsg(...) is specified after WithInfo(...), then WithInfoMsg(...) will overwrite any values from WithInfo(...). It's recommend that these two options not be used together.

func WithInfoMsg added in v0.5.0 

func WithInfoMsg(msg string, args ...interface{}) Option

WithInfoMsg allows an optional msg and optional info key/value pairs about an error event. If used in conjunction with the WithInfo(...) option, and WithInfo(...) is specified after WithInfoMsg(...), then WithInfo(...) will overwrite any values from WithInfo(...). It's recommend that these two options not be used together.

func WithNow 

func WithNow(now time.Time) Option

WithNow allows an option time.Time to represent now.

func WithRequest 

func WithRequest(r *Request) Option

WithRequest allows an optional request

func WithRequestInfo 

func WithRequestInfo(i *RequestInfo) Option

WithRequestInfo allows an optional RequestInfo

func WithResponse 

func WithResponse(r *Response) Option

WithResponse allows an optional response

func WithSchema added in v0.5.0 

func WithSchema(url *url.URL) Option

WithSchema is an optional schema for the cloudevents

type Request 

type Request struct {
	Operation string        `json:"operation,omitempty" class:"public"` // std audit field
	Endpoint  string        `json:"endpoint,omitempty" class:"public"`  // std audit field
	Details   proto.Message `json:"details,omitempty"`                  // boundary field
}

type RequestInfo 

type RequestInfo struct {
	EventId  string `json:"-"`
	Id       string `json:"id,omitempty" class:"public"`
	Method   string `json:"method,omitempty" class:"public"`
	Path     string `json:"path,omitempty" class:"public"`
	PublicId string `json:"public_id,omitempty" class:"public"`
}

RequestInfo defines the fields captured about a Boundary request.

func RequestInfoFromContext 

func RequestInfoFromContext(ctx context.Context) (*RequestInfo, bool)

RequestInfoFromContext attempts to get the RequestInfo value from the context provided

func TestRequestInfo 

func TestRequestInfo(t *testing.T) *RequestInfo

TestRequestInfo provides a test RequestInfo

type Response 

type Response struct {
	StatusCode int           `json:"status_code,omitempty"` // std audit
	Details    proto.Message `json:"details,omitempty"`     // boundary field
}

type SinkConfig 

type SinkConfig struct {
	Name           string                `hcl:"name"`             // Name defines a name for the sink.
	Description    string                `hcl:"description"`      // Description defines a description for the sink.
	EventTypes     []Type                `hcl:"event_types"`      // EventTypes defines a list of event types that will be sent to the sink. See the docs for EventTypes for a list of accepted values.
	EventSourceUrl string                `hcl:"event_source_url"` // EventSource defines an optional event source URL for the sink.  If not defined a default source will be composed of the https://hashicorp.com/boundary.io/ServerName/Path/FileName.
	AllowFilters   []string              `hcl:"allow_filters"`    // AllowFilters define a set predicates for including an event in the sink. If any filter matches, the event will be included. The filter should be in a format supported by hashicorp/go-bexpr.
	DenyFilters    []string              `hcl:"deny_filters"`     // DenyFilters define a set predicates for excluding an event in the sink. If any filter matches, the event will be excluded. The filter should be in a format supported by hashicorp/go-bexpr.
	Format         SinkFormat            `hcl:"format"`           // Format defines the format for the sink (JSONSinkFormat or TextSinkFormat).
	Type           SinkType              `hcl:"type"`             // Type defines the type of sink (StderrSink or FileSink).
	StderrConfig   *StderrSinkTypeConfig `hcl:"stderr"`           // StderrConfig defines parameters for a stderr output.
	FileConfig     *FileSinkTypeConfig   `hcl:"file"`             // FileConfig defines parameters for a file output.
	AuditConfig    *AuditConfig          `hcl:"audit_config"`     // AuditConfig defines optional parameters for audit events (if EventTypes contains audit)
}

SinkConfig defines the configuration for a Eventer sink

func DefaultSink added in v0.5.0 

func DefaultSink() *SinkConfig

func (*SinkConfig) Validate added in v0.5.0 

func (sc *SinkConfig) Validate() error

type SinkFilter added in v0.5.0 

type SinkFilter struct {
	Type   FilterType `hcl:"type"`   // Type of filter (allow or deny)
	Filter string     `hcl:"filter"` // Filter in a format supported by hashicorp/go-bexpr.
}

SinkFilter defines an event filter (allow or deny) for a sink

func (SinkFilter) Validate added in v0.5.0 

func (s SinkFilter) Validate() error

Validate a SinkFilter

type SinkFormat 

type SinkFormat string // SinkFormat defines the formatting for a sink in a config file stanza (json)

const (
	JSONSinkFormat      SinkFormat = "cloudevents-json" // JSONSinkFormat means the event is formatted as JSON
	TextSinkFormat      SinkFormat = "cloudevents-text" // TextSinkFormat means the event is formmatted as text
	TextHclogSinkFormat SinkFormat = "hclog-text"       // TextHclogSinkFormat means the event is formatted as an hclog text entry
	JSONHclogSinkFormat SinkFormat = "hclog-json"       // JSONHclogSinkFormat means the event is formated as an hclog json entry
)

func (SinkFormat) Validate added in v0.5.0 

func (f SinkFormat) Validate() error

type SinkType 

type SinkType string // SinkType defines the type of sink in a config stanza (file, stderr)

const (
	StderrSink SinkType = "stderr" // StderrSink is written to stderr
	FileSink   SinkType = "file"   // FileSink is written to a file
)

func (SinkType) Validate added in v0.5.0 

func (t SinkType) Validate() error

type StderrSinkTypeConfig added in v0.5.0 

type StderrSinkTypeConfig struct{}

StderrSinkTypeConfig contains configuration structures for file sink types

type TestConfig 

type TestConfig struct {
	EventerConfig     EventerConfig
	AllEvents         *os.File
	ErrorEvents       *os.File
	ObservationEvents *os.File
	AuditEvents       *os.File
}

func TestEventerConfig 

func TestEventerConfig(t *testing.T, testName string, opt ...Option) TestConfig

TestEventerConfig creates a test config and registers a cleanup func for its test tmp files.

type Type 

type Type string

Type represents the event's type 

const (
	EveryType       Type = "*"           // EveryType represents every (all) types of events
	ObservationType Type = "observation" // ObservationType represents observation events
	AuditType       Type = "audit"       // AuditType represents audit events
	ErrorType       Type = "error"       // ErrorType represents error events
	SystemType      Type = "system"      // SysType represents system events
)

func (Type) Validate added in v0.5.0 

func (et Type) Validate() error

type UserInfo 

type UserInfo struct {
	UserId        string `json:"id,omitempty" class:"public"`
	AuthAccountId string `json:"auth_account_id,omitempty" class:"public"`
}

UserInfo defines the fields captured about a user for a Boundary request.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.