[GSoC Proposal Draft] - Anuj Pal - Extension System (Railtie Equivalent)

[anuj-pal27]

1. Contact Information

• Email: anujpal27669@gmail.com
• GitHub: https://github.com/anuj-pal27
• Location: Etah, Uttar Pradesh, India

---

2. What project do you want to work on?

I want to work on the Extension System for Rage under rage-rb/rage. I found this project on the ideas list and reached out to the mentors @daz-codes and @cuneyter to discuss it further. The idea of building something foundational — a system that other gem authors will build on top of — is what drew me to it.

---

3. Why do you like Ruby, and why do you want to work on a Ruby project in GSoC?

I started with Ruby through Rails during a backend mentorship, and what struck me immediately was how expressive and readable the code is. Ruby feels like you are writing what you mean, not fighting the language to say it. I got curious about how Rails itself works under the hood — Railties, the boot process, middleware stacks — and that curiosity is what eventually led me to Rage.

I want to work on a Ruby project in GSoC because the Ruby open source community is genuinely collaborative. The maintainers take time to review and discuss ideas, not just merge PRs. That kind of environment is where I learn the most.

---

4. Describe your experience with Ruby, C, and other languages

• Ruby — Built backend features for a multi-tenant LMS using Rails, implemented RAG pipelines with pgvector, added real-time features via Action Cable. Currently contributing to Rage and have built a POC for the extension system.
• C — Basic understanding from college coursework, not my primary language.
• Other languages — TypeScript (Next.js, Node.js), Python, C++. Built and deployed production apps using the MERN stack and Next.js with Supabase.

---

5. Educational Background

B.Tech in Computer Science Engineering at RBS Engineering Technical Campus, Agra (2022–2026), currently in my 4th year with a CGPA of 8.13.

Alongside my degree, I completed a year-long Ruby on Rails internship under the mentorship of a senior backend developer in ROR at Security Compass, where I got hands-on experience building real backend features in a production Rails environment. No prior degrees or publications.

---

6. Pull Requests to Ruby Open Source Projects

rage-rb/rage (Rage framework)

• [Rendering] Custom renderer support #244 — Merged ✅
  Implements the config.renderer(:name) { ... } DSL. Registers custom renderer
  blocks and generates render_<name> methods on RageController::API at boot time.

• Add singular resource routing and specs #247 — Open
  Implements the singular resource route helper in the router DSL and updates
  the spec suite to validate all supported options and behaviors.

hostedgpt (Ruby on Rails) — https://github.com/AllYourBot/hostedgpt

• Localize Share Conversation dialog AllYourBot/hostedgpt#733
• Fix Deploy to Heroku button in README AllYourBot/hostedgpt#732

Rage — POC for the Extension System

• https://github.com/anuj-pal27/Rage_Railtie_POC

I have been actively contributing to Rage itself.

---

7. Other Commitments This Summer

I do not have any major commitments during the GSoC period. I have kept this summer free specifically to focus on GSoC. I can comfortably commit the full 40 hours per week.

---

8. Vacations or Trips This Summer

No trips or vacations planned during the GSoC period.

---

9. Classes This Summer

I will not be taking any classes during the GSoC coding period.

---

10. Other Employment This Summer

No other employment this summer. GSoC will be my primary focus.

---

11. Previous GSoC Participation

I applied to GSoC once before but was not selected — I was not prepared enough at the time and did not have a strong proposal or prior open source contributions. Since then I have building real projects with Rails, and investing time in understanding codebases deeply before proposing changes. This application is the result of that preparation.

---

12. Project Proposal

Please see the full proposal below.

---

Project: rage-rb/rage
Mentors: @daz-codes, @cuneyter
Contributor: Anuj Pal
Project Size: ~175 hours
Difficulty: Medium

---

1. Short Introduction

Hi, I'm Anuj, a Backend developer in Ruby on Rails. Currently in 4th year of my college. I came across Rage while looking for Ruby frameworks to contribute to, and the Extension System project immediately caught my attention.

I have been exploring how Rails solves this problem through Railties, reading the Rails source code, and building a small POC inside a real Rage app to understand the problem better. You can find my POC here:
https://github.com/anuj-pal27/Rage_Railtie_POC

