julewire-rack 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0505d309f127982b88645a56045d2f472d36acb14efe781f6f08290559f8763e
+  data.tar.gz: 00b881c32d5761ab740773b80098c9c47950ceb574e65d38f1d4c1e14d36adbe
+SHA512:
+  metadata.gz: '078de25613aef97e313246e95e5207771a61439ed22f4b5ca97c1276593bd00863285504486275505d187fab88ab63dedbe69913b617e0e9e4c29acdc7abde7a'
+  data.tar.gz: c35d17e54f37c11328f0582497a44084faf7f3ac28f9d5418b637d905d8327441efe71b4af276c4a88c9bc60c3e47daa27893044d8353db3a260c1b2fb34556b

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## Unreleased
+
+## 1.0.0 - 2026-06-21
+
+- Initial release: Rack-family request lifecycle support primitives for Julewire
+  integrations.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexander Grebennik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,15 @@
+# Julewire Rack
+
+Rack-family request lifecycle support for Julewire integrations.
+
+This gem is deliberately framework-neutral. It is the place for Rack request
+primitives that can be shared by Rails, Grape, and other Rack-based adapters.
+Rails and ActiveSupport EventReporter helpers stay in `julewire-rails_support`.
+
+It owns capture helpers for request bodies, response bodies, headers, content
+types, and JSON-ish payload extraction. It does not install middleware by
+itself; framework gems decide when those primitives belong in a request
+pipeline.
+
+Applications normally install a framework adapter, not this support gem. Use it
+directly when writing a Rack-shaped Julewire integration.

data/julewire-rack.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/julewire/rack/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "julewire-rack"
+  spec.version = Julewire::Rack::VERSION
+  spec.authors = ["Alexander Grebennik"]
+  spec.email = ["slbug@users.noreply.github.com", "sl.bug.sl@gmail.com"]
+
+  spec.summary = "Rack request lifecycle support for Julewire."
+  spec.description = "Rack-family support primitives for Julewire request integrations."
+  spec.homepage = "https://github.com/slbug/julewire"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.4"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/slbug/julewire/tree/main/gems/rack"
+  spec.metadata["changelog_uri"] = "https://github.com/slbug/julewire/blob/main/gems/rack/CHANGELOG.md"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir[
+      "CHANGELOG.md",
+      "LICENSE.txt",
+      "README.md",
+      "julewire-rack.gemspec",
+      "lib/**/*.rb"
+    ]
+  end
+  spec.executables = []
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "julewire-core", ">= 1.0"
+  spec.add_dependency "rack", ">= 3.2"
+  spec.add_dependency "zeitwerk", ">= 2.8.1"
+end

