Coder Legion - Recent posts tagged rails

What Is Idempotency?

Fri, 30 Oct 2026 09:28:35 +0000

🚀 What Happens When Your API Receives the Same Request Twice?

Imagine a customer clicks “Pay Now” twice because the page freezes.

Or a payment gateway retries a request because it never received your response.

💥 Without proper protection, your application might charge the customer twice!

This is where Idempotency becomes essential.

🔍 What Is Idempotency?

Idempotency means that performing the same operation multiple times produces the same result as performing it once.

For example, if a client retries a payment request, the system should return the original result instead of creating another payment.

🛠️ How Do We Implement It in Ruby on Rails?

A common approach is using an Idempotency-Key.

The client sends a unique key with the request:

POST /api/v1/payments
Idempotency-Key: order-123-payment

Rails can use that key to identify duplicate requests.

Step 1: Add a database constraint

add_index :payments, :idempotency_key, unique: true

Step 2: Store the key with the payment

Payment.create!(
  idempotency_key: idempotency_key,
  amount: amount,
  status: "pending"
)

Important: This is only a simplified example. A production implementation must handle duplicate-key exceptions, concurrent requests, and retries safely.

You should also define what happens when the same key is reused with different request parameters.

For payment APIs, store and return the original result for a matching key rather than processing the payment again.

💎 Why Is Idempotency Important?

✅ Prevents Duplicate Payments — Avoid charging customers twice when requests are retried.

✅ Makes Retries Safer — Network failures become easier to handle.

✅ Improves API Reliability — Clients can retry requests without accidentally repeating business operations.

✅ Protects Background Jobs — Prevent duplicate emails, orders, or other side effects when jobs run more than once.

✅ Supports Distributed Systems — Helps manage unreliable networks and repeated messages.

⚠️ One Important Detail

Idempotency is not just checking whether a request has been received before.

You must handle concurrent requests, database transactions, unique constraints, and external service calls carefully.

For example, a database transaction alone cannot guarantee that an external payment provider won't charge a customer twice.

💡 The goal is simple: make retries safe, even when failures happen.

Because in real-world applications, requests will fail, networks will time out, and background jobs will retry.

Your architecture should be ready for it!

💬 How do you handle duplicate requests in your Rails applications?

RubyOnRails #API #Idempotency #BackendDevelopment #SoftwareArchitecture #DistributedSystems #WebDevelopment #SoftwareEngineering

Building RAG on PostgreSQL with Pgvector and Ruby on rails

Fri, 16 Oct 2026 18:17:18 +0000

🧠 Your Database Is Already a Vector Database

Most RAG tutorials start the same way: "First, spin up a vector database."

But Stop.

If you're on Rails, you already have PostgreSQL.
With the pgvector extension it can store and search embeddings and for most applications, that's the whole answer.

🐘 Setup is one migration

`enable_extension "vector"

add_column :document_chunks, :embedding, :vector, limit: 1536`

💎 And one line in your model

Gemfile

gem "neighbor"

class DocumentChunk < ApplicationRecord has_neighbors :embedding, dimensions: 1536, normalize: true end

🔍 Searching is just ActiveRecord

DocumentChunk .where(tenant: Current.tenant) .nearest_neighbors(:embedding, query_vector, distance: "cosine") .limit(6)

Scoped, chainable, joinable. A normal Rails query.

🚀 Why this beats a separate vector DB

1️⃣ No new infrastructure
Nothing extra to deploy, monitor, back up, or upgrade.

2️⃣ Transactional consistency
Embeddings commit in the same transaction as the record. Two systems can't drift apart.

3️⃣ Authorization you already trust
This is the big one. Retrieval almost always needs scoping by tenant, project, or permission. In Postgres that's a WHERE clause. In an external store it's metadata filtering you have to keep in sync with your auth model.
Get it wrong, and one customer's documents land in another customer's LLM prompt.

4️⃣ Real joins
Chunks plus their documents, authors, and timestamps in one query.

⚠️ Three things that will bite you

