The use of a single byte makes it hard to debug tests because it is dumped in decimal format, not ASCII.

I'm imagining something that we could use as part of a GitHub README.md file that gives an overview of the application's structure from both a handler and message perspective.

Foreign in this context meaning any commands that are executed but not handled by this application, or any events that are handled that are not recorded by this application.

There is a mix of formatting. Some error messages use code-like syntax to describe the error and others do not.

The important thing is that these messages are targeted towards application developers and give them a clear sense of how to fix the problem. We should probably make more suggestions on fixes, like we do in testkit.

See dogmatiq/dogma#112 and dogmatiq/dogma@b3c4407 for an example.

Entity should implement fmt.Stringer and return a human readable description of the structure of the entity, suitable for output and diffing in tests.

It does not need to be machine-parsable.

The issue is that handlers that are implemented using projectionkit do not actually implement the dogma.ProjectionMessageHandler interface, but rather some database-specific message handler interface such as projectionkit/sqlprojection.MessageHandler or projectionkit/boltprojection.MessageHandler.

Using SQL as an example, the actual handler passed to RegisterProjection() is an adaptor constructed by a function such as sqlprojection.New() and has a static type of dogma.ProjectionMessageHandler. There is no clear path from the RegisterProjection() call to the concrete implementation of projectionkit/sqlprojection.MessageHandler.

@danilvpetrov and I have discussed a couple of possible solutions:

1. Add explicit support for projectionkit by identifying calls to its "constructor" functions (such as sqlprojection.New()) and analyzing the handler passed to this function instead.
2. Genericize this approach by looking through any arguments passed to any function whose return value is passed to RegisterXXX() to find a type that has a func Configure(XXXConfigurer) method, even if it does not implement the rest of the methods from dogma.XXXMessageHandler.

As per the changes to the CI configuration template in dogmatiq/template-go@eb5bb57.

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x78 pc=0x1495a6e]

goroutine 7 [running]:
github.com/dogmatiq/configkit/static.findConfigurerCalls(0xc0096ecc80, 0x0, 0xc0004eeda8, 0x1, 0x1, 0xc0004eeda8, 0x0, 0x1)
	/Users/james/go/pkg/mod/github.com/dogmatiq/[email protected]/static/analysis.go:100 +0x16e
github.com/dogmatiq/configkit/static.findIndirectConfigurerCalls(0xc0096ecc80, 0xc00075d858, 0xc045d68b80, 0x2202ca0, 0x0, 0xc03d044030)
	/Users/james/go/pkg/mod/github.com/dogmatiq/[email protected]/static/analysis.go:150 +0x165
github.com/dogmatiq/configkit/static.findConfigurerCalls(0xc0096ecc80, 0xc0319b0dc0, 0xc00075d810, 0x1, 0x0, 0x9, 0xc0319b0dc0, 0xc02621b5e0)
	/Users/james/go/pkg/mod/github.com/dogmatiq/[email protected]/static/analysis.go:118 +0x350
github.com/dogmatiq/configkit/static.analyzeApplication(0xc0096ecc80, 0xc0258d0e10, 0xc026011ea0, 0xc026010af0, 0xc026204370, 0xc02620be00, 0xc02620aeb0, 0x1c66388, 0xc008e00500, 0x1c74638, ...)
	/Users/james/go/pkg/mod/github.com/dogmatiq/[email protected]/static/analysis.go:31 +0x15f
github.com/dogmatiq/configkit/static.FromPackages(0xc03d9c80c0, 0x18, 0x18, 0xc01f8f2680, 0x2, 0x2)
	/Users/james/go/pkg/mod/github.com/dogmatiq/[email protected]/static/static.go:52 +0x2e9
github.com/dogmatiq/docserve/analyzer.(*Analyzer).analyzePackages(0xc000190ea0, 0xc000590900, 0xc03d9c8000, 0x18, 0x18, 0xc06cd7a6f0, 0x28, 0xc03d9c8000)
	/Users/james/grit/github.com/dogmatiq/docserve/analyzer/analyze.go:231 +0x5f9
github.com/dogmatiq/docserve/analyzer.(*Analyzer).analyze(0xc000190ea0, 0x1c71ac8, 0xc000044900, 0xc000590900, 0x0, 0x0)
	/Users/james/grit/github.com/dogmatiq/docserve/analyzer/analyze.go:74 +0x5b3
