jbr 3.6.1 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8ab569aab529193190b37620954eb2e95db5ac39ccb2a085a7caa2b6cf66981
-  data.tar.gz: 4d331b9c225a2d0fb8a978f166985f416528a23eac283c4afb31924aecf7bc8b
+  metadata.gz: a8a11f9cbda31f995ef0aa78f55db8502f7f5077fa1703db261f9a7705fea971
+  data.tar.gz: 6d178b20c67e47c33e5d4617b0fc1c8cc5637794de9ce3b4a94c0af407b8bab6
 SHA512:
-  metadata.gz: fbe6e4b68d03262584a83279ca00eff9a4a5886413498d5db6cbec643e070d12a863188914e95c87a9365fe8f7aa419796c4238824d3346847fdbbd71960c74e
-  data.tar.gz: c0a9624a47f0c4f3706acdabf95bab82cb9d6e2deef035e88edb08daa89d4cdb686bf6489ea6e3c5fcd5b67dcc2cae4388ed19d4f6db036144366a6bcf995864
+  metadata.gz: c2696a88809c0e13f8da7b7b49a7cedb59bde16d695f233a5719cac00ff83af779a1aeca7ee106d518b0301ef89bb46049ed54fc86a9b4e6a28c216a5e6c57d7
+  data.tar.gz: 2a50c2a089b340ff61d0723a845d12abc653ef7606e80c9963e20ff62c830ec7541039becb9e4999b883dba6e61b5edb323f96435eca25d2ce1ae6f63866719f

data/CHANGELOG.md

@@ -1,3 +1,33 @@
+## [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

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,31 +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:
-
-- 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.
-
-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.
-
-Where Jobber refuses anyway, the refusal says what the query would have cost against what was
-available, and what happens next follows from those two numbers:
+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:
 
 ```
 Throttled (cost 1885, 1254 of 10000 available, restoring 500/s)
 ```
 
-631 points short of a query the bucket holds five times over, so the shortfall is waited out —
-1.26 seconds at 500 a second — and the same question asked again, up to four times. Only a
-query costing more than the bucket *ever* holds is given up on, since no wait would help it;
-that one arrives as a `Jbr::Error` carrying the line above. Every connection this 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.
+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.
+
+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,37 +16,21 @@ 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 refusal_for(body), refusal(body) if body['errors'].present?
+      raise Error, refusal(body) if body['errors'].present?
       body.fetch('data')
     end
 
   private
 
-    # Refused for cost, or refused for the query. An endpoint that priced the query above what
-    # was left says so by naming the code, and says it again in the two numbers it reports —
-    # either is enough, since only one of them is documented and only one has been seen.
-    def refusal_for(body)
-      cost = body['extensions'].to_h['cost'].to_h
-      available = cost['throttleStatus'].to_h['currentlyAvailable']
-      coded = body['errors'].any? { |error| error.to_h.dig('extensions', 'code') == 'THROTTLED' }
-      priced = available && cost['requestedQueryCost'].to_f > available.to_f
-
-      coded || priced ? Throttled : Error
-    end
-
     # 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,7 +1,7 @@
 module Jbr
   # Credentials for one Jobber account, and the gateway to all they read or write.
   class OAuth
-    include Asking
+    include Refreshing
 
     # The mutation that revokes the app on the account.
     DISCONNECT_MUTATION = <<~GRAPHQL
@@ -13,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.
@@ -36,6 +38,22 @@ module Jbr
     def requests = Request.new oauth: self
     def visits = Visits.new oauth: self
 
+    # 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: {})
+      client.query statement, variables: variables
+    rescue GraphQL::Unauthorized
+      refresh ? retry : {}
+    rescue GraphQL::Error => error
+      # The transport's own class never leaves the gem: a caller told to rescue `Jbr::Error`
+      # was not catching a throttle, a 500 or an unreadable answer, and had its own job blow
+      # up instead of hearing that Jobber would not answer.
+      raise Error, error.message
+    end
+
     # Delete a token. If the token is invalid, do nothing.
     def delete
       client.query DISCONNECT_MUTATION