❌ Index opclass mismatch
vector_cosine_ops goes with cosine distance. Mismatch them and Postgres silently skips your index and sequential-scans the table.

❌ No similarity floor
Nearest neighbours are nearest, not relevant. Without a threshold, an unrelated question still returns chunks — which the model will happily use to hallucinate.

❌ Pure vector search
Embeddings are weak at exactly what users type literally: error codes, SKUs, invoice numbers. ERR_4012 and ERR_4013 are nearly identical in vector space.
Fix: hybrid search — pgvector + Postgres full-text, fused with Reciprocal Rank Fusion.

🎯 When to actually leave Postgres

Past roughly 5–10 million chunks, or when the vector workload starves your transactional workload for memory.
Until then, a dedicated vector database buys you one more service to operate and a second place for your authorization logic to be wrong.

Your database stays the source of truth. The vector index is a lookup layer on top of it.

💬 If you've shipped RAG in Rails — what pushed you off Postgres, if anything?

Elasticsearch with Ruby on Rails

Fri, 09 Oct 2026 06:22:39 +0000

🚀 Elasticsearch + Ruby on Rails: Beyond Database Queries

Ever noticed how searching millions of records can become slow and frustrating?

When your application needs fast, advanced, and intelligent search, Elasticsearch can make a real difference.

🔍 What is Elasticsearch?

Elasticsearch is a distributed search and analytics engine built on Apache Lucene. It helps applications search, filter, and analyze large amounts of data efficiently.

Unlike traditional database queries, it offers powerful full-text search, relevance scoring, and flexible filtering.

🛠️ How do we use it with Ruby on Rails?

Imagine you're building an e-commerce platform with thousands of products.

Users expect to search by product name, description, category, or even partial keywords — and get relevant results quickly.

With Rails, you can integrate Elasticsearch using gems such as elasticsearch-rails or searchkick.

For example, using Searchkick:

# Gemfile
gem "searchkick"

class Product < ApplicationRecord
  searchkick

  def search_data
    {
      name: name,
      description: description,
      category: category
    }
  end
end

Search products with:

Product.search("wireless headphones")

Instead of relying only on basic SQL matching, Elasticsearch can provide relevance-based results, typo tolerance, and advanced filtering.

Note: Elasticsearch must be installed and configured, and the data must be indexed before searching.

💡 Why use Elasticsearch?

✅ Faster Search — Search large datasets efficiently.

✅ Better Relevance — Rank results based on how closely they match the query.

✅ Typo Tolerance — Help users find results even when they misspell a word.

✅ Advanced Filtering — Combine full-text search with categories, prices, and other filters.

✅ Analytics & Aggregations — Analyze search trends and summarize large datasets.

⚠️ One important architectural decision

Elasticsearch is not a replacement for your primary database.

Use PostgreSQL or MySQL as your source of truth, and Elasticsearch as your search engine.

When Rails data changes, keep the search index synchronized — often through background jobs with Sidekiq — and account for indexing delays and failed jobs.

The goal isn't to replace SQL. It's to give your application a search experience that SQL alone may struggle to deliver at scale.

API Architecture

Mon, 05 Oct 2026 08:01:11 +0000

Here’s a concise LinkedIn-ready article focused on practical API architecture in Rails.

API Architecture: It’s More Than Just Endpoints

A well-designed API isn't simply about creating routes like:

GET /users
POST /orders

The real challenge is designing an architecture that remains secure, scalable, maintainable, and easy to integrate as the application grows.

️ How I approach API architecture with Ruby on Rails

A typical Rails API can be structured around clear layers:

Client → Routes → Controllers → Services → Models → Database

For example:

POST /api/v1/orders

The controller should handle the HTTP request and response, while the business logic can live in a Service Object.

Orders::Create.call(
  user: current_user,
  params: order_params
)

This keeps controllers thin and business logic easier to test and reuse.

Important architecture decisions

Versioning

/api/v1/...

API versioning allows you to evolve the API without immediately breaking existing clients.

Authentication & Authorization

Use mechanisms such as JWT, OAuth2, or token-based authentication, combined with authorization rules.

