active_force 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 657c5d9e979b06641cae8f6734a9a0371669dcc3fca816e89c0a23fca20537fb
-  data.tar.gz: c6e3646ea293a22d459faca15f8fbf9b16cbaf4482b7c38dc4e135dac22da6e7
+  metadata.gz: 1c4cc417eaaf0ad9a412c1a39374d80e4a723d0f8d6184eba87c09371e3ba56a
+  data.tar.gz: d8cdb8bc16ab43f8d1fbe4840788e412d5aa0ad3a25734cbc2b85d7138626c75
 SHA512:
-  metadata.gz: b9a1fb7822ad1950f32fc86e20e9e00cf29a5f471b2792eda9fe8ae9aae1db6f2b1817ac8fcf6fc9b0ec74ee351e62befb0aab8a6e83a7a5ec09a3761e656f85
-  data.tar.gz: 7f1cb6448305cef1fd185cce72571f1eff55aa3115444edf215dd031711fe6027b51922832392eb02a1e60a82b9d77616bffe271aad638344686122bdeae91c6
+  metadata.gz: c005126087818d2afa9ef019e537ae5920fea69f9275ba74293cbe97ea9335cfb62da1deedd1c58e707536357f45cf322dcfa48d38b6d007e89f5210dfaf86b2
+  data.tar.gz: 43623c0cda29edc52f3ccaddad50010a76d88417d6ebcbe5d80c2bd838518eddbaef217a41ec14c0e372ba50dbe8cad4cf3eaebe1f1f0998734bde19a4251d63

data/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## 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)
 

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

@@ -52,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
@@ -248,10 +248,20 @@ module ActiveForce
     def result
       soql = self.to_s
 
-      if soql.length >= ActiveForce.composite_batch_query_threshold
-        CompositeBatchQuery.call(soql, sfdc_client)
-      else
-        sfdc_client.query(soql)
+      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
 

data/lib/active_force/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveForce
-  VERSION = '0.26.0'
+  VERSION = '0.27.0'
 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_force
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Eloy Espinaco
@@ -198,6 +198,7 @@ files:
 - 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
@@ -233,7 +234,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Help you implement models persisting on Sales Force within Rails using RESTForce
 test_files:
@@ -248,6 +249,7 @@ test_files:
 - 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