@@ -64,16 +82,6 @@ module Jbr
 
   private
 
-    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.6.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

@@ -11,7 +11,6 @@ require 'active_support/core_ext/array/conversions'
 
 require 'graphql/error'
 require 'graphql/unauthorized'
-require 'graphql/throttled'
 require 'graphql/client'
 
 require 'jbr/mock'
@@ -20,14 +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/asking'
 require 'jbr/request'
 require 'jbr/oauth'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 3.6.1
+  version: 3.7.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -106,11 +106,9 @@ files:
 - README.md
 - lib/graphql/client.rb
 - lib/graphql/error.rb
-- lib/graphql/throttled.rb
 - lib/graphql/unauthorized.rb
 - lib/jbr.rb
 - lib/jbr/account.rb
-- lib/jbr/asking.rb
 - lib/jbr/client.rb
 - lib/jbr/cliental.rb
 - lib/jbr/error.rb
@@ -142,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/graphql/throttled.rb

@@ -1,6 +0,0 @@
-module GraphQL
-  # An endpoint refusing a query for what it costs rather than for anything about the query
-  # itself. Worth telling apart: the same query may be answered a moment later.
-  class Throttled < Error
-  end
-end

data/lib/jbr/asking.rb

@@ -1,40 +0,0 @@
-module Jbr
-  # What credentials do when they ask Jobber something: pace the request against both limits
-  # Jobber holds an app to, wait out a refusal it can recover from, and refresh a token that
-  # went stale on the way.
-  module Asking
-    # How many times a query refused for cost is asked again. Once is the answer where the
-    # bucket only had to refill, since the wait is worked out to cover exactly the shortfall.
-    # The rest are for a bucket the whole app shares: another process may drain it again while
-    # this one waits, and each attempt costs only the seconds Jobber says it needs.
-    ATTEMPTS = 4
-
-    # Run a statement, waiting for what Jobber will still answer and refreshing a stale token.
-    # @return [Hash] the data Jobber answered, or empty when the credentials are dead.
-    def query(statement, variables: {})
-      attempts = 0
-      begin
-        throttle.wait
-        client.query(statement, variables: variables) { |extensions| throttle.read extensions }
-      rescue GraphQL::Unauthorized
-        refresh ? retry : {}
-      rescue GraphQL::Throttled => error
-        # The refusal priced the query, so the throttle now knows the shortfall and `wait` at
-        # the top of the retry sits out exactly that. Only a query costing more than the bucket
-        # ever holds is hopeless; the rest is a walk that asked a moment too early.
-        raise Error, error.message unless throttle.affordable? && (attempts += 1) < ATTEMPTS
-
-        retry
-      rescue GraphQL::Error => error
-        # The transport's own class never leaves the gem: a caller told to rescue `Jbr::Error`
-        # was not catching a throttle, a 500 or an unreadable answer, and had its own job blow
-        # up instead of hearing that Jobber would not answer.
-        raise Error, error.message
-      end
-    end
-
-  private
-
-    def throttle = @throttle ||= Throttle.new
-  end
-end

data/lib/jbr/throttle.rb

@@ -1,52 +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
-      @maximum = status['maximumAvailable'].to_f
-      @restore_rate = status['restoreRate'].to_f
-    end
-
-    # Whether the bucket could ever pay for the query it last priced. A refusal is worth
-    # waiting out where it could: the shortfall refills and the same query goes through. Where
-    # the query costs more than the bucket ever holds, no wait will do — and where Jobber said
-    # nothing about the ceiling, one attempt at waiting is cheaper than assuming the worst.
-    # @return [Boolean] false only where the ceiling is known and the query is over it.
-    def affordable? = !@maximum.to_f.positive? || @cost.to_f <= @maximum
-
-  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