https://github.com/trustbit/bfkata
Software kata for DDD and Event Sourcing
https://github.com/trustbit/bfkata
Last synced: 9 months ago
JSON representation
Software kata for DDD and Event Sourcing
- Host: GitHub
- URL: https://github.com/trustbit/bfkata
- Owner: trustbit
- Created: 2022-11-18T14:06:51.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-02-01T10:07:30.000Z (over 3 years ago)
- Last Synced: 2024-06-20T08:47:21.283Z (almost 2 years ago)
- Language: Go
- Size: 889 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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.
1. Grab protobuf [protobuf definition](api/api.proto) for a small inventory-management server.
2. Generate events and API from that definition for your language. Implement your first method.
3. Install bfkata binary for your platform from [releases](https://github.com/trustbit/bfkata/releases) (or run go code from this repo)
4. Run `bfkata test` to verify that [behaviors](specs/bundle.txt) are implemented correctly
5. (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](api/api.proto) - defines contracts for API and events;
- [specs/bundle.txt](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](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](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](https://github.com/trustbit/bfkata/releases)
## With go 1.19 as package
If you have go 1.19 installed on your system (install 1.19, it has generics!), then:
```bash
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:
```bash
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 :)