2. Problem Understanding

Right now, if someone wants to integrate a third-party gem with Rage, they have to do all the setup manually in their app. There is no standard way for a gem to say "when Rage boots, run my setup code automatically."

For example, if someone wants to add error tracking with Sentry, they have to manually initialise it, configure it, and hook it into the right place themselves. This is extra work for every developer using that gem, and it is easy to get wrong.

Rails solved this problem a long time ago with Railties. A gem can inherit from Rails::Railtie, define its setup code inside lifecycle hooks like before_configuration or after_initialize, and Rails runs it automatically during boot. The developer using the gem does not have to do anything extra.

Rage does not have this yet. As Rage grows and more gems want to support it, this becomes a real problem. Without a standard extension system, every gem will solve it differently, or not at all.

3. Technical Approach

High-level Architecture

The extension system will have four main parts:

---

1. Rage::Extension Base Class

This is the class that any gem inherits from to plug into Rage. As soon as a gem inherits from it, Rage automatically knows about it — no manual registration needed.

class MyGem::Extension < Rage::Extension
  before_configuration { ... }
  after_initialize { ... }
end

This works because of Ruby's inherited hook:

module Rage
  class Extension
    @registered_extensions = []

    def self.inherited(subclass)
      @registered_extensions << subclass  # auto registers!
    end

    def self.run_before_configuration!
      @registered_extensions.each(&:run_before_configuration!)
    end

    def self.run_after_initialize!
      @registered_extensions.each(&:run_after_initialize!)
    end
  end
end

📎 POC: https://github.com/anuj-pal27/Rage_Railtie_POC

---

2. Where Hooks Plug Into Rage's Boot Process

I read through lib/rage/setup.rb to find exactly where the hooks need to be inserted. Here is how the current Rage boot sequence looks and where the extension hooks will be added:

lib/rage/setup.rb — Current Boot Sequence
        ↓
[NEW] Rage::Extension.run_before_configuration!   ← extensions set their defaults
        ↓
Rage.configure { } block runs                     ← user config is applied
        ↓
[NEW] Rage::Extension.run_initializers!           ← named initializers run
        ↓
Rage application boots
        ↓
[NEW] Rage::Extension.run_after_initialize!       ← middleware, services start
        ↓
App ready to serve requests ✅

This means user config always wins — extensions set defaults in before_configuration, and the user overrides them in Rage.configure. The order is guaranteed.

---

3. Lifecycle Hook Points

Hook	When it runs	What it's for
before_configuration	Before Rage.configure block	Setting extension defaults
initializer "name"	After user config, before boot	Named setup steps
after_initialize	After app fully boots	Middleware, starting services

Each hook is stored as a proc and run in registration order:

module Rage
  class Extension
    def self.before_configuration(&block)
      @before_configuration_hooks ||= []
      @before_configuration_hooks << block
    end

    def self.run_before_configuration!
      (@before_configuration_hooks || []).each(&:call)
    end
  end
end

---

4. Named Initializers

class MyGem::Extension < Rage::Extension
  initializer "my_gem.setup" do
    MyGem.setup!
  end
end

Internally stored as an ordered list of { name:, block: } pairs — the name makes it easy to debug which initializer failed during boot:

def self.initializer(name, &block)
  @initializers ||= []
  @initializers << { name: name, block: block }
end

def self.run_initializers!
  (@initializers || []).each do |init|
    init[:block].call
  rescue => e
    raise "Rage extension initializer '#{init[:name]}' failed: #{e.message}"
  end
end

---

5. Configuration Namespaces

Each extension needs its own config namespace without Rage knowing about it in advance. To ensure config.my_gem works alongside existing namespaces like config.server, config.logger etc., I'll extend Rage::Configuration itself.
The extension system will register a namespace accessor that lazily creates a nested config object when accessed — keeping everything under the same config object and avoiding parallel configuration trees.

# Rage::Configuration
def method_missing(name, *args)
  if name.to_s.end_with?("=")
    super
  else
    @extension_namespaces ||= {}
    @extension_namespaces[name] ||= ExtensionConfig.new
  end
end

def respond_to_missing?(*)
  true
end

So extensions can set their own defaults:

