Skip to content

refactor(server): embrace Falcon fiber reactor, strip thread mutexes, and modernize caching - #1141

Merged
gildesmarais merged 5 commits into
mainfrom
refactor/falcon-reactor-modernization
Sep 6, 2026
Merged

refactor(server): embrace Falcon fiber reactor, strip thread mutexes, and modernize caching#1141
gildesmarais merged 5 commits into
mainfrom
refactor/falcon-reactor-modernization

Conversation

@gildesmarais

@gildesmarais gildesmarais commented Sep 6, 2026

Copy link
Copy Markdown
Member

What changed

  • Migrate server runtime from Puma + Rack::Timeout to Falcon + Async fiber reactor.
  • Map Async::TimeoutError to 504 GATEWAY_TIMEOUT with standardized Retry-After: 300 headers.
  • Eliminate thread-blocking primitives (Concurrent::IVar, Concurrent::Map, Mutex, try_lock, spin loops).
  • Rebuild Feeds::Cache with fiber-native InFlight waiter (Async::Notification) and Data.define(:result, :expires_at). Safely propagates Async::Stop cancellation to pending waiters.
  • Streamline RateLimiter with lock-free fiber-safe hash tracking and automated window pruning.
  • Modernize AccountManager snapshot memoization and RequestContext using Fiber[:request_context].
  • Inline HTTP cache headers in Feeds::Renderer and eliminate redundant Feeds::HttpCache wrapper.
  • Prune obsolete flags async_feed_refresh_enabled and async_feed_refresh_stale_factor.
  • Standardize all feed token specs, integration tests, and docs on strategy: 'default' (while preserving legacy faraday token decode and execution backward compatibility).
  • Update OpenAPI schema and regenerated client types.
  • Bump html2rss dependency to released ~> 0.30 (0.30.0).
  • Remove private DevContainer volume mount.

Why

Switching to Falcon eliminates thread contention and unlocks fiber concurrency across asynchronous HTTP and caching pipelines. Stripping obsolete thread synchronization primitives (Mutex, concurrent-ruby) significantly reduces code complexity, allocation overhead, and legacy surface area while ensuring clean fiber cancellation semantics. Completes the Faraday -> HTTPX and Puma -> Falcon cutover with the published html2rss v0.30.0 release.

Risk

  • Low: The external HTTP API contract, rate limiting behavior, and feed rendering remain identical. Timeout responses consistently emit 504 Gateway Timeout. All 357 specs pass in the Dev Container.

Review map

  1. app/web/feeds/cache.rb — Fiber-native cache with Async::Notification in-flight deduplication.
  2. app/web/request/rate_limiter.rb — Lock-free rate limiting with automatic pruning.
  3. app/web/errors/error_classifier.rbAsync::TimeoutError classification and HTTPX error notes.
  4. app/web/config/runtime_env.rb & app/web/config/flags.rb — Runtime config and flag cleanup.
  5. app/web/feeds/renderer.rb — Inlined cache headers.
  6. spec/html2rss/web/feeds/source_resolver_spec.rb — Legacy faraday token backward compatibility spec.
  7. spec/html2rss/web/feeds/cache_spec.rb — Concurrency and fiber cancellation specs.
  8. Gemfile & Gemfile.lock — Bump html2rss to released 0.30.0.

Validation

  • Dev Container make ready (357 examples, 0 failures; RuboCop clean; Zeitwerk clean; YARD public docs clean; TypeScript clean; ESLint clean; Prettier clean).
  • Dev Container make openapi-verify passed.
  • Dev Container make ci-ready passed (Playwright frontend e2e smoke, OpenAPI verify, linting, formatting, full test suite).

@gildesmarais
gildesmarais enabled auto-merge (squash) September 6, 2026 08:48
@gildesmarais
gildesmarais merged commit 2e3b3cd into main Sep 6, 2026
15 checks passed
@gildesmarais
gildesmarais deleted the refactor/falcon-reactor-modernization branch September 6, 2026 08:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant