booqable 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13ee5f72ca221d2613d8691dd8c04fa189a38fbed8276b60878d2cce4c7f4f23
-  data.tar.gz: 54028d30a657d3651ad0d49fab923efba00e09fa9f0d2e36906e8cf068975abd
+  metadata.gz: ce7d8b0be4851e4e78229078331a2f73cbe7cb7702c1555df9dec0903be28d0e
+  data.tar.gz: c79ed318eb3a38534291ef5e4abeb6a5749c7a2684bcd1befbf43d6f7f1d0e8a
 SHA512:
-  metadata.gz: 51cb9ed5b66956cee3e429c51057e12884574fe3c8b3b907d6998caa1b037b5ca861c929ea7b26e8364369bf424b3686feff274149fa6a169da09d8048118390
-  data.tar.gz: d6389d7f934088b0447dba290054456f10380578f5b38622275d6e846c99872a5060c21b192b8524aa7d867fe1b58917c9ad03eebfacef716b83eca28dab8549
+  metadata.gz: 9d6dead61b0b4bfd8374c9b51aec7dccc724988b5417f9585018ee549840ee207756642b38aedbfcf4fdb4e313f9764fdc64b1d1d6e7593c057edb20d6095afc
+  data.tar.gz: c5e34b3a736ab3bdca397dfd1245d07b8dd8e246e32d4d0f24e097c41f52d47307c645a547592e60b90dc27f98e2e817193a1059f2696c0a726316c0693c1f88

data/CHANGELOG.md

@@ -1,4 +1,10 @@
-## [Unreleased]
+## [1.2.0] - 2026-05-27
+
+- Add optional `around_refresh_token` configuration. When provided, the OAuth
+  middleware yields the read + expiry-check + refresh sequence to the callable
+  so host applications can serialize concurrent token refreshes (e.g. with a
+  database transaction and advisory lock). The gem keeps no lock dependency.
+
 
 ## [1.1.0] - 2026-03-11
 

data/README.md

@@ -105,6 +105,30 @@ client = Booqable::Client.new(
 client.authenticate_with_code(params[:code])
 ```
 
+#### Serializing concurrent token refreshes
+
+When multiple processes share the same OAuth token (e.g. the same installation
+serving concurrent requests), pass an `around_refresh_token` callable to
+serialize the read + expiry-check + refresh sequence. The middleware yields
+to the callable once per request; the host application decides how to lock.
+
+```ruby
+Booqable::Client.new(
+  # ...other oauth options...
+  around_refresh_token: ->(&block) {
+    AppInstallation.transaction do
+      installation.with_advisory_lock!("app_installation:#{installation.id}", transaction: true) do
+        installation.reload
+        block.call
+      end
+    end
+  }
+)
+```
+
+The gem itself has no advisory-lock dependency — `around_refresh_token` is
+just a callable that takes a block.
+
 ### Single-Use Token Authentication
 
 For server-to-server communication requiring enhanced security:

data/lib/booqable/auth.rb

@@ -57,7 +57,8 @@ module Booqable
         api_endpoint: api_endpoint,
         redirect_uri: redirect_uri,
         read_token: read_token,
-        write_token: write_token
+        write_token: write_token,
+        around_refresh_token: around_refresh_token
       } if oauth_authenticated?
 
       builder.use Booqable::Middleware::Auth::ApiKey, {

data/lib/booqable/configurable.rb

@@ -48,6 +48,7 @@ module Booqable
                   :proxy,
                   :read_token,
                   :redirect_uri,
+                  :around_refresh_token,
                   :single_use_token,
                   :single_use_token_algorithm,
                   :single_use_token_company_id,
@@ -81,6 +82,7 @@ module Booqable
           proxy
           read_token
           redirect_uri
+          around_refresh_token
           single_use_token
           single_use_token_algorithm
           single_use_token_company_id

data/lib/booqable/default.rb

@@ -151,6 +151,17 @@ module Booqable
         Proc.new { }
       end
 
+      # Default `around_refresh_token` callable
+      #
+      # When non-nil, the OAuth middleware yields its read+check+refresh
+      # sequence to this callable so the host application can serialize
+      # concurrent refreshes (e.g. with an advisory lock).
+      #
+      # @return [Proc, nil]
+      def around_refresh_token
+        nil
+      end
+
       # Default API key from ENV
       # @return [String, nil] API key for authentication
       def api_key

data/lib/booqable/middleware/auth/oauth.rb

@@ -24,6 +24,10 @@ module Booqable
         # @option options [String] :api_endpoint API endpoint URL for the OAuth provider
         # @option options [Proc] :read_token Proc to read stored token
         # @option options [Proc] :write_token Proc to store new token
+        # @option options [Proc, nil] :around_refresh_token Optional callable
+        #   invoked with a block around the read+check+refresh sequence. The
+        #   host application can use it to serialize concurrent refreshes
+        #   (e.g. wrap the block in a database transaction + advisory lock).
         # @raise [KeyError] If required options are not provided
         def initialize(app, options = {})
           super(app)
@@ -33,6 +37,7 @@ module Booqable
           @api_endpoint = options.fetch(:api_endpoint)
           @read_token = options.fetch(:read_token)
           @write_token = options.fetch(:write_token)
+          @around_refresh_token = options[:around_refresh_token]
 
           @client = OAuthClient.new(
             client_id: @client_id,
@@ -50,10 +55,12 @@ module Booqable
         # @param env [Faraday::Env] The request environment
         # @return [Faraday::Response] The response from the next middleware
         def call(env)
-          @token = @client.get_access_token_from_hash(@read_token.call)
+          around_refresh_token do
+            @token = @client.get_access_token_from_hash(@read_token.call)
 
-          if @token.expired? || @token.expires_at.nil?
-            @token = refresh_token!
+            if @token.expired? || @token.expires_at.nil?
+              @token = refresh_token!
+            end
           end
 
           env.request_headers["Authorization"] ||= "Bearer #{@token.token}"
@@ -63,6 +70,16 @@ module Booqable
 
         private
 
+        # Yield to the configured around-callback, if any
+        #
+        # When a host application provides one (e.g. an advisory lock), the
+        # read+check+refresh sequence runs inside it so concurrent callers
+        # cannot interleave a read with another caller's refresh.
+        def around_refresh_token(&block)
+          return yield unless @around_refresh_token
+          @around_refresh_token.call(&block)
+        end
+
         # Refresh the expired OAuth token
         #
         # Uses the refresh token to obtain a new access token and stores it

data/lib/booqable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Booqable
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: booqable
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Hrvoje Šimić
@@ -166,7 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Official Booqable API client for Ruby.
 test_files: []