jbr 3.5.1 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5c1536ff754171e5bafc8e5501088b0372c673c98e3891786b43da0a69f5c75
-  data.tar.gz: 61bf56b9de47ec4ada6e406967c36240a95351d50a007730ce2506c0d7244864
+  metadata.gz: a8a11f9cbda31f995ef0aa78f55db8502f7f5077fa1703db261f9a7705fea971
+  data.tar.gz: 6d178b20c67e47c33e5d4617b0fc1c8cc5637794de9ce3b4a94c0af407b8bab6
 SHA512:
-  metadata.gz: 52d0070f75aa56d58874e301c0bb11b8b78fb108ac2327617094f9ee3676302fb8b59dee89942203dc993305356a43165b0fb053ac0257f1cb0f1299949ad5b3
-  data.tar.gz: 73c45d7ed55f796c7e0068eb19c33bc07e0a1ac2359a594b12eca096b43e8bf86058e4f67b3f03877d02e337a87ee81be3efca500df6deb6b9470a175065bdbc
+  metadata.gz: c2696a88809c0e13f8da7b7b49a7cedb59bde16d695f233a5719cac00ff83af779a1aeca7ee106d518b0301ef89bb46049ed54fc86a9b4e6a28c216a5e6c57d7
+  data.tar.gz: 2a50c2a089b340ff61d0723a845d12abc653ef7606e80c9963e20ff62c830ec7541039becb9e4999b883dba6e61b5edb323f96435eca25d2ce1ae6f63866719f

data/CHANGELOG.md

@@ -1,3 +1,56 @@
+## [3.7.0] - 2026-08-17
+
+- [New] `store:`, for credentials several processes hold copies of. A queue of workers each
+  building its own `oauth_for` used to refresh a hundred times over when the access token
+  expired, each spending a refresh token the first had already spent — and Jobber calls a
+  spent one a dead grant, so all but one of them would mark the credentials invalid and the
+  whole connection would be discarded. With a store the refresh happens under the app's own
+  lock, against the credentials as they are at that moment, and a holder that finds the token
+  already replaced adopts it without asking Jobber anything
+- [New] `Jbr::Visits#find`, reaching one visit by the ID Jobber files it under, the way jobs
+  already could. An app importing many of them can walk the account for IDs alone and then
+  fetch each visit on its own
+- [Change] The refresh moved to `Jbr::Refreshing`, which is what `OAuth` includes to do it
+
+## [3.6.2] - 2026-08-17
+
+- [Change] Nothing in this gem sleeps any more. 3.6.0 waited out a refusal for cost and asked
+  again, and 3.2.0 spaced every request 0.12s from the one before — both of which put a worker
+  to sleep, often with a transaction open around it. A caller asking from a background job has
+  a queue that will bring the whole job back later, and that is worth more than a held worker,
+  so a refusal is raised and the decision is the caller's. `Jbr::Throttle` and
+  `GraphQL::Throttled` go with the waiting; the numbers a refusal reports stay in its message
+- [Fix] A mocked `find` answers with the job on `Jbr.mock.jobs` filed under that ID, falling
+  back to `Jbr.mock.job` as before. An app that lists jobs and then looks one of them up — one
+  request for the IDs, then one job at a time — used to get whichever single job it had mocked,
+  whatever ID it asked for
+- [Change] Without the request spacing, an app walking many pages is on its own about Jobber's
+  other limit, 2,500 requests every five minutes. Nothing here has come close to it: the
+  spacing was insurance against a walk that no longer exists
+
+## [3.6.1] - 2026-08-17
+
+- [Fix] 3.6.0 shipped without the two files it added, `graphql/throttled` and `jbr/asking`, so
+  requiring the gem raised `LoadError` and nothing worked at all. The gem's file list comes
+  from `git ls-files` and the release commit never added them. 3.6.0 is yanked
+
+## [3.6.0] - 2026-08-17
+
+- [Fix] A refusal for cost the bucket can recover from is waited out and asked again, up to
+  four times, rather than raised. A walk of many pages drains the bucket faster than it
+  refills and gets `Throttled (cost 1885, 1254 of 10000 available, restoring 500/s)` — 631
+  points short of a query the bucket holds five times over. The refusal prices the query, so
+  the throttle already knows the shortfall: 1.26 seconds at 500 a second, and the same
+  question is answered
+- [Change] Only a query costing more than the bucket *ever* holds is given up on, since
+  waiting cannot help it. Where Jobber names no ceiling, one wait is tried rather than the
+  worst assumed
+- [New] `GraphQL::Throttled`, a `GraphQL::Error` for a query refused over what it costs rather
+  than over anything about the query. It never leaves the gem — a caller still sees
+  `Jbr::Error` — but it is what tells the two refusals apart inside it
+- [Change] What credentials do when they ask Jobber something is `Jbr::Asking`, mixed into
+  `Jbr::OAuth`, which was over a hundred lines with the retry in it
+
 ## [3.5.1] - 2026-08-17
 
 - [Change] A line item is how many of what, and nothing else. `description` was answered and

