dolly 3.1.5 → 3.2.0

data/lib/dolly/curl/write_reconciler.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require 'dolly/curl/document_helper'
+require 'dolly/exceptions'
+require 'dolly/curl/response_formatter'
+require 'dolly/curl/stale_connection'
+
+module Dolly
+  module Curl
+    # Reconciles ambiguous CouchDB writes after stale keep-alive failures.
+    # Depends on a transport that responds to +perform+ and +discard_handle+.
+    class WriteReconciler
+      include ResponseFormatter
+
+      def initialize(transport:, reader:, db_name:)
+        @transport = transport
+        @reader = reader
+        @documents = DocumentHelper.new(db_name: db_name)
+      end
+
+      def reconcile(method, uri, data, error, &block)
+        case method.to_sym
+        when :put then reconcile_put(uri, data, error, &block)
+        when :delete then reconcile_delete(uri, data, error, &block)
+        when :post then reconcile_post(uri, data, error, &block)
+        else raise_ambiguous(method, uri, error)
+        end
+      end
+
+      private
+
+      attr_reader :transport, :reader, :documents
+
+      def reconcile_post(uri, data, error, &block)
+        return reconcile_bulk_docs(uri, data, error, &block) if bulk_docs?(uri)
+
+        raise_ambiguous(:post, uri, error)
+      end
+
+      def reconcile_put(uri, data, error, &block)
+        doc_id, intended = put_target(uri, data, error)
+        resolve_put(uri, data, doc_id, intended, error, &block)
+      rescue *StaleConnection::ERRORS => retry_error
+        transport.discard_handle
+        raise_ambiguous(:put, uri, retry_error)
+      end
+
+      def put_target(uri, data, error)
+        doc_id = documents.id_from_uri(uri)
+        raise_ambiguous(:put, uri, error) unless doc_id
+
+        intended = documents.normalize(data)
+        raise_ambiguous(:put, uri, error) unless intended
+
+        [doc_id, intended]
+      end
+
+      def resolve_put(uri, data, doc_id, intended, error, &block)
+        stored = reader.fetch_document(doc_id)
+        return put_success(stored) if put_already_applied?(stored, intended)
+        return transport.perform(:put, uri, data, &block) if put_retryable?(stored, intended)
+
+        raise_ambiguous(:put, uri, error)
+      end
+
+      def put_already_applied?(stored, intended)
+        stored && documents.matches?(stored, intended)
+      end
+
+      def put_retryable?(stored, intended)
+        return documents.revision(intended).nil? if stored.nil?
+
+        revision = documents.revision(intended)
+        revision && documents.value(stored, :_rev) == revision
+      end
+
+      def put_success(stored)
+        {
+          ok: true,
+          id: documents.value(stored, :_id),
+          rev: documents.value(stored, :_rev)
+        }
+      end
+
+      def reconcile_delete(uri, data, error, &block)
+        doc_id = documents.id_from_uri(uri)
+        raise_ambiguous(:delete, uri, error) unless doc_id
+
+        expected_rev = documents.rev_from_uri(uri)
+        raise_ambiguous(:delete, uri, error) unless expected_rev
+
+        resolve_delete(uri, data, doc_id, expected_rev, error, &block)
+      rescue *StaleConnection::ERRORS => retry_error
+        transport.discard_handle
+        raise_ambiguous(:delete, uri, retry_error)
+      end
+
+      def resolve_delete(uri, data, doc_id, expected_rev, error, &block)
+        stored = reader.fetch_document(doc_id)
+        return { ok: true, id: doc_id } if stored.nil?
+        return { ok: true, id: doc_id } if documents.deleted?(stored)
+        return transport.perform(:delete, uri, data, &block) if documents.value(stored, :_rev) == expected_rev
+
+        raise_ambiguous(:delete, uri, error)
+      end
+
+      def reconcile_bulk_docs(uri, data, error, &block)
+        docs = documents.docs_from_bulk_payload(data)
+        raise_ambiguous(:post, uri, error) if docs.empty?
+
+        ids = docs.map { |doc| documents.id(doc) }.compact
+        raise_ambiguous(:post, uri, error) if ids.empty? || ids.size != docs.size
+
+        classify_and_retry_bulk(uri, docs, ids, error, &block)
+      rescue *StaleConnection::ERRORS => retry_error
+        transport.discard_handle
+        raise_ambiguous(:post, uri, retry_error)
+      end
+
+      def classify_and_retry_bulk(uri, docs, ids, error, &block)
+        rows_by_id = reader.fetch_documents_by_ids(ids)
+        results = []
+        pending = []
+
+        docs.each do |doc|
+          row = rows_by_id[documents.id(doc)]
+          stored = row && row[:doc]
+
+          if bulk_committed?(doc, stored, row)
+            results << bulk_success(doc, stored)
+          elsif bulk_unapplied?(doc, stored)
+            pending << doc
+          else
+            raise_ambiguous(:post, uri, error)
+          end
+        end
+
+        results.concat(retry_pending_bulk(uri, pending, &block)) if pending.any?
+        results
+      end
+
+      def retry_pending_bulk(uri, pending, &block)
+        retry_response = transport.perform(:post, uri, { docs: pending }, &block)
+        retry_results = response_format(retry_response, :post)
+        retry_results = [retry_results] unless retry_results.is_a?(Array)
+        retry_results
+      end
+
+      def bulk_committed?(intended, stored, row)
+        return true if documents.deleted?(intended) && bulk_deleted?(stored, row)
+        return false if stored.nil?
+
+        documents.matches?(stored, intended)
+      end
+
+      def bulk_deleted?(stored, row)
+        stored.nil? || documents.deleted?(stored) || row&.dig(:value, :deleted)
+      end
+
+      def bulk_unapplied?(intended, stored)
+        return true if stored.nil? && !documents.deleted?(intended)
+        return true if delete_still_present?(intended, stored)
+        return true if update_still_at_source_rev?(intended, stored)
+
+        false
+      end
+
+      def delete_still_present?(intended, stored)
+        documents.deleted?(intended) &&
+          stored &&
+          !documents.deleted?(stored) &&
+          documents.value(stored, :_rev) == documents.revision(intended)
+      end
+
+      def update_still_at_source_rev?(intended, stored)
+        !documents.deleted?(intended) &&
+          stored &&
+          documents.revision(intended) &&
+          documents.value(stored, :_rev) == documents.revision(intended)
+      end
+
+      def bulk_success(intended, stored)
+        id = documents.id(intended)
+        return deleted_bulk_success(id, stored) if documents.deleted?(intended)
+
+        { ok: true, id: id, rev: documents.value(stored, :_rev) }
+      end
+
+      def deleted_bulk_success(id, stored)
+        result = { ok: true, id: id }
+        rev = stored && documents.value(stored, :_rev)
+        result[:rev] = rev if rev
+        result
+      end
+
+      def bulk_docs?(uri)
+        uri.path.end_with?('/_bulk_docs')
+      end
+
+      def raise_ambiguous(method, uri, error)
+        raise Dolly::AmbiguousWriteError.new(method: method, uri: uri, cause: error)
+      end
+    end
+  end
+end

