I’m excited to announce foundation, a new Elixir library born out of the development of ElixirScope, my debugging and code intelligence platform. foundation aims to provide the essential, “boring but essential” infrastructure pieces that many Elixir applications need, saving you from building them yourself.
The Motivation Behind foundation
During the development of ElixirScope, I consistently encountered the need for robust infrastructure components. What started as simple configuration management quickly evolved into building custom event systems, telemetry handlers, circuit breakers, and more. This was infrastructure code that, while critical, diverted focus from the core product.
About fifty prompts into the project, I realized I had inadvertently created a comprehensive infrastructure library. It included:
- A configuration system with dynamic updates and subscriber notifications.
- An event store to track analysis pipeline activities.
- Intuitive telemetry integration.
- Circuit breakers and rate limiting for interacting with temperamental AI APIs.
- Service discovery for managing analysis components.
- Error handling that preserved context throughout the analysis chain.
The tipping point was debugging intermittent AI analysis failures, which turned out to be a classic distributed systems problem. Instead of piecing together disparate libraries, I found I already had a cohesive solution. This led to the extraction of foundation as a standalone library.
What Foundation Offers
foundation provides infrastructure components with a consistent API. Its core pieces include:
- Configuration management: Beyond environment variables and
Application.get_env, it handles dynamic updates. - Event system: Structured events with correlation tracking for easier debugging.
- Telemetry & monitoring: Actionable metrics to understand application behavior.
- Infrastructure protection: A unified API for circuit breakers, rate limiting, and connection pooling.
- Service discovery: A simple registry with health checking.
- Error handling: Structured errors that retain context.
API Examples
Here’s a glimpse of foundation’s API:
# Dynamic configuration with change notifications
:ok = Foundation.Config.update([:ai, :rate_limit], 100)
:ok = Foundation.Config.subscribe()
# Events with correlation tracking
correlation_id = Foundation.Utils.generate_correlation_id()
{:ok, event} = Foundation.Events.new_event(:ai_request, %{prompt_size: 1500},
correlation_id: correlation_id)
# Infrastructure protection that actually works together
result = Foundation.Infrastructure.execute_protected(
:ai_api_call,
[circuit_breaker: :openai_fuse, rate_limiter: {:ai_user, user_id}],
fn -> OpenAI.completion(prompt) end
)
Why foundation is Different
foundation is designed for practical use cases rather than theoretical perfection. Each component addresses a real-world need encountered during ElixirScope’s development. For example, the event system focuses on practical correlation IDs for debugging, not complex event sourcing. The configuration system prioritizes runtime updates and notifications.
It’s also built for incremental adoption, allowing you to integrate parts of foundation without a complete rewrite of your existing application.
Current Status and Future Plans
foundation is currently at v0.1.0. All tests pass, and comprehensive documentation, including Mermaid diagrams, is available.
I’m particularly interested in feedback on the API design and the utility of its abstractions for different use cases. The infrastructure protection layer, while effective for ElixirScope, is the most opinionated part and I’m keen to hear if it fits broader needs.
Future considerations include adding distributed coordination primitives like leadership election and distributed locks, as these are recurring requirements in ElixirScope’s development.
Installation and Links
To install foundation, add it to your mix.exs dependencies:
{:foundation, "~> 0.1.0"}
Useful Links:
- Hex.pm: https://hex.pm/packages/foundation
- Documentation: https://hexdocs.pm/foundation
- GitHub:
) and you can relatively quickly find if what you need is there…