data/README.md

@@ -26,6 +26,32 @@ Initialize with existing credentials:
 oauth = Jbr.oauth_for access_token:, refresh_token:, expires_at:, account_id:
 ```
 
+Where several processes hold copies of the same credentials — a queue of workers, each
+building its own — hand over a `store:` as well, and only one of them will ever spend the
+refresh token:
+
+```ruby
+oauth = Jbr.oauth_for account_id:, invalid_at:, store: credentials
+```
+
+The store is anything answering two methods. `exclusively` takes whatever lock the app keeps
+over those credentials and yields them *as they are right now*, read inside that lock; `write`
+records the ones Jobber handed back:
+
+```ruby
+def exclusively = with_lock { yield oauth_params }   # Active Record, in an app that has it
+
+def write(oauth) = update oauth: oauth
+```
+
+An expired access token is then refreshed once. Every other holder takes the lock, finds a
+token that is no longer the one it tried, adopts it, and asks Jobber nothing — where without a
+store each of them would spend a refresh token the first has already spent, and Jobber would
+call every one of those a dead grant.
+
+`exclusively` has to be exclusive against every **process** sharing the credentials, not just
+every thread: a `Mutex` satisfies this interface and fixes nothing on a fleet of workers.
+
 Access OAuth attributes:
 
 ```ruby
@@ -192,23 +218,23 @@ query never named a client.
 
 ### Rate limits
 
-Jobber holds an app to two limits at once: 2,500 requests every five minutes, and a bucket
-of query cost that drains as it is asked and refills at a rate it reports. Nothing has to be
-done about either — every request waits for itself:
+Jobber holds an app to two limits at once: 2,500 requests every five minutes, and a bucket of
+query cost that drains as it is asked and refills at a rate it reports. This gem does nothing
+about either — it never sleeps, and it never asks a second time. What it does is say exactly
+what happened, so the caller can decide:
 
-- It spaces itself 0.12 seconds from the request before, which is 2,500 spread evenly over
-  five minutes.
-- It reads `extensions.cost` off each answer, and where the bucket can no longer pay for a
-  page like the last one, it waits for the shortfall to refill at Jobber's own restore rate.
+```
+Throttled (cost 1885, 1254 of 10000 available, restoring 500/s)
+```
 
-A request that follows no other waits for nothing, so a single `find` is as quick as it ever
-was. Only a walk long enough to be a problem is slowed, and only by as much as it must be.
+That arrives as a `Jbr::Error`. 631 points short of a query the bucket holds five times over,
+which a second would have refilled — worth asking again. A cost above `maximumAvailable` is
+worth nothing but a smaller query. Either way the decision belongs to whoever called: from a
+background job, letting it fail so the queue brings it back is better than a worker asleep
+holding a transaction open.
 
