configkit

package module
v0.16.0 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2024 License: MIT Imports: 22 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

View Source 
var HandlerTypes = []HandlerType{
	AggregateHandlerType,
	ProcessHandlerType,
	IntegrationHandlerType,
	ProjectionHandlerType,
}

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 message types
  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 message types
  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 ToProto added in v0.13.3 

func ToProto(app Application) (*configpb.Application, error)

ToProto converts an application configuration to its protocol buffers representation.

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.

func FromProto added in v0.13.3 

func FromProto(app *configpb.Application) (Application, error)

FromProto converts an application configuration from its protocol buffers representation.

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() EntityMessages[message.Name]

	// 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 EntityMessage added in v0.15.0 

type EntityMessage struct {
	Kind                   message.Kind
	IsProduced, IsConsumed bool
}

EntityMessage describes a message used by a Dogma entity.

type EntityMessages added in v0.15.0 

type EntityMessages[K comparable] map[K]EntityMessage

EntityMessages describes the messages used by a Dogma entity.

func (EntityMessages[K]) Consumed added in v0.15.0 

func (m EntityMessages[K]) Consumed(filter ...message.Kind) iter.Seq2[K, message.Kind]

Consumed returns an iterator that yields the messages that are consumed by the entity.

func (EntityMessages[K]) IsEqual added in v0.15.0 

func (m EntityMessages[K]) IsEqual(n EntityMessages[K]) bool

IsEqual returns true if m is equal to n.

func (EntityMessages[K]) Produced added in v0.15.0 

func (m EntityMessages[K]) Produced(filter ...message.Kind) iter.Seq2[K, message.Kind]

Produced returns an iterator that yields the messages that are produced by the entity.

func (EntityMessages[K]) Update added in v0.15.0 

func (m EntityMessages[K]) Update(k K, fn func(K, *EntityMessage))

Update updates the message with the given key by calling fn.

If, after calling fn, the EntityMessage is neither produced nor consumed, it is removed from the map.

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

	// IsDisabled returns true if the handler is disabled.
	IsDisabled() bool
}

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() EntityMessages[message.Name]

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(k message.Kind) []HandlerType

ConsumersOf returns the handler types that can consume messages of kind k.

func ProducersOf 

func ProducersOf(k message.Kind) []HandlerType

ProducersOf returns the handler types that can produces messages of kind k.

func (HandlerType) Consumes 

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

Consumes returns the kind of messages that can be consumed by handlers of type t.

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(k message.Kind) bool

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

func (HandlerType) IsProducerOf 

func (t HandlerType) IsProducerOf(k message.Kind) bool

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

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.Kind

Produces returns the kinds of messages that can be produced by handlers of type t.

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 

func FromAggregate(h dogma.AggregateMessageHandler) RichAggregate

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() EntityMessages[message.Type]

	// 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

	// IsDisabled returns true if the handler is disabled.
	IsDisabled() bool
}

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 

func (s RichHandlerSet) ByType(t HandlerType) RichHandlerSet

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() EntityMessages[message.Type]

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 

func FromIntegration(h dogma.IntegrationMessageHandler) RichIntegration

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 

func FromProcess(h dogma.ProcessMessageHandler) RichProcess

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 

func FromProjection(h dogma.ProjectionMessageHandler) RichProjection

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.

Source Files

View all Source files

Directories

Path Synopsis
Package api exposes application configurations via a gRPC API.
 Package api exposes application configurations via a gRPC API.
internal
typename/goreflect
typename/gotypes
typename/internal/typenametest
validation
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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.