bilus / akasha

A minimal CQRS library for Ruby.

Akasha

A budding CQRS library for Ruby.

Installation

Add this line to your application's Gemfile:

gem 'akasha'

And then execute:

$ bundle

Or install it yourself as:

$ gem install akasha

Usage

There is an example Sinatra app under examples/sinatra showing how to use the library in a web application. This library itself makes no assumptions about any web framework, you can use it in any way you see fit.

TODO

• Command routing (default and user-defined)
• Synchronous EventHandler
• HTTP Eventstore storage backend
• Event#id for better idempotence (validate this claim)
• Async EventHandlers (storing cursors in Eventstore, configurable durability guarantees)
  • Uniform interface for Client -- use Event.
  • Rewrite Client
  • Refactor Client code
  • Take care of created_at/updated_at (saved_at?)
  • Tests for HttpEventStore
  • Projections
  • Test for AsyncEventRouter using events not aggregate
  • BUG: Projection reorders events (need to use fromAll after all)
  • Simplify AsyncEventRouter init
  • SyncEventRouter => EventRouter
  • Metadata not persisted
• Refactoring & simplification.
  • Hash-based event and command router
  • Assymetry between data and metadata
  • Faster shutdown
• Namespacing for events and aggregates and the projection
• Way to control the number of retries in face of network failures
• Version-based concurrency
  • Retries.
• Documentation
  • Yard docs on github pages
  • Quick start
  • Movie theater booking
• User-defined ConflictResolver.
• Snapshots
• Telemetry (configurable backend, default: Dogstatsd)
• Socket-based Eventstore storage backend

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. See Running tests.

You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org. While on a branch, add ".pre" to the version number.

Release rules:

1. All merges to master build & push gems and git tags with versions.
2. If version.rb is pre-release version, e.g. 4.0.0.pre, Travis will automatically append the build number and push it.
3. If version.rb is a regular version, e.g. 5.0.0, Travis will not append build number. (I haven't tested it yet.)

Running tests

Some tests require Eventstore to be running and available via eventstore host name. You can exclude these specs:

rspec --tag ~integration

The easiest way to run integration tests:

/bin/integration-tests.sh

This will use docker-compose to spin up containers containing the dependencies and tests themselves.

Because it's pretty slow, you may want to spin up a docker container containing event store:

docker run -e EVENTSTORE_START_STANDARD_PROJECTIONS=true --name akasha-eventstore -it -p 2113:2113 -p 1113:1113 -d eventstore/eventstore

and use RSpec run just integration specs like so:

rspec --tag integration

or run all tests:

rspec

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/bilus/akasha.

1. Create a new PR, setting version in lib/akasha/version.rb to a prerelease version, example: "0.4.0.pre".
2. Update CHANGELOG.

License

The gem is available as open source under the terms of the MIT License.

akasha's Issues

Simplify route registration methods

Do you like the current interface to CommandRouter?

  # This is how you link commands to aggregates.
  @command_router.register_default_route(:sign_up, User)

  # Nearly identital to the default handling above but we're setting the admin
  # flag to demo custom command handling.
  @command_router.register_route(:sign_up_admin) do |aggregate_id, **data|
[...]

I don't quite like the current method names, what should they be called? Any ideas?

If/when there's the ultimate DSL for this we can be more nit-picking but I'd like this to be intuitive even now.

Refactoring ideas

1. from @Holek: consider putting JS snippets into erb files

No `bundle update` in CI/CD

Too lazy to write: https://wconrad.github.io/20150123/why-to-check-in-gemfile-dot-lock.html :)

Unhandled events in stream break aggregate loading

Given an event in an aggregate's stream which isn't handled by the aggregate (no corresponding #on_xx), loading of the aggregate will fail due to a missing method.