-Where Jobber refuses for cost anyway, the `Jbr::Error` raised says what the query would have
-cost against what was available — `Throttled (cost 12400, 9500 of 10000 available, restoring
-500/s)` — so a query too big to ever run reads apart from a bucket that needed a moment. Every
-connection this gem asks for is bounded, because Jobber prices an unbounded one at its own
-maximum: twenty lines to a job, and twenty jobs or visits to a page.
+Every connection the gem asks for is bounded, to keep a query on the affordable side of that:
+twenty lines to a job, and twenty jobs or visits to a page.
 
 ### Events
 

data/lib/graphql/client.rb

@@ -16,16 +16,12 @@ module GraphQL
 
     # @param query [String] the GraphQL query string.
     # @param variables [Hash] the variables to interpolate into the query.
-    # @yield [Hash] the `extensions` the endpoint answered beside the data, where it did.
     # @return [Hash] the `data` portion of the GraphQL response.
     def query(query, variables: {})
       response = Net::HTTP.post @endpoint, { query:, variables: }.to_json, request_headers
       raise Unauthorized, response.body if response.code == '401'
       raise Error, response.body unless response.is_a? Net::HTTPSuccess
       body = JSON.parse(response.body)
-      # Before the refusal, not after it: an endpoint that reports what it will still answer
-      # reports it when it says no, which is when a caller most needs to know.
-      yield body['extensions'] if block_given?
       raise Error, refusal(body) if body['errors'].present?
       body.fetch('data')
     end
@@ -34,7 +30,7 @@ module GraphQL
 
     # What the endpoint refused, and — where it priced the refusal — what the query would have
     # cost against what was available. `Throttled` on its own leaves a caller unable to tell a
-    # query too big to ever run from a bucket that only needed a moment.
+    # query too big to ever run from a bucket that a moment would have refilled.
     def refusal(body)
       message = body['errors'].map { |error| error['message'] }.join '; '
       cost = body['extensions'].to_h['cost'].to_h

data/lib/jbr/mock/jobs.rb

@@ -1,8 +1,10 @@
 module Jbr
   # The jobs an app under test asked {Jbr.mock} to answer with.
   class Mock::Jobs < Jobs
-    # @return [Mock::Job] the one job the app named, whatever ID is asked for.
-    def find(_) = Mock::Job.new node: Jbr.mock.job
+    # The job filed under that ID where the app listed one, and otherwise the single job it
+    # named — which is every app that mocks a lookup without mocking a list.
+    # @return [Mock::Job] the job asked for.
+    def find(id) = Mock::Job.new node: listed(id) || Jbr.mock.job
 
     # @return [Enumerator<Mock::Job>] every job the app named.
     def each(&) = mocked(Jbr.mock.jobs).each(&)
@@ -20,5 +22,9 @@ module Jbr
     end
 
     def started?(job) = job[:scheduled_at] ? job[:scheduled_at] <= Time.now : false
+
+    # Only a real list is looked through: an app that mocked the list as something raising
+    # was mocking the walk failing, and a lookup is a question of its own.
+    def listed(id) = (Jbr.mock.jobs.find { |job| job[:id] == id } if Jbr.mock.jobs.is_a? Array)
   end
 end

data/lib/jbr/mock/visits.rb

@@ -10,6 +10,9 @@ module Jbr
     # @return [Enumerator<Mock::Visit>] those it dated before now.
     def past = mocked Jbr.mock.visits.select { |visit| started? visit }
 
+    # @return [Mock::Visit] the visit the app listed under that ID.
+    def find(id) = Mock::Visit.new node: listed(id)
+
   private
 
     def mocked(visits)
@@ -17,5 +20,7 @@ module Jbr
     end
 
     def started?(visit) = visit[:starts_at] ? visit[:starts_at] <= Time.now : false
+
+    def listed(id) = Jbr.mock.visits.to_a.find { |visit| visit[:id] == id }.to_h
   end
 end

data/lib/jbr/oauth.rb

@@ -1,6 +1,8 @@
 module Jbr
   # Credentials for one Jobber account, and the gateway to all they read or write.
   class OAuth
+    include Refreshing
+
     # The mutation that revokes the app on the account.
     DISCONNECT_MUTATION = <<~GRAPHQL
       mutation Disconnect {
@@ -11,13 +13,15 @@ module Jbr
       }
     GRAPHQL
 
