active_force 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2717b024f19c2c0dbf7530d606797a5880dfe629a154e6eebd083da381b917b1
-  data.tar.gz: ab29915f960873acd523a12f73af63f8c13b200e8cddbe4465ef28038cdebf2e
+  metadata.gz: 1c4cc417eaaf0ad9a412c1a39374d80e4a723d0f8d6184eba87c09371e3ba56a
+  data.tar.gz: d8cdb8bc16ab43f8d1fbe4840788e412d5aa0ad3a25734cbc2b85d7138626c75
 SHA512:
-  metadata.gz: dc4aa9e5110884da1008add3a996387d66af6c337328d56e773457fb24e61410a63d5bd3a734ab5bf79a44c4b5962a55aca1c00314af41d1275df663fa133f16
-  data.tar.gz: 6702930b7f9d47c2290c4e00300160f5e3261ed9c22834ab4bef55a8438f6ec778f97e51aab197b23d10b1d2b6c6d20dc3e2991b728a847529cf16e7121d6983
+  metadata.gz: c005126087818d2afa9ef019e537ae5920fea69f9275ba74293cbe97ea9335cfb62da1deedd1c58e707536357f45cf322dcfa48d38b6d007e89f5210dfaf86b2
+  data.tar.gz: 43623c0cda29edc52f3ccaddad50010a76d88417d6ebcbe5d80c2bd838518eddbaef217a41ec14c0e372ba50dbe8cad4cf3eaebe1f1f0998734bde19a4251d63

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Not released
 
