haveapi 0.30.0 → 0.30.2

data/spec/client_examples/context_spec.rb

@@ -25,6 +25,212 @@ describe HaveAPI::ClientExample::Context do
     expect(child).to be_frozen
   end
 
+  describe '#with' do
+    let(:fields) do
+      {
+        version: 1, host: 'api.test', base_url: 'https://api.test/mount/',
+        version_url: 'https://api.test/mount/v1/',
+        description: { 'resources' => { 'widget' => { 'label' => 'Widget' } } },
+        resource_path: [:widget, 2], resource: { 'label' => 'Widget' },
+        action_name: :show, action: { 'method' => 'GET' },
+        sample: { 'request' => { 'values' => [0, false, '', nil] } }, profile: Object.new
+      }
+    end
+    let(:parent) { described_class.new(**fields) }
+    let(:replacements) do
+      {
+        version: 2, host: 'other.test', base_url: 'https://other.test/api/',
+        version_url: 'https://other.test/api/v2/',
+        description: { 'resources' => { 'other' => { 'label' => 'Other' } } },
+        resource_path: [:other, 3], resource: { 'label' => 'Other' },
+        action_name: :update, action: { 'method' => 'POST' },
+        sample: { 'request' => { 'values' => [false, 0, nil, ''] } },
+        profile: Object.new
+      }
+    end
+
+    it 'returns a distinct frozen context sharing every unchanged field' do
+      child = parent.with
+
+      expect(child).not_to equal(parent)
+      expect(child).to be_frozen
+      described_class::FIELDS.each do |field|
+        expect(child.public_send(field)).to equal(parent.public_send(field))
+      end
+      expect(child.description['resources']['widget']).to equal(parent.description['resources']['widget'])
+    end
+
+    HaveAPI::ClientExample::Context::FIELDS.each do |field|
+      it "normalizes an explicit #{field} replacement like the constructor and shares other fields" do
+        changed = { field => replacements.fetch(field) }
+        child = parent.with(**changed)
+        constructor = described_class.new(**fields, **changed)
+
+        expect(child).to be_frozen
+        expect(child.public_send(field)).to eq(constructor.public_send(field))
+        (described_class::FIELDS - [field]).each do |unchanged|
+          expect(child.public_send(unchanged)).to equal(parent.public_send(unchanged))
+        end
+        expect(parent.public_send(field)).to eq(described_class.new(**fields).public_send(field))
+      end
+    end
+
+    it 'copies supplied nested containers and strings even when their outer hash is frozen' do
+      key = ['mutable key']
+      source = { key => [{ 'value' => 'safe' }] }.freeze
+      child = parent.with(description: source, resource: source, action: source, sample: source)
+
+      %i[description resource action sample].each do |field|
+        owned = child.public_send(field)
+        expect(owned).not_to equal(source)
+        expect(owned).to be_frozen
+        expect(owned.keys.first).not_to equal(key)
+        expect(owned.keys.first).to be_frozen
+        expect(owned.keys.first.first).to be_frozen
+        expect(owned.values.first).to be_frozen
+        expect(owned.values.first.first).to be_frozen
+        expect(owned.values.first.first.keys.first).to be_frozen
+        expect(owned.values.first.first['value']).to be_frozen
+      end
+      expect(key).not_to be_frozen
+      expect(key.first).not_to be_frozen
+      expect(source.values.first).not_to be_frozen
+      expect(source.values.first.first['value']).not_to be_frozen
+      key.first.replace('changed key')
+      source.values.first.first['value'].replace('changed')
+      %i[description resource action sample].each do |field|
+        expect(child.public_send(field)).to eq(['mutable key'] => [{ 'value' => 'safe' }])
+      end
+    end
+
+    it 'detaches explicitly supplied strings and converts resource path elements without retaining them' do
+      text = +'value'
+      path = [text, :widget, 7]
+      child = parent.with(version: text, host: text, base_url: text, version_url: text,
+                          resource_path: path, action_name: text)
+
+      %i[version host base_url version_url action_name].each do |field|
+        expect(child.public_send(field)).to eq('value')
+        expect(child.public_send(field)).not_to equal(text)
+        expect(child.public_send(field)).to be_frozen
+      end
+      expect(child.resource_path).to eq(%w[value widget 7])
+      expect(child.resource_path).to be_frozen
+      expect(child.resource_path).not_to equal(path)
+      expect(child.resource_path).to all(be_frozen)
+      expect(path).not_to be_frozen
+      expect(text).not_to be_frozen
+      text.replace('changed')
+      path << 'extra'
+      expect(child.version).to eq('value')
+      expect(child.resource_path).to eq(%w[value widget 7])
+    end
+
+    it 'copies explicitly supplied owned values again instead of treating frozen data as trusted' do
+      child = parent.with(description: parent.description, resource_path: parent.resource_path,
+                          sample: parent.sample)
+
+      %i[description resource_path sample].each do |field|
+        expect(child.public_send(field)).to eq(parent.public_send(field))
+        expect(child.public_send(field)).not_to equal(parent.public_send(field))
+      end
+      expect(child.description['resources']).not_to equal(parent.description['resources'])
+      expect(child.sample['request']['values']).not_to equal(parent.sample['request']['values'])
+    end
+
+    it 'keeps parent, sibling and chained derivations detached from their supplied inputs' do
+      data = { request: { name: 'safe' } }
+      child = parent.with(sample: data)
+      sibling = parent.with(sample: data)
+      grandchild = child.with(action_name: :update)
+      fields[:description]['resources']['widget']['label'].replace('changed source')
+      data[:request][:name].replace('changed sample')
+
+      expect(parent.description['resources']['widget']['label']).to eq('Widget')
+      expect(child.description).to equal(parent.description)
+      expect(sibling.description).to equal(parent.description)
+      expect(grandchild.description).to equal(parent.description)
+      expect(parent.sample).to eq('request' => { 'values' => [0, false, '', nil] })
+      expect(child.sample).to eq(request: { name: 'safe' })
+      expect(sibling.sample).to eq(child.sample)
+      expect(sibling.sample).not_to equal(child.sample)
+      expect(grandchild.sample).to equal(child.sample)
+      expect(child.action_name).to eq('show')
+      expect(grandchild.action_name).to eq('update')
+      expect { child.sample[:request][:name].replace('forbidden') }.to raise_error(FrozenError)
+    end
+
+    it 'distinguishes omitted fields from explicit nil replacements' do
+      child = parent.with(description: nil, resource: nil, action_name: nil, action: nil, sample: nil, profile: nil)
+
+      %i[description resource action_name action sample profile].each do |field|
+        expect(child.public_send(field)).to be_nil
+        expect(parent.public_send(field)).not_to be_nil
+      end
+      expect(child.version).to equal(parent.version)
+      expect(parent.with(version: nil, host: nil, base_url: nil, version_url: nil))
+        .to have_attributes(version: '', host: '', base_url: '', version_url: '')
+      expect(context.with.action_name).to be_nil
+    end
+
+    it 'shares arbitrary profiles and non-container leaves without freezing them' do
+      leaf = Object.new
+      profile = fields.fetch(:profile)
+      child = parent.with(description: { custom: leaf }, profile: leaf)
+
+      expect(parent.profile).to equal(profile)
+      expect(parent.with.profile).to equal(profile)
+      expect(profile).not_to be_frozen
+      expect(child.profile).to equal(leaf)
+      expect(child.description[:custom]).to equal(leaf)
+      expect(leaf).not_to be_frozen
+    end
+
+    it 'continues rejecting invalid resource paths' do
+      expect { parent.with(resource_path: nil) }.to raise_error(NoMethodError)
+      expect { described_class.new(**fields, resource_path: nil) }.to raise_error(NoMethodError)
+      expect(parent.resource_path).to eq(%w[widget 2])
+    end
+
+    it 'rejects unknown keywords before normalizing any supplied values' do
+      value = Object.new
+      allow(value).to receive(:to_s).and_call_original
+
+      expect { parent.with(version: value, unknown: true) }.to raise_error(ArgumentError, 'unknown keyword: :unknown')
+      expect { parent.with(unknown: true, other: false) }
+        .to raise_error(ArgumentError, 'unknown keywords: :unknown, :other')
+      expect { parent.with('version' => '2') }.to raise_error(ArgumentError, 'unknown keyword: "version"')
+      expect(value).not_to have_received(:to_s)
+      expect(parent).not_to respond_to(:unknown)
+      expect(parent.version).to eq('1')
+    end
+
+    it 'keeps subclass constructors, extra keywords and constructor effects on every derivation' do
+      subclass = Class.new(described_class) do
+        attr_reader :marker, :initializations
+
+        def initialize(marker: :default, initializations: 0, **fields)
+          @marker = marker
+          @initializations = initializations + 1
+          super(**fields)
+        end
+      end
+      original = subclass.new(**fields, marker: :original)
+      child = original.with(marker: :child, initializations: original.initializations)
+      defaulted = original.with
+
+      expect(child).to be_a(subclass)
+      expect(child).to be_frozen
+      expect(child.marker).to eq(:child)
+      expect(child.initializations).to eq(2)
+      expect(defaulted.marker).to eq(:default)
+      expect(original.marker).to eq(:original)
+      expect(original.initializations).to eq(1)
+      expect(child.description).to eq(original.description)
+      expect(child.description).not_to equal(original.description)
+    end
+  end
+
   it 'preserves legacy initialization constructors and wraps plain source' do
     renderer = Class.new(HaveAPI::ClientExample) do
       def initialize(host, base_url, version)

data/spec/client_examples/dynamic_js_spec.rb

@@ -83,6 +83,7 @@ RSpec.describe HaveAPI::ClientExamples::JsClient do
         end
       end
       options = { strict: true, noEmit: true, target: 'ES2020', module: 'ESNext', moduleResolution: 'node',
+                  ignoreDeprecations: '6.0',
                   typeRoots: [File.join(root, 'clients/js/node_modules/@types')], types: ['node'],
                   baseUrl: directory, paths: { 'haveapi-client' => [File.join(root, 'clients/js/dist/types/haveapi')] } }
       config = File.join(directory, 'tsconfig.json')

data/spec/client_examples/profile_mount_spec.rb

@@ -0,0 +1,215 @@
+require 'spec_helper'
+require 'base64'
+
+module ProfileMountSpec
+  User = Struct.new(:login)
+
+  module AuthenticationResources
+    class Session < HaveAPI::Resource
+      auth false
+      version :all
+
+      class Show < HaveAPI::Action
+        route ''
+        http_method :get
+        output(:hash) { string :id }
+        authorize { allow }
+      end
+    end
+  end
+
+  class Provider < HaveAPI::Authentication::Basic::Provider
+    def resource_module
+      AuthenticationResources
+    end
+
+    protected
+
+    def find_user(_request, username, password)
+      User.new(username) if %w[member admin].include?(username) && password == 'pass'
+    end
+  end
+
+  class Added < HaveAPI::Resource
+    auth false
+    version :all
+
+    class Index < HaveAPI::Action
+      route ''
+      http_method :get
+      output(:hash) { string :late }
+      authorize { allow }
+    end
+  end
+end
+
+describe HaveAPI::Server, '#mount' do
+  api do
+    define_resource(:Widget) do
+      version :all
+      auth false
+
+      define_action(:Show) do
+        route '{widget_id}'
+        http_method :get
+        desc HaveAPI.message('profile_mount_spec.action')
+        input(:hash) do
+          string :visible
+          string :secret, default: 'PRIVATE_DEFAULT'
+        end
+        output(:hash) do
+          string :visible
+          string :secret
+        end
+        authorize do |user|
+          unless user.login == 'admin'
+            input blacklist: [:secret]
+            output blacklist: [:secret]
+          end
+          allow
+        end
+
+        # rubocop:disable RSpec/NoExpectationExample
+        example 'visible sample' do
+          path_params 7
+          request({ visible: 'public sample' })
+          response({ visible: 'public response' })
+        end
+
+        example 'privileged sample' do
+          authorize { |user| user.login == 'admin' }
+          path_params 7
+          request({ secret: 'PRIVATE_SAMPLE' })
+          response({ secret: 'PRIVATE_RESPONSE' })
+        end
+        # rubocop:enable RSpec/NoExpectationExample
+      end
+
+      define_action(:Secret) do
+        route 'secret'
+        http_method :get
+        output(:hash) { string :admin_only }
+        authorize { |user| user.login == 'admin' ? allow : deny }
+      end
+    end
+  end
+
+  let(:server) { described_class.new(get_opt(:api_module)) }
+  let(:descriptions) { [] }
+  let(:contexts) { [] }
+  let(:documentation) { Class.new }
+  let(:adapter) do
+    selected_contexts = contexts
+    Class.new do
+      define_method(:resolve) { |**| nil }
+      define_method(:render) do |kind:, context:, **|
+        selected_contexts << context
+        { status: :code, code: JSON.generate(kind == :example ? context.sample : { url: context.version_url }) }
+      end
+    end.new
+  end
+
+  before do
+    generator = Module.new
+    generator.const_set(:VERSION, HaveAPI::VERSION)
+    generator.const_set(:Documentation, documentation)
+    stub_const('HaveAPI::GoClient', generator)
+    allow(registry).to receive(:require).with('haveapi/go_client/documentation').and_return(true)
+    allow(documentation).to receive(:new) do |description:, **|
+      descriptions << description
+      adapter
+    end
+    server.use_version([1, 2])
+    server.default_version = 1
+    server.auth_chain << ProfileMountSpec::Provider
+  end
+
+  def registry
+    server.instance_variable_get(:@documentation_clients)
+  end
+
+  def register(version = 1)
+    server.documentation_clients(version, go: { import_path: 'example.test/widget/client' })
+  end
+
+  def request_as(user, locale)
+    Rack::MockRequest.new(server.app).get(
+      '/mounted/api/v1/', 'HTTP_HOST' => 'example.org', 'HTTP_ACCEPT_LANGUAGE' => locale,
+                          'HTTP_AUTHORIZATION' => "Basic #{Base64.strict_encode64("#{user}:pass")}"
+    )
+  end
+
+  it 'captures the complete selected version after auth, action-state and post-mount routes exist' do
+    register
+    server.action_state = Object.new
+    server.connect_hook(:post_mount) do |_ret, api_server, _sinatra|
+      expect(api_server.documentation_client_profiles(1)).to be_empty
+      api_server.mount_resource('/mounted/api/v1/', 1, ProfileMountSpec::Added, api_server.routes[1][:resources])
+      {}
+    end
+    allow(server).to receive(:describe_version).and_call_original
+    server.mount('/mounted/api/')
+    expect(server).to have_received(:describe_version).once
+    expect(descriptions.size).to eq(1)
+    private_schema = descriptions.first
+    expect(private_schema['help']).to eq('/mounted/api/v1/')
+    expect(private_schema['resources'].keys).to include('widget', 'action_state', 'added')
+    expect(private_schema.dig('resources', 'widget', 'actions').keys).to include('show', 'secret')
+    expect(private_schema.dig('authentication', 'basic', 'resources')).to have_key('session')
+    expect(private_schema.dig('resources', 'widget', 'actions', 'show', 'input', 'parameters')).to have_key('secret')
+    expect(JSON.generate(private_schema)).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE')
+    expect(server.documentation_client_profiles(1).fetch(:go).package_version).to be_nil
+    expect(server.documentation_client_profiles(2)).to be_empty
+  end
+
+  it 'captures each configured version once and does not initialize from requests' do
+    register(1)
+    register(2)
+    server.mount('/mounted/api/')
+    expect(descriptions.map { |description| description['help'] }).to eq(['/mounted/api/v1/', '/mounted/api/v2/'])
+    request_as('member', 'en')
+    request_as('admin', 'cs')
+    expect(descriptions.size).to eq(2)
+    expect { register }.to raise_error(HaveAPI::ClientExample::Profiles::Invalid, /already mounted/)
+  end
+
+  it 'keeps private schema separate from sequential users, locales, HTML and samples' do
+    register
+    server.available_locales = %i[en cs]
+    ::I18n.backend.store_translations(:en, profile_mount_spec: { action: 'Visible English action' })
+    ::I18n.backend.store_translations(:cs, profile_mount_spec: { action: 'Viditelna ceska akce' })
+    server.mount('/mounted/api/')
+    privileged = request_as('admin', 'en')
+    expect(privileged.status).to eq(200)
+    expect(privileged.body).to include('PRIVATE_SAMPLE', 'Visible English action')
+    contexts.clear
+    public_response = request_as('member', 'cs')
+    expect(public_response.status).to eq(200)
+    expect(public_response.body).to include('Viditelna ceska akce', 'init-go', 'example.test/widget/client')
+    expect(public_response.body).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE', 'admin_only', 'haveapi.invalid', 'StructuralSchema')
+    selected = contexts.find { |context| context.action_name == 'show' }
+    expect(selected.action.dig(:input, :parameters).keys.map(&:to_s)).to eq(['visible'])
+    expect(selected.description[:resources]['widget'][:actions]).not_to have_key('secret')
+    expect(selected.sample[:request]).to eq(visible: 'public sample')
+    expect(selected.action[:description]).to eq('Viditelna ceska akce')
+    expect(request_as('member', 'en').body).to include('Visible English action')
+    expect(descriptions.size).to eq(1)
+  end
+
+  it 'makes the server unusable and publishes no profiles after an adapter failure' do
+    register
+    allow(documentation).to receive(:new).and_raise('PRIVATE_SCHEMA_DIAGNOSTIC')
+    expect { server.mount('/') }.to raise_error(HaveAPI::ClientExample::Profiles::Invalid, 'Configured documentation client schema or configuration is invalid')
+    expect(server.app).to be_nil
+    expect(server.documentation_client_profiles(1)).to be_empty
+  end
+
+  it 'makes the server unusable when a post-mount hook fails before finalization' do
+    register
+    server.connect_hook(:post_mount) { raise 'fixture mount failure' }
+    expect { server.mount('/') }.to raise_error(RuntimeError, 'fixture mount failure')
+    expect(documentation).not_to have_received(:new)
+    expect(server.app).to be_nil
+    expect(server.documentation_client_profiles(1)).to be_empty
+  end
+end