data/lib/julewire/rack/capture/body_content_type.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Rack
+    module Capture
+      module BodyContentType
+        JSON_ONLY = ["application/json", %r{\Aapplication/.+\+json\z}].freeze
+        BINARY_MEDIA_TYPES = %w[
+          application/gzip
+          application/octet-stream
+          application/pdf
+          application/x-gzip
+          application/zip
+        ].freeze
+        BINARY_MEDIA_PREFIXES = %w[
+          audio/
+          font/
+          image/
+          video/
+        ].freeze
+
+        class << self
+          def allowed?(target, selector:)
+            media_type = media_type_for(target)
+            return false if binary?(media_type)
+            return true if selector == true
+            return false unless selector
+
+            return false if media_type.empty?
+
+            Array(selector).any? { matches?(media_type, it) }
+          end
+
+          def binary?(media_type)
+            value = media_type.to_s
+            return true if BINARY_MEDIA_TYPES.include?(value)
+
+            BINARY_MEDIA_PREFIXES.any? { value.start_with?(it) }
+          end
+
+          def media_type_for(target)
+            normalized_media_type(raw_content_type(target))
+          end
+
+          def raw_content_type(target)
+            direct_content_type(target) || header_content_type(target)
+          rescue StandardError
+            nil
+          end
+
+          def direct_content_type(target)
+            return target.media_type if target.respond_to?(:media_type)
+            return target.content_mime_type.to_s if target.respond_to?(:content_mime_type) && target.content_mime_type
+            return target.content_type if target.respond_to?(:content_type)
+
+            target.get_header("CONTENT_TYPE") if target.respond_to?(:get_header)
+          end
+
+          def header_content_type(target)
+            header_value(target.headers, "content-type") if target.respond_to?(:headers)
+          end
+
+          def header_value(headers, key)
+            return unless headers.respond_to?(:[])
+
+            headers[key] || headers[key.upcase] || headers[key.split("-").map(&:capitalize).join("-")]
+          end
+
+          def matches?(media_type, matcher)
+            case matcher
+            when Regexp
+              matcher.match?(media_type)
+            else
+              media_type == normalized_media_type(matcher)
+            end
+          end
+
+          def normalized_media_type(value)
+            value.to_s.partition(";").first.strip.downcase
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/rack/capture/buffered_response_body.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Rack
+    module Capture
+      class BufferedResponseBody
+        class << self
+          def call(response, **) = new(response, **).summary_fields
+        end
+
+        def initialize(response, content_types:, limit:, mode: Settings::STRING_BODY)
+          @response = response
+          @content_types = content_types
+          @limit = limit
+          @mode = mode
+          @captured = +""
+          @total_bytes = 0
+          @truncated = false
+        end
+
+        def summary_fields
+          return {} unless BodyContentType.allowed?(@response, selector: @content_types)
+
+          body_parts = response_body_parts
+          return {} unless body_parts
+
+          if @limit.nil?
+            fields = unlimited_single_part_fields(body_parts)
+            return fields if fields
+          end
+
+          capture(body_parts)
+          return {} if @total_bytes.zero? && @captured.empty?
+
+          JsonBody.fields(:response, @captured, bytes: @total_bytes, truncated: @truncated, mode: @mode)
+        end
+
+        private
+
+        def response_body_parts
+          return unless @response.respond_to?(:stream)
+
+          stream = @response.stream
+          return if stream.respond_to?(:to_path)
+          return unless stream.respond_to?(:to_ary)
+
+          stream.to_ary
+        rescue StandardError
+          nil
+        end
+
+        def capture(body_parts)
+          body_parts.each do |part|
+            body = body_string(part)
+            next unless body
+
+            capture_part(body)
+          end
+        end
+
+        def body_string(part)
+          return part.to_str if part.respond_to?(:to_str)
+
+          nil
+        rescue StandardError
+          nil
+        end
+
+        def unlimited_single_part_fields(body_parts)
+          return unless body_parts.length == 1
+
+          body = body_string(body_parts.first)
+          return {} unless body && !body.empty?
+
+          JsonBody.fields(:response, body, bytes: body.bytesize, truncated: false, mode: @mode)
+        end
+
+        def capture_part(body)
+          bytesize = body.bytesize
+          @total_bytes += bytesize
+
+          return @captured << body if @limit.nil?
+
+          remaining = @limit - @captured.bytesize
+          if remaining <= 0
+            @truncated = true if bytesize.positive?
+            return
+          end
+
+          @captured << body.byteslice(0, remaining)
+          @truncated = true if bytesize > remaining
+        end
+      end
+    end
+  end
+end

data/lib/julewire/rack/capture/header_selection.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Rack
+    module Capture
+      class HeaderSelection
+        SENSITIVE_HEADERS = %w[
+          authorization
+          cookie
+          proxy-authorization
+          set-cookie
+          x-api-key
+        ].freeze
+        SENSITIVE_HEADER_SET = SENSITIVE_HEADERS.to_h { [it, true] }.freeze
+
+        class << self
+          def build(selector)
+            return new(true) if selector == true
+            return unless selector
+
+            new(Array(selector).to_h { [normalize_name(it), true] })
+          end
+
+          def normalize_name(name) = name.to_s.tr("_", "-").downcase
+        end
+
+        def initialize(selection)
+          @selection = selection
+        end
+
+        def include?(name)
+          @selection == true ? !SENSITIVE_HEADER_SET.key?(name) : @selection.key?(name)
+        end
+      end
+    end
+  end
+end