before_configuration do
  config.my_gem.enabled = true
  config.my_gem.api_key = nil
end

And users override in Rage.configure:

Rage.configure do
  config.my_gem.api_key = "abc123"
end

This preserves all current config behavior while safely adding extension namespaces. User config always wins because Rage.configure runs after before_configuration.

---

6. Execution Order — What Happens With Multiple Extensions?

When two or more gems register the same hook, they run in the order they were loaded — same as Rails. This is predictable and easy to reason about:

Gem A loaded → Gem A registered
Gem B loaded → Gem B registered

Boot:
  before_configuration:
    → Gem A defaults set
    → Gem B defaults set
  
  Rage.configure runs
    → user overrides applied
  
  after_initialize:
    → Gem A middleware injected
    → Gem B middleware injected

---

7. Edge Cases I Have Thought About

What if an extension raises during boot?
Named initializers wrap their execution in a rescue block and re-raise with the initializer name included, so the developer knows exactly which extension failed.

What if config is accessed before before_configuration runs?
ExtensionConfig uses method_missing to lazily create namespaces, so accessing config.my_gem before it is set just returns an empty ExtensionConfig object rather than raising a NoMethodError.

What if two extensions set the same config key?
Last write wins — same as Rails. The user's Rage.configure block always runs last, so user config is never overwritten by an extension.

---

8. Before vs After — The Developer Experience

Without the extension system today:

# config/initializers/sentry.rb — developer has to write all of this manually
Sentry.init do |config|
  config.dsn = ENV["SENTRY_DSN"]
  config.traces_sample_rate = 1.0
end

# config/application.rb — developer has to know to add this
Rage.configure do
  config.middleware.use Sentry::Rack::CaptureExceptions
end

With the extension system:

# Gemfile — this is all the developer has to do
gem "sentry-rage"

# config/application.rb — just set the DSN
Rage.configure do
  config.sentry.dsn = ENV["SENTRY_DSN"]
end

Everything else — middleware injection, tracing setup, backtrace cleaning — happens automatically. Zero manual wiring.

---

9. Full API Reference

class MyGem::Extension < Rage::Extension

  # Runs before Rage.configure — set your defaults here
  before_configuration do
    config.my_gem.enabled = true
    config.my_gem.api_key = nil
  end

  # Named initializer — runs after user config is applied
  initializer "my_gem.setup" do
    MyGem.setup!(api_key: config.my_gem.api_key)
  end

  # Runs after app fully boots — inject middleware, start services
  after_initialize do
    next unless config.my_gem.enabled
    Rage.application.middleware.use MyGem::Middleware
  end

end

---

10. Rake Task Support

After reading through both lib/rage/tasks.rb and Rails' Railtie source, I found that Rage already loads rake tasks from lib/tasks/**/*.rake inside Rage::Tasks.init. But there is no way for a gem to register its own rake tasks into that system yet.

The fix is straightforward — extensions register a block, and Rage::Tasks.init
runs all registered blocks before loading app tasks:

class MyGem::Extension < Rage::Extension
  rake_tasks do
    load "my_gem/tasks/my_gem.tasks"
  end
end

Internally in Rage::Extension:

def self.rake_tasks(&blk)
  @rake_task_blocks ||= []
  @rake_task_blocks << blk
end

def self.run_rake_tasks!
  (@rake_task_blocks || []).each(&:call)
end

And a one line change in Rage::Tasks.init:

def init
  load_db_tasks if defined?(StandaloneMigrations)
  Rage::Extension.run_rake_tasks!   # ← extensions register their tasks here
  load_app_tasks
end

This is a small, focused change that fits naturally into what Rage already does. Generators are a different story — Rage does not have a generator system yet so that needs more groundwork and is better left for V2.

---

4. Milestones & Timeline

Total: ~175 hours over 10 weeks

---

Week 1 — Codebase Familiarization & Final Design
The design is already largely shaped through pre-GSoC research — reading through lib/rage/setup.rb, studying Rails Railtie, building the POC, and discussing with mentors. Week 1 will be used to finalize any remaining design decisions,
get mentor sign-off on the API, and set up the development environment properly before writing any production code.

---

Week 2–3 — Core Extension System
Build the Rage::Extension base class with auto-registration using Ruby's inherited hook. This is the foundation everything else builds on. Write tests as I go.