-    # @param credentials [Hash] the tokens, their expiry, the account and when it went bad.
+    # @param credentials [Hash] the tokens, their expiry, the account, when it went bad, and
+    #   the `store:` these are kept in, where processes share them. See {Refreshing}.
     def initialize(credentials = {})
       @access_token = credentials[:access_token]
       @refresh_token = credentials[:refresh_token]
       @expires_at = credentials[:expires_at]
       @account_id = credentials[:account_id]
       @invalid_at = credentials[:invalid_at]
+      @store = credentials[:store]
     end
 
     # The credentials as Jobber last gave them, plus the moment a refusal to refresh landed.
@@ -34,11 +38,13 @@ module Jbr
     def requests = Request.new oauth: self
     def visits = Visits.new oauth: self
 
-    # Run a statement, waiting for what Jobber will still answer and refreshing a stale token.
+    # Run a statement, refreshing a stale token. Nothing here ever sleeps: where Jobber holds
+    # the app to a limit it says so, and a caller asking from a background job has a queue that
+    # will bring the whole job back later — which is worth more than a worker asleep holding a
+    # transaction open.
     # @return [Hash] the data Jobber answered, or empty when the credentials are dead.
     def query(statement, variables: {})
-      throttle.wait
-      client.query(statement, variables: variables) { |extensions| throttle.read extensions }
+      client.query statement, variables: variables
     rescue GraphQL::Unauthorized
       refresh ? retry : {}
     rescue GraphQL::Error => error
@@ -76,18 +82,6 @@ module Jbr
 
   private
 
-    def throttle = @throttle ||= Throttle.new
-
-    def refresh
-      output = self.class.post refresh_token: @refresh_token, grant_type: 'refresh_token'
-      @access_token = output[:access_token]
-      @refresh_token = output[:refresh_token]
-      @expires_at = output[:expires_at]
-    rescue Refused
-      @invalid_at = Time.now
-      false
-    end
-
     def client
       GraphQL::Client.new endpoint: 'https://api.getjobber.com/api/graphql',
         token: @access_token, headers: headers

data/lib/jbr/refreshing.rb

@@ -0,0 +1,48 @@
+module Jbr
+  # What credentials do when Jobber says the access token is stale, and how they do it safely
+  # where many processes hold copies of the same ones: through a store, only one of them asks
+  # Jobber for a new token and the rest take the one it wrote.
+  module Refreshing
+  private
+
+    # With no store there is nobody to compare against: refresh, and leave what we end up
+    # holding for the caller to persist.
+    def refresh
+      return exchange unless @store
+
+      @store.exclusively { |stored| renew stored }
+    end
+
+    # Under the store's lock, holding what it says right now. A token that is no longer the one
+    # we tried is one somebody else has already replaced, and adopting it asks Jobber nothing —
+    # which is what keeps a queue of workers from refreshing a hundred times over, each with a
+    # refresh token the first of them has already spent.
+    def renew(stored)
+      return adopt stored if stored[:access_token] != @access_token
+
+      @refresh_token = stored[:refresh_token]
+      exchange.tap { |renewed| @store.write self if renewed }
+    end
+
+    def exchange
+      adopt self.class.post(refresh_token: @refresh_token, grant_type: 'refresh_token')
+    rescue Refused
+      refused
+    end
+
+    def adopt(credentials)
+      @access_token = credentials[:access_token]
+      @refresh_token = credentials[:refresh_token]
+      @expires_at = credentials[:expires_at]
+      true
+    end
+
+    # Refused while holding the freshest refresh token there is, so the grant itself is dead
+    # rather than our copy being behind.
+    def refused
+      @invalid_at = Time.now
+      @store&.write self
+      false
+    end
+  end
+end

data/lib/jbr/version.rb

@@ -1,5 +1,5 @@
 # A Ruby client for the Jobber API.
 module Jbr
   # The version of this gem.
-  VERSION = '3.5.1'
+  VERSION = '3.7.0'
 end

data/lib/jbr/visits.rb

