ex_esdb

# Changelog

## version 0.1.2 (2025.07.14)

### Store Configuration Enhancement

#### New Environment Variables

- **`EX_ESDB_STORE_DESCRIPTION`**: Human-readable description of the store for documentation and operational purposes
- **`EX_ESDB_STORE_TAGS`**: Comma-separated tags for store categorization and filtering (e.g., "production,cluster,core")

#### Rich Store Configuration

- **Operational Metadata**: Added `created_at`, `version`, and `status` fields to store configuration
- **Resource Management**: Added `priority` and `auto_start` fields for resource allocation control
- **Administrative Info**: Enhanced store registry with `tags`, `environment`, and `description` fields
- **Enhanced Querying**: Store registry now supports filtering by tags, environment, priority, and other metadata

#### Configuration Integration

- **Runtime Configuration**: New environment variables integrated into `config/runtime.exs`
- **Options System**: Added parsers in `ExESDB.Options` with comma-separated tag parsing
- **Store Registry**: Enhanced `build_store_config/1` to include all new metadata fields
- **Development Environment**: Updated `dev-env/*.yaml` files with new environment variables

### Architectural Refactoring

#### NotificationSystem Introduction

- **New Core Component**: Created `ExESDB.NotificationSystem` as a core supervisor for event notification
- **Leadership Integration**: Moved `LeaderSystem` from clustering layer to core system
- **Core System Enhancement**: Updated `CoreSystem` to include `NotificationSystem` alongside `PersistenceSystem` and `StoreSystem`
- **Supervision Order**: `PersistenceSystem` → `NotificationSystem` → `StoreSystem` for proper dependency management

#### LeaderWorker Availability Fix

- **Core System Integration**: LeaderWorker now starts as part of core system, not clustering components
- **Startup Order**: LeaderWorker is available before clustering components attempt to use it
- **Resolved `:noproc` Error**: Fixed LeaderWorker activation failures by ensuring it's always running when needed
- **Single and Cluster Mode**: LeaderWorker now available in both single-node and cluster modes

#### System Architecture Cleanup

- **Removed LeadershipSystem**: Consolidated functionality into `NotificationSystem`
- **Cleaner Separation**: Core functionality (leadership, events) vs clustering (coordination, membership)
- **Improved Documentation**: Updated supervision tree documentation to reflect new architecture
- **Simplified Dependencies**: Reduced coupling between core and clustering components

### Process Management Enhancement

#### Graceful Shutdown Implementation

- **Universal Coverage**: All 18 GenServer processes now implement graceful shutdown
- **Terminate Callbacks**: Added `terminate/2` callbacks to all GenServers for proper cleanup
- **Exit Trapping**: Enabled `Process.flag(:trap_exit, true)` on all GenServers
- **Resource Cleanup**: Proper cleanup of Swarm registrations, PubSub subscriptions, and Khepri stores

#### Enhanced Process Lifecycle

- **Swarm Registration Cleanup**: Worker processes properly unregister from Swarm on shutdown
- **PubSub Subscription Cleanup**: EventProjector properly unsubscribes from topics
- **Khepri Store Shutdown**: Store processes gracefully stop Khepri instances
- **Network Monitoring**: NodeMonitor properly disables network monitoring on shutdown

### Development Environment

#### Configuration Updates

- **proc-sup Configuration**: Added description "Process Supervisor Event Store" and tags "development,cluster,proc-sup,core"
- **reg-gh Configuration**: Added description "Registration System Event Store" and tags "development,cluster,reg-gh,registration"
- **Environment-Specific Tags**: Different tags for development vs production environments
- **Consistent Formatting**: Standardized environment variable layout across all configuration files

### Benefits

#### Operational Improvements

- **Enhanced Monitoring**: Rich store metadata enables better operational visibility
- **Improved Debugging**: Store descriptions and tags help identify issues faster
- **Better Resource Management**: Priority and auto-start fields enable fine-grained control
- **Cleaner Shutdown**: All processes terminate gracefully without resource leaks

#### Development Experience

- **Clearer Architecture**: Separation of core vs clustering concerns
- **Consistent Configuration**: Standardized environment variable management
- **Better Testability**: Core components can be tested independently of clustering
- **Simplified Debugging**: LeaderWorker availability issues resolved

#### System Reliability

- **Reduced Race Conditions**: Proper startup order prevents timing-related failures
- **Resource Leak Prevention**: Graceful shutdown prevents resource accumulation
- **Improved Fault Tolerance**: Better separation of concerns reduces cascade failures
- **Enhanced Observability**: Rich metadata supports better monitoring and alerting

## version 0.1.1 (2025.07.13)

### StoreRegistry Refactoring

#### Enhanced Architecture

