rapitapir 0.1.0

data/lib/rapitapir/cli/server.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require 'webrick'
+require 'json'
+
+module RapiTapir
+  module CLI
+    # Development server for testing RapiTapir APIs
+    # Provides a simple HTTP server for development and testing
+    class Server
+      attr_reader :endpoints_file, :port, :config
+
+      def initialize(endpoints_file:, port: 3000, config: {})
+        @endpoints_file = endpoints_file
+        @port = port
+        @config = {
+          title: 'API Documentation',
+          description: 'Live API documentation',
+          auto_reload: true,
+          include_try_it: true
+        }.merge(config)
+      end
+
+      def start
+        server = create_webrick_server
+        setup_request_handlers(server)
+        setup_shutdown_handling(server)
+        server.start
+      end
+
+      private
+
+      def create_webrick_server
+        WEBrick::HTTPServer.new(
+          Port: @port,
+          DocumentRoot: Dir.pwd,
+          Logger: WEBrick::Log.new(File.open(File::NULL, 'w')),
+          AccessLog: []
+        )
+      end
+
+      def setup_request_handlers(server)
+        server.mount_proc '/' do |req, res|
+          handle_request(req, res)
+        end
+      end
+
+      def handle_request(req, res)
+        case req.path
+        when '/'
+          serve_documentation(res)
+        when '/api.json'
+          serve_openapi_json(res)
+        when '/reload'
+          serve_reload_endpoint(res)
+        else
+          res.status = 404
+          res.body = 'Not Found'
+        end
+      end
+
+      def setup_shutdown_handling(server)
+        trap('INT') { server.shutdown }
+        puts "Starting documentation server on port #{@port}..."
+        puts "Documentation server running at http://localhost:#{@port}"
+        puts 'Press Ctrl+C to stop'
+      end
+
+      def serve_documentation(response)
+        endpoints = load_endpoints
+        html_content = generate_documentation_html(endpoints)
+        html_content = add_auto_reload_if_enabled(html_content)
+
+        set_successful_response(response, html_content)
+      rescue StandardError => e
+        set_error_response(response, e)
+      end
+
+      def generate_documentation_html(endpoints)
+        require_relative '../docs/html_generator'
+        generator = RapiTapir::Docs::HtmlGenerator.new(
+          endpoints: endpoints,
+          config: config.merge(include_reload: true)
+        )
+        generator.generate
+      end
+
+      def add_auto_reload_if_enabled(html_content)
+        return html_content unless config[:auto_reload]
+
+        html_content.gsub('</body>', "#{auto_reload_script}</body>")
+      end
+
+      def set_successful_response(response, html_content)
+        response['Content-Type'] = 'text/html'
+        response.body = html_content
+      end
+
+      def set_error_response(response, error)
+        response.status = 500
+        response['Content-Type'] = 'text/html'
+        response.body = error_page(error)
+      end
+
+      def serve_openapi_json(response)
+        endpoints = load_endpoints
+
+        require_relative '../openapi/schema_generator'
+        generator = RapiTapir::OpenAPI::SchemaGenerator.new(endpoints: endpoints)
+
+        response['Content-Type'] = 'application/json'
+        response.body = generator.to_json
+      rescue StandardError => e
+        response.status = 500
+        response['Content-Type'] = 'application/json'
+        response.body = JSON.generate({ error: e.message })
+      end
+
+      def serve_reload_endpoint(response)
+        # This endpoint is called by the auto-reload script
+        # Return current file modification time
+        mtime = File.exist?(input_file) ? File.mtime(input_file).to_i : 0
+
+        response['Content-Type'] = 'application/json'
+        response.body = JSON.generate({ mtime: mtime })
+      end
+
+      def load_endpoints
+        raise "Error loading endpoints: File '#{@endpoints_file}' not found" unless File.exist?(@endpoints_file)
+
+        # Create a new binding to evaluate the endpoints file
+        evaluation_context = Object.new
+        evaluation_context.extend(RapiTapir::DSL)
+
+        begin
+          code = File.read(@endpoints_file)
+          evaluation_context.instance_eval(code, @endpoints_file)
+
+          # Return the registered endpoints
+          RapiTapir.endpoints
+        rescue StandardError => e
+          raise "Error loading endpoints from '#{@endpoints_file}': #{e.message}"
+        end
+      end
+
+      def auto_reload_script
+        <<~JAVASCRIPT
+          <script>
+            let lastMtime = 0;
+          #{'  '}
+            async function checkForUpdates() {
+              try {
+                const response = await fetch('/reload');
+                const data = await response.json();
+          #{'      '}
+                if (lastMtime === 0) {
+                  lastMtime = data.mtime;
+                } else if (data.mtime > lastMtime) {
+                  console.log('File changed, reloading...');
+                  window.location.reload();
+                }
+              } catch (error) {
+                console.log('Auto-reload check failed:', error);
+              }
+            }
+          #{'  '}
+            // Check for updates every 2 seconds
+            setInterval(checkForUpdates, 2000);
+            checkForUpdates(); // Initial check
+          </script>
+        JAVASCRIPT
+      end
+
+      def error_page(error)
+        <<~HTML
+          <!DOCTYPE html>
+          <html>
+          <head>
+            <title>Error - API Documentation</title>
+            <style>
+              body {#{' '}
+                font-family: Arial, sans-serif;#{' '}
+                margin: 40px;#{' '}
+                background-color: #f8f9fa;
+              }
+              .error {
+                background: #fff;
+                border: 1px solid #dc3545;
+                border-radius: 8px;
+                padding: 20px;
+                box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+              }
+              .error h1 {
+                color: #dc3545;
+                margin-top: 0;
+              }
+              .error pre {
+                background: #f8f9fa;
+                padding: 15px;
+                border-radius: 4px;
+                overflow-x: auto;
+                border: 1px solid #dee2e6;
+              }
+              .retry-button {
+                background: #007bff;
+                color: white;
+                border: none;
+                padding: 10px 20px;
+                border-radius: 4px;
+                cursor: pointer;
+                margin-top: 15px;
+              }
+              .retry-button:hover {
+                background: #0056b3;
+              }
+            </style>
+          </head>
+          <body>
+            <div class="error">
+              <h1>Error Loading Documentation</h1>
+              <p>There was an error processing your endpoint definitions:</p>
+              <pre>#{error.message}</pre>
+              <p>Please check your input file and try again.</p>
+              <button class="retry-button" onclick="window.location.reload()">Retry</button>
+            </div>
+          </body>
+          </html>
+        HTML
+      end
+
+      def mime_type(extension)
+        case extension
+        when '.html' then 'text/html'
+        when '.css' then 'text/css'
+        when '.js' then 'application/javascript'
+        when '.json' then 'application/json'
+        when '.xml' then 'application/xml'
+        else 'text/plain'
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/cli/validator.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module CLI
+    # Validator for RapiTapir endpoint definitions
+    # Validates endpoint configurations for correctness and completeness
+    class Validator
+      attr_reader :errors, :endpoints
+
+      def initialize(endpoints = [])
+        @endpoints = endpoints
+        @errors = []
+      end
+
+      def valid?
+        @errors.clear
+
+        return false if @endpoints.nil? || @endpoints.empty?
+
+        @endpoints.each_with_index do |endpoint, index|
+          validate_endpoint(endpoint, index)
+        end
+
+        @errors.empty?
+      end
+      alias validate valid?
+
+      private
+
+      def validate_endpoint(endpoint, index)
+        context = "Endpoint #{index + 1}"
+
+        return unless valid_endpoint_structure?(endpoint, context)
+
+        validate_endpoint_basics(endpoint, context)
+        validate_endpoint_content(endpoint, context)
+        validate_endpoint_consistency(endpoint, context)
+      end
+
+      def valid_endpoint_structure?(endpoint, context)
+        unless endpoint.respond_to?(:method) && endpoint.respond_to?(:path)
+          @errors << "#{context}: Missing method or path"
+          return false
+        end
+        true
+      end
+
+      def validate_endpoint_basics(endpoint, context)
+        validate_http_method(endpoint, context)
+        validate_summary(endpoint, context)
+        validate_output_definition(endpoint, context)
+        validate_parameters(endpoint) if endpoint.respond_to?(:input_specs) && endpoint.input_specs
+        validate_path(endpoint.path, context)
+      end
+
+      def validate_endpoint_content(endpoint, context)
+        validate_endpoint_inputs(endpoint, context)
+        validate_endpoint_outputs(endpoint, context)
+      end
+
+      def validate_endpoint_consistency(endpoint, context)
+        validate_path_parameters_consistency(endpoint, context)
+        validate_metadata(endpoint, context)
+      end
+
+      def validate_http_method(endpoint, context)
+        valid_methods = %w[GET POST PUT PATCH DELETE HEAD OPTIONS]
+        return if valid_methods.include?(endpoint.method.to_s.upcase)
+
+        @errors << "#{context}: Invalid HTTP method '#{endpoint.method}'"
+      end
+
+      def validate_summary(endpoint, context)
+        return unless !endpoint.metadata || !endpoint.metadata[:summary] || endpoint.metadata[:summary].empty?
+
+        @errors << "#{context}: missing summary"
+      end
+
+      def validate_output_definition(endpoint, context)
+        return unless !endpoint.respond_to?(:outputs) || endpoint.outputs.nil? || endpoint.outputs.empty?
+
+        @errors << "#{context}: missing output definition"
+      end
+
+      def validate_endpoint_inputs(endpoint, context)
+        return unless endpoint.respond_to?(:inputs)
+
+        endpoint.inputs.each_with_index do |input, input_index|
+          validate_input(input, "#{context}, Input #{input_index + 1}")
+        end
+      end
+
+      def validate_endpoint_outputs(endpoint, context)
+        return unless endpoint.respond_to?(:outputs)
+
+        endpoint.outputs.each_with_index do |output, output_index|
+          validate_output(output, "#{context}, Output #{output_index + 1}")
+        end
+      end
+
+      def validate_path(path, context)
+        unless path.is_a?(String) && !path.empty?
+          @errors << "#{context}: Path must be a non-empty string"
+          return
+        end
+
+        @errors << "#{context}: Path must start with '/'" unless path.start_with?('/')
+
+        # Check for invalid characters
+        @errors << "#{context}: Path contains invalid characters" if path.match?(%r{[^a-zA-Z0-9/_:-]})
+
+        # Check path parameter format
+        path.scan(/:(\w+)/).each do |param_match|
+          param_name = param_match[0]
+          unless param_name.match?(/^[a-zA-Z][a-zA-Z0-9_]*$/)
+            @errors << "#{context}: Invalid path parameter name '#{param_name}'"
+          end
+        end
+      end
+
+      def validate_input(input, context)
+        unless input.respond_to?(:kind) && input.respond_to?(:name) && input.respond_to?(:type)
+          @errors << "#{context}: Input missing required methods (kind, name, type)"
+          return
+        end
+
+        validate_input_kind(input, context)
+        validate_input_name(input, context)
+        validate_input_type(input, context)
+        validate_input_options_if_present(input, context)
+      end
+
+      def validate_input_kind(input, context)
+        valid_kinds = %i[query path header body]
+        return if valid_kinds.include?(input.kind)
+
+        @errors << "#{context}: Invalid input kind '#{input.kind}'"
+      end
+
+      def validate_input_name(input, context)
+        return if input.name.is_a?(Symbol) || input.name.is_a?(String)
+
+        @errors << "#{context}: Input name must be a symbol or string"
+      end
+
+      def validate_input_type(input, context)
+        validate_type(input.type, "#{context} type")
+      end
+
+      def validate_input_options_if_present(input, context)
+        return unless input.respond_to?(:options) && input.options
+
+        validate_input_options(input.options, context)
+      end
+
+      def validate_output(output, context)
+        unless output.respond_to?(:kind) && output.respond_to?(:type)
+          @errors << "#{context}: Output missing required methods (kind, type)"
+          return
+        end
+
+        validate_output_kind(output, context)
+        validate_output_type_for_kind(output, context)
+      end
+
+      def validate_output_kind(output, context)
+        valid_kinds = %i[json xml status header]
+        return if valid_kinds.include?(output.kind)
+
+        @errors << "#{context}: Invalid output kind '#{output.kind}'"
+      end
+
+      def validate_output_type_for_kind(output, context)
+        case output.kind
+        when :status
+          validate_status_code_type(output.type, context)
+        when :json, :xml
+          validate_type(output.type, "#{context} schema")
+        end
+      end
+
+      def validate_status_code_type(status_code, context)
+        return if status_code.is_a?(Integer) && status_code >= 100 && status_code <= 599
+
+        @errors << "#{context}: Status code must be an integer between 100-599"
+      end
+
+      def validate_type(type, context)
+        case type
+        when Symbol
+          validate_symbol_type(type, context)
+        when Hash
+          validate_hash_schema(type, context)
+        when Array
+          validate_array_type(type, context)
+        when Class, RapiTapir::Types::Base
+          # Allow custom classes and enhanced types - these are valid
+        else
+          @errors << "#{context}: Invalid type '#{type}'"
+        end
+      end
+
+      def validate_symbol_type(type, context)
+        valid_simple_types = %i[string integer float boolean date datetime]
+        return if valid_simple_types.include?(type)
+
+        @errors << "#{context}: Unknown type '#{type}'"
+      end
+
+      def validate_array_type(type, context)
+        if type.empty?
+          @errors << "#{context}: Array type cannot be empty"
+        else
+          type.each_with_index do |element_type, index|
+            validate_type(element_type, "#{context}[#{index}]")
+          end
+        end
+      end
+
+      def validate_hash_schema(schema, context)
+        schema.each do |key, value|
+          unless key.is_a?(Symbol) || key.is_a?(String)
+            @errors << "#{context}: Hash key '#{key}' must be a symbol or string"
+          end
+
+          validate_type(value, "#{context}.#{key}")
+        end
+      end
+
+      def validate_input_options(options, context)
+        unless options.is_a?(Hash)
+          @errors << "#{context}: Options must be a hash"
+          return
+        end
+
+        # Check for conflicting options
+        @errors << "#{context}: Cannot be both required and optional" if options[:required] && options[:optional]
+
+        # Validate description if present
+        return unless options[:description] && !options[:description].is_a?(String)
+
+        @errors << "#{context}: Description must be a string"
+      end
+
+      def validate_path_parameters_consistency(endpoint, context)
+        path_param_names = extract_path_parameter_names(endpoint)
+        input_path_params = extract_input_path_parameters(endpoint)
+
+        validate_missing_path_inputs(path_param_names, input_path_params, context)
+        validate_extra_path_inputs(path_param_names, input_path_params, context)
+      end
+
+      def extract_path_parameter_names(endpoint)
+        endpoint.path.scan(/:(\w+)/).flatten.map(&:to_sym)
+      end
+
+      def extract_input_path_parameters(endpoint)
+        return [] unless endpoint.respond_to?(:inputs)
+
+        endpoint.inputs
+                .select { |input| input.kind == :path }
+                .map(&:name)
+                .map(&:to_sym)
+      end
+
+      def validate_missing_path_inputs(path_param_names, input_path_params, context)
+        missing_inputs = path_param_names - input_path_params
+        return if missing_inputs.empty?
+
+        @errors << "#{context}: Missing input definitions for path parameters: #{missing_inputs.join(', ')}"
+      end
+
+      def validate_extra_path_inputs(path_param_names, input_path_params, context)
+        extra_inputs = input_path_params - path_param_names
+        return if extra_inputs.empty?
+
+        @errors << "#{context}: Extra path input definitions (not in path): #{extra_inputs.join(', ')}"
+      end
+
+      def validate_metadata(endpoint, context)
+        return unless endpoint.respond_to?(:metadata)
+
+        metadata = endpoint.metadata
+        return unless metadata.is_a?(Hash)
+
+        validate_metadata_summary(metadata, context)
+        validate_metadata_description(metadata, context)
+        validate_metadata_tags(metadata, context)
+        validate_metadata_deprecated_flag(metadata, context)
+      end
+
+      def validate_metadata_summary(metadata, context)
+        return unless metadata[:summary] && !metadata[:summary].is_a?(String)
+
+        @errors << "#{context}: Summary must be a string"
+      end
+
+      def validate_metadata_description(metadata, context)
+        return unless metadata[:description] && !metadata[:description].is_a?(String)
+
+        @errors << "#{context}: Description must be a string"
+      end
+
+      def validate_metadata_tags(metadata, context)
+        return unless metadata[:tags]
+        return if metadata[:tags].is_a?(Array) && metadata[:tags].all? { |tag| tag.is_a?(String) }
+
+        @errors << "#{context}: Tags must be an array of strings"
+      end
+
+      def validate_metadata_deprecated_flag(metadata, context)
+        return unless metadata[:deprecated] && ![true, false].include?(metadata[:deprecated])
+
+        @errors << "#{context}: Deprecated must be a boolean"
+      end
+
+      def validate_parameters(endpoint)
+        return unless endpoint.input_specs
+
+        validate_body_parameter_count(endpoint)
+        validate_parameter_types(endpoint)
+      end
+
+      def validate_body_parameter_count(endpoint)
+        body_params = endpoint.input_specs.select { |spec| spec.type == :body }
+        return unless body_params.length > 1
+
+        @errors << "#{endpoint.path}: multiple body parameters not allowed"
+      end
+
+      def validate_parameter_types(endpoint)
+        endpoint.input_specs.each do |input_spec|
+          next unless input_spec.respond_to?(:param_type)
+          next if valid_param_type?(input_spec.param_type)
+
+          @errors << "#{endpoint.path}: invalid parameter type '#{input_spec.param_type}'"
+        end
+      end
+
+      def valid_param_type?(type)
+        valid_types = [:string, :integer, :float, :boolean, :date, :datetime, Hash, Array]
+        valid_types.include?(type)
+      end
+
+      def validate_basic_properties(endpoint)
+        validate_summary_property(endpoint)
+        validate_output_property(endpoint)
+      end
+
+      def validate_summary_property(endpoint)
+        return if endpoint.metadata&.dig(:summary) && !endpoint.metadata[:summary].empty?
+
+        @errors << "#{endpoint.path}: missing summary"
+      end
+
+      def validate_output_property(endpoint)
+        return if valid_outputs?(endpoint)
+
+        @errors << "#{endpoint.path}: missing output definition"
+      end
+
+      def valid_outputs?(endpoint)
+        endpoint.respond_to?(:outputs) && endpoint.outputs&.any?
+      end
+
+      def valid_output_definition?(endpoint)
+        return true if endpoint.respond_to?(:outputs) && endpoint.outputs && !endpoint.outputs.empty?
+
+        false
+      end
+    end
+  end
+end