data/lib/dolly/curl.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'dolly/curl/stale_connection'
+require 'dolly/curl/response_formatter'
+require 'dolly/curl/document_helper'
+require 'dolly/curl/reader'
+require 'dolly/curl/write_reconciler'
+require 'dolly/curl/connection'
+
+module Dolly
+  # Namespace for Curb-based HTTP transport collaborators.
+  #
+  # Public CouchDB client API remains Dolly::Connection. Classes under
+  # Dolly::Curl are internal transport/retry helpers.
+  module Curl
+  end
+end

data/lib/dolly/document.rb

@@ -58,7 +58,7 @@ module Dolly
     end
 
     def doc_for_framework
-      return @doc if @doc
+      return @doc if defined?(@doc) && @doc
 
       return {} unless rails?
 

data/lib/dolly/exceptions.rb

@@ -47,6 +47,22 @@ module Dolly
     end
   end
 
+  class AmbiguousWriteError < RuntimeError
+    attr_reader :method, :uri, :cause
+
+    def initialize(method:, uri:, cause:)
+      @method = method
+      @uri = uri
+      @cause = cause
+      super()
+    end
+
+    def to_s
+      "Ambiguous #{method.upcase} to #{uri} after #{cause.class}: #{cause.message}. " \
+        'The request may or may not have been applied.'
+    end
+  end
+
   class PartitionedDataBaseExpectedError < RuntimeError; end
   class IndexNotFoundError < RuntimeError; end
   class InvalidConfigFileError < RuntimeError; end

data/lib/dolly/version.rb