- **Store Registration Centralization**: Moved store registration functionality from `StoreCluster` to dedicated `StoreRegistry` module
- **Self-Registration**: `StoreRegistry` now automatically registers its own store during initialization when `store_id` is provided
- **Simplified StoreCluster**: `StoreCluster` now focuses purely on cluster coordination without store registration concerns

#### API Integration

- **ExESDBGater.API Integration**: `list_stores()` function now directly calls `ExESDB.StoreRegistry.list_stores()` instead of maintaining local state
- **Single Source of Truth**: Store information is now centralized in `StoreRegistry` across the entire system
- **Improved Error Handling**: Added proper error handling for StoreRegistry calls in GaterAPI

#### System Integration

- **StoreSystem Supervision**: Added `StoreRegistry` to the `StoreSystem` supervisor with proper startup order
- **Component Isolation**: Each component now has a single, well-defined responsibility
- **Cleaner State Management**: Removed redundant store state from multiple components

#### Benefits

- **Separation of Concerns**: Clear boundaries between clustering and registration responsibilities
- **Maintainability**: Easier to maintain and reason about store registration logic
- **Testability**: Store registration can now be tested in isolation
- **Reduced Coupling**: Components are less tightly coupled and more modular

## version 0.0.17 (2025.07.01)

### Auto-Clustering

- `ExESDB` nodes now automatically join the cluster
- "Split-Brain" scenarios are now mitigated

### BCUtils

- All functionality related to styling is now transferred to the `:bc_utils` package.
- Added a Banner after startup.
- Logger filtering for Swarm and LibCluster noise reduction (via BCUtils.LoggerFilters)

### ExESDB Logger Filtering

#### Features

The `ExESDB.LoggerFilters` module provides additional log noise reduction specifically for ExESDB's distributed systems components:

- **Ra Consensus Filtering**: Reduces Ra heartbeat, append_entries, pre_vote, request_vote, and routine state transition messages while preserving all errors/warnings
- **Khepri Database Filtering**: Filters internal Khepri operations (cluster state, store operations) at info/debug levels while maintaining error/warning visibility
- **Enhanced Swarm Filtering**: Complements BCUtils filtering with additional ExESDB-specific Swarm noise reduction
- **Enhanced LibCluster Filtering**: Complements BCUtils filtering with additional ExESDB-specific cluster formation noise reduction

#### Benefits

- Dramatically improves log readability in development and production environments
- Intelligent filtering preserves all error and warning messages
- Focused on ExESDB-specific distributed systems infrastructure (Ra, Khepri)
- Works in conjunction with BCUtils.LoggerFilters for comprehensive noise reduction

### ExESDBGater

- The `ExESDB.GatewayAPI` is moved to the `:ex_esdb_gater` package.

#### Features

Snapshots Subsystem provides cluster wide support for reading and writing snapshots, using a key derived from the `source_uuid`, `stream_uuid` and `version` of the snapshot.

## version 0.0.16 (2025.06.26)

### Snapshots

#### Features

Snapshots Subsystem provides cluster wide support for reading and writing snapshots, using a key derived from the `source_uuid`, `stream_uuid` and `version` of the snapshot.

- `record_snapshot/5` function
- `delete_snapshot/4` function
- `read_snapshot/4` function
- `list_snapshots/3` function

#### Supported by Gateway API

It is advised to use `ExESDB.GatewayAPI` to access the Snapshots Subsystem.

## version 0.0.15 (2025.06.15)

### Subscriptions

#### Transient subscriptions

- `:by_stream`, `:by_event_type`, `:by_event_pattern`, `:by_event_payload`
- Events are forwarded to `Phoenix.PubSub` for now

#### Persistent subscriptions

- `:by_stream`, with support for replaying from a given version
- Events are forwarded to a specific subscriber process
- `ack_event/3` function is provided

#### "Follow-the-Leader"

Emitter processes are automatically started on the leader node,
when a new leader is elected.

#### Gateway API

- A cluster-wide gateway API is provided
- is an entry point for all the other modules
- provides basic High-Availability and Load-Balancing

## version 0.0.9-alpha (2025.05.04)

### Subscriptions

- `ExESDB.Subscriptions` module
- `func_registrations.exs` file
- emitter trigger in `khepri` now only uses the `erlang`-native :pg library (process groups)

#### Skeleton support for Commanded

- `ExESDB.Commanded.Adapter` module
- `ExESDB.Commanded.Mapper` module

## version 0.0.8-alpha

### 2025.04.13

- Added `ExESDB.EventStore.stream_forward/4` function
- Added `BeamCampus.ColorFuncs` module
- Added `ExESDB.Commanded.Adapter` module
- Refactored `ExESDB.EventStreamReader` and `ExESDB.EventStreamWriter` modules:
- Streams are now read and written using the `ExESDB.Streams` module
- Removed `ExESDB.EventStreamReader` module
- Removed `ExESDB.EventStreamWriter` module

## version 0.0.7-alpha

## version 0.0.1-alpha

### 2025.03.25

- Initial release