data/lib/julewire/rack/capture/headers.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Rack
+    module Capture
+      module Headers
+        class << self
+          def request(request, selector:)
+            env = request.env if request.respond_to?(:env)
+            return {} unless env.respond_to?(:each)
+
+            selection = HeaderSelection.build(selector)
+            return {} unless selection
+
+            capture_headers(env, selection) { request_header_name(it) }
+          end
+
+          def response(headers, selector:)
+            return {} unless headers.respond_to?(:each)
+
+            selection = HeaderSelection.build(selector)
+            return {} unless selection
+
+            capture_headers(headers, selection) { HeaderSelection.normalize_name(it) }
+          end
+
+          private
+
+          def capture_headers(headers, selection)
+            captured = {}
+            headers.each do |key, value|
+              name = yield key
+              next unless name && selection.include?(name)
+
+              captured[name] = header_value(value)
+            end
+            captured
+          end
+
+          def request_header_name(key)
+            name = key.to_s
+            return "content-type" if name == "CONTENT_TYPE"
+            return "content-length" if name == "CONTENT_LENGTH"
+            return unless name.start_with?("HTTP_")
+
+            HeaderSelection.normalize_name(name.delete_prefix("HTTP_"))
+          end
+
+          def header_value(value)
+            return value.join(", ") if value.is_a?(Array)
+
+            value.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/rack/capture/json_body.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Julewire
+  module Rack
+    module Capture
+      module JsonBody
+        BODY_KEYS = { request: :request_body, response: :response_body }.freeze
+        BODY_BYTES_KEYS = { request: :request_body_bytes, response: :response_body_bytes }.freeze
+        BODY_TRUNCATED_KEYS = { request: :request_body_truncated, response: :response_body_truncated }.freeze
+        JSON_KEYS = { request: :request_body_json, response: :response_body_json }.freeze
+        PARSE_ERROR_KEYS = { request: :request_body_parse_error, response: :response_body_parse_error }.freeze
+
+        class << self
+          def fields(prefix, body, bytes:, truncated:, mode:)
+            fields = {
+              BODY_BYTES_KEYS.fetch(prefix) => bytes,
+              BODY_TRUNCATED_KEYS.fetch(prefix) => truncated
+            }
+            return fields_with_raw_body(fields, prefix, body) unless mode == Settings::JSON_BODY
+            return fields if truncated
+
+            append_parsed_fields(fields, prefix, body)
+          end
+
+          private
+
+          def fields_with_raw_body(fields, prefix, body)
+            fields[BODY_KEYS.fetch(prefix)] = body
+            fields
+          end
+
+          def append_parsed_fields(fields, prefix, body)
+            fields[JSON_KEYS.fetch(prefix)] = JSON.parse(body)
+            fields
+          rescue JSON::ParserError => e
+            fields[PARSE_ERROR_KEYS.fetch(prefix)] = e.class.name
+            fields
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/rack/capture/request_body.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Rack
+    module Capture
+      class RequestBody
+        class << self
+          def call(request, **) = new(request, **).summary_fields
+        end
+
+        def initialize(request, content_types:, limit:, mode:)
+          @request = request
+          @content_types = content_types
+          @limit = limit
+          @mode = mode
+        end
+
+        def summary_fields
+          return {} unless BodyContentType.allowed?(@request, selector: @content_types)
+
+          captured, bytes, truncated = capture_body
+          return {} if captured.nil? || (captured.empty? && !truncated)
+
+          JsonBody.fields(:request, captured, bytes: bytes, truncated: truncated, mode: @mode)
+        end
+
+        private
+
+        def capture_body
+          body = bounded_body
+          bytes = content_length || body.bytesize
+          captured, truncated = capture(body, total_bytes: bytes)
+          [captured, bytes, truncated]
+        rescue StandardError
+          nil
+        end
+
+        def bounded_body
+          return request_body if @limit.nil?
+
+          length = content_length
+          return request_body if length && length <= @limit
+
+          read_body_stream(limit: @limit + 1)
+        end
+
+        def request_body
+          # Rack/Rails may already buffer raw_post; the byte cap applies after that read.
+          return @request.raw_post if @request.respond_to?(:raw_post)
+
+          read_body_stream(limit: nil)
+        end
+
+        def read_body_stream(limit:)
+          io = @request.body
+          original_position = nil
+          body = nil
+          begin
+            original_position = body_stream_position(io)
+            body = io.read(limit)
+          ensure
+            restore_body_stream(io, original_position)
+          end
+          body.to_str
+        end
+
+        def body_stream_position(io)
+          io.pos
+        rescue StandardError
+          nil
+        end
+
+        def restore_body_stream(io, original_position)
+          io.rewind
+        rescue StandardError
+          nil
+        ensure
+          restore_body_stream_position(io, original_position)
+        end
+
+        def restore_body_stream_position(io, original_position)
+          return unless original_position
+
+          io.pos = original_position
+        rescue StandardError
+          nil
+        end
+
+        def capture(body, total_bytes:)
+          return [body, false] if @limit.nil? || total_bytes <= @limit
+
+          [body.byteslice(0, @limit), true]
+        end
+
+        def content_length
+          value = @request.content_length if @request.respond_to?(:content_length)
+          value = @request.get_header("CONTENT_LENGTH") if value.nil?
+          integer = Integer(value)
+          integer if integer.positive?
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/julewire/rack/capture/settings.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Rack
+    module Capture
+      class Settings
+        JSON_BODY = :json
+        STRING_BODY = :string
+        CAPTURE_BODY_VALUES = [false, true, JSON_BODY, "json"].freeze
+        private_constant :CAPTURE_BODY_VALUES
+
+        include Julewire::Core::Integration::Settings
+
+        setting :body, default: false, predicate: true, validate: :validate_body
+        setting :body_bytes, default: 65_536, validate: byte_limit
+        setting :body_content_types, default: BodyContentType::JSON_ONLY
+        setting :headers, default: false, predicate: true
+
+        def body_mode
+          case body
+          when JSON_BODY, "json"
+            JSON_BODY
+          else
+            STRING_BODY
+          end
+        end
+
+        def enabled? = headers? || body?
+
+        private
+
+        def validate_body(value)
+          return value if CAPTURE_BODY_VALUES.include?(value)
+
+          raise Error, "body must be false, true, or :json"
+        end
+      end
+    end
+  end
+end

