configkit

package module
v0.13.0 Latest Latest
Warning

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

Go to latest
Published: Mar 25, 2024 License: MIT Imports: 16 Imported by: 28

README

Dogma Configuration Toolkit

Validate and inspect Dogma application configurations.

Documentation Latest Version Build Status Code Coverage

Documentation

Overview

Package configkit is a set of utilities for working with Dogma application configurations as well as that of their constituent message handlers and the messages that they operate upon.

Index

Constants

This section is empty.

Variables

HandlerTypes is a slice of the valid handler types.

Functions

func IsApplicationEqual added in v0.2.0

func IsApplicationEqual(a, b Application) bool

IsApplicationEqual compares two applications for equality.

It returns true if both applications:

  1. have the same identity
  2. produce and consume the same messages, with the same roles
  3. are implemented using the same Go types
  4. contain equivalent handlers

Point 3. refers to the type used to implement the dogma.Application interface (not the type used to implement the configkit.Application interface).

func IsHandlerEqual added in v0.2.0

func IsHandlerEqual(a, b Handler) bool

IsHandlerEqual compares two handlers for equality.

It returns true if both handlers:

  1. have the same identity
  2. produce and consume the same messages, with the same roles
  3. are implemented using the same Go types

Point 3. refers to the type used to implement the dogma.Aggregate, dogma.Process, dogma.Integration or dogma.Projection interface (not the type used to implement the configkit.Handler interface).

This definition of equality relies on the fact that no single Go type can implement more than one Dogma handler interface because they all contain a Configure() method with different signatures.

func Recover

func Recover(err *error)

Recover recovers from a configuration related panic.

It is intended to be used in a defer statement. If the panic value is a Error, it is assigned to *err.

func ToString added in v0.2.0

func ToString(e Entity) string

ToString returns a human-readable string representation of the given entity.

func ValidateIdentityKey added in v0.9.1

func ValidateIdentityKey(k string) error

ValidateIdentityKey returns nil if n is a valid application or handler key; otherwise, it returns an error.

func ValidateIdentityName added in v0.9.1

func ValidateIdentityName(n string) error

ValidateIdentityName returns nil if n is a valid application or handler name; otherwise, it returns an error.

Types

type Aggregate

type Aggregate interface {
	Handler
}

Aggregate is an interface that represents the configuration of a Dogma aggregate message handler.

type Application

type Application interface {
	Entity

	// Handlers returns the handlers within this application.
	Handlers() HandlerSet
}

Application is an interface that represents the configuration of a Dogma application.

type Entity

type Entity interface {
	// Identity returns the identity of the entity.
	Identity() Identity

	// TypeName returns the fully-qualified type name of the entity.
	TypeName() string

	// MessageNames returns information about the messages used by the entity.
	MessageNames() EntityMessageNames

	// AcceptVisitor calls the appropriate method on v for this entity type.
	AcceptVisitor(ctx context.Context, v Visitor) error
}

Entity is an interface that represents the configuration of a Dogma "entity" such as an application or handler.

Each implementation of this interface represents the configuration described by a call to the entity's Configure() method.

type EntityMessageNames

type EntityMessageNames struct {
	// Produced is a set of message names produced by the entity.
	Produced message.NameRoles

	// Consumed is a set of message names consumed by the entity.
	Consumed message.NameRoles
}

EntityMessageNames describes how messages are used within a Dogma entity where each message is identified by its name.

func (EntityMessageNames) All added in v0.2.0

All returns the type roles of all messages, both produced and consumed.

func (EntityMessageNames) Foreign added in v0.5.0

Foreign returns the subset of message names used by a set of entities that must be communicated beyond the scope of those entities.

This includes:

  • commands that are produced by the entity, but consumed elsewhere
  • commands that are consumed by the entity, but produced elsewhere
  • events that are consumed by the entity, but produced elsewhere

func (EntityMessageNames) IsEqual added in v0.2.0

IsEqual returns true if m is equal to o.

func (EntityMessageNames) RoleOf added in v0.2.0

RoleOf returns the role associated with n, if any.

type EntityMessageTypes