Consistent Responses

Define predictable JSON structures for:

Success responses
Validation errors
Authentication failures
API errors

Background Processing

Heavy operations shouldn't block the API request.

Rails + Sidekiq + Redis can move tasks such as emails, notifications, and data processing into background jobs.

Caching

Frequently requested data can be cached with Redis to reduce database load and improve response time.

Why good API architecture matters

A good architecture makes it easier to:

✅ Scale the application
✅ Add new API versions
✅ Integrate third-party systems
✅ Test business logic
✅ Maintain clean controllers
✅ Improve security
✅ Reduce technical debt

The goal isn't to build more endpoints.

The goal is to build an API that can evolve without becoming a bottleneck for the entire system.

RubyOnRails #Ruby #API #APIDesign #SoftwareArchitecture #BackendDevelopment #WebDevelopment #RESTAPI #SoftwareEngineering

One Rails App, Multiple Customers

Mon, 05 Oct 2026 08:00:48 +0000

Why Multi-Tenancy Matters

Imagine you are building a SaaS application.

You have 100 companies, but you don't want to deploy and maintain 100 separate applications.

That's where Multi-Tenancy comes in.

What is Multi-Tenancy?

Multi-tenancy allows a single application to serve multiple customers — called tenants — while keeping each tenant's data isolated.

For example:

                    Rails Application
                           │
          ┌────────────────┼────────────────┐
          ↓                ↓                ↓
       Tenant A         Tenant B         Tenant C
       Company A        Company B        Company C
          │                │                │
       Users/Data       Users/Data       Users/Data

Each company uses the same application, but should only be able to access its own data.

How can we implement it with Rails?

A common approach is adding a tenant_id to tenant-owned tables:

class User < ApplicationRecord
  belongs_to :tenant
end

Then queries are scoped to the current tenant:

current_tenant.users

For larger systems, another approach is database-per-tenant, where each customer gets a separate database.

The right strategy depends on your scale, security requirements, infrastructure, and operational complexity.

Why use Multi-Tenancy?

1️⃣ Lower Infrastructure Costs

One application can serve many customers instead of running separate deployments.

2️⃣ Easier Maintenance

Deploy features and bug fixes once instead of updating every customer environment.

3️⃣ Faster Scaling

You can scale application servers and background workers as the customer base grows.

4️⃣ Better SaaS Architecture

Multi-tenancy fits naturally with subscription-based products where many businesses share the same platform.

5️⃣ Centralized Development

One codebase means consistent features, security updates, and improvements across tenants.

⚠️ The important part

Multi-tenancy isn't simply adding a tenant_id.

You need to think about:

Data isolation
️ Authorization
️ Database architecture
⚡ Caching
Background jobs
Reporting
Tenant-aware integrations

A single missing tenant filter can become a serious data-isolation problem.

Skip the RSpec examples you don't need: rspec-tracer 2.0 in pre-release

Tue, 12 May 2026 17:28:12 +0000

A ground-up rewrite of test-skip caching for RSpec, with pluggable storage, Rails-aware tracking, and a per-example tracks: DSL.

You change one model. You run bundle exec rspec. Twenty minutes later, every test in the suite has run again — including the 1,800 examples that don't touch that model.

This is the problem rspec-tracer solves. Cold run of a suite: everything runs. Second run with no edits: nothing runs. Edit one file: only the examples that depend on that file re-run.

The 1.x line has been on RubyGems since 2021. I just shipped a 2.0 pre-release after a 4-year gap and a 17-day rebuild. This post is the field guide for what changed and how to test it.

Install

Pre-releases require explicit opt-in. In your Gemfile:

# 2.0 is in pre-release. Pin to the pre-release version explicitly;
# switch to '~> 2.0' once 2.0.0 final ships.
gem 'rspec-tracer', '= 2.0.0.pre.1', group: :test, require: false

Or one-shot:

gem install rspec-tracer --pre

Then in your spec_helper.rb or rails_helper.rb, before any application code:

require 'rspec_tracer'
RSpecTracer.start

