route_500_check 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b15f117febf23b2ce99b03f0a0177aeca8aa24e1c4d1c71d0730b1bdaca5391
+  data.tar.gz: 941a95a6427a6f92b759d481be967ea01de4d6df909817c5ad5c9282e29dd397
+SHA512:
+  metadata.gz: 86b6c5cd56e13f8c360a1d63b5d6ef80e59ccf659b34029b33840ec1593ee72379d81c12384a2de2845fa1bed94f734a07eec3ab393f1d12e7853197a419c190
+  data.tar.gz: 9aa0293e93bde3be504edd57f4eb87df565f9910fe2fb5592245b30494b49bbbcb34fb2f486e82b97e12e535c288fb4cf83ebdf77509f8b217493e9574d05556

data/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## v0.2.0
+
+### Summary
+
+This release focuses on **stability, safety, and operational clarity**.
+No new features were added. Existing functionality was refined to ensure
+predictable behavior in production cron jobs and CI environments.
+
+---
+
+### Added
+
+* Explicit **exit code semantics** to distinguish:
+
+  * HTTP 500 detection
+  * Configuration / safety stops
+  * Runtime failures
+* `SECURITY.md` documenting intended usage, safety guarantees, and non-goals
+* Validation layer (`DSL::Validator`) executed **before any HTTP requests**
+
+---
+
+### Changed
+
+* Entry point unified through CLI (`exe/route500check` → `Route500Check.run`)
+* DSL evaluation stabilized using instance-scoped execution
+* Route expansion logic centralized in `RouteParamBuilder`
+* Safety limit violations now raise a dedicated configuration exception
+* Human-readable configuration errors clearly separated from runtime failures
+
+---
+
+### Safety Improvements
+
+* Route expansion is fully deterministic and validated prior to execution
+* No HTTP requests are sent when configuration validation fails
+* Global and per-route limits are enforced consistently
+
+---
+
+### Exit Codes
+
+| Code | Meaning                                                        |
+| ---- | -------------------------------------------------------------- |
+| 0    | No HTTP 500 errors detected                                    |
+| 1    | Configuration or safety limit triggered (no requests executed) |
+| 2    | Runtime error or HTTP 500 detected                             |
+
+---
+
+### Compatibility Notes
+
+* No changes to DSL syntax
+* Existing configurations continue to work as-is
+* Behavior is stricter where misconfiguration previously led to silent over-execution
+
+---
+
+### Notes
+
+This version intentionally avoids feature expansion.
+Future releases will prioritize correctness and maintainability over additional DSL features.
+
+---
+
+© mntkst

data/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2025 mnstkst

data/README.md