---

Week 4 — Lifecycle Hook Points
Add all three hook points into Rage's boot process:

• before_configuration — runs before app config loads
• initializer — runs after user config, before app boots
• after_initialize — runs after app fully boots

Write tests for each hook point to make sure they fire in the right order.

---

Week 5 — Named Initializers
Add named initializer support with proper error handling — if an initializer raises, the error message includes the initializer name so the developer knows exactly what failed during boot.

---

Week 6–7 — Configuration Namespaces
Extend Rage's existing configuration to support dynamic extension namespaces. Handle edge cases like config conflicts and make sure user config always overrides extension defaults.

---

Week 8 — Middleware & Rake Task Support
Allow extensions to inject middleware into Rage's stack inside after_initialize. Also add rake task support by hooking into Rage::Tasks.init — extensions can register task blocks that load alongside the app's own rake tasks.

---

Week 9–10 — Sentry SDK Extension & Final Testing
Build a real Rage extension for the Sentry SDK as the final deliverable — covering middleware injection, config namespaces, named initializers, and backtrace cleanup. Fix any remaining issues, write documentation for gem authors, and submit the final work.

---

Rake tasks and generators are out of V1 scope and will be picked up in V2.

5. Deliverables

• Code — A pull request into Rage with the full extension system
• Examples — A real Rage extension for the Sentry SDK showing how the system works against a production-grade gem
• Docs — A simple guide for gem authors on how to build a Rage extension
• Tests — Unit and integration tests covering each hook, config namespace, initializer ordering, middleware injection, rake task loading, and the full Sentry extension end to end.

6. Real World Validation — Sentry SDK Extension

To prove the system works against a real-world gem, the final deliverable will be a Rage extension for the Sentry SDK. I studied how Sentry's existing Rails integration works through Sentry::Railtie and mapped each part to what Rage needs.

Sentry Scope

I'll be explicit about what is being ported from Sentry's Railtie. setup_backtrace_cleanup_callback and activate_tracing will be defined inside the Rage extension itself, not assumed to exist elsewhere.

In scope (ported / implemented):

• Sentry.init setup using user config
• Middleware insertion (Sentry::Rack::CaptureExceptions)
• Backtrace cleanup (setup_backtrace_cleanup_callback) — defined in the extension
• Tracing activation (activate_tracing) — defined in the extension

Out of scope for V1 (to be explored later):

• ActiveJob integration — Rage does not use Rails ActiveJob
• ActionCable integration — Rage has its own WebSocket system
• Rails error subscriber — Rails‑specific, no Rage equivalent

These exclusions will be clearly documented in both the proposal and code comments so the scope is unambiguous.

---

How Sentry currently boots in Rails:

config/initializers/sentry.rb
        ↓
Sentry.init { config... }        ← Main SDK setup
        ↓
sentry.use_rack_middleware       ← Middleware injected
        ↓
config.after_initialize          ← Tracing, backtrace cleaner
        ↓
Rails fully initialized ✅

How the same will work in Rage:

before_configuration             ← Set defaults (dsn, traces_sample_rate)
        ↓
sentry.setup initializer         ← Sentry.init with user config
        ↓
after_initialize                 ← Inject middleware, activate tracing
        ↓
Rage fully initialized ✅

Reference: https://github.com/getsentry/sentry-ruby/blob/master/sentry-rails/lib/sentry/rails/railtie.rb

After reading through Sentry's existing Rails Railtie, I mapped out what actually matters for Rage. Here's what I came up with:

class Sentry::RageExtension < Rage::Extension
  # Set sensible defaults before the user's config loads.
  # Mirrors what sentry-ruby expects before Sentry.init is called.
  before_configuration do
    config.sentry.dsn = ......
    .....
  end

  # Only initialize Sentry if the user actually set a DSN.
  # Sentry's own Railtie uses Sentry.initialized? as a guard —
  # doing the same thing here, just earlier in the boot process.
  initializer "sentry.setup" do
    next unless config.sentry.dsn

    Sentry.init do |s|
      s.dsn = config.sentry.dsn
      s.traces_sample_rate = config.sentry.traces_sample_rate
    end
  end

  # Rack middleware for capturing exceptions — this is the core of
  # what Sentry's Railtie does. Everything else is Rails-specific
  # and doesn't apply to Rage.
  after_initialize do
    next unless Sentry.initialized?

    Rage.application.middleware.use Sentry::Rack::CaptureExceptions
    setup_backtrace_cleanup_callback
    activate_tracing
  end
