rails-contact 0.1.17 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47e4ae3ee8279318a713c01eabbc5e85416f1f9847351aaf4fd56e3fe2ea51e1
-  data.tar.gz: c06b8d14fe450aa764ce09216db49c8a0a2877842099d0571cd965f2ff88ddd7
+  metadata.gz: f986b7426ce2b99924283ea2343ef48ed1f6f4c50c6e2763ba50f03be99b9a93
+  data.tar.gz: 8f04a3f04fdb7d9bb6921efa14df565be9b82029c03c522da8ac6b111e70e3f9
 SHA512:
-  metadata.gz: ace1203d3ff1d490b519b14175088dc483ac71780bf1186a233ef6e31a522927df60d6d95c8ee25ea9f6074d53a7a4887ae9b8cc8af9aab67119269e3eec3f85
-  data.tar.gz: ad9e1d740f6cd540a3528accaa1cf3e35d898df89da18312916ee3ba23b79cd6c93ab28a347eff56fa39335bbe464b3e69343a16c930c521bde8926646a2d712
+  metadata.gz: 7426fa7a4faf079dba58377b115f5b612463f55c7ab66aef7f4eec65fbb8b258c84dc91c148d63bd9b76e59bc08387b8df34052f4226ee066cde9eeba1eec916
+  data.tar.gz: 916da6b6432f11a44c8b260964f81feaa5092b2da83d4a5c9433d25c786d4e57d19d1b6f402a1c2ddaf043a8a8dbb69ea0da7308d82016323393d398e0a7b072

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.1.19
+
+- **Result counts are exact again, and bounded.** 0.1.17 replaced large exact
+  counts with the PostgreSQL planner's row estimate, which the index then
+  printed as if it were a count: a filtered list of 364 contacts reported
+  "Showing 1-25 of 1,005" across 41 pages, most of them empty, and host apps
+  reading `total_count` sized outbound campaigns off the same guess. Estimates
+  are worst exactly where they matter - a value the last `ANALYZE` has not
+  sampled (a freshly imported batch) falls back to `rows / n_distinct`.
+  `count_for` now runs `COUNT(*)` over the matching rows capped at
+  `MAX_EXACT_COUNT + 1` (10,000), with `ORDER BY` and eager-loading stripped
+  from the subquery so the database stops scanning at the `LIMIT` - the
+  full-table pass the estimate existed to avoid never happens, and every
+  realistic filtered list gets a true number. Past the cap,
+  `Search::Result#count_capped?` is true, `total_count` is the cap, and the
+  new `contact_count_label` helper renders it as "10,000+". `@count_capped` is
+  exposed to views alongside `@total_count`.
+
+## 0.1.18
+
+- **The `city` filter is a multi-select.** `?city[]=Pune&city[]=Delhi` now
+  filters on several current cities at once, matching how `region` and
+  `csv_import_id` already behave. The database backend always handled an
+  array (`where(current_city: [...])`) — only the parameter permit was
+  scalar, which silently dropped every value but the last. Blank entries
+  (the hidden option a `<select multiple>` always submits) are stripped, and
+  an old single-value bookmark (`?city=Pune`) is coerced to a one-element
+  array, so no existing link changes meaning. The database backend now drops
+  blank entries from `city`/`region` itself as well, so a caller reaching it
+  directly gets "no filter" from an untouched multi-select instead of zero
+  rows.
+
 ## 0.1.17
 
 - **Database backend free-text search is now prefix search.** `q` matches

data/app/controllers/rails/contact/contacts_controller.rb

@@ -17,6 +17,9 @@ module Rails
         ).call
         @contacts = result.records
         @total_count = result.total_count
+        # A capped count is a floor, not a total — the pager and any audience
+        # panel built on @total_count must render it as "N+".
+        @count_capped = result.count_capped?
         @page = result.page
         @per_page = result.per_page
         @total_pages = result.total_pages
