Shopify/semian
67.7
Adequate · 6 November 2026
5.9k
lines of production code
Ruby
with C
4
measurements over time
What this system is
Semian is a Ruby library that protects applications from cascading failures by implementing circuit breakers and resource management for external dependencies like databases, caches, and HTTP services. It provides adapters for Active Record (MySQL, PostgreSQL, Trilogy), Redis, Net::HTTP, and gRPC, allowing developers to configure fail-fast behaviors and dynamic error thresholds. The system supports both classic fixed-threshold and adaptive PID-controller-based circuit breaking, with comprehensive tooling for testing, benchmarking, and CI integration.
How it got here
2014 — Semian library initial release
6 changes.
This period marks the initial release of the Semian library, introducing core circuit breaking and semaphore-based resource protection features for Ruby applications. The work included implementing adaptive circuit breakers with PID controllers, adding specific adapters for Active Record, Trilogy, and PostgreSQL, and establishing a comprehensive test suite to ensure thread safety and correct state transitions.
2015–2019 — CI infrastructure and test harness
5 changes.
This period focused on establishing a robust continuous integration environment and comprehensive test infrastructure. Key efforts included creating a dedicated Dockerfile for consistent CI builds, automating test execution via shell scripts, and developing extensive helper modules and fixtures to support reliable testing of adapters, circuit breakers, and database interactions.
2022–2025 — adapter expansion and performance benchmarking
9 changes.
This period focused on expanding Semian's compatibility by adding support for Redis 5.0, Active Record Trilogy, and gRPC adapters, accompanied by comprehensive test suites for these integrations. The work also included creating detailed usage examples for various HTTP and database clients, alongside new benchmarking scripts and experimental tests to profile performance and compare adaptive versus classic circuit breaker behaviors.
Features
Add Net::HTTP integration examples
Added a suite of examples in the \examples/net\_http\ directory demonstrating how to integrate Semian with Ruby's standard \Net::HTTP\ library. These examples cover minimal circuit breaker and bulkhead configurations, extended usage with state change subscriptions, concurrency patterns using threads and process forks, dynamic resource configuration, and combined circuit breaker with bulkhead scenarios.
_examples/net\http · high confidence
Add Redis 5.0 adapter with configurable OOM circuit-breaking behavior
This change introduces a new adapter file (lib/semian/redis/v5.rb) to support the Redis 5.0 gem. It integrates Semian's circuit-breaking logic by prepending modules to the Redis client and error classes. A key behavioral addition is the ability to configure whether OutOfMemory (OOM) errors trigger circuit opening; by default, OOM errors open circuits for backward compatibility, but users can now set \open\_circuit\_on\_oom: false\ to allow reads/deletes to continue during OOM conditions, aiding recovery. The adapter also ensures ReadOnly errors do not mark circuits as open, facilitating faster reconnection to new primaries, and maps RedisClient errors to Semian-specific error classes.
lib/semian/redis · high confidence
Add examples for configuring Semian with the Active Record Trilogy adapter
Added two example scripts (00\_circuit\_minimal.rb and 03\_circuit\_open.rb) demonstrating how to configure and use the Semian circuit breaker with the Active Record Trilogy adapter. The minimal example shows basic setup, while the second example illustrates circuit breaker state transitions (closed, open, half-open) and error handling when connecting to healthy and unhealthy MySQL instances.
_examples/activerecord\_trilogy\adapter · high confidence
Added Dockerfile for CI environment
A new Dockerfile (semian-ci) has been added to provide a consistent development and CI environment. It is based on Ruby 3.4.3, installs necessary build dependencies (build-essential, libssl-dev, default-mysql-client), and sets up the application bundle for testing.
dockerfiles · high confidence
Added benchmarking scripts for Semian performance profiling
New Ruby scripts have been added to the benchmarks directory to measure the performance impact of the Semian library. The \flamegraph.rb\ script profiles CPU usage and generates flame graphs for HTTP requests, while \lru\_benchmarker.rb\ measures the throughput and memory consumption of resource registration. Additionally, \net\_http\_acquire\_benchmarker.rb\ benchmarks the latency and memory usage of HTTP acquisition, supporting both baseline comparisons and specific Semian versions via the SEMIAN\_VERSION environment variable.
scripts/benchmarks · high confidence
Added dual circuit breaker demo and terminal color helpers
The examples directory now includes a new \dual\_circuit\_breaker\_demo.rb\ script that demonstrates how to configure and switch between legacy and adaptive circuit breakers at runtime using a selector callable, alongside a \colors.rb\ utility that adds ANSI color formatting methods to the String class for improved output readability in examples.
examples · high confidence
Initial release of Semian library for resource protection and circuit breaking
Introduces the Semian library, which allows applications to control access to external services (such as MySQL or Redis) using semaphores and circuit breakers. This prevents system-wide performance degradation when external dependencies are slow or unresponsive. The library provides a registration API to define resources with configurable ticket counts, timeouts, and error thresholds, automatically opening circuits to fail fast after repeated errors and transitioning to half-open states for recovery. It supports global configuration for LRU caching, permissions, and thread safety, and includes built-in instrumentation and logging capabilities.
lib · high confidence
Introduce Active Record Trilogy and PostgreSQL adapters with adaptive circuit breaking
Semian now includes dedicated adapters for the Active Record Trilogy and PostgreSQL adapters, extending circuit breaker protection to these database connections alongside the existing MySQL2 support. The Trilogy adapter specifically implements \with\_resource\_timeout\ to dynamically adjust read timeouts during half-open state testing, while the PostgreSQL adapter provides a no-op implementation as it lacks IO-level timeout configuration. Additionally, the library introduces an adaptive circuit breaker that uses a PID controller to dynamically adjust rejection rates based on error rates, offering a more responsive alternative to the traditional fixed-threshold circuit breaker.
lib/semian · high confidence
New experimental resource and adaptive circuit breaker tests
The experiments directory now includes an \ExperimentalResource\ adapter that wraps a \MockService\ to simulate distributed service failures, allowing for complex testing of circuit breaker behaviors. This setup supports running both classic and adaptive circuit breaker experiments, featuring configurable endpoints, statistical latency distributions (log-normal), and service-wide degradation scenarios such as sudden error spikes, gradual error increases, and sustained loads. The addition includes a comprehensive suite of experiment scripts comparing adaptive versus classic circuit breaker performance under these varied stress conditions.
experiments · high confidence
Behavioural changes
Refactor Semian C extension into modular components with explicit Ruby API bindings
The Semian C extension has been restructured from a single monolithic file into distinct modules (resource, sysv\_semaphores, tickets, types) to improve maintainability and clarity. This change introduces explicit Ruby method bindings for resource management, including new methods to acquire/release semaphores without a block, destroy resources, reset registered worker counts, and query ticket/worker status. It also adds support for configurable semaphore permissions, quota-based ticket allocation, and better error handling for missing or corrupted semaphores, while ensuring thread safety through metadata locking and GVL release during blocking semaphore operations.
ext · high confidence
Standardize development environment with EditorConfig, RuboCop, and Rake task updates
The project now enforces consistent code style and formatting through new \.editorconfig\ and \.rubocop.yml\ files (including Shopify and thread-safety plugins). The \Rakefile\ has been updated to support parallel test execution, explicit example running, and benchmarking, while the default task now runs both tests and RuboCop. Additionally, a \.dockerignore\ file has been added to optimize Docker builds by excluding unnecessary files.
(repo-wide) · high confidence
Test coverage
Add test configuration for service host connectivity; Added binary SQL fixture for theme template tests; Added comprehensive test suite for Semian core components; Added gRPC test fixtures for the Echo adapter; Added test helper modules for adapters, background threads, circuit breakers, and time mocking; Automated test execution script for CI and local development; Expanded test coverage for database, HTTP, and gRPC adapters.
Dependencies
New gemfiles for Active Record adapters and Redis client variants
Added gemfiles to support testing against Active Record's PostgreSQL and Trilogy adapters, as well as various Redis client configurations (Redis 4, Redis 5, and redis-client). These files define the specific gem dependencies required to run the adapter-specific test suites.
gemfiles · high confidence
Upgrade to Ruby 3.2+ and Rails 8.1 with expanded adapter support
The gem now requires Ruby 3.2 or later and adds development dependencies for Active Record 8.1, PostgreSQL (pg), and gRPC 1.76.0, enabling testing and usage with these modern versions. The dependency list also includes Trilogy 2.9, hiredis 0.6, and redis 5.4.1, while updating linting tools like Rubocop to 1.81.7 and Shopify style guide to 2.18.0. The gemspec metadata has been updated to reflect the Shopify GitHub organization and include standard metadata fields.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 61 → 68 (+6.7)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 73 → 73 (+0.0)
- Architecture 100 → 100 (+0.0)
- Maturity 47 → 70 (+23.3)
- Readiness 68 → 68 (+0.0)
- Security 71 → 62 (-9.2)
- Performance 95 → 95 (+0.0)
Resolved (3)
- Ambiguous intent: register implies creation, but retrieve_or_register implies a lookup-first strategy. While distinct, the naming convention retrieve_or_register is verbose and inconsistent with the simple imperative style of register, destroy, and unregister. It suggests a 'get_or_create' pattern that isn't reflected in the other methods.
- Inconsistent naming for bulk operations: destroy_all_resources uses the full noun phrase, whereas unregister_all_resources also uses the full phrase. However, Semian.destroy (singular) vs Semian.destroy_all_resources (plural) is slightly inconsistent with the pattern of Semian.unregister vs Semian.unregister_all_resources. More importantly, destroy and unregister seem to do similar cleanup but on different scopes or types of resources, which is confusing without clear documentation. If they are distinct (e.g., one removes from LRU, one removes from global registry), the names should reflect that distinction more clearly (e.g., remove_from_registry vs cleanup_lru).
- Off-boarding risk: anonymized user #1
New (1)
- Off-boarding risk: anonymized user #1
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
Shopify/semian was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 6 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit ddeab8c829b67d4e2a8c3401fa6599e1ad25263e — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.2+preprod-5c4e66d9318b.