106 lines
2.7 KiB
Markdown
106 lines
2.7 KiB
Markdown
# Aether
|
|
|
|
**Distributed event sourcing primitives for Go, powered by NATS.**
|
|
|
|
---
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
make build # go build ./...
|
|
make test # go test ./...
|
|
make lint # golangci-lint run
|
|
make clean # go clean
|
|
```
|
|
|
|
## NATS Server Requirement
|
|
|
|
Integration tests require NATS with JetStream enabled:
|
|
|
|
```bash
|
|
brew install nats-server
|
|
nats-server -js
|
|
```
|
|
|
|
Run tests in a separate terminal after starting NATS.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
aether/
|
|
├── event.go # Event, ActorSnapshot, EventStore interface
|
|
├── eventbus.go # EventBus, EventBroadcaster interface
|
|
├── nats_eventbus.go # NATSEventBus implementation
|
|
├── metrics*.go # Prometheus metrics
|
|
├── store/ # EventStore implementations
|
|
│ ├── memory.go # InMemoryEventStore (testing)
|
|
│ └── jetstream.go # JetStreamEventStore (production)
|
|
├── cluster/ # Cluster management
|
|
│ ├── manager.go # ClusterManager
|
|
│ ├── discovery.go # NodeDiscovery
|
|
│ ├── hashring.go # ConsistentHashRing
|
|
│ ├── shard.go # ShardManager
|
|
│ ├── leader.go # LeaderElection
|
|
│ └── types.go # Cluster types
|
|
├── examples/ # Usage examples
|
|
└── eventstorming/ # Domain modeling reference
|
|
```
|
|
|
|
## Core Patterns
|
|
|
|
### Event Versioning
|
|
|
|
Events for each actor must have monotonically increasing versions:
|
|
|
|
```go
|
|
currentVersion, _ := store.GetLatestVersion(actorID)
|
|
event := &aether.Event{
|
|
ActorID: actorID,
|
|
Version: currentVersion + 1,
|
|
// ...
|
|
}
|
|
err := store.SaveEvent(event)
|
|
if errors.Is(err, aether.ErrVersionConflict) {
|
|
// Reload and retry
|
|
}
|
|
```
|
|
|
|
### Namespace Isolation
|
|
|
|
Namespaces provide logical boundaries for events:
|
|
|
|
```go
|
|
// Event bus namespace
|
|
ch := eventBus.Subscribe("tenant-abc")
|
|
eventBus.Publish("tenant-abc", event)
|
|
|
|
// Store namespace
|
|
store, _ := store.NewJetStreamEventStoreWithNamespace(natsConn, "events", "tenant-abc")
|
|
```
|
|
|
|
Namespaces sanitize special characters and prefix stream names for complete data isolation.
|
|
|
|
### JetStream Cache Behavior
|
|
|
|
`JetStreamEventStore` caches actor versions for performance. Cache is invalidated when `GetLatestVersion` detects a newer version from external writes.
|
|
|
|
## Testing
|
|
|
|
- Unit tests: `go test -v ./...`
|
|
- Single test: `go test -v -run TestName`
|
|
- Single file: `go test -v ./store/...`
|
|
- Benchmarks: `go test -bench=. -benchmem`
|
|
|
|
Integration tests require running NATS server first.
|
|
|
|
## Linting
|
|
|
|
```bash
|
|
golangci-lint run
|
|
golangci-lint run --fix
|
|
```
|
|
|
|
## References
|
|
|
|
- [vision.md](./vision.md) - Product vision and principles
|
|
- [examples/README.md](./examples/README.md) - Example patterns |