Black Friday Kata

Status: stabilizing the domain internally at Trustbit. Not for public use, yet.

Short Story

This is a scaffolding for DDD and Event Sourcing Kata from Trustbit. It is about inventory management.

Grab protobuf protobuf definition for a small inventory-management server.
Generate events and API from that definition for your language. Implement your first method.
Install bfkata binary for your platform from releases (or run go code from this repo)
Run bfkata test to verify that behaviors are implemented correctly
(Future) Run bfkata stress to see how code performs under high load

Long Story

At Trustbit, we want to make it easy to do a domain-modeling kata with event sourcing in a language of your choice. This is good for learning, sharing, and pushing the state of the art. If you are interested, please follow along!

We have picked inventory-management domain, because it brings some interesting behaviors and fault scenarios.

To streamline kata, we took the liberty of:

Defining the API - it is as minimal as possible
Defining event contracts
Writing them down in Google proto3 syntax - so that you can scaffold implementation in a language of your choice
Writing event-driven specs (tests)
Bundling these specs in a cross-platform spec runner

In other worlds:

api/api.proto - defines contracts for API and events;
specs/bundle.txt - contains tests that define desired behaviors;
bfkata binary (this project) - tests any implementation.

This kata is solvable without much code. We went ahead and did it ourselves, as a part of Learning & Sharing at Trustbit.

If you want to play with a slighly different API or behaviors, you could easily do so by forking the project and changing API/specs according to your needs.

Inventory vs Spec APIs

There are two sets of APIs implement:

Inventory service - the real service with methods like "add location" and "reserve (inventory)"
Spec service - special service to run specs remotely.

1. Inventory API

Inventory API is as simple as we could get it. It has methods:

AddLocations
AddProducts
ListLocations
MoveLocation
UpdateInventory
GetLocInventory
Reserve

There are following domain events:

LocationAdded
LocationMoved
ProductAdded
InventoryUpdated
Reserved

You can find full definition in api/api.proto.

2. Spec API

This API has two methods:

About - to return info about the implementation
Spec - to execute a single event-driven spec against this endpoint. bfkata will use it to verify all behaviors.

Event-Driven Specs

Event-driven specs look like this:

move locations
------------------------------------------
GIVEN:
  LocationAdded id:1  name:"Warehouse"
  LocationAdded id:2  name:"Container"
WHEN:
  MoveLocationReq id:2  newParent:1
THEN:
  MoveLocationResp 
EVENTS:
  LocationMoved id:2  newParent:

They are bundled as text file in specs/bundle.txt.

If you want to play with your own specs, just copy bundle.txt someplace, modify and pass to bfkata test as file argument.

Running bfkata

The easiest way to run bfkata is by downloading the latest release for your platform from Releases

With go 1.19 as package

If you have go 1.19 installed on your system (install 1.19, it has generics!), then:

go install github.com/trustbit/bfkata@latest

# prints:
# go: downloading github.com/trustbit/bfkata v1.0.5

bfkata  

# bfkata - test scaffolding for Black Friday kata. Commands:
#
#  api       - print bundled contracts
#  specs     - print bundled test specs
#  test      - run test suite aginst a provided gRPC endpoint

From source code

Clone this repository then run:

go run *.go

# bfkata - test scaffolding for Black Friday kata. Commands:
#
#  api       - print bundled contracts
#  specs     - print bundled test specs
#  test      - run test suite aginst a provided gRPC endpoint

From binary

not implemented yet. Ping Rinat (@abdullin on Twitter) to setup proper releases :)

trustbit / bfkata