volcano-sdk 0.9.2 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92b94c10570347e736103b57ee437cf54d72ca334a8e87f3528087655fd80e78
-  data.tar.gz: 68c2e41eac585bc12ee2086c5574431136de600236737e820224b88579ca91ca
+  metadata.gz: bb4b4a206147014ad99f42983e545238fd1c46600a127cbe932db4877afd6db9
+  data.tar.gz: 5064a928176a3dd8350d066000c405c1d03b87499b3cbc9bd0a9534b65785247
 SHA512:
-  metadata.gz: 76a68bc5ba09715be91401c60e8b7183f75450907e51d9b9fc1a0437d262538de69c8b22ab78f184ff0b3cb57f267a8bf45efd8f29c8669b2c82a0a655a95806
-  data.tar.gz: 1b055512555848049b55205e62fb9b60b126f333469d3c9eef8d09712201136c03dc70e93fe2cb2f67b388f6902f5dd4df8b76da7618c54ccfb9d9bb2ac3625e
+  metadata.gz: 9ea3fff976b1358651b6f0117a23ccb353edb01139b9876f07b2bca473acd607550779702d0a8821c5cc612194e0fb51f279df52fd41a192b44916d60dd50844
+  data.tar.gz: 7b4761b2c1c25f131968de7662668f04c83ad90fe13532b4b7b277685fe23966ca585f578d6337bbe28dbf9c1a584dc38c0d243420f56851af559f0f6fbce085

data/README.md

@@ -4,6 +4,8 @@ Official Ruby SDK for Volcano. Requires Ruby 3.2 or later.
 
 Start with the [Ruby quickstart](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/README.md).
 
+See [Authentication](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/authentication.md) for account, session, email, and OAuth workflows.
+
 ## Install
 
 Add the gem to your Gemfile and run `bundle install`:
@@ -41,7 +43,7 @@ failures raise typed errors under `Volcano::Error`.
 ```ruby
 result = client.auth.sign_up(
   email: "new-user@example.com",
-  password: "secret",
+  password: "correct-horse-battery-staple",
   metadata: { display_name: "New User" }
 )
 puts result.message if result.confirmation_required
@@ -53,7 +55,7 @@ addresses. Pass `sign_in_when_allowed: true` to follow it with `sign_in` only wh
 confirmation is not required:
 
 ```ruby
-result = client.auth.sign_up(email: "new-user@example.com", password: "secret", sign_in_when_allowed: true)
+result = client.auth.sign_up(email: "new-user@example.com", password: "correct-horse-battery-staple", sign_in_when_allowed: true)
 session = result.session # nil when no follow-up sign-in ran.
 ```
 
@@ -63,7 +65,7 @@ A failed follow-up raises its usual typed error; it does not undo the successful
 ### Sign in
 
 ```ruby
-session = client.auth.sign_in(email: "user@example.com", password: "secret")
+session = client.auth.sign_in(email: "user@example.com", password: "correct-horse-battery-staple")
 current_session = client.auth.current_session
 raise "session changed" unless current_session == session
 ```
@@ -82,7 +84,8 @@ container/string/time subclasses, non-finite numbers, duplicate JSON keys, and
 structures deeper than 100 levels raise `TypeError`. Use the typed `auth.user`
 profile when you need Ruby `Time` values. Successful `user`, `update_user`,
 `convert_anonymous`, and `confirm_email_change` calls update this snapshot
-without changing credentials or emitting an authentication-state event.
+without changing credentials or emitting an authentication-state event unless an HTTP 401
+requires automatic refresh. Successful recovery rotates credentials and emits `:token_refreshed`.
 Previously returned sessions remain unchanged.
 
 ### Get the current user
@@ -103,7 +106,7 @@ is in flight raises
 
 ```ruby
 user = client.auth.update_user(
-  password: "new-secret",
+  password: "new-correct-horse-battery-staple",
   metadata: { display_name: "Grace", avatar: nil }
 )
 raise "wrong user" unless user.id == session.user_id