@@ -136,7 +139,6 @@ module Rails
         metadata_scalars << :sort if config.metadata_sorts.any?
 
         permitted = params.permit(
-          :city,
           :sync_eligible,
           :starred,
           :travel_date_start,
@@ -144,16 +146,17 @@ module Rails
           :contact_created_at_start,
           :contact_created_at_end,
           *metadata_scalars,
+          city: [],
           region: [],
           csv_import_id: [],
           **metadata_arrays.index_with { [] }
         )
 
-        ([ :region, :csv_import_id ] + metadata_arrays).each { |key| normalize_multi_select!(permitted, key) }
+        ([ :city, :region, :csv_import_id ] + metadata_arrays).each { |key| normalize_multi_select!(permitted, key) }
         permitted
       end
 
-      # region, csv_import_id and every configured :values metadata filter are
+      # city, region, csv_import_id and every configured :values metadata filter are
       # multi-selects: a <select multiple> submits param[] (an array) plus a
       # hidden param[]="" that Rails always sends, so the blank must be
       # stripped — otherwise IN ('', 'x') matches every blank-valued row.

data/app/helpers/rails/contact/application_helper.rb

@@ -5,6 +5,13 @@ module Rails
         [ contact.given_name, contact.family_name ].map { |part| part.to_s.first.to_s.upcase }.join
       end
 
+      # A count the backend stopped at its cap is a floor, not a total, so it
+      # renders as "10,000+". Rendering it plain reads as an exact number and
+      # is how a guessed 1,005 once sized a WhatsApp broadcast.
+      def contact_count_label(count, capped = false)
+        "#{number_with_delimiter(count.to_i)}#{'+' if capped}"
+      end
+
       def contact_chip(value)
         value.presence || "-"
       end

data/app/views/rails/contact/_index_pagination.html.erb

@@ -4,7 +4,7 @@
       <% start_i = (@page - 1) * @per_page + 1 %>
       <% end_i = [ @page * @per_page, @total_count ].min %>
       Showing <span class="font-medium text-gray-900"><%= start_i %>–<%= end_i %></span>
-      of <span class="font-medium text-gray-900"><%= number_with_delimiter(@total_count) %></span>
+      of <span class="font-medium text-gray-900"><%= contact_count_label(@total_count, @count_capped) %></span>
       <% if @per_page.present? && @per_page > 0 %>
         <span class="text-gray-500">(<%= @per_page %> per page)</span>
       <% end %>

data/lib/rails/contact/search/backends/database.rb

@@ -22,9 +22,12 @@ module Rails
             scope = apply_filters(scope, filters)
             scope = apply_query(scope, query) if query.present?
 
+            total_count, count_capped = count_for(scope)
+
             Search::Result.new(
               records: scope.offset(offset).limit(per_page).to_a,
-              total_count: count_for(scope),
+              total_count: total_count,
+              count_capped: count_capped,
               page: page,
               per_page: per_page
             )
@@ -65,33 +68,33 @@ module Rails
           end
 
           # Exact COUNT(*) walks every matching row and was one of the two
-          # full-table passes behind 40-second index pages. On PostgreSQL,
-          # large counts come from the planner's row estimate instead —
-          # milliseconds regardless of table size. Small results (under
-          # APPROX_COUNT_THRESHOLD) still count exactly: cheap to do, and
-          # operators expect precise numbers on short lists. Estimates are
-          # for pager display only — never feed them into arithmetic.
-          APPROX_COUNT_THRESHOLD = 1_000
-
+          # full-table passes behind 40-second index pages; the planner
+          # estimate that replaced it then printed guesses as counts — a sheet
+          # of 364 contacts read "1,005 · Page 1 / 41", and the same number
+          # sized a WhatsApp broadcast. So count exactly, but bounded:
+          # COUNT(*) over the matching rows capped at MAX_EXACT_COUNT + 1 lets
+          # the database stop scanning at the LIMIT, so no view pays a
+          # full-table pass, while every realistic filtered list gets a true
+          # number. Past the cap the caller is told so and shows "10,000+".
+          MAX_EXACT_COUNT = 10_000
+
+          # Returns [count, capped]. count never exceeds MAX_EXACT_COUNT.
           def count_for(scoped)
