How truemail-rb/truemail-rack works
Project type and purpose
• This is a monolithic Rack-based web API (“truemail-rack”) written in Ruby.
• Purpose: expose a RESTful HTTP interface to the core Truemail gem for email validation (regex, DNS/MX, SMTP).
• No database. Uses environment variables for configuration and external services (DNS resolver, SMTP servers).
File structure
• Top‐level:
– config.ru – Rack entrypoint
– app/truemail_server – core application code
– config/system & initializers – configuration loader, types, environment setup
– spec – RSpec tests (requests, unit, system)
– CI & linting configurations (.circleci, .github, .rubocop, etc.)
• app/truemail_server:
– controllers/… – HTTP endpoints: healthcheck, version, validator, error handling
– router.rb – maps URL paths to controllers
– rack_cascade.rb – Rack middleware cascade (authentication, logging, error catching)
– services/… – AccessToken auth, EmailValidator orchestrator, Environment reader, Version
• No persistence layer.
• External dependencies appear only at runtime: DNS lookups, SMTP sessions.
README for additional insights
• Describes three main endpoints:
– GET /?email=… (with Authorization header)
– GET /version
– GET /healthcheck
• Lists environment variables controlling: tokens, regex patterns, MX/SMTP behavior, DNS servers, logging.
• Uses Thin as the Rack web server.
a. Main components:
1. API Client (curl, HTTP client, mobile/web UI)
2. HTTP Server (Thin)
3. Rack Middleware Cascade
4. Router
5. Controllers:
– ValidatorController
– VersionController
– HealthcheckController
– ErrorController
6. Services Layer:
– AccessTokenService (auth)
– EmailValidatorService (calls Truemail core)
– EnvironmentService (reads & validates ENV configs)
7. Truemail Core (external Ruby gem)
8. External Services: DNS resolver(s), SMTP servers
b. Data flow & interactions:
Client → Thin (TCP) → Rack Cascade (logging, auth via AccessTokenService) → Router
→ Controller logic (e.g. ValidatorController)
→ EnvironmentService (load config)
→ EmailValidatorService (invoke Truemail core)
→ Truemail core performs:
• Regex check
• DNS/MX lookup → DNS resolver
• SMTP session → SMTP server
← collects results
← returns JSON response
← Controller renders JSON → Rack → Thin → Client
c. Architectural patterns & principles:
• Separation of concerns: middleware vs routing vs controllers vs services
• Single‐responsibility: each service handles one aspect (auth, config, validation)
• External dependency inversion: core gem isolated behind service layer
• Stateless, config-via-ENV, no persistence
d. Key technologies & libraries:
• Ruby, Rack, Thin
• Truemail gem (email validation core)
• RSpec for tests
• CI: CircleCI, CodeClimate, linters (Rubocop, Yamllint, etc.)