How displayful/turnstiled works
Project type and purpose
• This is a Ruby gem (turnstiled) designed to plug into a Ruby on Rails application.
• Its sole purpose is to streamline the integration of Cloudflare Turnstile CAPTCHA—automating asset injection, helper methods, controller concerns, and server-side verification.
File structure
• Top-level files:
• turnstiled.gemspec, Gemfile/Gemfile.lock – gem metadata and dependencies
• Rakefile, bin/ scripts – development tasks and wrappers for tests and linting
• app/
• assets/config/turnstiled/manifest.js – asset pipeline manifest
• app/javascript/turnstiled – Stimulus controller and mock widget for development/testing
• lib/turnstiled
• engine.rb – Rails::Engine to hook into asset pipeline and isolate namespace
• controller_methods.rb – Concern injecting verify_turnstile_request
• view_helper.rb – Helper methods (turnstile_javascript_tag, turnstile_tag)
• verifier.rb – Server-side verification logic against Cloudflare API
• test/ – unit tests for each module
Extract architectural insights from the README
• The gem:
• Exposes view helpers to embed JS and widget markup
• Provides a mock widget in dev/test via Stimulus for predictable callbacks
• Offers a controller concern to verify incoming tokens
• Makes outbound HTTPS calls to Cloudflare’s verification endpoint
Main components
a. Rails Host Application
– Uses turnstiled Engine under the hood
– Calls helper methods in views and controller concerns in controllers
b. Turnstiled Engine (Railtie)
– Mounts assets into Rails’ asset pipeline
– Auto-loads Stimulus controllers and styles
c. ViewHelper Module
– Renders <script> tags and
containers
d. Front-end JavaScript
– Official Turnstile widget (production)
– MockTurnstileWidget (development/test)
– Stimulus controller listens for widget callback, injects token into form
e. Rails Controller Concern
– verify_turnstile_request runs before actions to enforce verification
f. Verifier Module
– Performs HTTP POST to https://challenges.cloudflare.com/turnstile/v0/siteverify
– Parses JSON response, raises or returns boolean
g. Cloudflare Turnstile Service (external)
Relationships and data flows
1. User loads a Rails view →
ViewHelper injects <script> and widget markup
2. Browser requests Turnstile JS from Cloudflare CDN →
Widget is rendered client-side
3. User solves captcha →
Widget JS fires callback → Stimulus controller captures token →
Token appended to form field cf-turnstile-response
4. Form submitted → Rails controller action invoked →
Controller Concern extracts token → calls Verifier
5. Verifier POSTs token+secret to Cloudflare →
Cloudflare returns success/failure →
Controller Concern allows or rejects request
Architectural patterns and design principles
• Rails Engine pattern for plug-and-play integration
• MVC extension via controller concerns and view helpers
• Asset Pipeline + Stimulus for encapsulated front-end behavior
• Single-Responsibility: each module has one clear purpose
• Environment-aware code paths (mock vs. real widget)