data/lib/julewire/rack/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Rack
+    VERSION = "1.0.0"
+  end
+end

data/lib/julewire/rack.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "julewire/core"
+
+module Julewire
+  module Rack
+    class Error < Julewire::Error; end
+  end
+
+  loader = Zeitwerk::Loader.for_gem_extension(self)
+  loader.setup
+end

data/lib/julewire-rack.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "julewire/rack"

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: julewire-rack
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Alexander Grebennik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: julewire-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+description: Rack-family support primitives for Julewire request integrations.
+email:
+- slbug@users.noreply.github.com
+- sl.bug.sl@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- julewire-rack.gemspec
+- lib/julewire-rack.rb
+- lib/julewire/rack.rb
+- lib/julewire/rack/capture/body_content_type.rb
+- lib/julewire/rack/capture/buffered_response_body.rb
+- lib/julewire/rack/capture/header_selection.rb
+- lib/julewire/rack/capture/headers.rb
+- lib/julewire/rack/capture/json_body.rb
+- lib/julewire/rack/capture/request_body.rb
+- lib/julewire/rack/capture/settings.rb
+- lib/julewire/rack/version.rb
+homepage: https://github.com/slbug/julewire
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/slbug/julewire
+  source_code_uri: https://github.com/slbug/julewire/tree/main/gems/rack
+  changelog_uri: https://github.com/slbug/julewire/blob/main/gems/rack/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.14
+specification_version: 4
+summary: Rack request lifecycle support for Julewire.
+test_files: []