type EntityMessageTypes struct {
	// Produced is a set of message types produced by the entity.
	Produced message.TypeRoles

	// Consumed is a set of message types consumed by the entity.
	Consumed message.TypeRoles
}

EntityMessageTypes describes how messages are used within a Dogma entity where each message is identified by its type.

func (EntityMessageTypes) All added in v0.2.0

All returns the type roles of all messages, both produced and consumed.

func (EntityMessageTypes) Foreign added in v0.5.0

Foreign returns the subset of message types used by a set of entities that must be communicated beyond the scope of those entities.

This includes:

  • commands that are produced by this entity, but consumed elsewhere
  • commands that are consumed by this entity, but produced elsewhere
  • events that are consumed by this entity, but produced elsewhere

func (EntityMessageTypes) IsEqual added in v0.2.0

IsEqual returns true if m is equal to o.

func (EntityMessageTypes) RoleOf added in v0.2.0

RoleOf returns the role associated with t, if any.

type Error

type Error = validation.Error

Error is an error representing a fault in an entity's configuration.

type Handler

type Handler interface {
	Entity

	// HandlerType returns the type of handler.
	HandlerType() HandlerType
}

Handler is a specialization of the Entity interface for message handlers.

type HandlerSet

type HandlerSet map[Identity]Handler

HandlerSet is a collection of handlers.

func NewHandlerSet

func NewHandlerSet(handlers ...Handler) HandlerSet

NewHandlerSet returns a HandlerSet containing the given handlers.

It panics if any of the handler identities conflict.

func (HandlerSet) AcceptVisitor added in v0.1.1

func (s HandlerSet) AcceptVisitor(ctx context.Context, v Visitor) error

AcceptVisitor visits each handler in the set.

It returns the error returned by the first handler to return a non-nil error. It returns nil if all handlers accept the visitor without failure.

The order in which handlers are visited is not guaranteed.

func (HandlerSet) Add

func (s HandlerSet) Add(h Handler) bool

Add adds a handler to the set.

It returns true if the handler was added, or false if the set already contained a handler with the same name or key as h.

func (HandlerSet) Aggregates added in v0.3.0

func (s HandlerSet) Aggregates() []Aggregate

Aggregates returns a slice containing the aggregate handlers in the set.

func (HandlerSet) ByIdentity

func (s HandlerSet) ByIdentity(i Identity) (Handler, bool)

ByIdentity returns the handler with the given identity.

func (HandlerSet) ByKey

func (s HandlerSet) ByKey(k string) (Handler, bool)

ByKey returns the handler with the given key.

func (HandlerSet) ByName

func (s HandlerSet) ByName(n string) (Handler, bool)

ByName returns the handler with the given name.

func (HandlerSet) ByType

func (s HandlerSet) ByType(t HandlerType) HandlerSet

ByType returns the subset of handlers of the given type.

func (HandlerSet) ConsumersOf

func (s HandlerSet) ConsumersOf(n message.Name) HandlerSet

ConsumersOf returns the subset of handlers that consume messages with the given name.

func (HandlerSet) Filter

func (s HandlerSet) Filter(fn func(Handler) bool) HandlerSet

Filter returns the subset of handlers for which the given predicate function returns true.

func (HandlerSet) Find

func (s HandlerSet) Find(fn func(Handler) bool) (Handler, bool)

Find returns a handler from the set for which the given predicate function returns true.

func (HandlerSet) Has

func (s HandlerSet) Has(h Handler) bool

Has returns true if s contains h.

func (HandlerSet) Integrations added in v0.3.0

func (s HandlerSet) Integrations() []Integration

Integrations returns a slice containing the integration handlers in the set.

func (HandlerSet) IsEqual added in v0.2.0

func (s HandlerSet) IsEqual(o HandlerSet) bool

IsEqual returns true if o contains the same handlers as s.

func (HandlerSet) MessageNames added in v0.7.3

func (s HandlerSet) MessageNames() EntityMessageNames

MessageNames returns information about the messages used all handlers in s.

func (HandlerSet) Processes added in v0.3.0

func (s HandlerSet) Processes() []Process

Processes returns a slice containing the process handlers in the set.

func (HandlerSet) ProducersOf