@@ -1,3 +1,3 @@
 module Dolly
-  VERSION = "3.1.5"
+  VERSION = "3.2.0"
 end

data/test/bulk_document_test.rb

@@ -44,4 +44,71 @@ class BulkDocumentTest < Test::Unit::TestCase
     assert_equal [], @doc.docs
     assert_equal [], @doc.payload[:docs]
   end
+
+  test 'save reconciles when bulk post is ambiguous but docs are committed' do
+    docs = 2.times.map { |i| Doc.new(name: "doc-#{i}").tap { |d| d.id = "doc/#{i}" } }
+    docs.each { |d| @doc << d }
+
+    connection = @doc.connection
+    curl = connection.send(:curl_connection)
+    curl.stubs(:perform).with do |method, uri, *_|
+      method.to_sym == :post && uri.path.end_with?('/_bulk_docs')
+    end.raises(Curl::Err::RecvError)
+
+    curl.reader.stubs(:fetch_documents_by_ids).returns(
+      docs.each_with_object({}) do |d, memo|
+        memo[d.id] = { id: d.id, doc: d.to_h.merge(_rev: "1-#{d.id}") }
+      end
+    )
+
+    @doc.save
+
+    assert_equal [], @doc.errors
+    assert_equal [], @doc.docs
+    docs.each { |d| assert_equal "1-#{d.id}", d.rev }
+  end
+
+  test 'save retries only unapplied docs after ambiguous bulk post' do
+    committed = Doc.new(name: 'committed').tap { |d| d.id = 'doc/1' }
+    pending = Doc.new(name: 'pending').tap { |d| d.id = 'doc/2' }
+    @doc << committed
+    @doc << pending
+
+    connection = @doc.connection
+    curl = connection.send(:curl_connection)
+    bulk_attempts = 0
+    retry_body = [{ ok: true, id: 'doc/2', rev: '2-doc/2' }]
+    pending_payloads = []
+
+    curl.stubs(:perform).with do |method, uri, data, *_|
+      next false unless method.to_sym == :post && uri.path.end_with?('/_bulk_docs')
+
+      bulk_attempts += 1
+      raise Curl::Err::RecvError if bulk_attempts == 1
+
+      pending_payloads << data
+      true
+    end.returns(
+      stub(
+        status: '200',
+        body_str: retry_body.to_json,
+        header_str: ''
+      )
+    )
+
+    curl.reader.stubs(:fetch_documents_by_ids).returns(
+      'doc/1' => { id: 'doc/1', doc: committed.to_h.merge(_rev: '1-doc/1') },
+      'doc/2' => { id: 'doc/2', error: 'not_found' }
+    )
+
+    @doc.save
+
+    assert_equal 2, bulk_attempts
+    assert_equal 1, pending_payloads.size
+    assert_equal ['doc/2'], pending_payloads.first[:docs].map { |d| d[:_id] || d['_id'] }
+    assert_equal [], @doc.errors
+    assert_equal [], @doc.docs
+    assert_equal '1-doc/1', committed.rev
+    assert_equal '2-doc/2', pending.rev
+  end
 end

data/test/connection_test.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class ConnectionTest < Test::Unit::TestCase
+  setup do
+    clear_thread_local_curl!
+    @connection = Dolly::Connection.new
+  end
+
+  teardown do
+    clear_thread_local_curl!
+  end
+
+  test 'response_format raises ResourceNotFound for 404 responses' do
+    response = build_curl_response(status: 404, body: '{"error":"not_found"}')
+
+    assert_raises(Dolly::ResourceNotFound) do
+      @connection.send(:response_format, response, :get)
+    end
+  end
+
+  test 'response_format raises ServerError for 5xx responses' do
+    response = build_curl_response(status: 500, body: '{"error":"internal"}')
+
+    error = assert_raises(Dolly::ServerError) do
+      @connection.send(:response_format, response, :get)
+    end
+
+    assert_equal 500, error.instance_variable_get(:@msg)
+  end
+
+  test 'response_format raises ServerError for 4xx responses' do
+    response = build_curl_response(status: 400, body: '{"error":"bad_request"}')
+
+    error = assert_raises(Dolly::ServerError) do
+      @connection.send(:response_format, response, :get)
+    end
+
+    assert_equal 400, error.instance_variable_get(:@msg)
+  end
+
+  test 'response_format returns headers for head responses' do
+    response = build_curl_response(status: 200, body: '', headers: "ETag: \"abc\"\r\n")
+
+    assert_equal "ETag: \"abc\"\r\n", @connection.send(:response_format, response, :head)
+  end
+
+  test 'response_format returns parsed json for successful responses' do
+    response = build_curl_response(status: 200, body: '{"ok":true,"count":2}')
+
+    assert_equal({ ok: true, count: 2 }, @connection.send(:response_format, response, :get))
+  end
+
+  test 'response_format returns raw body when json parsing fails' do
+    response = build_curl_response(status: 200, body: 'plain text')
+
+    assert_equal 'plain text', @connection.send(:response_format, response, :get)
+  end
+
+  test 'request performs get against couchdb with query params' do
+    stub_request(:get, 'http://localhost:5984/test/doc/1?rev=1-abc')
+      .to_return(status: 200, body: '{"ok":true}', headers: { 'Content-Type' => 'application/json' })
+
+    result = @connection.request(:get, 'doc/1', rev: '1-abc')
+
+    assert_equal({ ok: true }, result)
+  end
+
+  test 'request path reuses thread local curl between calls' do
+    stub_request(:get, %r{http://localhost:5984/test/_uuids})
+      .to_return(status: 200, body: '{"uuids":["abc"]}', headers: { 'Content-Type' => 'application/json' })
+
+    @connection.tools('_uuids')
+    first_handle = @connection.send(:curl_connection).thread_local_handle
+    @connection.tools('_uuids')
+    second_handle = @connection.send(:curl_connection).thread_local_handle
+
+    assert_same first_handle, second_handle
+  end
+
+  test 'request performs post against couchdb' do
+    stub_request(:post, 'http://localhost:5984/test/_bulk_docs')
+      .with(body: '{"docs":[]}')
+      .to_return(status: 200, body: '{"ok":true}', headers: { 'Content-Type' => 'application/json' })
+
+    result = @connection.request(:post, '_bulk_docs', docs: [])
+
+    assert_equal({ ok: true }, result)
+  end
+
+  test 'request performs put against couchdb' do
+    stub_request(:put, 'http://localhost:5984/test/doc%2F1')
+      .with(body: '{"foo":"bar"}')
+      .to_return(status: 201, body: '{"ok":true,"id":"doc/1","rev":"1-abc"}', headers: { 'Content-Type' => 'application/json' })
+
+    result = @connection.put('doc/1', foo: 'bar')
+
+    assert_equal({ ok: true, id: 'doc/1', rev: '1-abc' }, result)
+  end
+
+  test 'request performs delete against couchdb' do
+    stub_request(:delete, 'http://localhost:5984/test/doc%2F1?rev=1-abc')
+      .to_return(status: 200, body: '{"ok":true}', headers: { 'Content-Type' => 'application/json' })
+
+    result = @connection.delete('doc/1', '1-abc')
+
+    assert_equal({ ok: true }, result)
+  end
+
+  test 'request sends custom headers' do
+    stub_request(:put, 'http://localhost:5984/test/doc%2F1/attachment.txt')
+      .with(headers: { 'Content-Type' => 'text/plain' })
+      .to_return(status: 201, body: '{"ok":true}', headers: { 'Content-Type' => 'application/json' })
+
+    result = @connection.attach('doc/1', 'attachment.txt', 'payload', 'Content-Type' => 'text/plain')
+
+    assert_equal({ ok: true }, result)
+  end
+
+  test 'curl transport helpers stay outside the public connection api' do
+    assert_raises(NoMethodError) { @connection.curl_connection }
+    assert_raises(NoMethodError) { @connection.fetch_document('doc/1') }
+    assert_raises(NoMethodError) { @connection.fetch_documents_by_ids(['doc/1']) }
+
+    curl = @connection.send(:curl_connection)
+    assert_equal 'test', curl.db_name
+    assert_instance_of Dolly::Curl::Reader, curl.reader
+  end
+
+  private
+
+  def build_curl_response(status:, body:, headers: '')
+    stub(status: status.to_s, body_str: body, header_str: headers)
+  end
+
+  def clear_thread_local_curl!
+    store = Thread.current[Dolly::Curl::Connection::THREAD_STORE_KEY]
+    return unless store
+
+    store.each_value { |handle| handle.close rescue nil }
+    store.clear
+    Thread.current[Dolly::Curl::Connection::THREAD_STORE_KEY] = nil
+  end
+end