@@ -0,0 +1,255 @@
+# Route500Check
+
+Route500Check is a lightweight checker focused on **HTTP 500 errors** in Rails applications.
+It does not depend on Rails internals and checks pages via real HTTP requests, just like end users.
+
+* Focused on HTTP 500 detection
+* Safe for large-scale sites (anti-runaway design)
+* Suitable for CI / cron jobs
+
+Route500Check is designed as a **safety-focused operational tool**, not a crawler or scanner.
+
+---
+
+## Installation
+
+```ruby
+gem "route_500_check"
+```
+
+```bash
+bundle install
+bundle exec rails generate route500_check:install
+```
+
+---
+
+## Basic Usage
+
+### config/route_500_check.rb
+
+```ruby
+base_url "http://localhost:3000"
+default_limit 100
+
+route "/"
+
+route "/foo/:id" do
+  id 1000..9999
+  sample 10
+end
+```
+
+### Run
+
+```bash
+bundle exec route500check
+```
+
+### Production (recommended)
+
+```bash
+ROUTE500CHECK_BASE_URL=https://example.com ONLY=public bundle exec route500check
+```
+
+---
+
+## base_url Priority
+
+```
+ENV["ROUTE500CHECK_BASE_URL"]
+↓
+DSL base_url
+↓
+error
+```
+
+In production environments, it is recommended to use environment variables
+instead of modifying the DSL configuration.
+
+---
+
+## ONLY=public
+
+```bash
+ONLY=public bundle exec route500check
+```
+
+Runs checks only for public-facing pages.
+
+Default excluded prefixes:
+
+```
+/admin
+/api
+/internal
+/rails
+/assets
+/health
+```
+
+Custom prefixes:
+
+```ruby
+only_public do
+  exclude_prefix "/admin"
+  exclude_prefix "/api"
+end
+```
+
+---
+
+## Safety Guards
+
+Route500Check includes multiple safety mechanisms to prevent accidental overload
+or misuse.
+
+### default_limit (global hard limit)
+
+```ruby
+default_limit 100
+```
+
+Absolute upper bound for the total number of expanded routes.
+
+If the expanded route count exceeds this limit, execution stops **before any HTTP
+requests are sent**.
+
+### route limit
+
+```ruby
+limit 20
+```
+
+Effective rule:
+
+```
+min(route_limit, default_limit)
+```
+
+---
+
+## sample
+
+```ruby
+sample 10
+```
+
+* Random selection per route
+* No duplicate URLs within the same route
+* Applied before global limits
+
+---
+
+## ignore_status
+
+```ruby
+ignore_status [502, 503]
+```
+
+Affects exit code determination only.
+Statuses are still logged and written to JSON output.
+
+---
+
+## Output
+
+### STDOUT
+
+Human-readable logs intended for operators.
+
+### JSON (always generated)
+
+File: `route_500_check_result.json`
+Location: current working directory
+
+Includes:
+
+* Summary (status counts, latency)
+* Detailed per-route results
+
+---
+
+## Exit Codes
+
+Route500Check separates exit codes by intent, making it safe for automation.
+
+| Exit code | Meaning                                                        |
+| --------- | -------------------------------------------------------------- |
+| `0`       | No HTTP 500 errors detected                                    |
+| `1`       | Configuration or safety limit triggered (no requests executed) |
+| `2`       | Runtime error or HTTP 500 detected                             |
+
+### Exit code `1` (Configuration / Safety)
+
+Exit code `1` indicates that Route500Check stopped **before sending any HTTP
+requests**, for example:
+
+* Expanded route count exceeds `default_limit`
+* Route sampling or limit configuration prevents safe execution
+
+Example output:
+
+```text
+[route_500_check][CONFIG] Route expansion exceeded safety limit.
+- expanded routes: 122
+- default_limit:   10
+
+This is NOT a runtime error.
+Adjust default_limit or route sample/limit settings.
+```
+
+This exit code does **not** indicate HTTP 500 errors.
+
+---
+
+## Security Considerations
+
+Route500Check is intended for **site owners and operators** to monitor their own
+applications.
+
+### Controlled Request Expansion
+
+To prevent accidental overload or abuse:
+
+* All routes must be explicitly defined
+* Total request count is validated **before execution**
+* Execution stops immediately if safety limits are exceeded
+* No HTTP requests are sent when validation fails
+
+### Not a Scanning Tool
+
+Route500Check intentionally avoids features common in scanning or crawling tools:
+
+* No automatic discovery
+* No recursive crawling
+* No parallel request amplification
+* No authentication or authorization bypass
+
+### Clear Failure Semantics
+
+Configuration and safety stops are clearly distinguished from runtime failures:
+
+* Configuration / safety violations return exit code `1`
+* Runtime errors and HTTP 500 detection return exit code `2`
+
+This separation reduces the risk of misinterpretation in CI, cron jobs, and
+monitoring systems.
+
+### Intended Usage
+
+Route500Check is suitable for:
+
+* Verifying critical user-facing routes
+* Detecting HTTP 500 regressions
+* Safe execution in production cron jobs and CI pipelines
+
+It is **not intended for penetration testing, stress testing, or content
+discovery**.
+
+---
+
+## License
+
+MIT
+© mntkst

