haveapi 0.29.5 → 0.29.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91faacf7a526f1d4a85e3ac834af09b31870084892a4fe423c89f788b785831f
-  data.tar.gz: 81ece8ab753c147e13401933bd8086e11c6a20f8e1991cb86ac80df6afbfccac
+  metadata.gz: f3555b00c36ae85444baaa5d2da5e69e70343a8d9528e6fee181ed947bf762d6
+  data.tar.gz: 19613608cf068c2ec9ed2ecb8eda34fbdfab5da9515708a9786f8648059bfd48
 SHA512:
-  metadata.gz: 4d2c6c8cc96b841f645193d248023ea939f36a55af8e7dc2ed710ed770a15de89c34897cd9f3db969c4e1867b4e70ebcbcdf0c15f702d8acf917cee3cbc543a2
-  data.tar.gz: c7ff9c297474a183ba391e8567088494c0b98456f1cbb37b6a36599a955a4b6aca30ec2d5f631fc8d9fdc2c18319059eb5fda188fe75d2574d3875a52dda4544
+  metadata.gz: 8658ea7fb6d61350395fa2a3e9a7ac11467d732c27e4b460cb3105e53bbd2f3784f2426bcdc4760c672cce876af1ef111aaba61fa9a2b79be9bbda90fc7954a8
+  data.tar.gz: c03998dc485dca010fc82ab5156e463c3c673b2365e8caed997d08393203907addbb86ae8a01faf280be5b0453cd323c165ed6b6bf428a009a4412114a593b6d

data/haveapi.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
   s.required_ruby_version = ">= #{File.read('../../.ruby-version').strip}"
 
   s.add_dependency 'activesupport', '>= 7.1'
-  s.add_dependency 'haveapi-client', '~> 0.29.5'
+  s.add_dependency 'haveapi-client', '~> 0.29.7'
   s.add_dependency 'i18n', '>= 1.6', '< 2'
   s.add_dependency 'json'
   s.add_dependency 'mail'

data/lib/haveapi/action.rb

@@ -132,7 +132,7 @@ module HaveAPI
         @initialized = true
       end
 
-      def validate_build
+      def validate_build(path: nil)
         check_build("#{self}.input") do
           input.validate_build
         end
@@ -140,6 +140,10 @@ module HaveAPI
         check_build("#{self}.output") do
           output.validate_build
         end
+
+        check_build("#{self}.examples") do
+          @examples&.validate_build(self, path:)
+        end
       end
 
       def model_adapter(layout)

data/lib/haveapi/client_examples/http.rb

@@ -95,7 +95,7 @@ module HaveAPI::ClientExamples
     end
 
     def resolve_path(method, path, path_params, input_params)
-      ret = path.clone
+      ret = path.dup
 
       path_params.each do |v|
         ret.sub!(/\{[a-zA-Z\-_]+\}/, v.to_s)

data/lib/haveapi/client_examples/js_client.rb

@@ -101,18 +101,20 @@ module HaveAPI::ClientExamples
 
       case action[:output][:layout]
       when :hash
-        out << "# reply is an instance of HaveAPI.Client.Response\n"
-        out << "# reply.response() returns an object with output parameters:\n"
+        out << "  // reply is an instance of HaveAPI.Client.Response\n"
+        out << "  // reply.response() returns an object with output parameters:\n"
         out << JSON.pretty_generate(sample[:response] || {}).split("\n").map do |v|
           "  // #{v}"
         end.join("\n")
+        out << "\n"
 
       when :hash_list
-        out << "# reply is an instance of HaveAPI.Client.Response\n"
-        out << "# reply.response() returns an array of objects:\n"
+        out << "  // reply is an instance of HaveAPI.Client.Response\n"
+        out << "  // reply.response() returns an array of objects:\n"
         out << JSON.pretty_generate(sample[:response] || []).split("\n").map do |v|
           "  // #{v}"
         end.join("\n")
+        out << "\n"
 
       when :object
         out << "  // reply is an instance of HaveAPI.Client.ResourceInstance\n"

data/lib/haveapi/example.rb

@@ -1,5 +1,9 @@
+require 'date'
+
 module HaveAPI
   class Example
+    JSON_SCALARS = [String, Numeric, TrueClass, FalseClass, NilClass].freeze
+
     def initialize(title)
       @title = title
     end
@@ -74,8 +78,179 @@ module HaveAPI
       end
     end
 
+    def validate_build(action, path:, index:)
+      return unless provided?
+      return unless structured_data_provided?
+
+      @validation_context = "#{action} example #{example_name(index)}"
+
+      validate_path_params(action, path) if path
+      validate_payload('request', @request, action.input, require_required: true) unless @request.nil?
+      validate_payload('response', @response, action.output, require_required: false) unless @response.nil?
+      validate_errors(action.input) unless @errors.nil?
+    ensure
+      @validation_context = nil
+    end
+
     protected
 
+    def structured_data_provided?
+      %i[
+        @path_params @request @response @status @message @errors @http_status
+      ].any? { |name| !instance_variable_get(name).nil? }
+    end
+
+    def example_name(index)
+      @title.to_s.empty? ? "##{index + 1}" : @title.inspect
+    end
+
+    def validate_path_params(action, path)
+      expected = action.path_param_names(path).length
+      actual = @path_params.nil? ? 0 : @path_params.length
+      return if actual == expected
+
+      invalid!("path_params has #{actual} values, but route #{path.inspect} requires #{expected}")
+    end
+
+    def validate_payload(name, value, params, require_required:)
+      unless params
+        invalid!("#{name} is provided, but the action has no #{name == 'request' ? 'input' : 'output'} parameters")
+      end
+
+      objects =
+        case params.layout
+        when :object, :hash
+          invalid!("#{name} must be an object") unless value.is_a?(Hash)
+          [value]
+        when :object_list, :hash_list
+          unless value.is_a?(Array) && value.all?(Hash)
+            invalid!("#{name} must be a list of objects")
+          end
+          value
+        else
+          invalid!("#{name} uses unsupported layout #{params.layout.inspect}")
+        end
+
+      objects.each_with_index do |object, index|
+        location = objects.length > 1 ? "#{name}[#{index}]" : name
+        validate_object(location, object, params, require_required:)
+      end
+    end
+
+    def validate_object(location, object, params, require_required:)
+      normalized = normalize_keys(location, object)
+      known = params.params.to_h { |param| [param.name.to_sym, param] }
+      unknown = normalized.keys - known.keys
+      invalid!("#{location} contains unknown parameters: #{unknown.join(', ')}") unless unknown.empty?
+
+      if require_required
+        missing = known.values.filter_map do |param|
+          param.name unless !param.required? || normalized.has_key?(param.name.to_sym)
+        end
+        invalid!("#{location} is missing required parameters: #{missing.join(', ')}") unless missing.empty?
+      end
+
+      normalized.each do |param_name, param_value|
+        validate_value("#{location}.#{param_name}", param_value, known.fetch(param_name))
+      end
+    end
+
+    def normalize_keys(location, object)
+      object.each_with_object({}) do |(key, value), ret|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          invalid!("#{location} parameter name #{key.inspect} is not a string or symbol")
+        end
+
+        normalized = key.to_sym
+        invalid!("#{location} repeats parameter #{normalized}") if ret.has_key?(normalized)
+
+        ret[normalized] = value
+      end
+    end
+
+    def validate_value(location, value, param)
+      if value.nil?
+        invalid!("#{location} cannot be null") unless param.nullable?
+        return
+      end
+
+      if param.is_a?(HaveAPI::Parameters::Resource)
+        validate_resource_value(location, value, param)
+        return
+      end
+
+      valid =
+        case param.type.to_s
+        when 'Integer'
+          value.is_a?(Integer)
+        when 'Float'
+          value.is_a?(Numeric) && value.finite?
+        when 'Boolean'
+          [true, false].include?(value)
+        when 'Datetime'
+          valid_datetime?(value)
+        when 'String', 'Text'
+          value.is_a?(String)
+        else
+          json_value?(value)
+        end
+
+      invalid!("#{location} has invalid #{param.type} value #{value.inspect}") unless valid
+    end
+
+    def validate_resource_value(location, value, param)
+      return if value.is_a?(Integer) || value.is_a?(String)
+
+      unless value.is_a?(Hash)
+        invalid!("#{location} must be a resource ID or object")
+      end
+
+      normalized = normalize_keys(location, value)
+      id_name = param.value_id.to_sym
+      invalid!("#{location} resource object is missing #{id_name}") unless normalized.has_key?(id_name)
+      invalid!("#{location}.#{id_name} must be an integer or string") unless [
+        Integer,
+        String
+      ].any? { |klass| normalized.fetch(id_name).is_a?(klass) }
+      invalid!("#{location} is not JSON-compatible") unless json_value?(value)
+    end
+
+    def valid_datetime?(value)
+      return true if value.is_a?(Time) || value.is_a?(DateTime)
+      return false unless value.is_a?(String)
+
+      DateTime.iso8601(value)
+      true
+    rescue ArgumentError
+      false
+    end
+
+    def json_value?(value)
+      return value.finite? if value.is_a?(Float)
+      return true if JSON_SCALARS.any? { |klass| value.is_a?(klass) }
+      return value.all? { |item| json_value?(item) } if value.is_a?(Array)
+
+      if value.is_a?(Hash)
+        return value.all? do |key, item|
+          (key.is_a?(String) || key.is_a?(Symbol)) && json_value?(item)
+        end
+      end
+
+      false
+    end
+
+    def validate_errors(input)
+      invalid!('errors must be an object') unless @errors.is_a?(Hash)
+
+      known = input ? input.params.map { |param| param.name.to_sym } : []
+      unknown = @errors.keys.map(&:to_sym) - known
+      invalid!("errors refer to unknown input parameters: #{unknown.join(', ')}") unless unknown.empty?
+    end
+
+    def invalid!(message)
+      raise "#{@validation_context}: #{message}"
+    end
+
     def filter_input_params(context, input)
       return nil if input.nil?
 

data/lib/haveapi/example_list.rb

@@ -19,6 +19,12 @@ module HaveAPI
       ret
     end
 
+    def validate_build(action, path:)
+      @examples.each_with_index do |example, index|
+        example.validate_build(action, path:, index:)
+      end
+    end
+
     def each(&)
       @examples.each(&)
     end

data/lib/haveapi/server.rb

@@ -640,7 +640,9 @@ module HaveAPI
 
     def validate_resources(resources)
       resources.each_value do |r|
-        r[:actions].each_key(&:validate_build)
+        r[:actions].each do |action, path|
+          action.validate_build(path:)
+        end
 
         validate_resources(r[:resources])
       end

data/lib/haveapi/version.rb

@@ -1,4 +1,4 @@
 module HaveAPI
   PROTOCOL_VERSION = '2.0'.freeze
-  VERSION = '0.29.5'.freeze
+  VERSION = '0.29.7'.freeze
 end

data/spec/client_examples/syntax_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+require 'open3'
+require 'tempfile'
+require 'haveapi/client_examples/curl'
+require 'haveapi/client_examples/http'
+require 'haveapi/client_examples/js_client'
+require 'haveapi/client_examples/php_client'
+require 'haveapi/client_examples/ruby_client'
+
+describe HaveAPI::ClientExamples do
+  let(:action) do
+    {
+      method: 'POST',
+      path: '/v1/widgets/{widget_id}/update',
+      input: {
+        layout: :hash,
+        namespace: :widget,
+        parameters: {
+          name: { type: 'String' },
+          enabled: { type: 'Boolean' }
+        }
+      },
+      output: {
+        layout: :hash,
+        namespace: :widget,
+        parameters: {
+          id: { type: 'Integer' },
+          name: { type: 'String' }
+        }
+      }
+    }
+  end
+  let(:sample) do
+    {
+      path_params: [101],
+      request: { name: 'documented widget', enabled: true },
+      response: { id: 101, name: 'documented widget' },
+      status: true,
+      message: nil,
+      errors: nil,
+      http_status: 200
+    }
+  end
+  let(:client_args) do
+    [
+      'api.example.test',
+      'https://api.example.test',
+      1,
+      %w[widget],
+      {},
+      'update',
+      action
+    ]
+  end
+
+  def syntax_check(command, source, suffix)
+    Tempfile.create(['haveapi-example-', suffix]) do |file|
+      file.write(source)
+      file.flush
+      output, status = Open3.capture2e(*command, file.path)
+      [status, output]
+    end
+  end
+
+  it 'generates valid JavaScript' do
+    source = HaveAPI::ClientExamples::JsClient.new(*client_args).example(sample)
+    status, output = syntax_check(%w[node --check], source, '.mjs')
+
+    expect(status).to be_success, output
+  end
+
+  it 'generates valid PHP' do
+    source = HaveAPI::ClientExamples::PhpClient.new(*client_args).example(sample)
+    status, output = syntax_check(%w[php -l], "<?php\n#{source}", '.php')
+
+    expect(status).to be_success, output
+  end
+
+  it 'generates valid Ruby' do
+    source = HaveAPI::ClientExamples::RubyClient.new(*client_args).example(sample)
+    status, output = syntax_check(%w[ruby -c], source, '.rb')
+
+    expect(status).to be_success, output
+  end
+
+  it 'generates shell-parseable curl requests' do
+    source = HaveAPI::ClientExamples::Curl.new(*client_args).request(sample)
+    status, output = syntax_check(%w[bash -n], source, '.sh')
+
+    expect(status).to be_success, output
+  end
+
+  it 'generates structurally valid HTTP requests and responses' do
+    generator = HaveAPI::ClientExamples::Http.new(*client_args)
+    request_headers, request_body = generator.request(sample).split("\n\n", 2)
+    request_lines = request_headers.lines(chomp: true)
+
+    expect(request_lines.shift).to eq('POST /v1/widgets/101/update HTTP/1.1')
+    expect(request_lines).to include('Host: api.example.test', 'Content-Type: application/json')
+    expect(JSON.parse(request_body)).to eq(
+      'widget' => {
+        'name' => 'documented widget',
+        'enabled' => true
+      }
+    )
+
+    response_headers, response_body = generator.response(sample).split("\n\n", 2)
+    response_lines = response_headers.lines(chomp: true)
+    expect(response_lines.shift).to eq('HTTP/1.1 200 OK')
+    content_length = response_lines
+                     .find { |line| line.start_with?('Content-Length: ') }
+                     .split(': ', 2)
+                     .last
+                     .to_i
+    expect(content_length).to eq(response_body.bytesize)
+    expect(JSON.parse(response_body)).to include('status' => true)
+  end
+end