@@ -207,8 +210,9 @@ hosted_url = client.auth.get_hosted_auth_url(
 ```
 
 Store `hosted_state` in the user's signed server-side session before redirecting
-to `hosted_url`. After parsing the returned fragment into a `Volcano::Session`,
-validate and adopt it atomically:
+to `hosted_url`. In the callback, atomically fetch and delete the stored state before validation,
+even if validation or adoption fails. Reject a missing or already-consumed state.
+After parsing the returned fragment into a `Volcano::Session`, validate and adopt it:
 
 ```ruby
 session = client.auth.adopt_hosted_auth_session(
@@ -239,8 +243,9 @@ authorization_url = client.auth.sign_in_with_oauth(
 ```
 
 Store `oauth_state` in the user's signed server-side session, then redirect the
-user to the returned URL. In the callback, pass the returned and stored states
-to the SDK so it rejects login CSRF before exchanging the one-time code:
+user to the returned URL. In the callback, atomically fetch and delete the stored nonce as `stored_oauth_state`;
+reject a missing or already-consumed nonce. Pass the returned and consumed states to
+the SDK so it rejects login CSRF before exchanging the one-time code:
 
 ```ruby
 session = client.auth.exchange_oauth_code(
@@ -338,9 +343,11 @@ replacement as an "other" session. If replacement occurs, the method raises
 client.auth.delete_session('00000000-0000-4000-8000-000000000099')
 ```
 
-The request uses the current access token. Deleting that token's own session
-clears local credentials, including when the request outcome is uncertain;
-deleting another session preserves them. If another authentication operation
+The request uses the current access token. When its JWT contains a readable UUID `session_id`,
+deleting that session clears local credentials even if the request outcome is uncertain.
+Without that identifier, the SDK cannot recognize self-deletion. Deleting another session does not
+itself clear local state. HTTP 401 recovery can rotate credentials and emit `:token_refreshed`;
+a server-rejected refresh clears the captured session before the operation raises. If another authentication operation
 replaces the session before deletion finishes, the method raises
 `Volcano::Error::SessionChangedError` instead of clearing the replacement or
 acknowledging a stale result.
@@ -354,13 +361,12 @@ session = client.auth.sign_in_anonymously(metadata: { device: "mobile" })
 Anonymous sign-ins must be enabled for the project. Convert the account before
 signing out if the user needs to recover it later.
 
-Attach email credentials without changing the anonymous user's ID or current
-session:
+Attach email credentials while preserving the anonymous user's ID:
 
 ```ruby
 user = client.auth.convert_anonymous(
   email: "user@example.com",
-  password: "secure-password",
+  password: "a-long-example-password-2026",
   metadata: { display_name: "Ada" }
 )
 ```
@@ -371,7 +377,7 @@ as verified.
 ### Reset the password
 
 ```ruby
-client.auth.reset_password(token: "recovery-token", new_password: "new-secret")
+client.auth.reset_password(token: "recovery-token", new_password: "new-correct-horse-battery-staple")
 ```
 
 Success returns `nil`. The reset revokes the recovered account's existing
@@ -384,9 +390,9 @@ Pass `access_token` to `Volcano::Client.new` to start without a refresh token or
 known user identity. Construction makes no request and leaves `refresh_token`,
 `user_id`, and `user` as `nil`. `auth.user` validates and caches the profile
 without changing credentials. Without a refresh token, `refresh_session` raises
-`Volcano::Error::AuthenticationError`. `sign_out` revokes the server session using
-the access token and clears local state. Supply `refresh_token` alongside
-`access_token` to enable refresh.
+`Volcano::Error::AuthenticationError`. `sign_out` clears local state and revokes the server
+session when the access JWT contains a readable UUID `session_id`. Supplied credentials require both a refresh token and an access JWT with a readable UUID
+`session_id` to enable refresh.
 See the [token bootstrap example](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/README.md#use-a-supplied-access-token).
 
 ### Adopt an existing session
@@ -412,8 +418,9 @@ raise "refresh failed" unless client.auth.current_session.equal?(refreshed)
 ```
 
 On success, `refresh_session` replaces the in-memory session and returns the
-immutable new snapshot. An authentication failure clears the session that
-initiated the request. Server and transport failures preserve it, and a late
+immutable new snapshot. An authentication rejection from the refresh endpoint clears the captured session.
+Missing refresh credentials, failed session-continuity checks, server errors, and
+transport failures preserve it, and a late
 response never replaces a newer session. The SDK does not persist sessions.
 
 ### Observe auth-state changes
@@ -430,7 +437,8 @@ subscription.unsubscribe
 Registration immediately yields `:initial_session`. Successful session
 creation, refresh, and local clearing yield `:signed_in`, `:token_refreshed`,
 and `:signed_out`. Callbacks are delivered locally in transition order after the
-state lock is released, and callback failures cannot interrupt auth operations.
+state lock is released. Callback `StandardError` failures are isolated; exceptions such as
+`Interrupt` propagate after the session transition has committed.
 The SDK does not broadcast between processes or persist sessions.
 
 ### Sign out the current session
@@ -441,8 +449,10 @@ raise "still signed in" if client.auth.current_session
 ```
 
 Sign-out uses the refresh token directly when the SDK received both credentials together from
-sign-in or a validated refresh. Supplied credentials use the access-token session; on HTTP 401,
-the SDK can refresh once and revoke that same session without adopting the renewed credentials.
+sign-in or a validated refresh. Supplied credentials use the access-token session when its JWT
+contains a readable UUID `session_id`; on HTTP 401, the SDK can refresh once and revoke that
+same session without adopting the renewed credentials. Without that identifier, sign-out uses
+the supplied refresh token, or only clears local state if no refresh token is available.
 It revokes the captured session and clears the captured in-memory
 session. It succeeds without a request when no session exists. If revocation
 fails, the SDK still clears that session and raises the typed error. Sign-out waits for an already-running refresh and uses its validated credentials.
@@ -464,7 +474,7 @@ goes to the function's own domain rather than to `api_url`, so an egress rule
 that allows only the API host will block it; the resolved endpoint is cached for
 the lifetime the platform gives it. Deployments with no public function domain
 invoke through the API host instead. It uses the
-active user session when present, then a configured service key, then the
+current session token, including a supplied `access_token`, then a configured service key, then the
 anonymous key. An anonymous key can invoke a public function without a user
 session; the function receives no user identity. The immutable result includes
 the response body, status, headers, and `X-Volcano-Version`. The body can be a
@@ -473,20 +483,33 @@ deeply frozen. Invalid JSON or JSON that cannot decode to valid UTF-8 is
 returned as the original decoded response text; malformed Unicode is not repaired.
 Ruby's standard JSON nesting limit (100) also falls back to text.
 A function's own
-non-2xx response is returned when the version header proves it ran; platform
-failures raise typed SDK errors.
+non-2xx response is returned when Volcano confirms it ran; non-success platform
+HTTP responses raise typed SDK errors.
+
+Function resolution and invocation recover from a platform HTTP 401 before dispatch:
+the SDK refreshes the captured session and retries the rejected request once.
+Concurrent calls share successful recovery. Replacing or signing out that session
+prevents replay under another identity. The call preserves its original payload values.
+A function's own response, HTTP 403, or a network failure never triggers this retry.
+Anonymous and service keys do not refresh.
+
+See the [functions guide](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/functions.md).
 
 ### Read project logs
 
 ```ruby
 project_id = "00000000-0000-4000-8000-000000000001"
-page = client.logs.search(
+logs_client = Volcano::Client.new(
+  anon_key: ENV.fetch("VOLCANO_ANON_KEY"),
+  access_token: ENV.fetch("VOLCANO_PROJECT_ACCESS_TOKEN")
+)
+page = logs_client.logs.search(
   project_id,
   { resource: { type: "function" }, limit: 100 }
 )
 page.data.each { |event| puts [event["timestamp"], event["body"]] }
 
-activity = client.logs.activity(
+activity = logs_client.logs.activity(
   project_id,
   { resource: { type: "function" }, bucket_count: 24 }
 )
@@ -496,7 +519,9 @@ puts activity.total
 `search` returns an immutable page of retained runtime or deployment log
 events. Pass `next_cursor` back as `cursor` to continue a search. `activity`
 returns immutable time buckets using the same resource selector and query
-syntax. Both methods require an active user session.
+syntax. Both methods require a platform user token or a project access token.
+A `read_only` project token is sufficient; end-user sessions cannot read project logs.
+See the [logs guide](https://github.com/Kong/volcano-sdk-ruby/blob/main/docs/logs.md).
 
 ### Query a database
 

data/lib/volcano/function_auth.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Keeps function resolution and invocation on the captured session lineage.
+  class FunctionAuth
+    def initialize(client)
+      @client = client
+      @binding = client.capture_session_binding
+      @fallback_token = client.function_token.dup.freeze
+    end
+
+    def run
+      @binding = @client.auth.__send__(:owned_session_binding, @binding) if @binding.last
+      yield(token)
+    rescue Error::AuthenticationError => e
+      raise unless @binding.last && e.status == 401
+
+      refresh(e)
+      yield(token)
+    ensure
+      validate
+    end
+
+    private
+
+    def token
+      return @client.auth.__send__(:owned_session_binding, @binding).last.access_token if @binding.last
+
+      validate
+      @fallback_token
+    end
+
+    def refresh(original)
+      # Resolution has released its cache lock before refresh callbacks run.
+      @client.auth.__send__(:refresh_captured_session, @binding)
+    rescue Error::SessionChangedError
+      raise
+    rescue Error::VolcanoError
+      raise original
+    end
+
+    def validate
+      if @binding.last
+        @client.auth.__send__(:validate_read_failure, @binding)
+      elsif @client.capture_session_binding[1] != @binding[1]
+        raise Error::SessionChangedError
+      end
+    end
+  end
+  private_constant :FunctionAuth
+end

data/lib/volcano/functions.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'function_auth'
+
 module Volcano
   # Invokes deployed Volcano functions by name.
   class Functions
@@ -17,21 +19,33 @@ module Volcano
     end
 
     def invoke(name, payload = {})
+      auth = FunctionAuth.new(@client)
       validate_invocation(name, payload)
-      authorization = @client.function_token
-      resolution = resolve(authorization, name)
-      response = Transport.invoke { invoke_resolved(authorization, resolution, payload.dup) }
+      invoke_owned(auth, name.dup.freeze, ImmutableQueryValue.capture(payload))
+    end
+
+    private
+
+    def invoke_owned(auth, name, payload)
+      authorization, resolution = auth.run { |token| [token, resolve(token, name)] }
+      response = authenticated_invoke(auth, resolution, payload)
       if stale_mapping?(response)
-        # The function was deleted and recreated, so the cached identity no
-        # longer exists. Resolve again before giving up.
         FunctionResolution.forget(@api_url, authorization, name)
-        resolution = resolve(authorization, name)
-        response = Transport.invoke { invoke_resolved(authorization, resolution, payload.dup) }
+        resolution = auth.run { |token| resolve(token, name) }
+        response = authenticated_invoke(auth, resolution, payload)
       end
       function_response(response)
     end
 
-    private
+    def authenticated_invoke(auth, resolution, payload)
+      auth.run do |token|
+        response = Transport.invoke { invoke_resolved(token, resolution, payload) }
+        if response.status == 401 && header(response.headers, FUNCTION_INVOKED_HEADER).nil?
+          Transport.body(response, 200)
+        end
+        response
+      end
+    end
 
     # A platform 404 means the cached function identity is gone. A function that
     # answers 404 itself must be returned rather than retried: invoking twice
@@ -82,9 +96,7 @@ module Volcano
     end
 
     def cached_resolution(cached)
-      return cached.resolution if cached.resolution
-
-      raise Error::NotFoundError.new('Function was not found', status: 404)
+      cached.resolution || raise(Error::NotFoundError.new('Function was not found', status: 404))
     end
 
     def validate_invocation(name, payload)
@@ -101,10 +113,8 @@ module Volcano
 
       # Absent when the deployment serves no public invocation domain, as in
       # local development; the function is reached through the API instead.
-      FunctionResolution::Resolution.new(
-        function_id: function_id,
-        invoke_url: FunctionResolution.valid_invoke_url(payload['invoke_url'], @api_url)
-      )
+      invoke_url = FunctionResolution.valid_invoke_url(payload['invoke_url'], @api_url)
+      FunctionResolution::Resolution.new(function_id: function_id, invoke_url: invoke_url)
     end
 
     def cache_ttl(payload)
@@ -129,8 +139,6 @@ module Volcano
       )
     end
 
-    def header(headers, name)
-      headers&.find { |key, _| key.casecmp?(name) }&.last
-    end
+    def header(headers, name) = headers&.find { |key, _| key.casecmp?(name) }&.last
   end
 end

data/lib/volcano/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: volcano-sdk
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.9.3
 platform: ruby
 authors:
 - Kong
@@ -153,6 +153,7 @@ files:
 - lib/volcano/connection_string.rb
 - lib/volcano/database.rb
 - lib/volcano/errors.rb
+- lib/volcano/function_auth.rb
 - lib/volcano/function_resolution.rb
 - lib/volcano/function_response.rb
 - lib/volcano/functions.rb