hexastack-core

The foundational kernel of Hexastack: dependency injection, abstract ports, domain abstractions, configuration registry, and the modular bootstrap lifecycle.

Part of the Hexastack Framework · Governed by Hexaqual.

1. Overview & Capabilities

hexastack-core serves as the zero-dependency (excluding pydantic and rodi) microkernel for all Hexastack packages. It establishes:

• Dependency Injection Engine: Powered by rodi, managing service lifecycles (singleton, scoped, transient).
• Distributed & Persistent Cache Adapters: CachePort and AsyncCachePort with in-memory (InMemoryCache, AsyncInMemoryCache), distributed Redis/Valkey (RedisCacheAdapter, AsyncRedisCacheAdapter), and persistent L2 filesystem storage (DiskCacheAdapter, AsyncDiskCacheAdapter).
• High-Availability Primitives & Locks: LockPort and AsyncLockPort (reentrant in-memory, OS FileLockAdapter, and distributed RedisLockAdapter) and LeaderElectionPort / AsyncLeaderElectionPort (single-process and distributed Redis lease coordination).
• Unified Object & File Storage: StoragePort and AsyncStoragePort with in-memory (InMemoryStorage, AsyncInMemoryStorage), local filesystem (LocalStorageAdapter, AsyncLocalStorageAdapter), and unified multi-cloud storage via fsspec (FsspecStorageAdapter, AsyncFsspecStorageAdapter for S3, GCS, Azure Blob Storage).
• Core Domain Primitives: Generic Result[T, E], generic types, and standard exception hierarchies (HexastackError, ConfigurationError, MissingDependencyError, LockError, LeaderElectionError, StorageError, StorageNotFoundError).
• Core Port Contracts: Standard abstract protocols and ABCs for repositories (Repository[E, ID]), unit of work (UnitOfWork), caching (CachePort), object storage (StoragePort), distributed locks (LockPort), leader election (LeaderElectionPort), logging (LoggerPort), presenters (PresenterPort), feature flags (FeatureFlagPort), and bootstrappers (BootstrapperPort).
• Configuration & Type Registries: Type-safe Pydantic configuration parsing from TOML (ConfigRegistry) and generic type registries (GenericTypeRegistry).
• Three-Phase Bootstrap Engine: Deterministic orchestration of Phase 1 config registration, Phase 2 container assembly, and Phase 3 reflective scanning.
• Testing & Quality Toolkit:
  • assert_clean_architecture(...): Hexagonal architecture boundary verification powered by pytest-archon.
  • create_test_runtime(...): Lightweight in-memory DI test harness and doubles (TestRuntime).
  • cqrs_strategy(...): Hypothesis property-based fuzzing strategy generator for Pydantic/dataclass CQRS models.
  • Feature flag testing: @parametrize_flags, flag_scope, @require_feature, and @require_extra.
• Context Utilities: Async-safe correlation ID and context variable management (get_correlation_id, set_correlation_id, UserContext).

2. Package Anatomy & Key Components

hexastack_core/
├── domain/          # Result[T, E], HexastackError, Entity, ValueObject, EvaluationContext, HexastackConfig, HexastackCoreConfig
├── ports/           # Repository, UnitOfWork, BootstrapperPort, LoggerPort, CachePort, StoragePort, LockPort, LeaderElectionPort
├── adapters/        # InMemory, Redis, DiskCache, FileLock, Storage (InMemory, Local, Fsspec) implementations
├── infra/           # Bootstrap engine, ConfigRegistry, GenericTypeRegistry, decorators
├── testing/         # assert_clean_architecture, create_test_runtime, cqrs_strategy, flag_scope, isolation
└── utils/           # Context variable utilities, reflection helpers

Key Exports

3. Monorepo & Sibling Relationships

graph TD
    subgraph SiblingPackages ["Dependent Sibling Packages"]
        CQRS["hexastack-cqrs"]
        LOG["hexastack-logging"]
        DB["hexastack-db"]
        FASTAPI["hexastack-fastapi"]
        GRAPHQL["hexastack-graphql"]
        MCP["hexastack-mcp"]
        GRPC["hexastack-grpc"]
        CLI["hexastack-cli"]
        UMBRELLA["hexastack"]
    end

    subgraph CoreKernel ["hexastack-core"]
        DI["rodi.Container"]
        BOOT["Bootstrap Engine"]
        PORTS["Abstract Ports (UoW, Repo, Logger)"]
        CONF["ConfigRegistry"]
    end

    CQRS -->|implements BootstrapperPort, uses rodi| CoreKernel
    LOG -->|implements LoggerPort & BootstrapperPort| CoreKernel
    DB -->|implements Repository & UnitOfWork ports| CoreKernel
    FASTAPI -->|implements BootstrapperPort, consumes DI| CoreKernel
    GRAPHQL -->|implements BootstrapperPort, consumes DI| CoreKernel
    MCP -->|implements BootstrapperPort, consumes DI| CoreKernel
    GRPC -->|implements BootstrapperPort, consumes DI| CoreKernel
    CLI -->|implements BootstrapperPort, consumes DI| CoreKernel
    UMBRELLA -->|orchestrates bootstrap| CoreKernel

Explicit Dependencies (Direct)

• pydantic>=2.13.4: Schema validation and config parsing.
• rodi>=2.1.0: Fast, lightweight dependency injection container.

Implied / Behavioral Relationships (DI-Mediated)

• Provides Ports: Defines UnitOfWorkPort and Repository implemented by hexastack-db.
• Provides Telemetry Contract: Defines LoggerPort implemented by hexastack-logging.
• Provides Bootstrap Framework: All siblings expose extension entry points implementing BootstrapperPort.

4. Installation

# Standalone installation
pip install hexastack-core

# Via umbrella package
pip install hexastack

5. Configuration Reference

Configuration schemas are registered under [hexastack]:

[hexastack]
app_name = "my-application"
environment = "production" # "development", "staging", "production", "test"
debug = false

6. Quickstart Example

from hexastack_core.infra.bootstrap import bootstrap
from hexastack_core.ports.bootstrap import BootstrapperPort, BootstrapContext
from hexastack_core.domain.result import Ok, Err, Result


# 1. Implement a custom extension
class ServiceBootstrapper(BootstrapperPort):
    name = "custom_service"
    order = 10

    def configure(self, context: BootstrapContext) -> None:
        context.container.add_instance("Service Configured", declared_class=str)


# 2. Run deterministic bootstrap
result = bootstrap(bootstrappers=[ServiceBootstrapper()], auto_discover=False)
value = result.container.get(str)
print(value)  # "Service Configured"