data/spec/documentation/examples_spec.rb

@@ -56,6 +56,43 @@ describe HaveAPI::Example do
           { name: 'alpha' }
         end
       end
+
+      define_action(:ValidatedExample) do
+        route 'validated/{widget_id}'
+        http_method :post
+        authorize { allow }
+
+        input(:hash) do
+          string :name, required: true
+          integer :count
+          bool :active
+          datetime :created_at
+          custom :metadata
+        end
+
+        output(:hash) do
+          integer :count
+          bool :accepted
+        end
+
+        # rubocop:disable RSpec/NoExpectationExample
+        example 'valid structured data' do
+          path_params 101
+          request({
+                    name: 'alpha',
+                    count: 2,
+                    active: true,
+                    created_at: '2026-07-26T10:30:00Z',
+                    metadata: { source: 'documentation' }
+                  })
+          response({ count: 2 })
+        end
+        # rubocop:enable RSpec/NoExpectationExample
+
+        def exec
+          { count: input[:count], accepted: true }
+        end
+      end
     end
   end
 
@@ -94,4 +131,129 @@ describe HaveAPI::Example do
     expect(api_response[:examples].first[:request]).to be_nil
     expect(api_response[:examples].first[:response]).to be_nil
   end
+
+  describe 'build validation' do
+    def example_for(action, path:, title: 'invalid example', &)
+      example = HaveAPI::Example.new(title)
+      example.instance_eval(&)
+      example.validate_build(action, path:, index: 0)
+    end
+
+    def validated_example_action
+      self.class.const_get(:ApiModule)::Widget::ValidatedExample
+    end
+
+    it 'accepts valid structured and prose-only examples' do
+      expect do
+        example_for(
+          validated_example_action,
+          path: '/v1/widgets/validated/{widget_id}',
+          title: 'valid'
+        ) do
+          path_params 101
+          request(name: 'alpha', count: 2, active: false)
+          response(count: 2)
+        end
+      end.not_to raise_error
+
+      expect do
+        example_for(validated_example_action, path: '/v1/widgets/validated/{widget_id}') do
+          comment 'The prose describes a request that is not represented as structured data.'
+        end
+      end.not_to raise_error
+    end
+
+    it 'rejects path parameter count and request layout errors' do
+      expect do
+        example_for(validated_example_action, path: '/v1/widgets/validated/{widget_id}') do
+          request([{ name: 'alpha' }])
+        end
+      end.to raise_error(/path_params has 0 values.*requires 1/)
+
+      expect do
+        example_for(validated_example_action, path: '/v1/widgets/validated') do
+          request([{ name: 'alpha' }])
+        end
+      end.to raise_error(/request must be an object/)
+    end
+
+    it 'rejects unknown, missing, and incorrectly typed request parameters' do
+      expect do
+        example_for(validated_example_action, path: '/v1/widgets/validated/{widget_id}') do
+          path_params 101
+          request(name: 'alpha', mystery: true)
+        end
+      end.to raise_error(/unknown parameters: mystery/)
+
+      expect do
+        example_for(validated_example_action, path: '/v1/widgets/validated/{widget_id}') do
+          path_params 101
+          request(count: 2)
+        end
+      end.to raise_error(/missing required parameters: name/)
+
+      expect do
+        example_for(validated_example_action, path: '/v1/widgets/validated/{widget_id}') do
+          path_params 101
+          request(name: 'alpha', count: 'two')
+        end
+      end.to raise_error(/request.count has invalid Integer value/)
+    end
+
+    it 'allows abbreviated responses but validates present fields and error keys' do
+      expect do
+        example_for(validated_example_action, path: '/v1/widgets/validated/{widget_id}') do
+          path_params 101
+          request(name: 'alpha')
+          response(count: 1)
+        end
+      end.not_to raise_error
+
+      expect do
+        example_for(validated_example_action, path: '/v1/widgets/validated/{widget_id}') do
+          path_params 101
+          request(name: 'alpha')
+          response(accepted: 'yes')
+        end
+      end.to raise_error(/response.accepted has invalid Boolean value/)
+
+      expect do
+        example_for(validated_example_action, path: '/v1/widgets/validated/{widget_id}') do
+          path_params 101
+          request(name: 'alpha')
+          status false
+          errors missing: ['is invalid']
+        end
+      end.to raise_error(/errors refer to unknown input parameters: missing/)
+    end
+
+    it 'accepts resource IDs and rejects malformed resource objects' do
+      output = HaveAPI::Params.new(:output, validated_example_action)
+      output.add_block(proc do
+        resource HaveAPI::Resources::ActionState, name: :state
+      end)
+      output.exec
+      action = Struct.new(:input, :output) do
+        def path_param_names(_path)
+          []
+        end
+
+        def to_s
+          'ResourceExampleAction'
+        end
+      end.new(nil, output)
+
+      expect do
+        example_for(action, path: '/v1/resource-example') do
+          response(state: 101)
+        end
+      end.not_to raise_error
+
+      expect do
+        example_for(action, path: '/v1/resource-example') do
+          response(state: { label: 'missing ID' })
+        end
+      end.to raise_error(/resource object is missing id/)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haveapi
 version: !ruby/object:Gem::Version
-  version: 0.29.5
+  version: 0.29.7
 platform: ruby
 authors:
 - Jakub Skokan
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.29.5
+        version: 0.29.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.29.5
+        version: 0.29.7
 - !ruby/object:Gem::Dependency
   name: i18n
   requirement: !ruby/object:Gem::Requirement
@@ -325,6 +325,7 @@ files:
 - spec/authentication/token_spec.rb
 - spec/authentication/token_version_routes_spec.rb
 - spec/authorization_spec.rb
+- spec/client_examples/syntax_spec.rb
 - spec/common_spec.rb
 - spec/documentation/auth_filtering_spec.rb
 - spec/documentation/current_user_html_escaping_spec.rb