@@ -16,8 +16,25 @@ module Jbr
     # @return [Enumerator<Visit>] the visits that started before now.
     def past = walk until_now
 
+    # Shadows Enumerable#find on purpose, the way jobs do: a visit is reached by the ID Jobber
+    # files it under, not by asking every visit on the account whether it is the one.
+    # @param id [String] the Jobber ID of the visit.
+    # @return [Visit, nil] nil when Jobber has no visit under that ID.
+    def find(id)
+      node = @oauth.query(one, variables: { id: id })['visit']
+      Visit.new node: node if node
+    end
+
   private
 
+    def one
+      <<~GRAPHQL
+        query($id: EncodedId!) {
+          visit(id: $id) { #{FIELDS} #{selections} }
+        }
+      GRAPHQL
+    end
+
     # Twenty a page, the same as jobs: Jobber prices a query by its page size, and what an
     # includes brings back is charged for on top of every row of it.
     def page

data/lib/jbr.rb

@@ -19,13 +19,13 @@ require 'jbr/url'
 require 'jbr/error'
 require 'jbr/refused'
 require 'jbr/token'
+require 'jbr/refreshing'
 # Phone before Cliental, and Cliental before the records that include it: what each asks
 # Jobber for about a client is built as they load.
 require 'jbr/phone'
 require 'jbr/cliental'
 require 'jbr/named'
 require 'jbr/resource'
-require 'jbr/throttle'
 require 'jbr/request'
 require 'jbr/oauth'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 3.5.1
+  version: 3.7.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -140,10 +140,10 @@ files:
 - lib/jbr/properted.rb
 - lib/jbr/property.rb
 - lib/jbr/quote.rb
+- lib/jbr/refreshing.rb
 - lib/jbr/refused.rb
 - lib/jbr/request.rb
 - lib/jbr/resource.rb
-- lib/jbr/throttle.rb
 - lib/jbr/token.rb
 - lib/jbr/url.rb
 - lib/jbr/version.rb

data/lib/jbr/throttle.rb

@@ -1,44 +0,0 @@
-module Jbr
-  # How much Jobber will still answer, and how long to wait before asking again. Jobber holds
-  # an app to two limits at once, and this keeps both: a count of requests over a window, and
-  # a bucket of query cost that drains as it is asked and refills at a rate it reports.
-  class Throttle
-    # Jobber answers 2,500 requests every 5 minutes, which is one every 0.12 seconds. Spacing
-    # them is what keeps a walk of many pages under the count, whatever each page costs.
-    SPACING = 300.0 / 2_500
-
-    # @return [Float] the seconds waited, which is zero where nothing was owed.
-    def wait
-      owed = [ spacing_owed, restore_owed ].max
-      sleep owed if owed.positive?
-      @asked_at = Time.now
-      owed
-    end
-
-    # Takes in what the answer said it had left. Jobber reports the bucket beside the data,
-    # so what the next caller may ask for is known before they ask for it.
-    # @param extensions [Hash, nil] the +extensions+ Jobber answered beside the data.
-    def read(extensions)
-      cost = extensions.to_h['cost'].to_h
-      status = cost['throttleStatus'].to_h
-      # What a refused query would have cost is what it costs: Jobber prices it either way,
-      # and only an answered one reports an actual.
-      @cost = (cost['actualQueryCost'] || cost['requestedQueryCost']).to_f
-      @available = status['currentlyAvailable'].to_f
-      @restore_rate = status['restoreRate'].to_f
-    end
-
-  private
-
-    # Nothing is owed to the first caller: a request that follows no other is not too soon.
-    def spacing_owed = (@asked_at ? [ SPACING - (Time.now - @asked_at), 0.0 ].max : 0.0)
-
-    # What the last answer cost is what the next one is taken to cost, since a walk asks the
-    # same query of every page. Where the bucket cannot pay for it, wait for it to refill.
-    def restore_owed
-      return 0.0 unless @restore_rate.to_f.positive? && @available.to_f < @cost.to_f
-
-      (@cost - @available) / @restore_rate
-    end
-  end
-end