func (s HandlerSet) ProducersOf(n message.Name) HandlerSet

ProducersOf returns the subset of handlers that produce messages with the given name.

func (HandlerSet) Projections added in v0.3.0

func (s HandlerSet) Projections() []Projection

Projections returns a slice containing the projection handlers in the set.

func (HandlerSet) RangeAggregates added in v0.3.0

func (s HandlerSet) RangeAggregates(fn func(Aggregate) bool) bool

RangeAggregates invokes fn once for each aggregate handler in the set.

Iteration stops when fn returns false or once fn has been invoked for all aggregate handlers in the set.

It returns true if fn returned true for all aggregate handlers.

func (HandlerSet) RangeIntegrations added in v0.3.0

func (s HandlerSet) RangeIntegrations(fn func(Integration) bool) bool

RangeIntegrations invokes fn once for each integration handler in the set.

Iteration stops when fn returns false or once fn has been invoked for all integration handlers in the set.

It returns true if fn returned true for all integration handlers.

func (HandlerSet) RangeProcesses added in v0.3.0

func (s HandlerSet) RangeProcesses(fn func(Process) bool) bool

RangeProcesses invokes fn once for each process handler in the set.

Iteration stops when fn returns false or once fn has been invoked for all process handlers in the set.

It returns true if fn returned true for all process handlers.

func (HandlerSet) RangeProjections added in v0.3.0

func (s HandlerSet) RangeProjections(fn func(Projection) bool) bool

RangeProjections invokes fn once for each projection handler in the set.

Iteration stops when fn returns false or once fn has been invoked for all projection handlers in the set.

It returns true if fn returned true for all projection handlers.

type HandlerType

type HandlerType string

HandlerType is an enumeration of the types of handlers.

const (
	// AggregateHandlerType is the handler type for dogma.AggregateMessageHandler.
	AggregateHandlerType HandlerType = "aggregate"

	// ProcessHandlerType is the handler type for dogma.ProcessMessageHandler.
	ProcessHandlerType HandlerType = "process"

	// IntegrationHandlerType is the handler type for dogma.IntegrationMessageHandler.
	IntegrationHandlerType HandlerType = "integration"

	// ProjectionHandlerType is the handler type for dogma.ProjectionMessageHandler.
	ProjectionHandlerType HandlerType = "projection"
)

func ConsumersOf

func ConsumersOf(r message.Role) []HandlerType

ConsumersOf returns the handler types that can consume messages with the given role.

func ProducersOf

func ProducersOf(r message.Role) []HandlerType

ProducersOf returns the handler types that can produces messages with the given role.

func (HandlerType) Consumes

func (t HandlerType) Consumes() []message.Role

Consumes returns the roles of messages that can be consumed by handlers of this type.

func (HandlerType) Is

func (t HandlerType) Is(types ...HandlerType) bool

Is returns true if t is one of the given types.

func (HandlerType) IsConsumerOf

func (t HandlerType) IsConsumerOf(r message.Role) bool

IsConsumerOf returns true if handlers of type t can consume messages with the given role.

func (HandlerType) IsProducerOf

func (t HandlerType) IsProducerOf(r message.Role) bool

IsProducerOf returns true if handlers of type t can produce messages with the given role.

func (HandlerType) MarshalBinary

func (t HandlerType) MarshalBinary() ([]byte, error)

MarshalBinary returns a binary representation of the handler type.

func (HandlerType) MarshalText

func (t HandlerType) MarshalText() ([]byte, error)

MarshalText returns a UTF-8 representation of the handler type.

func (HandlerType) MustBe

func (t HandlerType) MustBe(types ...HandlerType)

MustBe panics if t is not one of the given types.

func (HandlerType) MustNotBe

func (t HandlerType) MustNotBe(types ...HandlerType)

MustNotBe panics if t is one of the given types.

func (HandlerType) MustValidate

func (t HandlerType) MustValidate()

MustValidate panics if t is not a valid handler type.

func (HandlerType) Produces

func (t HandlerType) Produces() []message.Role

Produces returns the roles of messages that can be produced by handlers of this type.

func (HandlerType) ShortString

func (t HandlerType) ShortString() string

ShortString returns a short (3-character) representation of the handler type.