-            return scoped.count unless postgres?(scoped)
+            total = scoped.klass.unscoped.from(bounded_scope(scoped), :bounded_count).count
 
-            estimate = planner_estimate(scoped)
-            return scoped.count if estimate.nil? || estimate < APPROX_COUNT_THRESHOLD
-
-            estimate
+            [ [ total, MAX_EXACT_COUNT ].min, total > MAX_EXACT_COUNT ]
           end
 
-          # EXPLAIN (FORMAT JSON) without ANALYZE executes nothing; the
-          # relation's own to_sql carries its bound values inlined, so there
-          # is no injection surface beyond what the scope already is.
-          # Estimates track table statistics, so they are only as fresh as
-          # the last ANALYZE.
-          def planner_estimate(scoped)
-            plan = scoped.klass.connection.select_value("EXPLAIN (FORMAT JSON) #{scoped.to_sql}")
-            JSON.parse(plan.to_s).dig(0, "Plan", "Plan Rows")
-          rescue ActiveRecord::StatementInvalid, JSON::ParserError
-            nil
+          # ORDER BY is stripped rather than kept: recent_first orders by
+          # updated_at and a metadata sort is a CASE expression — either one
+          # makes the planner sort the whole matching set before it can honour
+          # the LIMIT, which is the full pass this is here to avoid. SELECT 1
+          # keeps it a bare row scan, and eager-loading has no bearing on how
+          # many rows match.
+          def bounded_scope(scoped)
+            scoped.except(:order, :includes, :eager_load, :preload)
+                  .select("1")
+                  .limit(MAX_EXACT_COUNT + 1)
           end
 
           # Escape LIKE metacharacters (% _ \) so a user typing "%" can't widen
@@ -106,8 +109,16 @@ module Rails
 
           def apply_filters(scope, filters)
             scoped = scope
-            scoped = scoped.where(current_city: filters["city"]) if filters["city"].present?
-            scoped = scoped.where(region_name: filters["region"]) if filters["region"].present?
+            # city and region are multi-selects: one value or many. Blanks are
+            # dropped here as well as in the controller — an untouched
+            # <select multiple> submits [""], and `where(col: [""])` would
+            # return nothing at all rather than "no city filter". A caller
+            # reaching the backend directly gets the same answer as one coming
+            # through filter_params.
+            %w[city region].zip(%i[current_city region_name]).each do |key, column|
+              values = Array(filters[key]).map(&:to_s).reject(&:blank?)
+              scoped = scoped.where(column => values) if values.any?
+            end
             scoped = scoped.where(starred: ActiveModel::Type::Boolean.new.cast(filters["starred"])) if filters["starred"].present?
             if filters["sync_eligible"].present?
               scoped = scoped.where(sync_eligible: ActiveModel::Type::Boolean.new.cast(filters["sync_eligible"]))

data/lib/rails/contact/search/result.rb

@@ -1,7 +1,14 @@
 module Rails
   module Contact
     module Search
-      Result = Struct.new(:records, :total_count, :page, :per_page, keyword_init: true) do
+      Result = Struct.new(:records, :total_count, :page, :per_page, :count_capped, keyword_init: true) do
+        # True when the backend stopped counting at its cap, so total_count is
+        # a floor ("10,000+") rather than the whole set. Views must say so —
+        # a capped number rendered plain reads as an exact count.
+        def count_capped?
+          !!count_capped
+        end
+
         def total_pages
           return 0 if total_count.zero? || per_page.zero?
 

data/lib/rails/contact/version.rb

@@ -1,5 +1,5 @@
 module Rails
   module Contact
-    VERSION = "0.1.17"
+    VERSION = "0.1.19"
   end
 end

data/spec/controllers/contacts_controller_spec.rb

@@ -4,16 +4,26 @@ RSpec.describe Rails::Contact::ContactsController do
   let(:controller) { described_class.new }
 
   describe "private filter params" do