That's it for the basic install. Run your suite twice; the second run skips everything that didn't change.

What changed since 1.x

The 2.0 surface is rebuilt around an explicit input-taxonomy model (every test is a pure function of its inputs; cache invalidation is input-digest mismatch). What that translates to for users:

1. Pluggable storage

# Default: JSON (preserves 1.x layout)
storage_backend :json

# SQLite: single-file DB, MRI-only
storage_backend :sqlite

For large suites (5,000+ examples) the SQLite backend cuts cache-load time substantially. JRuby falls back to :json automatically with a one-time warn.

2. Pluggable remote cache (for CI)

The 1.x line had S3-only remote cache. 2.0 ships three backends:

# S3 (preserves the 1.x layout, including LocalStack support)
remote_cache_backend :s3, bucket: 'my-cache', prefix: 'rspec-tracer'

# Local filesystem (NFS / shared mount / dev cache)
remote_cache_backend :local_fs, path: '/mnt/shared-cache'

# Redis (with optional per-key TTL + PR-branches sidecar)
remote_cache_backend :redis,
  url: ENV['REDIS_URL'],
  ttl: 7 * 24 * 3600,
  prefix: 'rspec-tracer'

The CI flow (rake rspec_tracer:remote_cache:download / :upload) is preserved bit-for-bit. The only thing that changes is the backend you point at.

3. Per-example `tracks:` DSL

This is the headline new surface. RSpec metadata key:

RSpec.describe AdminController,
               tracks: { files: 'app/policies/**/*.rb', env: 'ROLE_CONFIG' } do
  it 'gates on the feature flag' do
    # ...
  end
end

Use cases the tracker can't auto-observe:

Config files baked at boot — Oj-loaded JSON / YAML that's read once and mmap'd; the IO hooks won't see runtime reads, so declared globs are the escape hatch.
Env-var branches — code that does if ENV['FEATURE_X'] == 'on'; flipping the env should invalidate the example.
Pre-compiled Ruby constants — values baked at boot that the per-example coverage delta can't see.

Cascade is union (parent + child both contribute), unlike RSpec's default metadata cascade which clobbers on shared keys.

4. `track_env(*names)` config DSL

Symmetric to track_files but for env vars every test depends on:

# In .rspec-tracer
track_env 'AUTH_TOKEN', 'DATABASE_URL', 'RAILS_*', '*_API_KEY'

Single-wildcard patterns supported: 'PREFIX_*', '*_SUFFIX', bare '*'. Patterns are expanded against the live ENV at config-load time; the persisted env_snapshot.json carries concrete keys only.

5. Rails preset

For Rails projects, the tracker has to attach inputs Coverage doesn't observe — views, locales, fixtures, factories, helpers, config YAML, schema. The preset handles this:

# In .rspec-tracer
track_rails_defaults

Opt out per category:

track_rails_defaults except: [:views, :locales]

Plus auto-detection: when ::Rails::VERSION is defined at RSpecTracer.start time, the engine attaches an ActionView template subscriber + an opt-in AR schema subscriber.

The ERB/Slim/Jbuilder tracking via render_template.action_view was the most-requested missing 1.x feature. It's the canonical path now: a view edit invalidates exactly the examples that rendered the partial.

6. `bin/rspec-tracer` CLI

Five sub-commands, all opt-in:

$ rspec-tracer doctor
OK   ruby:        ruby 3.3.10 (2026-04-18)
OK   rspec-tracer: 2.0.0.pre.1
OK   root:        /Users/me/projects/my-app
OK   cache_path:  /Users/me/projects/my-app/rspec_tracer_cache
INFO SimpleCov:   not loaded (this is fine; SimpleCov is optional)
OK   Rails:       7.2.0.1
OK   schema:      v3 (matches gem)
INFO remote_cache: not configured (skip)

$ rspec-tracer cache:info
Cache size: 14.4 MiB · last run: 2026-05-06T14:13:22Z · 12 runs retained

$ rspec-tracer cache:clear
Removed: rspec_tracer_cache/, rspec_tracer_coverage/, rspec_tracer_report/