func (HandlerType) String

func (t HandlerType) String() string

String returns a string representation of the handler type.

func (*HandlerType) UnmarshalBinary

func (t *HandlerType) UnmarshalBinary(data []byte) error

UnmarshalBinary unmarshals a type from its binary representation.

func (*HandlerType) UnmarshalText

func (t *HandlerType) UnmarshalText(text []byte) error

UnmarshalText unmarshals a type from its UTF-8 representation.

func (HandlerType) Validate

func (t HandlerType) Validate() error

Validate returns an error if t is not a valid handler type.

type Identity

type Identity struct {
	// Name is the name component of the identity.
	//
	// For handlers, it is unique within an application at any given version,
	// but may be changed over time.
	//
	// It is allowed, but not recommended to use the same name for an
	// application as one of its constituent handlers.
	Name string

	// Key is the key component of the identity.
	//
	// It is not only unique within an application, but forever immutable. It is
	// not permitted for an application and one of its constituent handlers to
	// share the same key.
	Key string
}

Identity is the application-defined identity of a Dogma entity.

func MustNewIdentity

func MustNewIdentity(n, k string) Identity

MustNewIdentity returns a new identity.

It panics if either of the name or key components is invalid.

func NewIdentity

func NewIdentity(n, k string) (Identity, error)

NewIdentity returns a new identity.

It returns a non-nil error if either of the name or key components is invalid.

func (Identity) ConflictsWith

func (i Identity) ConflictsWith(ident Identity) bool

ConflictsWith returns true if i has the same name or key as ident.

func (Identity) IsZero

func (i Identity) IsZero() bool

IsZero returns true if the identity is the zero-value.

func (Identity) MarshalBinary added in v0.2.0

func (i Identity) MarshalBinary() ([]byte, error)

MarshalBinary returns a binary representation of the identity.

func (Identity) MarshalText added in v0.2.0

func (i Identity) MarshalText() ([]byte, error)

MarshalText returns a UTF-8 representation of the identity.

func (Identity) String

func (i Identity) String() string

func (*Identity) UnmarshalBinary added in v0.2.0

func (i *Identity) UnmarshalBinary(data []byte) error

UnmarshalBinary unmarshals an identity from its binary representation.

func (*Identity) UnmarshalText added in v0.2.0

func (i *Identity) UnmarshalText(text []byte) error

UnmarshalText unmarshals an identity from its UTF-8 representation.

func (Identity) Validate

func (i Identity) Validate() error

Validate returns an error if i is not a valid identity.

type Integration

type Integration interface {
	Handler
}

Integration is an interface that represents the configuration of a Dogma integration message handler.

type Process

type Process interface {
	Handler
}

Process is an interface that represents the configuration of a Dogma process message handler.

type Projection

type Projection interface {
	Handler
}

Projection is an interface that represents the configuration of a Dogma projection message handler.

type RichAggregate

type RichAggregate interface {
	RichHandler

	// Handler returns the underlying message handler.
	Handler() dogma.AggregateMessageHandler
}

RichAggregate is a specialization of Aggregate that exposes information about the Go types used to implement the underlying Dogma handler.

func FromAggregate

FromAggregate returns the configuration for an aggregate message handler.

It panics if the handler is configured incorrectly. Use Recover() to convert configuration related panic values to errors.

type RichApplication

type RichApplication interface {
	RichEntity

	// Handlers returns the handlers within this application.
	Handlers() HandlerSet

	// RichHandlers returns the handlers within this application.
	RichHandlers() RichHandlerSet

	// Application returns the underlying application.
	Application() dogma.Application
}

RichApplication is a specialization of Application that exposes information about the Go types used to implement the Dogma application.

func FromApplication

func FromApplication(a dogma.Application) RichApplication

FromApplication returns the configuration for an application.

It panics if the application is configured incorrectly. Use Recover() to convert configuration related panic values to errors.

type RichEntity

type RichEntity interface {
	Entity

	// ReflectType returns the reflect.Type of the Dogma entity.
	ReflectType() reflect.Type

	// MessageTypes returns information about the messages used by the entity.
	MessageTypes() EntityMessageTypes

	// AcceptRichVisitor calls the appropriate method on v for this
	// configuration type.
	AcceptRichVisitor(ctx context.Context, v RichVisitor) error
}