end

---

Looking forward to working closely with the mentors to ship something the Rage ecosystem can build on for years.

[rsamoilov]

Hi @anuj-pal27

This is a very strong and well-researched proposal!

One minor comment: instead of building a dummy extension, I highly recommend picking a real, popular Ruby gem (e.g., Sentry SDK or Datadog SDK) and writing an actual Rage extension for it as your final deliverable. This will prove the system works for real-world use cases and allow you to polish the implementation.

[anuj-pal27]

Hey @rsamoilov , I've updated the proposal above based on your feedback. Here's a quick summary of what changed:

• Replaced the dummy extension with a real Sentry SDK extension as the final deliverable

• Added more technical depth to Section 3 — boot sequence diagram, method_missing config implementation, execution order with multiple extensions, edge cases, and a before/after developer experience comparison

• Added Rake task support to V1 scope with a clear implementation approach hooking into Rage::Tasks.init

Please let me know if anything needs to be changed!

[rsamoilov]

Hey @anuj-pal27 , it's a strong proposal overall. A few things to address before submitting:

1. Timeline inconsistency on hooks: Your technical approach lists before_configuration, initializer, and after_initialize, but Week 5–6 in the timeline lists before_configuration, before_initialize, and after_initialize. Which set of hooks are you actually building?

2. Config namespace integration: The ExtensionConfig class is presented in isolation, but Rage already has Rage::Configuration with nested config for server, middleware, logger, etc. How does config.my_gem plug into the existing config object?

3. Sentry scope: setup_backtrace_cleanup_callback and activate_tracing appear in your code but are undefined. Be specific about which parts of Sentry's Railtie you'll port and which Rails-specific features (ActiveJob hooks, background job tracing, etc.) you'll skip.

4. Weeks 1–2: Your design is already quite detailed, so "Research & Design" for two full weeks feels redundant.

5. Contributions to Rage: Landing even a small PR to rage-rb/rage before the deadline (bug fix, test, docs) would significantly strengthen your application.

With these addressed, this is in great shape!

[anuj-pal27]

Hey, thank you so much for the detailed feedback — this is really helpful. Here's how I plan to address each point:

1. Timeline inconsistency — The correct set of hooks is before_configuration, initializer, and after_initialize. before_initialize was a mistake in the timeline, I'll fix that.

2. Config namespace integration — I'll clarify how ExtensionConfig plugs into the existing Rage::Configuration object so config.my_gem works alongside the existing config.server, config.logger etc.

3. Sentry scope — I'll be explicit about what's being ported. setup_backtrace_cleanup_callback and activate_tracing will be defined as part of the extension itself. ActiveJob hooks, background job tracing, and anything Rails-specific will be out of scope and clearly documented as such.

4. Weeks 1–2 — Agreed, I'll compress research into Week 1 and move implementation start to Week 2.

5. PR to Rage — Already on it. I'll aim to get a small PR in before the deadline.

[rsamoilov]

PR to Rage — Already on it. I'll aim to get a small PR in before the deadline.

Sorry, I got it all mixed up - you're already working on custom renderers. That's more than enough!

[anuj-pal27]

No worries! Yes, I'm actively working on the custom renderers implementation. Also been going through the codebase and found a typo in the README — pushing that fix as well. Trying to dig deeper into the code to find any bugs or small improvements I can contribute before the deadline!

[anuj-pal27]

Hey @rsamoilov , thank you so much for taking the time to review and share such detailed feedback — it really helped me improve the proposal. I've addressed all the points you mentioned. Whenever you get some free time, please do take a look!

[rsamoilov]

Hi @anuj-pal27 , this looks great 👍
Don't forget to submit your proposal in the GSoC dashboard!

[anuj-pal27]

Thank you so much @rsamoilov ! Really appreciate all the guidance throughout this process — it made a huge difference. Will submit it on the GSoC dashboard.