$ rspec-tracer report:open
Opening rspec_tracer_report/index.html ...

$ rspec-tracer explain spec.foo_spec.rb_42
Example: spec/foo_spec.rb:42 - "GET /admin returns 403 for unauthenticated"
Status: re-run scheduled
Reason: Files changed (app/controllers/admin_controller.rb)
Dependencies (12):
  - app/controllers/admin_controller.rb [changed since cache]
  - app/policies/admin_policy.rb
  - config/locales/en.yml
  - ...

The CLI is opt-in for local dev convenience; the rake rspec_tracer:remote_cache:* tasks remain first-class for CI integration.

7. HTML + JSON reporters

The 1.x line had a single HTML reporter. 2.0 adds a JSON reporter for CI dashboards and a terminal-summary reporter that fires after every run:

rspec-tracer: 1887 examples tracked · 5 re-run · 1882 skipped (99% cached)
by reason: 5 Files changed
cache: /path/to/rspec_tracer_cache (14.4 MiB; +6.7 KiB vs prev run)
report: /path/to/rspec_tracer_report/report.json

For parallel_tests users: 1.x emitted reports per worker, then purge_worker_dirs! deleted them — leaving users with no usable output. 2.0 emits ONCE at the merged top-level location after all workers finish.

8. SimpleCov branch coverage now works

The 1.x caveat ("SimpleCov would not report branch coverage results even when enabled") is gone. The coverage-stack rewrite decoupled rspec-tracer's line-only emission from SimpleCov's branch tracking. Users who turned enable_coverage :branch off when adopting rspec-tracer 1.x can re-enable in 2.0.

9. Boot-time warns

For two common user-trust traps:

SimpleCov loaded but not started before RSpecTracer.start (load-order is part of the documented contract; the warn surfaces it instead of silently bolting onto a Coverage already in flight).
track_ar_schema_notifications enabled with use_transactional_fixtures defaulting to true (per-example BEGIN/COMMIT fires sql.active_record and attributes db/schema.rb to every AR-touching example; the warn points at the README "Narrow AR-schema attribution" guidance).

10. Schema-version field + Rails 8.0 + CI recipes

Schema-version field in last_run.json for explicit cross-version cache validation. Cache-shape changes bump the field; mismatched caches refuse-to-load with an info-level "cold run" log line.

Rails 8.0 is CI-gated (Ruby 3.2+). docs/CI_RECIPES.md translates the GitHub Actions cache pattern to CircleCI / GitLab CI / Buildkite / Heroku CI — the 4-component cache-key (runner.os + .ruby-version + lib/rspec_tracer/version.rb + Gemfile-hash) translates 1:1 across providers.

Migration from 1.x

The full guide is in UPGRADING.md. Headlines:

Ruby ≥ 3.1 is the floor (1.x supported Ruby 2.5+). Ruby 3.2 / 3.3 / 3.4 / 4.0 + JRuby 9.4 are CI-gated. Rails 7.0 / 7.1 / 7.2 / 8.0 + RSpec 3.12 / 3.13 are CI-gated.
Cache schema bump — first run on 2.0 is cold; warm caches resume on subsequent runs. Existing CI integration (the rake tasks, env vars, rspec_tracer_cache/ directory contracts) is preserved bit-for-bit.
Deprecated — four configs continue to work with one warn line each, slated for removal in 3.0: reports_s3_path / use_local_aws config DSL, and RSPEC_TRACER_REPORTS_S3_PATH / RSPEC_TRACER_USE_LOCAL_AWS env vars.
Removed — cucumber feature-file integration suite (contributor-facing only), Ruby ≤ 3.0 / Rails ≤ 6.x support, Windows.

Why pre-release

A 2.0 of a gem people use in their CI deserves a real testing window. The pre-release is on RubyGems with --pre opt-in; 2.0.0 final is targeted in ~2 weeks once the observation-window feedback is incorporated.