RichEntity is a specialization of the Entity interface that exposes information about the Go types used to implement the Dogma entity.

type RichHandler

type RichHandler interface {
	RichEntity

	// HandlerType returns the type of handler.
	HandlerType() HandlerType
}

RichHandler is a specialization of the Handler interface that exposes information about the Go types used to implement the Dogma application.

type RichHandlerSet

type RichHandlerSet map[Identity]RichHandler

RichHandlerSet is a collection of rich handlers.

func NewRichHandlerSet

func NewRichHandlerSet(handlers ...RichHandler) RichHandlerSet

NewRichHandlerSet returns a RichHandlerSet containing the given handlers.

It panics if any of the handler identities conflict.

func (RichHandlerSet) AcceptRichVisitor added in v0.1.1

func (s RichHandlerSet) AcceptRichVisitor(ctx context.Context, v RichVisitor) error

AcceptRichVisitor visits each handler in the set.

It returns the error returned by the first handler to return a non-nil error. It returns nil if all handlers accept the visitor without failure.

The order in which handlers are visited is not guaranteed.

func (RichHandlerSet) Add

func (s RichHandlerSet) Add(h RichHandler) bool

Add adds a handler to the set.

It returns true if the handler was added, or false if the set already contained a handler with the same name or key as h.

func (RichHandlerSet) Aggregates added in v0.3.0

func (s RichHandlerSet) Aggregates() []RichAggregate

Aggregates returns a slice containing the aggregate handlers in the set.

func (RichHandlerSet) ByIdentity

func (s RichHandlerSet) ByIdentity(i Identity) (RichHandler, bool)

ByIdentity returns the handler with the given identity.

func (RichHandlerSet) ByKey

func (s RichHandlerSet) ByKey(k string) (RichHandler, bool)

ByKey returns the handler with the given key.

func (RichHandlerSet) ByName

func (s RichHandlerSet) ByName(n string) (RichHandler, bool)

ByName returns the handler with the given name.

func (RichHandlerSet) ByType

ByType returns the subset of handlers of the given type.

func (RichHandlerSet) ConsumersOf

func (s RichHandlerSet) ConsumersOf(t message.Type) RichHandlerSet

ConsumersOf returns the subset of handlers that consume messages of the given type.

func (RichHandlerSet) Filter

func (s RichHandlerSet) Filter(fn func(RichHandler) bool) RichHandlerSet

Filter returns the subset of handlers for which the given predicate function returns true.

func (RichHandlerSet) Find

func (s RichHandlerSet) Find(fn func(RichHandler) bool) (RichHandler, bool)

Find returns a handler from the set for which the given predicate function returns true.

func (RichHandlerSet) Has

func (s RichHandlerSet) Has(h RichHandler) bool

Has returns true if s contains h.

func (RichHandlerSet) Integrations added in v0.3.0

func (s RichHandlerSet) Integrations() []RichIntegration

Integrations returns a slice containing the integration handlers in the set.

func (RichHandlerSet) IsEqual added in v0.2.0

func (s RichHandlerSet) IsEqual(o RichHandlerSet) bool

IsEqual returns true if o contains the same handlers as s.

func (RichHandlerSet) MessageTypes added in v0.7.3

func (s RichHandlerSet) MessageTypes() EntityMessageTypes

MessageTypes returns information about the messages used all handlers in s.

func (RichHandlerSet) Processes added in v0.3.0

func (s RichHandlerSet) Processes() []RichProcess

Processes returns a slice containing the process handlers in the set.

func (RichHandlerSet) ProducersOf

func (s RichHandlerSet) ProducersOf(t message.Type) RichHandlerSet

ProducersOf returns the subset of handlers that produce messages of the given type.

func (RichHandlerSet) Projections added in v0.3.0

func (s RichHandlerSet) Projections() []RichProjection

Projections returns a slice containing the projection handlers in the set.

func (RichHandlerSet) RangeAggregates added in v0.3.0

func (s RichHandlerSet) RangeAggregates(fn func(RichAggregate) bool) bool

RangeAggregates invokes fn once for each aggregate handler in the set.

Iteration stops when fn returns false or once fn has been invoked for all aggregate handlers in the set.

It returns true if fn returned true for all aggregate handlers.

func (RichHandlerSet) RangeIntegrations added in v0.3.0

func (s RichHandlerSet) RangeIntegrations(fn func(RichIntegration) bool) bool

RangeIntegrations invokes fn once for each integration handler in the set.

Iteration stops when fn returns false or once fn has been invoked for all integration handlers in the set.

It returns true if fn returned true for all integration handlers.

func (RichHandlerSet) RangeProcesses added in v0.3.0

func (s RichHandlerSet) RangeProcesses(fn func(RichProcess) bool) bool

RangeProcesses invokes fn once for each process handler in the set.

Iteration stops when fn returns false or once fn has been invoked for all process handlers in the set.

It returns true if fn returned true for all process handlers.

func (RichHandlerSet) RangeProjections added in v0.3.0

func (s RichHandlerSet) RangeProjections(fn func(RichProjection) bool) bool

RangeProjections invokes fn once for each projection handler in the set.

Iteration stops when fn returns false or once fn has been invoked for all projection handlers in the set.

It returns true if fn returned true for all projection handlers.

type RichIntegration

type RichIntegration interface {
	RichHandler

	// Handler returns the underlying message handler.
	Handler() dogma.IntegrationMessageHandler
}

RichIntegration is a specialization of Integration that exposes information about the Go types used to implement the underlying Dogma handler.

func FromIntegration

FromIntegration returns the configuration for an integration message handler.

It panics if the handler is configured incorrectly. Use Recover() to convert configuration related panic values to errors.

type RichProcess

type RichProcess interface {
	RichHandler

	// Handler returns the underlying message handler.
	Handler() dogma.ProcessMessageHandler
}

RichProcess is a specialization of Process that exposes information about the Go types used to implement the underlying Dogma handler.

func FromProcess

FromProcess returns the configuration for a process message handler.

It panics if the handler is configured incorrectly. Use Recover() to convert configuration related panic values to errors.

type RichProjection

type RichProjection interface {
	RichHandler

	// Handler returns the underlying message handler.
	Handler() dogma.ProjectionMessageHandler

	// DeliveryPolicy returns the projection's delivery policy.
	DeliveryPolicy() dogma.ProjectionDeliveryPolicy
}

RichProjection is a specialization of Projection that exposes information about the Go types used to implement the underlying Dogma handler.

func FromProjection

FromProjection returns the configuration for a projection message handler.

It panics if the handler is configured incorrectly. Use Recover() to convert configuration related panic values to errors.

type RichVisitor

type RichVisitor interface {
	VisitRichApplication(context.Context, RichApplication) error
	VisitRichAggregate(context.Context, RichAggregate) error
	VisitRichProcess(context.Context, RichProcess) error
	VisitRichIntegration(context.Context, RichIntegration) error
	VisitRichProjection(context.Context, RichProjection) error
}

RichVisitor is a visitor that visits "rich" configurations.

type Visitor

type Visitor interface {
	VisitApplication(context.Context, Application) error
	VisitAggregate(context.Context, Aggregate) error
	VisitProcess(context.Context, Process) error
	VisitIntegration(context.Context, Integration) error
	VisitProjection(context.Context, Projection) error
}

Visitor is a visitor that visits configurations.

Directories

Path Synopsis
Package api exposes application configurations via a gRPC API.
Package api exposes application configurations via a gRPC API.
Package fixtures is a set of test fixtures and mocks of the various configkit interfaces.
Package fixtures is a set of test fixtures and mocks of the various configkit interfaces.
internal
Package message provides utilities for representing information about Dogma messages and their use within an application.
Package message provides utilities for representing information about Dogma messages and their use within an application.
Package static uses static analysis to produce application and handler configurations directly from source code.
Package static uses static analysis to produce application and handler configurations directly from source code.
visualization
dot
Package dot generates a visualization of a Dogma application configurations in Graphviz DOT format.
Package dot generates a visualization of a Dogma application configurations in Graphviz DOT format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL