volcano-sdk 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 255837a17bdecec1c4973e91d21885299b563a70adced0adf20fbbeb5bd8020d
-  data.tar.gz: edc269875f2132e437787412be884aeb0149acb81fb48397b750271b970afaa6
+  metadata.gz: bf20d0cdb7959be9f989d8b1f1e5f88b53a065a7b899b42f7c3a09af5d1327c6
+  data.tar.gz: 3350d3a721b2d25b67aaf0a76a8cab45cb1ca26c69d386c600789bb60589cfca
 SHA512:
-  metadata.gz: b5e51ede8b8946bb3aca753f0e0661d5e93c9ca6c3dccae7bd5dc78a34b64cf645138a2edd09f6c0c402a920505087410b12d14ce5485ae6ae46630295be21cf
-  data.tar.gz: 38ca82b2e5e0ca112e2be5d7de5ac4719686622524e162d3db6526d0dcd4462d640ca1df17012265aa87243122176ee5f06083f3b7a8ea4e1090e04569b13711
+  metadata.gz: 94a0671011cb9256c3bf768fe05fbea0e1d49fb8c3d29adb694cc5a01eb83e80fb0d978b4aa1c83919a3b38ca7cdd6069a7af5b41eaefa743622bdc745f68083
+  data.tar.gz: 756140f1665c4f360839a37da9ad15de033cf45373bee40a57b7b109d8d0830094af36974923841d538722869bd9f7fe987c7e3f50a55d5b5f9e657d6106d84f

data/README.md

@@ -671,6 +671,13 @@ client.locks.with_lock("deploy", ttl: 30) do |guard|
 end
 ```
 
+Acquisition accepts caller-owned UUID `token` and `request_id` values and retries
+an ambiguous transport failure or HTTP 503 once with the same request and credential.
+Retain those IDs to recover an uncertain acquisition. Other lock methods accept
+`request_id`; block-scoped helpers forward initial IDs only to acquisition.
+See the [lock guide](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/locks.md)
+for examples and fencing requirements.
+
 `locks.get` returns immutable lock availability, expiry, and fencing-token
 state without acquiring the lock.
 `locks.renew` returns a new immutable lease and leaves the previous value

data/lib/volcano/generated_transport.rb

@@ -47,57 +47,57 @@ module Volcano
       @api_factory = api_factory || method(:build_apis)
     end
 
-    def acquire_project_lock(authorization:, key:, ttl:, token:)
+    def acquire_project_lock(authorization:, key:, ttl:, token:, request_id: SecureRandom.uuid)
       invoke do
         apis = @api_factory.call(authorization)
         body = Generated::ProjectLockLeaseRequest.new(ttl_seconds: ttl)
-        result = apis.locks.acquire_project_lock_with_http_info(key, token, SecureRandom.uuid, body)
+        result = apis.locks.acquire_project_lock_with_http_info(key, token, request_id, body)
         data, status, headers = result
         response(data, status, headers)
       end
     end
 
-    def get_project_lock(authorization:, key:)
+    def get_project_lock(authorization:, key:, request_id: SecureRandom.uuid)
       invoke do
         apis = @api_factory.call(authorization)
         data, status, headers = apis.locks.get_project_lock_with_http_info(
           key,
-          SecureRandom.uuid
+          request_id
         )
         response(data, status, headers)
       end
     end
 
-    def force_release_project_lock(authorization:, key:)
+    def force_release_project_lock(authorization:, key:, request_id: SecureRandom.uuid)
       invoke do
         apis = @api_factory.call(authorization)
         data, status, headers = apis.locks.force_release_project_lock_with_http_info(
           key,
-          SecureRandom.uuid
+          request_id
         )
         response(data, status, headers)
       end
     end
 
-    def renew_project_lock(authorization:, key:, ttl:, token:)
+    def renew_project_lock(authorization:, key:, ttl:, token:, request_id: SecureRandom.uuid)
       invoke do
         apis = @api_factory.call(authorization)
         body = Generated::ProjectLockLeaseRequest.new(ttl_seconds: ttl)
         result = apis.locks.renew_project_lock_with_http_info(
-          key, token, SecureRandom.uuid, body
+          key, token, request_id, body
         )
         data, status, headers = result
         response(data, status, headers)
       end
     end
 
-    def release_project_lock(authorization:, key:, token:)
+    def release_project_lock(authorization:, key:, token:, request_id: SecureRandom.uuid)
       invoke do
         apis = @api_factory.call(authorization)
         data, status, headers = apis.locks.release_project_lock_with_http_info(
           key,
           token,
-          SecureRandom.uuid
+          request_id
         )
         response(data, status, headers)
       end

data/lib/volcano/lock_auto_renewal.rb

@@ -10,10 +10,11 @@ module Volcano
     RENEWAL_REQUEST_BUDGET_SECONDS = 1.0
     RENEWER_SHUTDOWN_TIMEOUT_SECONDS = 1.0
 
-    def with_lock(key, ttl:, &)
+    def with_lock(key, ttl:, token: nil, request_id: nil, &)
       validate_ttl(ttl)
       started_at = LockLeaseClock.capture
-      guard = LockGuard.new(acquire(key, ttl: ttl), ttl: ttl, started_at: started_at)
+      lease = acquire(key, ttl: ttl, token: token, request_id: request_id)
+      guard = LockGuard.new(lease, ttl: ttl, started_at: started_at)
       owned_key = guard.lease.key
       renewer = lock_renewer(owned_key, guard, ttl)
       LockSession.new(self, owned_key, guard, renewer, method(:renewal_delay)).run(&)

data/lib/volcano/locks.rb

@@ -13,8 +13,8 @@ module Volcano
       @transport = transport
     end
 
-    def get(key)
-      payload = Transport.body(get_response(key), 200)
+    def get(key, request_id: nil)
+      payload = lock_request(:get_project_lock, 200, key: key, request_id: request_id)
       LockState.new(
         held: payload.fetch('held'),
         expires_at: parse_time(payload['expires_at']),
@@ -22,84 +22,68 @@ module Volcano
       )
     end
 
-    def acquire(key, ttl:)
-      token = SecureRandom.uuid
-      payload = Transport.body(acquire_response(key, ttl, token), 201)
-      LockLease.new(
-        key: key,
-        token: token,
-        expires_at: parse_time(payload['expires_at']),
-        fencing_token: payload['fencing_token']
-      )
+    def acquire(key, ttl:, token: nil, request_id: nil)
+      validate_ttl(ttl)
+      parameters = {
+        authorization: @client.service_token.dup.freeze, key: key.dup.freeze,
+        ttl: ttl, token: request_uuid(token, 'token'), request_id: request_uuid(request_id, 'request_id')
+      }.freeze
+      payload = acquire_payload(parameters)
+      build_lease(parameters[:key], parameters[:token], payload)
     end
 
-    def renew(key, lease, ttl:)
-      payload = Transport.body(renew_response(key, lease, ttl), 200)
-      LockLease.new(
-        key: key,
-        token: lease.token,
-        expires_at: parse_time(payload['expires_at']),
-        fencing_token: payload['fencing_token']
-      )
+    def renew(key, lease, ttl:, request_id: nil)
+      validate_ttl(ttl)
+      payload = lock_request(:renew_project_lock, 200, key: key, ttl: ttl,
+                                                       token: lease.token, request_id: request_id)
+      build_lease(key, lease.token, payload)
     end
 
-    def release(key, lease)
-      response = Transport.invoke do
-        @transport.release_project_lock(
-          authorization: @client.service_token,
-          key: key,
-          token: lease.token
-        )
-      end
-      Transport.body(response, 204)
+    def release(key, lease, request_id: nil)
+      lock_request(:release_project_lock, 204, key: key, token: lease.token, request_id: request_id)
       nil
     end
 
-    def force_release(key)
-      Transport.body(force_release_response(key), 204)
+    def force_release(key, request_id: nil)
+      lock_request(:force_release_project_lock, 204, key: key, request_id: request_id)
       nil
     end
 
     private
 
-    def get_response(key)
-      Transport.invoke do
-        @transport.get_project_lock(
-          authorization: @client.service_token,
-          key: key
-        )
-      end
+    def acquire_payload(parameters)
+      perform_request(:acquire_project_lock, 201, parameters)
+    rescue Error::TransportError, Error::ServerError => e
+      raise unless e.status.nil? || e.status == 503
+
+      perform_request(:acquire_project_lock, 201, parameters)
+    end
+
+    def lock_request(operation, status, **parameters)
+      parameters[:authorization] = @client.service_token
+      parameters[:request_id] = request_uuid(parameters[:request_id], 'request_id')
+      perform_request(operation, status, parameters)
     end
 
-    def force_release_response(key)
-      Transport.invoke do
-        @transport.force_release_project_lock(
-          authorization: @client.service_token,
-          key: key
-        )
-      end
+    def perform_request(operation, status, parameters)
+      response = Transport.invoke { @transport.public_send(operation, **parameters) }
+      Transport.body(response, status)
     end
 
-    def acquire_response(key, ttl, token)
-      Transport.invoke do
-        @transport.acquire_project_lock(
-          authorization: @client.service_token,
-          key: key,
-          ttl: ttl,
-          token: token
-        )
-      end
+    def request_uuid(value, name)
+      return SecureRandom.uuid.freeze if value.nil?
+
+      valid = value.is_a?(String) && value.match?(/\A[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/i)
+      raise ArgumentError, "#{name} must be a UUID string" unless valid
+
+      value.dup.freeze
     end
 
-    def renew_response(key, lease, ttl)
-      Transport.invoke do
-        @transport.renew_project_lock(
-          authorization: @client.service_token,
-          key: key,
-          ttl: ttl,
-          token: lease.token
-        )
-      end
+    def build_lease(key, token, payload)
+      LockLease.new(
+        key: key, token: token, expires_at: parse_time(payload['expires_at']),
+        fencing_token: payload['fencing_token']
+      )
     end
 
     def parse_time(value)

data/lib/volcano/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Volcano
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: volcano-sdk
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Kong