+## 0.27.0
+- Emit `query.active_force` notifications for logical query executions, including aggregates and composite batch queries, with SOQL, model, client identity, transport, and standard exception payloads. Cache hits count as logical queries, not API calls. (https://github.com/Beyond-Finance/active_force/pull/117)
+
+## 0.26.0
+- Add ability to query using Composite Batch Api (https://github.com/Beyond-Finance/active_force/pull/114)
+
 ## 0.25.0
 - Add support for Rails 8.x (https://github.com/Beyond-Finance/active_force/pull/108)
 

data/README.md

@@ -293,6 +293,47 @@ When using rails, you can generate a model with all the fields you have on your
 
     rails g active_force:model <table name>
 
+### Query notifications
+
+ActiveForce emits `query.active_force` through `ActiveSupport::Notifications` for
+logical query executions, including `count`, `sum`, and composite batch queries.
+Requiring ActiveForce does not install a logger or query detector.
+
+```ruby
+subscriber = ActiveSupport::Notifications.subscribe('query.active_force') do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  # Inspect event.duration and event.payload in your development/test tooling.
+end
+
+# When no longer needed:
+ActiveSupport::Notifications.unsubscribe(subscriber)
+```
+
+Subscriber callbacks run synchronously and are not isolated from the query
+itself: if your subscriber raises, that exception replaces the query's real
+result or real exception (this is standard `ActiveSupport::Notifications`
+behavior, the same as Rails' own `sql.active_record`). Wrap any subscriber
+logic that could fail — network calls, external clients — in its own `rescue`.
+
+The payload contains:
+
+- `soql`: the executed SOQL string, including raw values. Treat it as sensitive;
+  only log it deliberately with appropriate data handling.
+- `model`: the queried `ActiveForce::SObject` class.
+- `client_id`: the client's Ruby `object_id` (process-local identity, not credentials).
+- `transport`: `:query` or `:composite_batch`. Aggregates retain direct `:query`
+  transport regardless of the composite threshold.
+
+Failed executions include ActiveSupport's standard `exception` and
+`exception_object` fields and still raise the original exception. Consumers
+counting successful queries should exclude those events.
+
+These are **logical queries, not Salesforce API-call counts**. Restforce HTTP-cache
+hits still count; no cache-hit marker is exposed. Internal retries and later
+pagination do not emit additional events. Lazy query construction and repeated
+access to loaded records emit none. Instrumentation does not enumerate results.
+Direct Restforce calls, SOSL, writes, and Bulk APIs are outside this event.
+
 ## Contributing
 
 1. Fork it
@@ -308,3 +349,7 @@ When using rails, you can generate a model with all the fields you have on your
  [3]: https://github.com/bkeepers/dotenv
  [4]: https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/bulk_api_2_0.htm
 
+
+## License
+
+[MIT](LICENSE.txt).

data/lib/active_force/active_query.rb

@@ -1,6 +1,7 @@
 require 'active_support/all'
 require 'active_force/query'
 require 'active_force/select_builder'
+require 'active_force/composite_batch_query'
 require 'forwardable'
 
 module ActiveForce
@@ -51,14 +52,14 @@ module ActiveForce
     alias_method :all, :to_a
 
     def count
-      sfdc_client.query(super.to_s).first.expr0
+      execute_query(super.to_s).first.expr0
     end
 
     def sum(field)
       raise ArgumentError, 'field is required' if field.blank?
       raise UnknownFieldError.new(sobject, field) unless mappings.key?(field.to_sym)
 
-      sfdc_client.query(super(mappings.fetch(field.to_sym)).to_s).first.expr0
+      execute_query(super(mappings.fetch(field.to_sym)).to_s).first.expr0
     end
 
     def limit limit
@@ -245,7 +246,23 @@ module ActiveForce
     end
 
     def result
-      sfdc_client.query(self.to_s)
+      soql = self.to_s
+
+      transport = soql.length >= ActiveForce.composite_batch_query_threshold ? :composite_batch : :query
+      execute_query(soql, transport)
+    end
+
+    def execute_query(soql, transport = :query)
+      client = sfdc_client
+      payload = { soql: soql, model: sobject, client_id: client.object_id, transport: transport }
+
+      ActiveSupport::Notifications.instrument('query.active_force', payload) do
+        if transport == :composite_batch
+          CompositeBatchQuery.call(soql, client)
+        else
+          client.query(soql)
+        end
+      end
     end
 
     def build_order_by(args)

data/lib/active_force/composite_batch_query.rb

@@ -0,0 +1,42 @@
+require 'active_support/all'
+
+module ActiveForce
+  class CompositeBatchQuery
+    def self.call(soql, sfdc_client = ActiveForce.sfdc_client)
+      new(soql, sfdc_client).call
+    end
+
+    attr_reader :sfdc_client, :soql
+
+    def initialize(soql, sfdc_client)
+      @sfdc_client = sfdc_client
+      @soql = soql
+    end
+
+    def call
+      results = sfdc_client.batch do |subrequests|
+        subrequests.requests << {
+          method: "GET",
+          url: "v#{subrequests.options[:api_version]}/query?" + {q: soql}.to_query
+        }
+      end
+
+      r = results.first
+
+      process_composite_batch_error_response(r) if r.statusCode >= 300
+
+      r.result
+    end
+
+    private
+
+    def process_composite_batch_error_response(r)
+      response_value = {status: r.statusCode, body: r.result.as_json}
+      error_code = r.result.dig(0, "errorCode")
+      message = "#{error_code}: #{r.result.dig(0, "message")}"
+      message << "\nRESPONSE: #{r.result.to_json}"
+
+      raise Restforce::ErrorCode.get_exception_class(error_code).new(message, response_value)
+    end
+  end
+end

data/lib/active_force/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveForce
-  VERSION = '0.25.0'
+  VERSION = '0.27.0'
 end

data/lib/active_force.rb

@@ -9,8 +9,16 @@ module ActiveForce
 
   class << self
     attr_accessor :sfdc_client
+    attr_writer :composite_batch_query_threshold
+
+    def composite_batch_query_threshold
+      @composite_batch_query_threshold ||= 100_000
+
+      return @composite_batch_query_threshold.call if @composite_batch_query_threshold.respond_to?(:call)
+
+      @composite_batch_query_threshold
+    end
   end
 
   self.sfdc_client = Restforce.new
-
 end

data/spec/active_force/active_query_spec.rb

@@ -557,6 +557,26 @@ describe ActiveForce::ActiveQuery do
     end
   end
 
+  describe '#result routing' do
+    after do
+      ActiveForce.instance_variable_set(:@composite_batch_query_threshold, nil)
+    end
+
+    it 'uses sfdc_client.query when SOQL is at or below the threshold' do
+      ActiveForce.composite_batch_query_threshold = 100_000
+      expect(client).to receive(:query).and_return([])
+      expect(ActiveForce::CompositeBatchQuery).not_to receive(:call)
+      active_query.where("Id = 'foo'").to_a
+    end
+
+    it 'uses CompositeBatchQuery.call when SOQL exceeds the threshold' do
+      ActiveForce.composite_batch_query_threshold = 0
+      expect(ActiveForce::CompositeBatchQuery).to receive(:call).and_return([])
+      expect(client).not_to receive(:query)
+      active_query.where("Id = 'foo'").to_a
+    end
+  end
+
   describe "#order" do
     context 'when it is symbol' do 
       it "should add an order condition with actual SF field name" do

data/spec/active_force/composite_batch_query_spec.rb

@@ -0,0 +1,101 @@
+require 'spec_helper'
+
+describe ActiveForce::CompositeBatchQuery do
+  let(:soql) { "SELECT Id FROM Account WHERE Name = 'Test'" }
+  let(:api_version) { '58.0' }
+  let(:sfdc_client) { double(Restforce) }
+  let(:subrequests) do
+    double('subrequests', requests: [], options: { api_version: api_version })
+  end
+
+  describe '.call' do
+    it 'delegates to new(...).call' do
+      result_record = double('result_record')
+      instance = instance_double(described_class)
+      allow(described_class).to receive(:new).with(soql, sfdc_client).and_return(instance)
+      allow(instance).to receive(:call).and_return(result_record)
+
+      expect(described_class.call(soql, sfdc_client)).to eq(result_record)
+    end
+
+    it 'defaults to ActiveForce.sfdc_client when no client is provided' do
+      default_client = double(Restforce)
+      allow(ActiveForce).to receive(:sfdc_client).and_return(default_client)
+
+      instance = instance_double(described_class)
+      allow(described_class).to receive(:new).with(soql, default_client).and_return(instance)
+      allow(instance).to receive(:call).and_return(double('result'))
+
+      expect { described_class.call(soql) }.not_to raise_error
+      expect(described_class).to have_received(:new).with(soql, default_client)
+    end
+  end
+
+  describe '#call' do
+    context 'when the response is successful' do
+      let(:result_record) { double(Restforce::Collection) }
+      let(:batch_result) do
+        double(Restforce::Mash, statusCode: 200, result: result_record)
+      end
+
+      before do
+        allow(sfdc_client).to receive(:batch).and_yield(subrequests).and_return([batch_result])
+      end
+
+      it 'sends a GET batch subrequest with the correct URL' do
+        described_class.call(soql, sfdc_client)
+
+        expected_url = "v#{api_version}/query?" + { q: soql }.to_query
+        expect(subrequests.requests).to include(
+          hash_including(method: 'GET', url: expected_url)
+        )
+      end
+
+      it 'returns the result from the batch response' do
+        expect(described_class.call(soql, sfdc_client)).to eq(result_record)
+      end
+    end
+
+    context 'when the response statusCode is exactly 300' do
+      let(:error_body) do
+        [{ 'errorCode' => 'MULTIPLE_CHOICES', 'message' => 'multiple records found' }]
+      end
+      let(:batch_result) do
+        double('batch_result', statusCode: 300, result: error_body)
+      end
+
+      before do
+        allow(sfdc_client).to receive(:batch).and_yield(subrequests).and_return([batch_result])
+      end
+
+      it 'treats it as an error' do
+        expect {
+          described_class.call(soql, sfdc_client)
+        }.to raise_error(Restforce::ResponseError)
+      end
+    end
+
+    context 'when the response is an error' do
+      let(:error_body) do
+        [{ 'errorCode' => 'MALFORMED_QUERY', 'message' => 'unexpected token' }]
+      end
+      let(:batch_result) do
+        double(Restforce::Mash, statusCode: 400, result: error_body)
+      end
+
+      before do
+        allow(sfdc_client).to receive(:batch).and_yield(subrequests).and_return([batch_result])
+      end
+
+      it 'raises a Restforce error with the correct error code and message' do
+        expect {
+          described_class.call(soql, sfdc_client)
+        }.to raise_error(Restforce::ErrorCode::MalformedQuery) do |error|
+          expect(error.message).to include('MALFORMED_QUERY')
+          expect(error.message).to include('unexpected token')
+          expect(error.message).to include('RESPONSE:')
+        end
+      end
+    end
+  end
+end

data/spec/active_force/query_notifications_spec.rb

@@ -0,0 +1,164 @@
+require 'spec_helper'
+
+describe 'query.active_force notifications' do
+  let(:model) do
+    Class.new(ActiveForce::SObject) do
+      self.table_name = 'Widgets'
+      field :id, from: 'Id'
+      field :amount, from: 'Amount__c'
+    end
+  end
+  let(:client) { double('client') }
+  let(:query) { ActiveForce::ActiveQuery.new(model) }
+  let(:events) { [] }
+
+  around do |example|
+    subscriber = ActiveSupport::Notifications.subscribe('query.active_force') do |*args|
+      events << ActiveSupport::Notifications::Event.new(*args)
+    end
+    example.run
+  ensure
+    ActiveSupport::Notifications.unsubscribe(subscriber)
+  end
+
+  before do
+    allow(model).to receive(:sfdc_client).and_return(client)
+  end
+
+  it 'emits the SOQL, model, nonsecret client identity and direct transport without enumerating the result' do
+    result = double('unloaded collection')
+    expect(client).to receive(:query).with(query.to_s).and_return(result)
+    expect(query.send(:result)).to equal(result)
+    expect(events.size).to eq(1)
+    expect(events.first.payload).to eq(soql: query.to_s, model: model,
+      client_id: client.object_id, transport: :query)
+  end
+
+  it 'does not emit for lazy construction or SOQL rendering' do
+    query.where(id: 'fake-id').select(:id).to_s
+    expect(events).to be_empty
+  end
+
+  it 'does not emit again when loaded records are reused' do
+    expect(client).to receive(:query).once.and_return([])
+    result = query.to_a
+    expect(query.to_a).to equal(result)
+    expect(events.size).to eq(1)
+  end
+
+  it 'counts separate logical queries even when a client returns the same cached result' do
+    cached_result = []
+    expect(client).to receive(:query).twice.and_return(cached_result)
+    2.times { ActiveForce::ActiveQuery.new(model).to_a }
+    expect(events.size).to eq(2)
+    expect(events.map(&:payload).uniq.size).to eq(1)
+    expect(events.first.payload).not_to have_key(:cache_hit)
+  end
+
+  it 'does not emit for pages retrieved while enumerating the returned collection' do
+    collection = double('paginated collection')
+    expect(client).to receive(:query).once.and_return(collection)
+    expect(collection).to receive(:to_a) do
+      client.get('/fake/next-page')
+      []
+    end
+    expect(client).to receive(:get).with('/fake/next-page')
+    query.to_a
+    expect(events.size).to eq(1)
+  end
+
+  it 'emits once when the client retries internally' do
+    attempts = 0
+    allow(client).to receive(:query) do
+      begin
+        attempts += 1
+        raise IOError if attempts == 1
+        []
+      rescue IOError
+        retry
+      end
+    end
+    query.to_a
+    expect(attempts).to eq(2)
+    expect(events.size).to eq(1)
+  end
+
+  it 'distinguishes client instances' do
+    other_client = double('other client', query: [])
+    allow(client).to receive(:query).and_return([])
+    query.to_a
+    allow(model).to receive(:sfdc_client).and_return(other_client)
+    ActiveForce::ActiveQuery.new(model).to_a
+    expect(events.map { |event| event.payload[:client_id] }).to eq([client.object_id, other_client.object_id])
+  end
+
+  [:query, :composite_batch].each do |transport|
+    context "with #{transport} transport" do
+      before do
+        allow(ActiveForce).to receive(:composite_batch_query_threshold).and_return(transport == :query ? 100_000 : 0)
+      end
+
+      it 'preserves the result and emits one event' do
+        result = double('unloaded result')
+        if transport == :query
+          expect(client).to receive(:query).with(query.to_s).and_return(result)
+        else
+          expect(client).not_to receive(:query)
+          expect(ActiveForce::CompositeBatchQuery).to receive(:call).with(query.to_s, client).and_return(result)
+        end
+        expect(query.send(:result)).to equal(result)
+        expect(events.size).to eq(1)
+        expect(events.first.payload[:transport]).to eq(transport)
+      end
+
+      it 'preserves the original exception and standard notification error payload' do
+        error = IOError.new('fake failure')
+        if transport == :query
+          allow(client).to receive(:query).and_raise(error)
+        else
+          allow(ActiveForce::CompositeBatchQuery).to receive(:call).and_raise(error)
+        end
+        expect { query.to_a }.to raise_error { |raised| expect(raised).to equal(error) }
+        expect(events.size).to eq(1)
+        expect(events.first.payload).to include(exception: ['IOError', 'fake failure'], exception_object: error,
+          transport: transport, soql: query.to_s, model: model, client_id: client.object_id)
+        expect(query.loaded?).to be false
+      end
+    end
+  end
+
+  [:count, :sum].each do |operation|
+    context "##{operation}" do
+      let(:arguments) { operation == :sum ? [:amount] : [] }
+
+      before do
+        allow(ActiveForce).to receive(:composite_batch_query_threshold).and_return(0)
+      end
+
+      it 'retains direct query transport and the aggregate value even above the composite threshold' do
+        expect(ActiveForce::CompositeBatchQuery).not_to receive(:call)
+        aggregate = double('aggregate', expr0: 42)
+        expect(client).to receive(:query).and_return([aggregate])
+        expect(query.public_send(operation, *arguments)).to eq(42)
+        expect(events.size).to eq(1)
+        expression = operation == :sum ? 'sum(Amount__c)' : 'count(Id)'
+        expect(events.first.payload).to eq(soql: "SELECT #{expression} FROM Widgets", model: model,
+          client_id: client.object_id, transport: :query)
+      end
+
+      it 'reports failed aggregate executions without replacing the exception' do
+        error = IOError.new('fake aggregate failure')
+        allow(client).to receive(:query).and_raise(error)
+        expect { query.public_send(operation, *arguments) }.to raise_error { |raised| expect(raised).to equal(error) }
+        expect(events.size).to eq(1)
+        expect(events.first.payload[:exception_object]).to equal(error)
+      end
+    end
+  end
+
+  it 'does not emit for invalid sum arguments' do
+    expect { query.sum(nil) }.to raise_error(ArgumentError)
+    expect { query.sum(:unknown) }.to raise_error(ActiveForce::UnknownFieldError)
+    expect(events).to be_empty
+  end
+end

data/spec/active_force_spec.rb

@@ -4,4 +4,24 @@ describe ActiveForce do
   it 'should have a version number' do
     expect(ActiveForce::VERSION).to_not be_nil
   end
+
+  describe '.composite_batch_query_threshold' do
+    after do
+      ActiveForce.instance_variable_set(:@composite_batch_query_threshold, nil)
+    end
+
+    it 'returns 100_000 by default' do
+      expect(ActiveForce.composite_batch_query_threshold).to eq(100_000)
+    end
+
+    it 'allows setting a custom integer value' do
+      ActiveForce.composite_batch_query_threshold = 25_000
+      expect(ActiveForce.composite_batch_query_threshold).to eq(25_000)
+    end
+
+    it 'supports callable values (proc/lambda)' do
+      ActiveForce.composite_batch_query_threshold = -> { 50_000 }
+      expect(ActiveForce.composite_batch_query_threshold).to eq(50_000)
+    end
+  end
 end

metadata

@@ -1,17 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: active_force
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Eloy Espinaco
 - Pablo Oldani
 - Armando Andini
 - José Piccioni
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -173,6 +172,7 @@ files:
 - lib/active_force/bulk/job.rb
 - lib/active_force/bulk/job_result.rb
 - lib/active_force/bulk/records.rb
+- lib/active_force/composite_batch_query.rb
 - lib/active_force/field.rb
 - lib/active_force/mapping.rb
 - lib/active_force/query.rb
@@ -195,8 +195,10 @@ files:
 - spec/active_force/bulk/record_spec.rb
 - spec/active_force/bulk_spec.rb
 - spec/active_force/callbacks_spec.rb
+- spec/active_force/composite_batch_query_spec.rb
 - spec/active_force/field_spec.rb
 - spec/active_force/mapping_spec.rb
+- spec/active_force/query_notifications_spec.rb
 - spec/active_force/query_spec.rb
 - spec/active_force/sobject/includes_spec.rb
 - spec/active_force/sobject/select_spec.rb
@@ -218,7 +220,6 @@ metadata:
   bug_tracker_uri: https://github.com/Beyond-Finance/active_force/issues
   changelog_uri: https://github.com/Beyond-Finance/active_force/blob/main/CHANGELOG.md
   source_code_uri: https://github.com/Beyond-Finance/active_force
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -233,8 +234,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Help you implement models persisting on Sales Force within Rails using RESTForce
 test_files:
@@ -246,8 +246,10 @@ test_files:
 - spec/active_force/bulk/record_spec.rb
 - spec/active_force/bulk_spec.rb
 - spec/active_force/callbacks_spec.rb
+- spec/active_force/composite_batch_query_spec.rb
 - spec/active_force/field_spec.rb
 - spec/active_force/mapping_spec.rb
+- spec/active_force/query_notifications_spec.rb
 - spec/active_force/query_spec.rb
 - spec/active_force/sobject/includes_spec.rb
 - spec/active_force/sobject/select_spec.rb