-    it "permits city/sync_eligible and coerces a scalar region to an array" do
+    # city joined region as a multi-select in 0.1.18, so a scalar from an old
+    # bookmark is coerced to a one-element array rather than kept as a string.
+    it "permits sync_eligible and coerces scalar city/region to arrays" do
       controller.params = ActionController::Parameters.new(city: "Delhi", region: "Europe", sync_eligible: "true", x: "1")
       permitted = controller.send(:filter_params)
-      expect(permitted.to_h).to eq({ "city" => "Delhi", "region" => [ "Europe" ], "sync_eligible" => "true" })
+      expect(permitted.to_h).to eq({ "city" => [ "Delhi" ], "region" => [ "Europe" ], "sync_eligible" => "true" })
     end
 
-    it "permits multi-select region[] and csv_import_id[] arrays" do
-      controller.params = ActionController::Parameters.new(region: [ "Europe", "Asia" ], csv_import_id: [ "5", "7" ])
+    it "permits multi-select city[], region[] and csv_import_id[] arrays" do
+      controller.params = ActionController::Parameters.new(city: [ "Pune", "Delhi" ], region: [ "Europe", "Asia" ], csv_import_id: [ "5", "7" ])
       permitted = controller.send(:filter_params)
-      expect(permitted.to_h).to eq({ "region" => [ "Europe", "Asia" ], "csv_import_id" => [ "5", "7" ] })
+      expect(permitted.to_h).to eq({ "city" => [ "Pune", "Delhi" ], "region" => [ "Europe", "Asia" ], "csv_import_id" => [ "5", "7" ] })
+    end
+
+    it "strips the blank a city multi-select submits, and drops it when only blanks arrive" do
+      controller.params = ActionController::Parameters.new(city: [ "", "Pune" ])
+      expect(controller.send(:filter_params).to_h).to eq({ "city" => [ "Pune" ] })
+
+      controller.params = ActionController::Parameters.new(city: [ "" ])
+      expect(controller.send(:filter_params).to_h).to eq({})
     end
 
     it "strips the hidden blank a <select multiple> submits" do

data/spec/helpers/application_helper_spec.rb

@@ -6,6 +6,11 @@ RSpec.describe Rails::Contact::ApplicationHelper, type: :helper do
     expect(helper.contact_initials(contact)).to eq("AS")
   end
 
+  it "renders an exact count plainly and a capped one as a floor" do
+    expect(helper.contact_count_label(1_005)).to eq("1,005")
+    expect(helper.contact_count_label(10_000, true)).to eq("10,000+")
+  end
+
   it "returns fallback chip for blank values" do
     expect(helper.contact_chip(nil)).to eq("-")
     expect(helper.contact_chip("x")).to eq("x")

data/spec/search/database_backend_spec.rb

@@ -29,6 +29,28 @@ RSpec.describe Rails::Contact::Search::Backends::Database do
     end
   end
 
+  # City became a multi-select in 0.1.18. The backend always accepted an array
+  # here — what was missing was a permit that let one through.
+  describe "city filter (multi-select)" do
+    # Distinct from the factory default ("Delhi"), so alice/bob/carol above
+    # can't drift into these expectations.
+    let!(:pune)   { create(:rails_contact_contact, given_name: "Pia", current_city: "Pune") }
+    let!(:jaipur) { create(:rails_contact_contact, given_name: "Dev", current_city: "Jaipur") }
+    let!(:kochi)  { create(:rails_contact_contact, given_name: "Mira", current_city: "Kochi") }
+
+    it "matches contacts in every selected city (array -> IN)" do
+      expect(records("city" => [ "Pune", "Jaipur" ])).to match_array([ pune, jaipur ])
+    end
+
+    it "matches a single city exactly as before (scalar)" do
+      expect(records("city" => "Kochi")).to match_array([ kochi ])
+    end
+
+    it "applies no constraint when the selection is blank only" do
+      expect(records("city" => [ "" ]).count).to eq(Rails::Contact::Contact.count)
+    end
+  end
+
   describe "query sanitization" do
     def search_for(query)
       described_class.new.search(query, {}, page: 1, per_page: 25).records
@@ -107,50 +129,49 @@ RSpec.describe Rails::Contact::Search::Backends::Database do
   describe "result counting" do
     let(:backend) { described_class.new }
 
-    it "counts exactly on non-PostgreSQL adapters" do
-      result = backend.search("", {}, page: 1, per_page: 25)
-      expect(result.total_count).to eq(Rails::Contact::Contact.count)
+    def result(filters = {}, per_page: 25)
+      backend.search("", filters, page: 1, per_page: per_page)
     end
 
-    context "when the adapter reports PostgreSQL" do
-      before { allow(backend).to receive(:postgres?).and_return(true) }
-
-      it "uses the planner estimate at or above the threshold" do
-        allow(backend).to receive(:planner_estimate).and_return(50_000)
+    it "counts a filtered scope exactly" do
+      # The production bug: a sheet holding one contact reported four figures
+      # because the count was a planner estimate, not a count.
+      expect(result({ "csv_import_id" => [ "imp_1" ] }).total_count).to eq(1)
+    end
 
-        expect(backend.search("", {}, page: 1, per_page: 25).total_count).to eq(50_000)
-      end
+    it "counts the unfiltered scope exactly" do
+      expect(result.total_count).to eq(Rails::Contact::Contact.count)
+    end
 
-      it "counts exactly below the threshold" do
-        allow(backend).to receive(:planner_estimate).and_return(5)
+    it "reports pages from the real count" do
+      expect(result({}, per_page: 2).total_pages).to eq(2)
+    end
 
-        expect(backend.search("", {}, page: 1, per_page: 25).total_count)
-          .to eq(Rails::Contact::Contact.count)
-      end
+    it "counts the same under a metadata sort" do
+      # ORDER BY is stripped inside the count subquery so the LIMIT can
+      # short-circuit; stripping it must not change the answer.
+      config = Rails::Contact.configuration
+      original = config.metadata_sorts
+      config.metadata_sorts = { "score" => { key: "score" } }
 
-      it "falls back to an exact count when the planner call fails" do
-        # No stub on planner_estimate: on this SQLite harness the real
-        # EXPLAIN (FORMAT JSON) raises and the rescue returns nil.
-        expect(backend.search("", {}, page: 1, per_page: 25).total_count)
-          .to eq(Rails::Contact::Contact.count)
-      end
+      expect(result({ "sort" => "score" }).total_count).to eq(3)
+    ensure
+      config.metadata_sorts = original
     end
 
-    describe "#planner_estimate" do
-      let(:scope) { Rails::Contact::Contact.all }
-
-      it "reads Plan Rows from EXPLAIN (FORMAT JSON)" do
-        allow(scope.klass.connection).to receive(:select_value)
-          .with(/\AEXPLAIN \(FORMAT JSON\)/)
-          .and_return('[{"Plan": {"Plan Rows": 123456}}]')
+    context "when more rows match than the cap" do
+      before { stub_const("#{described_class}::MAX_EXACT_COUNT", 2) }
 
-        expect(backend.send(:planner_estimate, scope)).to eq(123_456)
+      it "clamps the count to the cap and flags it" do
+        expect(result.total_count).to eq(2)
+        expect(result.count_capped?).to be(true)
       end
 
-      it "returns nil on malformed planner output" do
-        allow(scope.klass.connection).to receive(:select_value).and_return("not json")
+      it "does not flag a set that exactly fills the cap" do
+        carol.destroy!
 
-        expect(backend.send(:planner_estimate, scope)).to be_nil
+        expect(result.total_count).to eq(2)
+        expect(result.count_capped?).to be(false)
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-contact
 version: !ruby/object:Gem::Version
-  version: 0.1.17
+  version: 0.1.19
 platform: ruby
 authors:
 - Kshitiz Sinha