If you're a 1.x user: the migration is bundle update rspec-tracer after pinning the pre-release version, plus optionally adopting track_rails_defaults if you're on Rails. The first run is cold (cache schema cut); subsequent runs return to warm.

If you're new to rspec-tracer: try the cookbook recipes; the Quick start gets a fresh project running in ~5 minutes.

Where to send feedback

GitHub Discussions: the pre-release thread for usage questions, install reports, rough edges.
Issues: open one for bugs. Add the 2.0-feedback label if applicable.
Migration questions: comment on the discussion thread; I'll answer in the open so others see.

I'll cut a pre.2 if pre.1 surfaces blockers; otherwise 2.0.0.rc.1 in ~2 weeks, then 2.0.0 final after a final review window.

Repo: https://github.com/avmnu-sng/rspec-tracer
Release: https://github.com/avmnu-sng/rspec-tracer/releases/tag/v2.0.0.pre.1
Discussion: https://github.com/avmnu-sng/rspec-tracer/discussions/180

Thanks for reading. Bug reports + thoughts welcome.

Hotwire vs. React: A Guide for the "One-Person Framework"

Tue, 17 Mar 2026 12:47:49 +0000

The Default Choice

For the last five years, the "Standard Web Stack" has been undeniable:
Backend API (Rails/Node) + SPA Frontend (React/Vue).

It is the architecture taught in bootcamps. It is the architecture demanded by recruiters. And for a long time, if you wanted a "modern" feeling application—no page reloads, snappy transitions, real-time updates—it was the only way.

But it comes with a cost. I call it The React Tax.

With the maturity of Rails 7 (and now Rails 8) and Hotwire, that tax is no longer mandatory. Here is why I believe Hotwire is the superior choice for 95% of Rails projects.

The Problem: Two Apps, One Product

When you choose React, you aren't building "an app." You are building two apps.

The Backend: Dealing with serialization, JWTs, CORS, and versioning.
The Frontend: Dealing with route management, global state (Redux/Context), effect hooks, and package.json hell.

Suddenly, a simple feature like "Rename a Project" requires:

Frontend: Update UI state optimistically.
Frontend: Dispatch API call.
Backend: Handle auth.
Backend: Update DB.
Backend: Serialize JSON response.
Frontend: Handle success/error.
Frontend: Re-sync local state.

With Hotwire, the flow is:

Controller: Update DB.
View: Render HTML.

1. The "Single Source of Truth" Myth

The hardest problem in Computer Science is naming things. The second hardest is Cache Invalidation.

When you duplicate your database state into a Redux store or React Query cache, you are inviting bugs. Is the user list stale? Did the socket update the count? Why does the UI say "Premium" but the API returned 403?

Hotwire rejects this premise.
With Turbo, the server is the single source of truth. When data changes, you don't update a client-side JSON cache; you simply replace the HTML chunk on the screen with fresh HTML from the server.

You eliminate an entire class of "State desync" bugs because you have no client-side state.

2. Velocity: The "One Person Framework"

Rails 8 is pushing the concept of the "One Person Framework." The idea is that a single developer should be able to build a startup that used to require a team of 5.

If you are a solo dev or a small team using React, you are spending 50% of your time managing the glue between your backend and frontend.

With Hotwire (Turbo Drive + Turbo Frames + Stimulus), you stay in Ruby/ERB land for 90% of the work. You write standard Rails views. You get SPA-speed navigation for free via Turbo Drive. You get dynamic partial updates via Frames.

The Context Switch Cost:

React: Switch from Ruby to JS. Switch from ERB to JSX. Switch from RSpec to Jest.
Hotwire: Stay in the flow.

3. "But React feels better"

This was true in 2016. It is not true today.

Turbo Drive (which intercepts link clicks and form submissions) makes a standard Rails app feel instant. It merges the <head> and replaces the <body> without a full browser reload.

Need real-time? Turbo Streams over ActionCable allows you to broadcast updates to millions of users with a few lines of Ruby.

# app/models/message.rb
after_create_commit { broadcast_append_to "chat_room" }

That one line creates a WebSocket connection that appends the new message to the DOM of every active user. Doing this in React requires setting up a socket context, listeners, state reducers, and safety checks.