data/SECURITY.md

@@ -0,0 +1,119 @@
+# Security Policy
+
+## Purpose
+
+Route500Check is designed as a **safety-focused operational tool** for site owners and operators.
+Its primary purpose is to detect HTTP 500 errors on explicitly defined routes using real HTTP requests,
+while preventing accidental overload or misuse.
+
+This document explains the security-related design principles and intended usage of Route500Check.
+
+---
+
+## Intended Usage
+
+Route500Check is intended for:
+
+* Monitoring critical user-facing routes
+* Detecting HTTP 500 regressions in Rails applications
+* Safe execution in production cron jobs and CI pipelines
+
+It is **not intended** for:
+
+* Penetration testing
+* Stress testing or load testing
+* Crawling or content discovery
+* Scanning systems you do not own or operate
+
+---
+
+## Controlled Request Execution
+
+Route500Check includes multiple safeguards to ensure controlled execution:
+
+* All routes must be explicitly defined by the user
+* No automatic discovery or recursive crawling is performed
+* Route expansion is deterministic and predictable
+* Total request count is validated **before execution**
+
+If safety validation fails, execution stops immediately and **no HTTP requests are sent**.
+
+---
+
+## Safety Limits
+
+### Global Limit (`default_limit`)
+
+The `default_limit` setting defines an absolute upper bound for the total number of HTTP requests
+that can be generated from all routes.
+
+If the expanded route count exceeds this limit:
+
+* Route500Check stops before sending any requests
+* Exit code `1` is returned
+* A clear configuration-related message is displayed
+
+This mechanism prevents accidental overload due to misconfiguration.
+
+### Per-route Limits
+
+Each route may define its own:
+
+* `limit`
+* `sample`
+
+Effective limits are calculated safely, and always respect the global `default_limit`.
+
+---
+
+## Exit Code Semantics
+
+Route500Check separates exit codes by intent to reduce operational risk:
+
+| Exit code | Meaning                                                        |
+| --------- | -------------------------------------------------------------- |
+| `0`       | No HTTP 500 errors detected                                    |
+| `1`       | Configuration or safety limit triggered (no requests executed) |
+| `2`       | Runtime error or HTTP 500 detected                             |
+
+Exit code `1` indicates a **safety stop**, not a runtime failure and not an HTTP 500 detection.
+
+---
+
+## Non-goals and Explicit Limitations
+
+To avoid misuse, Route500Check intentionally does **not** provide:
+
+* Parallel or high-volume request execution
+* Automatic endpoint discovery
+* Authentication or authorization bypass mechanisms
+* Rate limit evasion or throttling circumvention
+
+Any use outside the intended scope may violate laws, regulations, or terms of service.
+
+---
+
+## Responsible Use
+
+Users are responsible for ensuring that Route500Check is executed only against systems they own
+or are authorized to operate.
+
+The authors and maintainers of Route500Check assume no responsibility for misuse of this tool
+outside its intended operational scope.
+
+---
+
+## Reporting Security Issues
+
+If you believe you have found a security vulnerability in Route500Check itself (not in a target
+application), please report it responsibly.
+
+At this time, please open a GitHub issue with a clear description of the problem and steps to
+reproduce it. Sensitive details should be minimized.
+
+---
+
+## Policy Updates
+
+This security policy may be updated as the project evolves. Please review it periodically to
+stay informed about Route500Check's security posture.

data/exe/route500check

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "route_500_check"
+
+# 実行は必ず CLI 経由に集約
+Route500Check.run

data/lib/generators/route_500_check/install_generator.rb

@@ -0,0 +1,11 @@
+module Route500Check
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_config
+        copy_file "route_500_check.rb", "config/route_500_check.rb"
+      end
+    end
+  end
+end

data/lib/generators/route_500_check/templates/route_500_check.rb

@@ -0,0 +1,57 @@
+# Route500Check configuration file
+#
+# This file defines which routes should be checked for HTTP 500 errors.
+# Routes are expanded and validated before execution to ensure safe operation.
+#
+# No HTTP requests are sent if validation fails.
+
+# Base URL for requests.
+# In production, it is recommended to use the environment variable
+# ROUTE500CHECK_BASE_URL instead of hard-coding this value.
+#
+# Example:
+#   ROUTE500CHECK_BASE_URL=https://example.com bundle exec route500check
+#
+base_url "http://localhost:3000"
+
+# Global safety limit.
+# This is an absolute upper bound for the total number of HTTP requests
+# after route expansion.
+#
+default_limit 50
+
+# Run checks only for public-facing pages.
+# Useful when executing against production environments.
+#
+# only_public do
+#   exclude_prefix "/admin"
+#   exclude_prefix "/api"
+# end
+
+# -----------------------
+# Route definitions
+# -----------------------
+
+# Simple static route
+route "/"
+
+# Route with path parameters
+route "/items/:id" do
+  id 1..100
+  sample 10
+end
+
+# Route with explicit limit
+route "/categories/:category_id" do
+  category_id [1, 2, 3, 4, 5]
+  limit 5
+end
+
+# -----------------------
+# Optional settings
+# -----------------------
+
+# Ignore specific HTTP status codes when determining exit code.
+# These statuses are still logged and written to JSON output.
+#
+# ignore_status [502, 503]

data/lib/route_500_check/checker.rb

@@ -0,0 +1,71 @@
+# lib/route_500_check/checker.rb
+
+require "net/http"
+require "uri"
+
+module Route500Check
+  class Checker
+    def initialize(base_url)
+      @base_url = base_url
+    end
+
+    def check(path)
+      uri   = build_uri(path)
+      start = now
+
+      response = Net::HTTP.get_response(uri)
+      finish   = now
+
+      build_success_result(
+        path: path,
+        uri: uri,
+        response: response,
+        start: start,
+        finish: finish
+      )
+    rescue => e
+      finish = now rescue nil
+
+      build_error_result(
+        path: path,
+        uri: uri,
+        error: e,
+        start: start,
+        finish: finish
+      )
+    end
+
+    private
+
+    def build_uri(path)
+      URI.join(@base_url, path)
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def elapsed_ms(start, finish)
+      return nil unless start && finish
+      ((finish - start) * 1000).round(1)
+    end
+
+    def build_success_result(path:, uri:, response:, start:, finish:)
+      {
+        path: path,
+        url: uri.to_s,
+        status: response.code.to_i,
+        elapsed_ms: elapsed_ms(start, finish)
+      }
+    end
+
+    def build_error_result(path:, uri:, error:, start:, finish:)
+      {
+        path: path,
+        url: uri.to_s,
+        error: error.message,
+        elapsed_ms: elapsed_ms(start, finish)
+      }
+    end
+  end
+end

data/lib/route_500_check/cli.rb

@@ -0,0 +1,21 @@
+# lib/route500_check/cli.rb
+
+module Route500Check
+  class CLI
+    EXIT_OK  = 0
+    EXIT_500 = 2
+
+    def run
+      config = DSL.load!
+      DSL::Validator.validate!(config)
+
+      Runner.run
+    rescue Route500Check::Errors::RouteLimitExceeded => e
+      warn "[route_500_check][CONFIG] #{e.message}"
+      exit 1
+    rescue => e
+      warn "[route_500_check][FATAL] #{e.class}: #{e.message}"
+      exit 2
+    end
+  end
+end

data/lib/route_500_check/dsl/route_definition.rb

@@ -0,0 +1,10 @@
+# dsl/route_definition.rb
+Route = Struct.new(:path, :expanded_paths, :limit)
+
+module Route500Check::DSL
+  class RouteDefinition
+    def self.load
+      # DSLを読み、placeholder展開済みの Route を返す
+    end
+  end
+end

data/lib/route_500_check/dsl/validator.rb

@@ -0,0 +1,23 @@
+# lib/route_500_check/dsl/validator.rb
+module Route500Check
+  class DSL::Validator
+    def self.validate!(config)
+      expanded =
+        RouteParamBuilder.expand(
+          config.routes,
+          config.default_limit
+        )
+
+      total = expanded.size
+      limit = config.default_limit
+
+      return unless limit
+      return if total <= limit
+
+      raise Route500Check::Errors::RouteLimitExceeded.new(
+        actual: total,
+        limit: limit
+      )
+    end
+  end
+end

data/lib/route_500_check/dsl.rb

@@ -0,0 +1,95 @@
+# lib/route_500_check/dsl.rb
+require "route_500_check/route_param_builder"
+require "route_500_check/only_public_builder"
+
+module Route500Check
+  RouteDef = Struct.new(:template, :params)
+
+  class DSL
+    CONFIG_PATH = "config/route_500_check.rb"
+
+    class << self
+      attr_accessor :current
+    end
+
+    attr_reader :routes, :ignore_statuses
+
+    def initialize
+      @routes               = []
+      @default_limit        = nil
+      @ignore_statuses      = []
+      @only_public_prefixes = nil
+      @base_url             = nil
+    end
+
+    # ==========
+    # Load config
+    # ==========
+    def self.load!
+      unless File.exist?(CONFIG_PATH)
+        raise <<~MSG
+          [route_500_check] Config file not found: #{CONFIG_PATH}
+
+          Please run:
+              rails generate route500_check:install
+        MSG
+      end
+
+      self.current = new
+
+      begin
+        DSL.current.instance_eval(File.read(CONFIG_PATH))
+      rescue Exception => e
+        raise "[route_500_check] Failed to load config: #{e.message}"
+      end
+
+      current
+    end
+
+    # ==========
+    # Global settings
+    # ==========
+    def base_url(value = nil)
+      value ? (@base_url = value) : @base_url
+    end
+
+    def default_limit(value = nil)
+      value ? (@default_limit = value) : @default_limit
+    end
+
+    def ignore_status(values = nil)
+      if values
+        @ignore_statuses = Array(values).map(&:to_i)
+      else
+        @ignore_statuses
+      end
+    end
+
+    # ==========
+    # ONLY=public DSL
+    # ==========
+    def only_public(&block)
+      builder = ::Route500Check::OnlyPublicBuilder.new
+      builder.instance_eval(&block)
+      @only_public_prefixes = builder.prefixes
+    end
+
+    def only_public_prefixes
+      @only_public_prefixes
+    end
+
+    # ==========
+    # route DSL
+    # ==========
+    def route(path, &block)
+      params = {}
+
+      if block
+        builder = ::Route500Check::RouteParamBuilder.new(params)
+        builder.instance_eval(&block)
+      end
+
+      @routes << RouteDef.new(path, params)
+    end
+  end
+end

data/lib/route_500_check/errors.rb

@@ -0,0 +1,26 @@
+module Route500Check
+  module Errors
+    class RouteLimitExceeded < StandardError
+      attr_reader :actual, :limit
+
+      def initialize(actual:, limit:)
+        @actual = actual
+        @limit  = limit
+        super(build_message)
+      end
+
+      private
+
+      def build_message
+        <<~MSG.strip
+          Route expansion exceeded safety limit.
+          - expanded routes: #{actual}
+          - default_limit:   #{limit}
+
+          This is NOT a runtime error.
+          Adjust default_limit or route sample/limit settings.
+        MSG
+      end
+    end
+  end
+end

data/lib/route_500_check/executor/request_runner.rb

@@ -0,0 +1,12 @@
+# executor/request_runner.rb
+module Route500Check::Executor
+  class RequestRunner
+    def self.run(routes, config)
+      routes.flat_map do |route|
+        route.expanded_paths.map do |path|
+          run_one(path, config)
+        end
+      end
+    end
+  end
+end

data/lib/route_500_check/only_public_builder.rb

@@ -0,0 +1,45 @@
+# lib/route_500_check/only_public_builder.rb
+
+module Route500Check
+  class OnlyPublicBuilder
+    DEFAULT_EXCLUDE_PREFIXES = %w[
+      /admin
+      /api
+      /internal
+      /rails
+      /assets
+      /health
+    ].freeze
+
+    # ======================
+    # DSL 用（既存仕様そのまま）
+    # ======================
+    def initialize
+      @prefixes = []
+    end
+
+    def exclude_prefix(prefix)
+      @prefixes << prefix
+    end
+
+    def prefixes
+      @prefixes
+    end
+
+    # ======================
+    # 実行用（Runner から利用）
+    # ======================
+    def self.filter(paths, prefixes = nil)
+      effective_prefixes =
+        if prefixes && !prefixes.empty?
+          prefixes
+        else
+          DEFAULT_EXCLUDE_PREFIXES
+        end
+
+      paths.reject do |path|
+        effective_prefixes.any? { |prefix| path.start_with?(prefix) }
+      end
+    end
+  end
+end

data/lib/route_500_check/railtie.rb

@@ -0,0 +1,9 @@
+module Route500Check
+  class Railtie < Rails::Railtie
+    railtie_name :route_500_check
+
+    generators do
+      require_relative "../generators/route_500_check/install_generator"
+    end
+  end
+end

data/lib/route_500_check/reporter/json.rb

@@ -0,0 +1,27 @@
+# lib/route_500_check/reporter/json.rb
+
+require "json"
+require "time"
+
+module Route500Check
+  module Reporter
+    class Json
+      DEFAULT_OUTPUT_PATH = "route500check.json"
+
+      def self.write(results:, summary:, output_path: nil)
+        payload = build_payload(results: results, summary: summary)
+        File.write(output_path || DEFAULT_OUTPUT_PATH, JSON.pretty_generate(payload))
+      end
+
+      private
+
+      def self.build_payload(results:, summary:)
+        {
+          generated_at: Time.now.utc.iso8601,
+          summary: summary,
+          results: results
+        }
+      end
+    end
+  end
+end

data/lib/route_500_check/result/result.rb

@@ -0,0 +1,5 @@
+# result/result.rb
+Result = Struct.new(
+  :path, :url, :status, :elapsed_ms, :error,
+  keyword_init: true
+)

data/lib/route_500_check/result/summary.rb

@@ -0,0 +1,10 @@
+# result/summary.rb
+class Summary
+  def initialize(results)
+    @results = results
+  end
+
+  def has_500?
+    @results.any? { |r| r.status.to_i >= 500 }
+  end
+end

data/lib/route_500_check/route_param_builder.rb

@@ -0,0 +1,108 @@
+# lib/route_500_check/route_param_builder.rb
+
+module Route500Check
+  class RouteParamBuilder
+    # ======================
+    # DSL 用
+    # ======================
+    def initialize(params)
+      @params = params
+    end
+
+    def sample(n)
+      @params[:__sample__] = n
+    end
+
+    def limit(n)
+      @params[:__limit__] = n
+    end
+
+    def method_missing(name, *args, &block)
+      @params[name.to_sym] =
+        if args.length <= 1
+          args.first
+        else
+          args
+        end
+    end
+
+    def respond_to_missing?(_name, _include_private = false)
+      true
+    end
+
+    # ======================
+    # 実行用（Runner が呼ぶ）
+    # ======================
+    def self.expand(route_defs, default_limit)
+      route_defs.flat_map do |route|
+        template = route.template
+        params   = route.params || {}
+
+        placeholders =
+          template.scan(/:(\w+)/).flatten.map(&:to_sym)
+
+        # placeholder が無い場合
+        if placeholders.empty?
+          paths = [template]
+        else
+          values_map =
+            placeholders.map do |key|
+              raw = params[key]
+              values =
+                case raw
+                when Range
+                  raw.to_a
+                when Array
+                  raw.flat_map { |v| v.is_a?(Range) ? v.to_a : v }
+                else
+                  [raw]
+                end
+
+              [key, values]
+            end.to_h
+
+          combinations = cartesian_product(values_map)
+
+          # sample
+          if params[:__sample__]
+            combinations = combinations.sample(params[:__sample__])
+          end
+
+          # limit（route → global の順で適用）
+          route_limit  = params[:__limit__]
+          global_limit = default_limit
+
+          effective_limit =
+            if route_limit && global_limit
+              [route_limit, global_limit].min
+            else
+              route_limit || global_limit
+            end
+
+          if effective_limit
+            combinations = combinations.take(effective_limit)
+          end
+
+          paths =
+            combinations.map do |combo|
+              path = template.dup
+              combo.each { |k, v| path.sub!(":#{k}", v.to_s) }
+              path
+            end
+        end
+
+        paths
+      end
+    end
+
+    def self.cartesian_product(values_map)
+      keys   = values_map.keys
+      values = values_map.values
+
+      values
+        .shift
+        .product(*values)
+        .map { |combo| keys.zip(combo).to_h }
+    end
+  end
+end

data/lib/route_500_check/runner.rb

@@ -0,0 +1,130 @@
+# lib/route_500_check/runner.rb
+
+require "route_500_check/route_param_builder"
+require "route_500_check/only_public_builder"
+
+module Route500Check
+  class Runner
+    EXIT_OK  = 0
+    EXIT_500 = 2
+
+    def self.run(_options = {})
+      config = DSL.load!
+
+      runtime_base_url =
+        ENV["ROUTE500CHECK_BASE_URL"] ||
+        config.base_url
+
+      unless runtime_base_url
+        abort "[route_500_check] base_url is required (ENV or DSL)"
+      end
+
+      puts "[route_500_check] base_url=#{runtime_base_url}"
+
+      checker = Checker.new(runtime_base_url)
+
+      # ---- route expansion ----
+      paths =
+        RouteParamBuilder.expand(
+          config.routes,
+          config.default_limit
+        )
+
+      # ---- ONLY=public ----
+      if ENV["ONLY"] == "public"
+        paths =
+          OnlyPublicBuilder.filter(
+            paths,
+            config.only_public_prefixes
+          )
+      end
+
+      # ---- execute ----
+      results = []
+
+      paths.each do |path|
+        result = checker.check(path)
+        results << result
+
+        if result[:error]
+          puts "[route_500_check] ERROR #{result[:url]} #{result[:error]}"
+        else
+          puts "[route_500_check] GET #{result[:url]} -> #{result[:status]} (#{result[:elapsed_ms]}ms)"
+        end
+      end
+
+      # ---- summary ----
+      summary = build_summary(results)
+      print_summary(summary)
+
+      ignored = config.ignore_status || []
+
+      has_500 = results.any? do |r|
+        s = r[:status]
+        s && s >= 500 && !ignored.include?(s)
+      end
+
+      Reporter::Json.write(
+        results: results,
+        summary: summary
+      )
+
+      exit(has_500 ? EXIT_500 : EXIT_OK)
+    end
+
+    # ==========
+    # summary helpers
+    # ==========
+    def self.print_summary(s)
+      puts "[route_500_check] Result summary:"
+      puts "  total_routes: #{s[:total_routes]}"
+      puts "  success:      #{s[:success]}"
+      puts "  errors:       #{s[:errors]}"
+      puts "  http_2xx:     #{s[:http_2xx]}"
+      puts "  http_3xx:     #{s[:http_3xx]}"
+      puts "  http_4xx:     #{s[:http_4xx]}"
+      puts "  http_5xx:     #{s[:http_5xx]}"
+      puts "  max_latency:  #{s[:max_latency_ms] ? "#{s[:max_latency_ms]}ms" : '-'}"
+      puts "  avg_latency:  #{s[:avg_latency_ms] ? "#{s[:avg_latency_ms]}ms" : '-'}"
+    end
+
+    def self.build_summary(results)
+      total = results.size
+
+      error_count = results.count { |r| r[:error] }
+
+      statuses = results.map { |r| r[:status] }.compact
+
+      http_2xx = statuses.count { |s| s >= 200 && s < 300 }
+      http_3xx = statuses.count { |s| s >= 300 && s < 400 }
+      http_4xx = statuses.count { |s| s >= 400 && s < 500 }
+      http_5xx = statuses.count { |s| s >= 500 }
+
+      http_4xx_breakdown =
+        statuses
+          .select { |s| s >= 400 && s < 500 }
+          .tally
+          .transform_keys(&:to_s)
+
+      success = total - error_count - http_5xx
+
+      elapsed = results.map { |r| r[:elapsed_ms] }.compact
+
+      {
+        total_routes: total,
+        success: success,
+        errors: error_count,
+
+        http_2xx: http_2xx,
+        http_3xx: http_3xx,
+        http_4xx: http_4xx,
+        http_5xx: http_5xx,
+
+        http_4xx_breakdown: http_4xx_breakdown,
+
+        max_latency_ms: elapsed.max,
+        avg_latency_ms: elapsed.any? ? (elapsed.sum / elapsed.size.to_f).round(1) : nil
+      }
+    end
+  end
+end

