trace_request_id 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f42a8225e6860b237f499a3b00e8d1204d1035873cbd8b9c69caee39b8de100c
+  data.tar.gz: a9934505dcb9b0528e20edddce2eb27edfa03d26f6f5a8a568c7ea7df8b4da74
+SHA512:
+  metadata.gz: 8d04f12d5654cb4a7ebc16934b430cdc853a100911b4c9406ab297a2398e33522921c7977f435849dba1d95951475b0682640d216a69af44fccf1574c47c456f
+  data.tar.gz: 0cfa01653d617229b8057f8d80494ea7fa6461536448050e0b07ed7e424957cc2686b2e6b5cdce2c8e92ae0352722fed23837df244dbce87b569e1953eaf0276

data/README.md

@@ -0,0 +1,127 @@
+# TraceRequestId
+
+A Ruby gem that stores X-Request-Id in thread context and passes it to Sidekiq jobs to trace user journeys.
+This gem helps maintain request context across different parts of your application, making it easier to track
+and debug user requests through your system.
+
+## Features
+
+- Thread-safe storage of request IDs
+- Automatic UUID generation for new requests
+- Sidekiq integration for passing request IDs to background jobs
+- Rails middleware support for automatic request ID handling
+- Simple API for managing request IDs
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'trace_request_id'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install trace_request_id
+
+## Usage
+
+### Basic Usage
+
+```ruby
+# Get the current request ID (returns nil if not set)
+TraceRequestId.id
+
+# Set a request ID
+TraceRequestId.id = "custom-request-id"
+
+# Get or initialize a request ID (generates UUID if not set)
+TraceRequestId.id(init: true)
+
+# Clear the current request ID
+TraceRequestId.clear
+```
+
+### Sinatra Integration
+
+```ruby
+class MyApplication < Sinatra::Base
+  use Rack::TraceId
+end
+```
+
+### Rails Integration
+
+The gem provides a Rails middleware that automatically handles request IDs.
+
+It registers Rails middleware using Railtie, inserting it after ActionDispatch::RequestId
+
+The middleware:
+- Extracts the request ID from the Rails request (set by ActionDispatch::RequestId)
+- Stores it in the thread context for the duration of the request
+- Cleans up the thread context after the request completes
+
+### Sidekiq Integration
+
+The gem registers Sidekiq middleware automatically using Railtie.
+The gem provides both client and server middleware to maintain request context across background jobs.
+
+#### Client Middleware
+
+- Captures the current trace ID from the thread context
+- Stores it in the job payload before saving to Redis
+- Generates a new UUID if no trace ID exists
+
+#### Server Middleware
+
+- Restores the trace ID from the job payload to the worker thread context
+- Automatically cleans up the thread context after the job completes
+
+## Thread Safety
+
+The gem is designed to be thread-safe. Each thread maintains its own request ID context, making it safe to use in multi-threaded environments.
+
+Example of thread isolation:
+
+```ruby
+# Main thread
+TraceRequestId.id = "main-thread-id"
+
+# Different threads maintain separate contexts
+thread1 = Thread.new do
+  TraceRequestId.id = "thread1-id"
+  # TraceRequestId.id returns "thread1-id"
+end
+
+thread2 = Thread.new do
+  TraceRequestId.id = "thread2-id"
+  # TraceRequestId.id returns "thread2-id"
+end
+
+# Main thread still has its original ID
+# TraceRequestId.id returns "main-thread-id"
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, to run the tests:
+- rspec --pattern spec/*.rb
+- cd spec/dummy_app
+- rspec
+- cd ../spec/dummy_app_no_sidekiq
+- rspec
+- cd ../spec/dummy_sinatra
+- rspec
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/den1049/trace_request_id.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). 

data/lib/rack/trace_id.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Rack
+  # Middleware to store +request_id+ in the thread context as +trace_id+ and clean it up at the end of the request.
+  #
+  # For rails app it needs to be inserted after ActionDispatch::RequestId to ensure that request_id
+  # will be retrieved or generated with ActionDispatch::RequestId.
+  #   config.middleware.insert_after ActionDispatch::RequestId, Rack::TraceId
+  class TraceId
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      with_trace_id(env) do
+        @app.call(env)
+      end
+    end
+
+    private
+
+    # Extracts +request_id+ from +env+ argument, then wraps block with thread context store and clear steps
+    def with_trace_id(env)
+      TraceRequestId.id = env_request_id(env)
+
+      yield
+    ensure
+      TraceRequestId.clear
+    end
+
+    def env_request_id(env)
+      return env['HTTP_X_REQUEST_ID'] || SecureRandom.uuid unless defined?(ActionDispatch::Request)
+
+      # extract request_id assigned by ActionDispatch::RequestId middleware
+      req = ActionDispatch::Request.new env
+      req.request_id
+    end
+  end
+end

data/lib/trace_request_id/railtie.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class TraceRequestId
+  class Railtie < Rails::Railtie # :nodoc:
+    initializer 'trace_request_id.configure_rails_initialization' do |app|
+      app.middleware.insert_after ActionDispatch::RequestId, Rack::TraceId
+      register_sidekiq_middleware if defined?(Sidekiq)
+    end
+
+    private
+
+    def register_sidekiq_middleware
+      register_sidekiq_client_middleware
+      register_sidekiq_server_middleware
+      register_sidekiq_test_middleware if defined?(Sidekiq::Testing)
+    end
+
+    def register_sidekiq_client_middleware
+      Sidekiq.configure_client do |config|
+        config.client_middleware do |chain|
+          chain.add SidekiqClientMiddleware
+        end
+      end
+    end
+
+    def register_sidekiq_server_middleware
+      Sidekiq.configure_server do |config|
+        config.client_middleware do |chain|
+          chain.add SidekiqClientMiddleware
+        end
+
+        config.server_middleware do |chain|
+          chain.add SidekiqServerMiddleware
+        end
+      end
+    end
+
+    def register_sidekiq_test_middleware
+      # attach Sidekiq middleware to Sidekiq:Testing
+      Sidekiq::Testing.server_middleware do |chain|
+        chain.add SidekiqServerMiddleware
+      end
+    end
+  end
+end

data/lib/trace_request_id/sidekiq_client_middleware.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class TraceRequestId
+  # Stores +trace_id+ from the thread context to the job context before saving it to Redis.
+  #
+  # It needs to be inserted in the SidekiqClient chain at the start.
+  #   Sidekiq.configure_client do |config|
+  #     config.client_middleware do |chain|
+  #       chain.add TraceRequestId::SidekiqClientMiddleware
+  #       # ... other client middlewares
+  #     end
+  #   end
+  #
+  #   Sidekiq.configure_server do |config|
+  #     config.client_middleware do |chain|
+  #       chain.add TraceRequestId::SidekiqClientMiddleware
+  #       # ... other client middlewares
+  #     end
+  #   end
+  class SidekiqClientMiddleware
+    def call(_worker_class, job, _queue, _redis_pool = '')
+      job[TraceRequestId::TRACE_ID] = TraceRequestId.id(init: true)
+      yield
+    end
+  end
+end

data/lib/trace_request_id/sidekiq_server_middleware.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class TraceRequestId
+  # Restores +trace_id+ from the job context (Redis) to the thread context before starting a job.
+  #
+  # It needs to be inserted in the SidekiqClient chain at the start.
+  #   Sidekiq.configure_server do |config|
+  #     config.server_middleware do |chain|
+  #       chain.add TraceRequestId::SidekiqServerMiddleware
+  #       # ... other server middlewares
+  #     end
+  #   end
+  class SidekiqServerMiddleware
+    def call(_worker, job, _queue)
+      TraceRequestId.id = job[TraceRequestId::TRACE_ID]
+
+      yield
+    ensure
+      TraceRequestId.clear
+    end
+  end
+end

data/lib/trace_request_id/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class TraceRequestId
+  VERSION = '0.1.2'
+end

data/lib/trace_request_id.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'trace_request_id/version'
+require_relative 'rack/trace_id'
+require_relative 'trace_request_id/railtie' if defined?(Rails::Railtie)
+require_relative 'trace_request_id/sidekiq_client_middleware' if defined?(Sidekiq)
+require_relative 'trace_request_id/sidekiq_server_middleware' if defined?(Sidekiq)
+
+# Module to store trace id in the thread context
+class TraceRequestId
+  TRACE_ID = '__trace_id'
+
+  class << self
+    # Get the current trace id, or +nil+ if one has not been set.
+    def id(init: false)
+      self.id = new_trace_id_value if init && current_trace_id.to_s.strip.empty?
+
+      current_trace_id
+    end
+
+    # Set the new trace id.
+    def id=(new_trace_id)
+      Thread.current.thread_variable_set(TRACE_ID, new_trace_id)
+    end
+
+    # Clear the trace id from the current thread.
+    def clear
+      Thread.current.thread_variable_set(TRACE_ID, nil)
+    end
+
+    private
+
+    def current_trace_id
+      Thread.current.thread_variable_get(TRACE_ID)
+    end
+
+    def new_trace_id_value
+      SecureRandom.uuid
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: trace_request_id
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Denis
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-06-18 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  This gem helps track user journey storing X-Request-Id in the thread context
+                        and passing it to Sidekiq jobs
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/rack/trace_id.rb
+- lib/trace_request_id.rb
+- lib/trace_request_id/railtie.rb
+- lib/trace_request_id/sidekiq_client_middleware.rb
+- lib/trace_request_id/sidekiq_server_middleware.rb
+- lib/trace_request_id/version.rb
+homepage: https://github.com/den1049/trace_request_id
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/den1049/trace_request_id
+  source_code_uri: https://github.com/den1049/trace_request_id
+  changelog_uri: https://github.com/den1049/trace_request_id/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: A gem to store X-Request-Id in thread context and pass it to Sidekiq jobs
+test_files: []