When SHOULD you use React?

I am not a React hater. It is an incredible piece of engineering. You should use React (or Vue/Svelte) if:

You are building a high-fidelity tool: e.g., Figma, an in-browser video editor, or a complex drag-and-drop Trello clone.
You need "Offline First": If the app must function 100% without an internet connection (PWA with heavy local sync).
Your API serves multiple clients: If you have a Mobile App, a Web App, and a Desktop App that all need the exact same API, maybe a decoupled frontend makes sense (though native apps are moving to Server-Driven UI too!).

The Verdict

For the vast majority of SaaS products—dashboards, marketplaces, social networks, project management tools—the "React Tax" is a waste of resources.

Hotwire gives you 80% of React's interactivity with 10% of the complexity.

If you want to ship features, use Hotwire. If you want to configure Webpack, use React.

Are you sticking with the React ecosystem, or have you tried the Hotwire life? Let’s discuss below.

How We Solved “Unable to Get Certificate CRL” in Rails: A Debugging Story

Thu, 13 Nov 2025 11:53:55 +0000

If you’ve been around Rails long enough, you’ve probably battled your fair share of SSL demons. But this one? This one had personality.

It was a Seahorse::Client::NetworkingError that failed only on macOS — yet worked perfectly inside Docker. The kind of “it works on my container” bug that makes you question every life choice leading up to this point.

So here’s the story of how we chased down a ghostly SSL error, only to discover that the real culprit was… OpenSSL itself.

⚠️ The Error

Seahorse::Client::NetworkingError
SSL_connect returned=1 errno=0 peeraddr=[...]
state=error: certificate verify failed (unable to get certificate CRL)

This popped up whenever our Rails app tried connecting to AWS S3 using the aws-sdk-ruby gem.

The Contradiction That Made No Sense

From the get-go, the bug refused to play by any rules of logic.

❌ It failed locally but
✅ Worked flawlessly in Docker

That told us one thing: the problem wasn’t our code. It was the environment. macOS and Docker’s Linux setup were behaving differently.

The “Wait, What?” Moment

We decided to test the SSL connection manually, expecting it to fail the same way:

openssl s_client -connect 52.219.66.109:443 -servername s3.ap-south-1.amazonaws.com < /dev/null

Result?

Verify return code: 0 (ok)

So, macOS’s OpenSSL tool had no problem verifying the certificate. But Rails (and the AWS SDK) still choked on it.

At this point, confusion levels were high. Coffee consumption was higher.

The Real Test — Inside the Rails Console

To rule out any system-level differences, we went straight into rails c:

require 'aws-sdk-s3'
s3 = Aws::S3::Client.new(region: 'ap-south-1')
s3.list_buckets

Result:

certificate verify failed (unable to get certificate CRL)

Boom. So the system OpenSSL was fine, but Ruby’s built-in OpenSSL (via Net::HTTP) was throwing a tantrum.

The Root Cause — A Policy Change in OpenSSL

That cryptic message — “unable to get certificate CRL” — turned out to be the key.

A CRL (Certificate Revocation List) is basically a “blacklist” for certificates that have been revoked. The problem? The AWS certificate didn’t actually have a CRL defined.

We checked with:

openssl s_client ... | openssl x509 -noout -text | grep "CRL Distribution Points"

Result:

X509v3 CRL Distribution Points:
# (empty)

Comparing environments made things click:

Environment	OpenSSL Version	Result
macOS (failing)	3.4.0 (new)	❌ Fails
Docker (working)	3.0.11 (stable)	✅ Works

Turns out, OpenSSL 3.4.0 introduced stricter validation rules. It now treats missing CRL entries as fatal errors — whereas the 3.0.x series simply shrugged and moved on.

So no, your Mac isn’t broken — it’s just being too helpful.

The Fixes — Two Paths to Sanity

After a lot of trial (and some error), we landed on two solid fixes.

Fix 1: The Local-Only (Insecure but Practical) Workaround

Since this issue only showed up in development, one quick way to move on is to tell AWS SDK to skip SSL verification locally.

Create: config/initializers/aws_ssl_workaround.rb

# WARNING: LOCAL DEVELOPMENT ONLY
# OpenSSL 3.4.0 enforces stricter CRL policies, so skip verification here.
if Rails.env.development?
  Aws.config.update(ssl_verify_peer: false)
end

✅ Pros:

Works instantly
Doesn’t affect production

⚠️ Cons:

Insecure (but fine for local development)

Fix 2: Match Environments (I tried this one!)

The better long-term solution is to make your local OpenSSL match Docker’s version.

Install an older OpenSSL (3.0.x):
```
brew install openssl@3.0
```

Reinstall Ruby:

rbenv uninstall 3.2.2
RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@3.0)" rbenv install 3.2.2

Reinstall gems:
```
gem install bundler
bundle install
```

Now your local Ruby is linked against OpenSSL 3.0 — just like Docker and peace is restored.

Confirmation & References

Turns out, we weren’t the only ones haunted by this ghost:

openssl/openssl#28758 — CRL verification failures in OpenSSL 3.6.0
ruby/openssl#949 — Net::HTTP failing due to stricter CRL rules

Takeaway

SSL errors can feel like black magic, but more often than not, they’re version mismatches in disguise.

So next time something works in Docker but not on your laptop, remember: sometimes it’s not your code, it’s just your OpenSSL being extra.

Thanks for reading! If you found this helpful, share it with a fellow developer who’s currently staring at an SSL error and losing their mind.

Coder Legion - Recent posts tagged rails

What Is Idempotency?

🔍 What Is Idempotency?

🛠️ How Do We Implement It in Ruby on Rails?

💎 Why Is Idempotency Important?

⚠️ One Important Detail

RubyOnRails #API #Idempotency #BackendDevelopment #SoftwareArchitecture #DistributedSystems #WebDevelopment #SoftwareEngineering

Building RAG on PostgreSQL with Pgvector and Ruby on rails

Gemfile

Elasticsearch with Ruby on Rails

🔍 What is Elasticsearch?

🛠️ How do we use it with Ruby on Rails?

💡 Why use Elasticsearch?

⚠️ One important architectural decision

API Architecture

️ How I approach API architecture with Ruby on Rails

Important architecture decisions

Why good API architecture matters

RubyOnRails #Ruby #API #APIDesign #SoftwareArchitecture #BackendDevelopment #WebDevelopment #RESTAPI #SoftwareEngineering

One Rails App, Multiple Customers

What is Multi-Tenancy?

How can we implement it with Rails?

Why use Multi-Tenancy?

⚠️ The important part

Skip the RSpec examples you don't need: rspec-tracer 2.0 in pre-release

Install

What changed since 1.x

1. Pluggable storage

2. Pluggable remote cache (for CI)

3. Per-example tracks: DSL

4. track_env(*names) config DSL

5. Rails preset

6. bin/rspec-tracer CLI

7. HTML + JSON reporters

8. SimpleCov branch coverage now works

9. Boot-time warns

10. Schema-version field + Rails 8.0 + CI recipes

Migration from 1.x

Why pre-release

Where to send feedback

Hotwire vs. React: A Guide for the "One-Person Framework"

The Default Choice

The Problem: Two Apps, One Product

1. The "Single Source of Truth" Myth

2. Velocity: The "One Person Framework"

3. "But React feels better"

When SHOULD you use React?

The Verdict

How We Solved “Unable to Get Certificate CRL” in Rails: A Debugging Story

⚠️ The Error

The Contradiction That Made No Sense

The “Wait, What?” Moment

The Real Test — Inside the Rails Console

The Root Cause — A Policy Change in OpenSSL

The Fixes — Two Paths to Sanity

Fix 1: The Local-Only (Insecure but Practical) Workaround

Fix 2: Match Environments (I tried this one!)

Confirmation & References

Takeaway

3. Per-example `tracks:` DSL

4. `track_env(*names)` config DSL

6. `bin/rspec-tracer` CLI