dogmatiq / dogmacli

🚧 Command line tools for Dogma applications.

Dogma Command Line Tools

The dogma command line interface contains various tools for working with Dogma applications.

Installation

go install github.com/dogmatiq/dogmacli/cmd/dogma@latest

dogmacli's Issues

Ensure no two handlers within the same application produce the same event.

Check that an event is always recorded when an aggregate instance is created or destroyed.

Validate control flow within routing methods.

• every declared consumed message type should be handled
• any other type should result in a `panic(dogma.UnexpectedMessage)
• if there is a type switch (or similar simple branching) warn if a case is for a message that is not declared as being consumed

Check for out-of-order create/destroy/record.

Ensure no two handlers within the same application consume the same command.

Validate control flow within timeout hint methods.

• every declared consumed message type should be handled
• any other type should result in a `panic(dogma.UnexpectedMessage)
• if there is a type switch (or similar simple branching) warn if a case is for a message that is not declared as being consumed

We also need to ensure that projections implemented using projectionkit are analysed properly.

Suggest using `NoTimeoutMessagesBehavior` if a process does not declare any timeouts.

Ensure aggregate and process New() methods never return nil.

Add a subcommand for generating application graphs.

This would use github.com/dogmatiq/configkit/visualization/dot to generate dot files, and if there are actual graphviz bindings for Go we could generate the resulting PNG/SVG images too.

Check for processes that never end.

This check might not be feasible as it is perfectly reasonable to have a process that lives for the entire lifetime of the application, but perhaps we can mark those processes in some way.

Most processes should be fairly short lived.

Suggest using `NoTimeoutHintBehavior` if a handler unconditionally returns a 0 timeout hint.

We also need to ensure that projections implemented using projectionkit are analysed properly.

Suggest using stateless behavior if an aggregate/process declares an empty root type.

Add check that identities do not collide.

• As per the spec (MUST)
  • handlers can't share names
  • handlers and their application must have distinct keys
• As per recommendations (SHOULD)
  • don't share app name with a handler

We also need to ensure that projections implemented using projectionkit are analysed properly.

Add flag to disable recommendations.

Some of the checks align with SHOULD clauses from the specification, but we should be able to run in a mode that only complains if MUST clauses are violated.

Check that aggregate handlers are pure.

This is a bit of a catch-all task that ensures aggregate handlers are pure functions - they should get everything they need from the commands they receive and their current state.

@danilvpetrov I seem to recall in Hive that we may have broken this rule - one of the aggregates is responsible for choosing a domain name randomly, or something like that? Or was it actually deterministic?

Ensure scope log methods are vetted as printf-style functions.

The standard vet tool has something that does this automatically, but I'm not sure what heuristic it uses to begin treating a function as "printf-like". It possibly doesn't work for Dogma because the methods are on interfaces.

Validate control-flow within handler methods.

• every declared consumed message type should be handled
• any other type should result in a `panic(dogma.UnexpectedMessage)
• if there is a type switch (or similar simple branching) warn if a case is for a message that is not declared as being consumed

We also need to ensure that projections implemented using projectionkit are analysed properly.

Ensure that New() methods return a constant/literal.

Ensure processes never route messages to empty IDs.

Add check to ensure that message types do not fill multiple roles within an application.

We also need to ensure that projections implemented using projectionkit are analysed properly.

Check for process timeout loops.

If a process creates a timeout, but upon handling that timeout only schedules another timeout, (and so on) there is an infinite loop that never produces any meaningful work.

Suggest that messages implement `DescribableMessage`.

Check the values of message-producing methods on the scope.

For each of:

• ExecuteCommand()
• RecordEvent()
• ScheduleTimeout()

Check that the parameter they're passed is declared as being produced in the config of THIS handler, and it's the correct role.

Ensure handlers declare consumed/produced messages correctly.

• Aggregates
  • must consume at least one command
  • must produce at least one event
• Processes
  • must consume at least one event
  • must produce at least one command
  • (timeouts are optional)
• Integrations
  • must consume at least one command
  • (events are optional)
• Projections
  • must consume at least one event
  • ensure that projections implemented using projectionkit are analysed properly

None of them can declare the same message type more than once.

Check that timeout times are derived from times in messages, not the system time.

This one might be near impossible, but it should at least catch some common cases like using time.Now().

I'm not 100% confident this is something we want to enforce all the time, but it might be better to produce a diagnostic about it so that its brought to people's attention, then relax it if we find valid use cases for using the system time.

Ensure aggregates never route messages to empty IDs.