github.com/dogmatiq/docserve/analyzer.(*Analyzer).Analyze(0xc000190ea0, 0x1c71ac8, 0xc000044900, 0xc000590900, 0xc000044910, 0x0)
	/Users/james/grit/github.com/dogmatiq/docserve/analyzer/analyze.go:31 +0x56
github.com/dogmatiq/docserve/analyzer.(*Orchestrator).handle(0xc000191140, 0x1c71ac8, 0xc000044900, 0xc000590900, 0x0, 0x1, 0x0)
	/Users/james/grit/github.com/dogmatiq/docserve/analyzer/orchestrator.go:51 +0xa7
github.com/dogmatiq/docserve/analyzer.(*Orchestrator).Run(0xc000191140, 0x1c71ac8, 0xc000044900, 0x1, 0x14)
	/Users/james/grit/github.com/dogmatiq/docserve/analyzer/orchestrator.go:31 +0x105
main.main.func1.1(0xc00008ca18, 0x8)
	/Users/james/grit/github.com/dogmatiq/docserve/cmd/docserve/main.go:47 +0x3c
golang.org/x/sync/errgroup.(*Group).Go.func1(0xc000120450, 0xc000074500)
	/Users/james/go/pkg/mod/golang.org/x/[email protected]/errgroup/errgroup.go:57 +0x59
created by golang.org/x/sync/errgroup.(*Group).Go
	/Users/james/go/pkg/mod/golang.org/x/[email protected]/errgroup/errgroup.go:54 +0x66
make: *** [run] Error 2

From router-gl@cwx, /cc @danilvpetrov

• Functions for merging EntityMessage[Types|Names] with role conflict detection
• Change ForeignMessage[Types|Names]() to work on on EntityMessage[Types|Names] instead of application interfaces (#60)

Concrete types

• message.NameRoles
• message.NameSet
• message.TypeRoles
• message.TypeSet
• EntityMessageNames
• EntityMessageTypes
• HandlerSet
• RichHandlerSet

There are various other concrete types, such as Identity that contain only scalars, and hence are already comparable with ==.

Interfaces

• Entity
• Application
• Aggregate
• Integration
• Process
• Projection

The RichXXX interfaces do not need additional comparison operations, as they implement the "non-rich" interfaces above which fully describe the identity of the types available from the RichXXX interfaces.

See the template repo CI configuration.

Currently the application and handler values themselves can be nil, but this is not made particularly obviously. Additional, MessageType is unable to represent message types for Go types that are not compiled into the current binary.

This would allow applications and handlers to control how they are referenced in error messages.

This would be useful, for example, with projection kit where the actual handler type would be something unfamiliar to the user (such as *sql.adaptor).

At time of writing, the only way to build a configkit representation of an application is by calling the dogma.Application.Configure() method. However, for most applications all the information required is available statically.

If we were able to build a configkit.Application representation by anaylizing the AST directly that would let us do things like generate application graphs directly from source code.

It may also serve as a useful basis for some of the more advanced checks proposed for inclusion in dogmavet.

It ticks every controller even if the handler type is disabled.

This repo contains the "config API" which is a gRPC service for communicating application configurations. The gRPC definitions and the Go server/client implementations live alongside each other.

I think we should consider moving the gRPC definitions into their own repository (much like dogmatiq/envelopespec and dogmatiq/transportspec) to divorce them from any particular implementation. It seems odd to hide these definitions away in an internal package here while making the others easily accessible.

Due to the code currently prototyped for fixing #104, there is a need to initialise message.Name with the any possible implementation of go/types.Type interface. This would allow bypassing complicated type conversions when analysing the packages statically.

The proposed solution is to add an initialising method to the message package with the following code:

// NameOfType returns the fully-qualified type name of t.
func NameOfType(t types.Type) Name {
	if t == nil {
		panic("type must not be nil")
	}

	return Name{t.String()}
}

These are commands handled by this application, but not produced by this application.

These are similar to the handler-type based method son HandlerSet(), which includes ranging functions:

• RangeCommands(fn)
• RangeEvents(fn)
• RangeTimeouts(fn)

And functions for returning a subset filtered by role:

• Commands() [Name|Type]Roles
• Events() [Name|Type]Roles
• Timeouts() [Name|Type]Roles