data/lib/route_500_check/version.rb

@@ -0,0 +1,3 @@
+module Route500Check
+  VERSION = '0.1.0'
+end

data/lib/route_500_check.rb

@@ -0,0 +1,31 @@
+# lib/route_500_check.rb
+
+require "route_500_check/version"
+
+# DSL 関連
+require "route_500_check/route_param_builder"
+require "route_500_check/only_public_builder"
+require "route_500_check/dsl"
+require "route_500_check/dsl/validator"
+require "route_500_check/errors"
+
+# 実行系
+require "route_500_check/checker"
+require "route_500_check/reporter/json"
+require "route_500_check/runner"
+require "route_500_check/cli"
+
+module Route500Check
+  def self.define(&block)
+    DSL.current ||= DSL.new
+    DSL.current.instance_eval(&block)
+  end
+
+  def self.run
+    CLI.new.run
+  end
+end
+
+if defined?(Rails)
+  require "route_500_check/railtie"
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: route_500_check
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- mntkst
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: DSL-based HTTP 500 error detector for Rails applications
+email:
+executables:
+- route500check
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- SECURITY.md
+- exe/route500check
+- lib/generators/route_500_check/install_generator.rb
+- lib/generators/route_500_check/templates/route_500_check.rb
+- lib/route_500_check.rb
+- lib/route_500_check/checker.rb
+- lib/route_500_check/cli.rb
+- lib/route_500_check/dsl.rb
+- lib/route_500_check/dsl/route_definition.rb
+- lib/route_500_check/dsl/validator.rb
+- lib/route_500_check/errors.rb
+- lib/route_500_check/executor/request_runner.rb
+- lib/route_500_check/only_public_builder.rb
+- lib/route_500_check/railtie.rb
+- lib/route_500_check/reporter/json.rb
+- lib/route_500_check/result/result.rb
+- lib/route_500_check/result/summary.rb
+- lib/route_500_check/route_param_builder.rb
+- lib/route_500_check/runner.rb
+- lib/route_500_check/version.rb
+homepage: https://github.com/mntkst/route_500_check
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mntkst/route_500_check
+  source_code_uri: https://github.com/mntkst/route_500_check
+  changelog_uri: https://github.com/mntkst/route_500_check/releases
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Detect HTTP 500 errors by scanning selected Rails routes
+test_files: []