statelydb 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1518fe47ef69d7e171862c88f5b8a9425116dc1390623724dc95e285e960b728
-  data.tar.gz: f5e9faad6e851892a695a47590e7430908e419b44c2f94a60087fec4c316c808
+  metadata.gz: f1d7563d7f40d84bdc1ef3dacff41707ed1d915b638223d33b488ca4c7de531f
+  data.tar.gz: dd682b92fbc100505e15820c5415acadc9defc6bc2f2d0dad5b5797deddbf24b
 SHA512:
-  metadata.gz: acc4be2621242c08236efdf8e1f9fa48090070c3c4ad12583481bc2a2df4ee5638fbb665059a0138a7bf53270bed8d6bf0f5290843dd5d488b71274f2a3284b8
-  data.tar.gz: ddccab6882a70b7eab33c56893fd9cae614ee67c5343b0953f7af33d3fe487418eb00c3300d3a24ae6e14df88f5cf49609b9e1f4a966db10d646ab184c00a685
+  metadata.gz: c0f27aa770fdf0c7b3386ac37862226cb4b5215766d265e47c82323b2157966e6ce0d87b5e4081d8d9dcd549f45cd0f6527203b0025b0e6c62ce0780c81dae74
+  data.tar.gz: de86db0a2a0227e6bec231d11c378bffff42fa7911ccc0874bd3ed97fae7f73d0ac29ce55b31817f75bfa82c0b63daa79dabd28276a66e17e2748770450f6243

data/lib/api/auth/get_auth_token_pb.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: auth/get_auth_token.proto
+
+require 'google/protobuf'
+
+
+descriptor_data = "\n\x19\x61uth/get_auth_token.proto\x12\x0cstately.auth\"B\n\x13GetAuthTokenRequest\x12\x1f\n\naccess_key\x18\x01 \x01(\tH\x00R\taccessKeyB\n\n\x08identity\"W\n\x14GetAuthTokenResponse\x12\x1d\n\nauth_token\x18\x01 \x01(\tR\tauthToken\x12 \n\x0c\x65xpires_in_s\x18\x02 \x01(\x04R\nexpiresInSBv\n\x10\x63om.stately.authB\x11GetAuthTokenProtoP\x01\xa2\x02\x03SAX\xaa\x02\x0cStately.Auth\xca\x02\x0cStately\\Auth\xe2\x02\x18Stately\\Auth\\GPBMetadata\xea\x02\rStately::Authb\x06proto3"
+
+pool = Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Stately
+  module Auth
+    GetAuthTokenRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("stately.auth.GetAuthTokenRequest").msgclass
+    GetAuthTokenResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("stately.auth.GetAuthTokenResponse").msgclass
+  end
+end

data/lib/api/auth/service_pb.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: auth/service.proto
+
+require 'google/protobuf'
+
+require 'api/auth/get_auth_token_pb'
+
+
+descriptor_data = "\n\x12\x61uth/service.proto\x12\x0cstately.auth\x1a\x19\x61uth/get_auth_token.proto2i\n\x0b\x41uthService\x12Z\n\x0cGetAuthToken\x12!.stately.auth.GetAuthTokenRequest\x1a\".stately.auth.GetAuthTokenResponse\"\x03\x90\x02\x01\x42q\n\x10\x63om.stately.authB\x0cServiceProtoP\x01\xa2\x02\x03SAX\xaa\x02\x0cStately.Auth\xca\x02\x0cStately\\Auth\xe2\x02\x18Stately\\Auth\\GPBMetadata\xea\x02\rStately::Authb\x06proto3"
+
+pool = Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Stately
+  module Auth
+  end
+end

data/lib/api/auth/service_services_pb.rb

@@ -0,0 +1,29 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# Source: auth/service.proto for package 'Stately.Auth'
+
+require 'grpc'
+require 'api/auth/service_pb'
+
+module Stately
+  module Auth
+    module AuthService
+      # AuthService is the service for vending access tokens used to connect to
+      # StatelyDB. This API is meant to be used from SDKs. Access Keys are created
+      # and managed from the stately.dbmanagement.UserService.
+      class Service
+
+        include ::GRPC::GenericService
+
+        self.marshal_class_method = :encode
+        self.unmarshal_class_method = :decode
+        self.service_name = 'stately.auth.AuthService'
+
+        # GetAuthToken returns a short-lived access token from some proof of
+        # identity. This operation will fail if the identity cannot be verified.
+        rpc :GetAuthToken, ::Stately::Auth::GetAuthTokenRequest, ::Stately::Auth::GetAuthTokenResponse
+      end
+
+      Stub = Service.rpc_stub_class
+    end
+  end
+end

data/lib/common/auth/{auth0_token_provider.rb → auth_token_provider.rb}

@@ -6,8 +6,10 @@ require "async/http/internet"
 require "async/semaphore"
 require "json"
 require "logger"
-require "weakref"
+require "grpc"
 require_relative "token_provider"
+require_relative "token_fetcher"
+require_relative "../../error"
 
 LOGGER = Logger.new($stdout)
 LOGGER.level = Logger::WARN
@@ -22,20 +24,25 @@ module StatelyDB
       # which vends tokens from auth0 with the given client_id and client_secret.
       # It will default to using the values of `STATELY_CLIENT_ID` and `STATELY_CLIENT_SECRET` if
       # no credentials are explicitly passed and will throw an error if none are found.
-      class Auth0TokenProvider < TokenProvider
+      class AuthTokenProvider < TokenProvider
         # @param [String] origin The origin of the OAuth server
         # @param [String] audience The OAuth Audience for the token
         # @param [String] client_secret The StatelyDB client secret credential
         # @param [String] client_id The StatelyDB client ID credential
+        # @param [String] access_key The StatelyDB access key credential
+        # @param [Float] base_retry_backoff_secs The base retry backoff in seconds
         def initialize(
           origin: "https://oauth.stately.cloud",
           audience: "api.stately.cloud",
-          client_secret: ENV.fetch("STATELY_CLIENT_SECRET"),
-          client_id: ENV.fetch("STATELY_CLIENT_ID")
+          client_secret: ENV.fetch("STATELY_CLIENT_SECRET", nil),
+          client_id: ENV.fetch("STATELY_CLIENT_ID", nil),
+          access_key: ENV.fetch("STATELY_ACCESS_KEY", nil),
+          base_retry_backoff_secs: 1
         )
           super()
           @actor = Async::Actor.new(Actor.new(origin: origin, audience: audience,
-                                              client_secret: client_secret, client_id: client_id))
+                                              client_secret: client_secret, client_id: client_id, access_key: access_key,
+                                              base_retry_backoff_secs: base_retry_backoff_secs))
           # this initialization cannot happen in the constructor because it is async and must run on the event loop
           # which is not available in the constructor
           @actor.init
@@ -60,33 +67,50 @@ module StatelyDB
           # @param [String] audience The OAuth Audience for the token
           # @param [String] client_secret The StatelyDB client secret credential
           # @param [String] client_id The StatelyDB client ID credential
+          # @param [String] access_key The StatelyDB access key credential
+          # @param [Float] base_retry_backoff_secs The base retry backoff in seconds
           def initialize(
             origin:,
             audience:,
             client_secret:,
-            client_id:
+            client_id:,
+            access_key:,
+            base_retry_backoff_secs:
           )
             super()
-            @client = Async::HTTP::Client.new(Async::HTTP::Endpoint.parse(origin))
-            @client_id = client_id
-            @client_secret = client_secret
-            @audience = audience
 
-            @access_token = nil
-            @expires_at_unix_secs = nil
+            @token_fetcher = nil
+            if !access_key.nil?
+              @token_fetcher = StatelyDB::Common::Auth::StatelyAccessTokenFetcher.new(
+                origin: origin, access_key: access_key, base_retry_backoff_secs: base_retry_backoff_secs
+              )
+            elsif !client_secret.nil? && !client_id.nil?
+              @token_fetcher = StatelyDB::Common::Auth::Auth0TokenFetcher.new(origin: origin, audience: audience,
+                                                                              client_secret: client_secret, client_id: client_id)
+            else
+              raise StatelyDB::Error.new("unable to find client credentials in STATELY_ACCESS_KEY or STATELY_CLIENT_ID and " \
+                                         "STATELY_CLIENT_SECRET environment variables. Either pass your credentials in " \
+                                         "explicitly or set these environment variables",
+                                         code: GRPC::Core::StatusCodes::UNAUTHENTICATED,
+                                         stately_code: "Unauthenticated")
+            end
+
+            @token_state = nil
             @pending_refresh = nil
           end
 
           # Initialize the actor. This runs on the actor thread which means
           # we can dispatch async operations here.
           def init
+            # disable the async lib logger. We do our own error handling and propagation
+            Console.logger.disable(Async::Task)
             refresh_token
           end
 
           # Close the token provider and kill any background operations
           def close
             @scheduled&.stop
-            @client&.close
+            @token_fetcher&.close
           end
 
           # Get the current access token
@@ -94,8 +118,7 @@ module StatelyDB
           # @return [String] The current access token
           def get_token(force: false)
             if force
-              @access_token = nil
-              @expires_at_unix_secs = nil
+              @token_state = nil
             else
               token, ok = valid_access_token
               return token if ok
@@ -107,11 +130,10 @@ module StatelyDB
           # Get the current access token and whether it is valid
           # @return [Array] The current access token and whether it is valid
           def valid_access_token
-            return "", false if @access_token.nil?
-            return "", false if @expires_at_unix_secs.nil?
-            return "", false if @expires_at_unix_secs < Time.now.to_i
+            return "", false if @token_state.nil?
+            return "", false if @token_state.expires_at_unix_secs < Time.now.to_i
 
-            [@access_token, true]
+            [@token_state.token, true]
           end
 
           # Refresh the access token
@@ -151,19 +173,16 @@ module StatelyDB
           # @return [String] The new access token
           def refresh_token_impl
             Sync do
-              resp_data = make_auth0_request
-
-              new_access_token = resp_data["access_token"]
-              new_expires_in_secs = resp_data["expires_in"]
+              token_result = @token_fetcher.fetch
+              new_expires_in_secs = token_result.expires_in_secs
               new_expires_at_unix_secs = Time.now.to_i + new_expires_in_secs
-              if @expires_at_unix_secs.nil? || new_expires_at_unix_secs > @expires_at_unix_secs
 
-                @access_token = new_access_token
-                @expires_at_unix_secs = new_expires_at_unix_secs
+              # only update the token state if the new expiry is later than the current one
+              if @token_state.nil? || new_expires_at_unix_secs > @token_state.expires_at_unix_secs
+                @token_state = TokenState.new(token: token_result.token, expires_at_unix_secs: new_expires_at_unix_secs)
               else
-
-                new_access_token = @access_token
-                new_expires_in_secs = @expires_at_unix_secs - Time.now.to_i
+                # otherwise use the existing expiry time for scheduling the refresh
+                new_expires_in_secs = @token_state.expires_at_unix_secs - Time.now.to_i
               end
 
               # Schedule a refresh of the token ahead of the expiry time
@@ -182,24 +201,21 @@ module StatelyDB
                 @scheduled = nil
               end
 
-              new_access_token
+              @token_state.token
             end
           end
+        end
 
-          def make_auth0_request
-            headers = [["content-type", "application/json"]]
-            body = JSON.dump({ "client_id" => @client_id, client_secret: @client_secret, audience: @audience,
-                               grant_type: DEFAULT_GRANT_TYPE })
-            Sync do
-              # TODO: Wrap this in a retry loop and parse errors like we
-              # do in the Go SDK.
-              response = @client.post("/oauth/token", headers, body)
-              raise "Auth request failed" if response.status != 200
-
-              JSON.parse(response.read)
-            ensure
-              response&.close
-            end
+        # Persistent state for the token provider
+        class TokenState
+          attr_reader :token, :expires_at_unix_secs
+
+          # Create a new TokenState
+          # @param [String] token The access token
+          # @param [Integer] expires_at_unix_secs The unix timestamp when the token expires
+          def initialize(token:, expires_at_unix_secs:)
+            @token = token
+            @expires_at_unix_secs = expires_at_unix_secs
           end
         end
       end

data/lib/common/auth/interceptor.rb

@@ -11,7 +11,7 @@ module StatelyDB
       class Interceptor < GRPC::ClientInterceptor
         # @param [TokenProvider] token_provider The token provider to use for authentication
         def initialize(
-          token_provider: Auth0TokenProvider.new
+          token_provider: AuthTokenProvider.new
         )
           super()
           @token_provider = token_provider

data/lib/common/auth/token_fetcher.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative "../net/conn"
+require_relative "../error_interceptor"
+require_relative "../../api/auth/service_services_pb"
+require "grpc"
+
+module StatelyDB
+  module Common
+    # A module for Stately Cloud auth code
+    module Auth
+      # Result from a token fetch operation
+      class TokenResult
+        attr_reader :token, :expires_in_secs
+
+        # Create a new TokenResult
+        # @param [String] token The access token
+        # @param [Integer] expires_in_secs The number of seconds until the token expires
+        def initialize(token:, expires_in_secs:)
+          @token = token
+          @expires_in_secs = expires_in_secs
+        end
+      end
+
+      # TokenFetcher is an abstract base class that should be extended
+      # for individual token fetcher implementations
+      class TokenFetcher
+        # Get the current access token
+        # @return [TokenResult] The fetched TokenResult
+        def fetch
+          raise "Not Implemented"
+        end
+
+        # Close the token provider and kill any background operations
+        def close
+          raise "Not Implemented"
+        end
+      end
+
+      # Auth0TokenFetcher is a TokenFetcher that fetches tokens from an Auth0 server
+      class Auth0TokenFetcher < TokenFetcher
+        # @param [String] origin The origin of the OAuth server
+        # @param [String] audience The OAuth Audience for the token
+        # @param [String] client_secret The StatelyDB client secret credential
+        # @param [String] client_id The StatelyDB client ID credential
+        def initialize(origin:, audience:, client_secret:, client_id:)
+          super()
+          @client = Async::HTTP::Client.new(Async::HTTP::Endpoint.parse(origin))
+          @audience = audience
+          @client_secret = client_secret
+          @client_id = client_id
+        end
+
+        # Fetch a new token from auth0
+        # @return [TokenResult] The fetched TokenResult
+        def fetch
+          headers = [["content-type", "application/json"]]
+          body = JSON.dump({ "client_id" => @client_id, client_secret: @client_secret, audience: @audience,
+                             grant_type: DEFAULT_GRANT_TYPE })
+          Sync do
+            response = @client.post("/oauth/token", headers, body)
+            raise "Auth request failed" if response.status != 200
+
+            resp_data = JSON.parse(response.read)
+            TokenResult.new(token: resp_data["access_token"], expires_in_secs: resp_data["expires_in"])
+          ensure
+            response&.close
+          end
+        end
+
+        def close
+          @client&.close
+        end
+      end
+
+      # StatelyAccessTokenFetcher is a TokenFetcher that fetches tokens from the StatelyDB API
+      class StatelyAccessTokenFetcher < TokenFetcher
+        NON_RETRYABLE_ERRORS = [
+          GRPC::Core::StatusCodes::UNAUTHENTICATED,
+          GRPC::Core::StatusCodes::PERMISSION_DENIED,
+          GRPC::Core::StatusCodes::NOT_FOUND,
+          GRPC::Core::StatusCodes::UNIMPLEMENTED,
+          GRPC::Core::StatusCodes::INVALID_ARGUMENT
+        ].freeze
+        RETRY_ATTEMPTS = 10
+
+        # @param [String] origin The origin of the OAuth server
+        # @param [String] access_key The StatelyDB access key credential
+        # @param [Float] base_retry_backoff_secs The base backoff time in seconds
+        def initialize(origin:, access_key:, base_retry_backoff_secs:)
+          super()
+          @access_key = access_key
+          @base_retry_backoff_secs = base_retry_backoff_secs
+          @channel = Common::Net.new_channel(endpoint: origin)
+          error_interceptor = Common::ErrorInterceptor.new
+          @stub = Stately::Auth::AuthService::Stub.new(nil, nil, channel_override: @channel,
+                                                                 interceptors: [error_interceptor])
+        end
+
+        # Fetch a new token from the StatelyDB API
+        # @return [TokenResult] The fetched TokenResult
+        def fetch
+          RETRY_ATTEMPTS.times do |i|
+            resp = @stub.get_auth_token(Stately::Auth::GetAuthTokenRequest.new(access_key: @access_key))
+            return TokenResult.new(token: resp.auth_token, expires_in_secs: resp.expires_in_s)
+          rescue StatelyDB::Error => e
+            # raise if it's the final attempt or if the error is not retryable
+            raise e unless self.class.retryable_error?(e) && i < RETRY_ATTEMPTS - 1
+
+            # exponential backoff
+            sleep(backoff(i, @base_retry_backoff_secs))
+          end
+        end
+
+        def close
+          @channel&.close
+        end
+
+        # Check if an error is retryable
+        # @param [StatelyDB::Error] err The error to check
+        # @return [Boolean] True if the error is retryable
+        def self.retryable_error?(err)
+          !NON_RETRYABLE_ERRORS.include?(err.code)
+        end
+      end
+    end
+  end
+end
+
+# backoff returns a duration to wait before retrying a request. `attempt` is
+# the current attempt number, starting from 0 (e.g. the first attempt is 0,
+# then 1, then 2...).
+#
+# @param [Integer] attempt The current attempt number
+# @param [Float] base_backoff The base backoff time in seconds
+# @return [Float] The duration in seconds to wait before retrying
+def backoff(attempt, base_backoff)
+  # Double the base backoff time per attempt, starting with 1
+  exp = 2**attempt
+  # Add a full jitter to the backoff time, from no wait to 100% of the exponential backoff.
+  # See https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+  jitter = rand
+  (exp * jitter * base_backoff)
+end

data/lib/statelydb.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "api/db/service_services_pb"
-require "common/auth/auth0_token_provider"
+require "common/auth/auth_token_provider"
 require "common/auth/interceptor"
 require "common/net/conn"
 require "common/error_interceptor"
@@ -30,7 +30,7 @@ module StatelyDB
     # @param region [String] the region to connect to.
     def initialize(store_id:,
                    schema:,
-                   token_provider: Common::Auth::Auth0TokenProvider.new,
+                   token_provider: Common::Auth::AuthTokenProvider.new,
                    endpoint: nil,
                    region: nil)
       if store_id.nil?

data/sig/statelydb.rbi

@@ -213,7 +213,7 @@ module StatelyDB
         region: T.nilable(String)
       ).void
     end
-    def initialize(store_id:, schema:, token_provider: Common::Auth::Auth0TokenProvider.new, endpoint: nil, region: nil); end
+    def initialize(store_id:, schema:, token_provider: Common::Auth::AuthTokenProvider.new, endpoint: nil, region: nil); end
 
     # _@return_ — nil
     sig { void }
@@ -479,7 +479,7 @@ module StatelyDB
       class Interceptor < GRPC::ClientInterceptor
         # _@param_ `token_provider` — The token provider to use for authentication
         sig { params(token_provider: TokenProvider).void }
-        def initialize(token_provider: Auth0TokenProvider.new); end
+        def initialize(token_provider: AuthTokenProvider.new); end
 
         # gRPC client unary interceptor
         # 
@@ -572,6 +572,105 @@ module StatelyDB
         def add_jwt_to_grpc_request(metadata:); end
       end
 
+      # Result from a token fetch operation
+      class TokenResult
+        # Create a new TokenResult
+        # 
+        # _@param_ `token` — The access token
+        # 
+        # _@param_ `expires_in_secs` — The number of seconds until the token expires
+        sig { params(token: String, expires_in_secs: Integer).void }
+        def initialize(token:, expires_in_secs:); end
+
+        # Returns the value of attribute token.
+        sig { returns(T.untyped) }
+        attr_reader :token
+
+        # Returns the value of attribute expires_in_secs.
+        sig { returns(T.untyped) }
+        attr_reader :expires_in_secs
+      end
+
+      # TokenFetcher is an abstract base class that should be extended
+      # for individual token fetcher implementations
+      class TokenFetcher
+        # Get the current access token
+        # 
+        # _@return_ — The fetched TokenResult
+        sig { returns(TokenResult) }
+        def fetch; end
+
+        # Close the token provider and kill any background operations
+        sig { returns(T.untyped) }
+        def close; end
+      end
+
+      # Auth0TokenFetcher is a TokenFetcher that fetches tokens from an Auth0 server
+      class Auth0TokenFetcher < StatelyDB::Common::Auth::TokenFetcher
+        # _@param_ `origin` — The origin of the OAuth server
+        # 
+        # _@param_ `audience` — The OAuth Audience for the token
+        # 
+        # _@param_ `client_secret` — The StatelyDB client secret credential
+        # 
+        # _@param_ `client_id` — The StatelyDB client ID credential
+        sig do
+          params(
+            origin: String,
+            audience: String,
+            client_secret: String,
+            client_id: String
+          ).void
+        end
+        def initialize(origin:, audience:, client_secret:, client_id:); end
+
+        # Fetch a new token from auth0
+        # 
+        # _@return_ — The fetched TokenResult
+        sig { returns(TokenResult) }
+        def fetch; end
+
+        sig { returns(T.untyped) }
+        def close; end
+      end
+
+      # StatelyAccessTokenFetcher is a TokenFetcher that fetches tokens from the StatelyDB API
+      class StatelyAccessTokenFetcher < StatelyDB::Common::Auth::TokenFetcher
+        NON_RETRYABLE_ERRORS = T.let([
+  GRPC::Core::StatusCodes::UNAUTHENTICATED,
+  GRPC::Core::StatusCodes::PERMISSION_DENIED,
+  GRPC::Core::StatusCodes::NOT_FOUND,
+  GRPC::Core::StatusCodes::UNIMPLEMENTED,
+  GRPC::Core::StatusCodes::INVALID_ARGUMENT
+].freeze, T.untyped)
+        RETRY_ATTEMPTS = T.let(10, T.untyped)
+
+        # _@param_ `origin` — The origin of the OAuth server
+        # 
+        # _@param_ `access_key` — The StatelyDB access key credential
+        # 
+        # _@param_ `base_retry_backoff_secs` — The base backoff time in seconds
+        sig { params(origin: String, access_key: String, base_retry_backoff_secs: Float).void }
+        def initialize(origin:, access_key:, base_retry_backoff_secs:); end
+
+        # Fetch a new token from the StatelyDB API
+        # 
+        # _@return_ — The fetched TokenResult
+        sig { returns(TokenResult) }
+        def fetch; end
+
+        sig { returns(T.untyped) }
+        def close; end
+
+        # Check if an error is retryable
+        # 
+        # _@param_ `err` — The error to check
+        # 
+        # _@return_ — True if the error is retryable
+        sig { params(err: StatelyDB::Error).returns(T::Boolean) }
+        def self.retryable_error?(err); end
+      end
+
       # TokenProvider is an abstract base class that should be extended
       # for individual token provider implementations
       class TokenProvider
@@ -592,7 +691,7 @@ module StatelyDB
       # which vends tokens from auth0 with the given client_id and client_secret.
       # It will default to using the values of `STATELY_CLIENT_ID` and `STATELY_CLIENT_SECRET` if
       # no credentials are explicitly passed and will throw an error if none are found.
-      class Auth0TokenProvider < StatelyDB::Common::Auth::TokenProvider
+      class AuthTokenProvider < StatelyDB::Common::Auth::TokenProvider
         # _@param_ `origin` — The origin of the OAuth server
         # 
         # _@param_ `audience` — The OAuth Audience for the token
@@ -600,15 +699,21 @@ module StatelyDB
         # _@param_ `client_secret` — The StatelyDB client secret credential
         # 
         # _@param_ `client_id` — The StatelyDB client ID credential
+        # 
+        # _@param_ `access_key` — The StatelyDB access key credential
+        # 
+        # _@param_ `base_retry_backoff_secs` — The base retry backoff in seconds
         sig do
           params(
             origin: String,
             audience: String,
             client_secret: String,
-            client_id: String
+            client_id: String,
+            access_key: String,
+            base_retry_backoff_secs: Float
           ).void
         end
-        def initialize(origin: "https://oauth.stately.cloud", audience: "api.stately.cloud", client_secret: ENV.fetch("STATELY_CLIENT_SECRET"), client_id: ENV.fetch("STATELY_CLIENT_ID")); end
+        def initialize(origin: "https://oauth.stately.cloud", audience: "api.stately.cloud", client_secret: ENV.fetch("STATELY_CLIENT_SECRET", nil), client_id: ENV.fetch("STATELY_CLIENT_ID", nil), access_key: ENV.fetch("STATELY_ACCESS_KEY", nil), base_retry_backoff_secs: 1); end
 
         # Close the token provider and kill any background operations
         # This just invokes the close method on the actor which should do the cleanup
@@ -631,15 +736,21 @@ module StatelyDB
           # _@param_ `client_secret` — The StatelyDB client secret credential
           # 
           # _@param_ `client_id` — The StatelyDB client ID credential
+          # 
+          # _@param_ `access_key` — The StatelyDB access key credential
+          # 
+          # _@param_ `base_retry_backoff_secs` — The base retry backoff in seconds
           sig do
             params(
               origin: String,
               audience: String,
               client_secret: String,
-              client_id: String
+              client_id: String,
+              access_key: String,
+              base_retry_backoff_secs: Float
             ).void
           end
-          def initialize(origin:, audience:, client_secret:, client_id:); end
+          def initialize(origin:, audience:, client_secret:, client_id:, access_key:, base_retry_backoff_secs:); end
 
           # Initialize the actor. This runs on the actor thread which means
           # we can dispatch async operations here.
@@ -675,9 +786,25 @@ module StatelyDB
           # _@return_ — The new access token
           sig { returns(String) }
           def refresh_token_impl; end
+        end
+
+        # Persistent state for the token provider
+        class TokenState
+          # Create a new TokenState
+          # 
+          # _@param_ `token` — The access token
+          # 
+          # _@param_ `expires_at_unix_secs` — The unix timestamp when the token expires
+          sig { params(token: String, expires_at_unix_secs: Integer).void }
+          def initialize(token:, expires_at_unix_secs:); end
+
+          # Returns the value of attribute token.
+          sig { returns(T.untyped) }
+          attr_reader :token
 
+          # Returns the value of attribute expires_at_unix_secs.
           sig { returns(T.untyped) }
-          def make_auth0_request; end
+          attr_reader :expires_at_unix_secs
         end
       end
     end
@@ -1069,6 +1196,22 @@ module Stately
     end
   end
 
+  module Auth
+    GetAuthTokenRequest = T.let(::Google::Protobuf::DescriptorPool.generated_pool.lookup("stately.auth.GetAuthTokenRequest").msgclass, T.untyped)
+    GetAuthTokenResponse = T.let(::Google::Protobuf::DescriptorPool.generated_pool.lookup("stately.auth.GetAuthTokenResponse").msgclass, T.untyped)
+
+    module AuthService
+      Stub = T.let(Service.rpc_stub_class, T.untyped)
+
+      # AuthService is the service for vending access tokens used to connect to
+      # StatelyDB. This API is meant to be used from SDKs. Access Keys are created
+      # and managed from the stately.dbmanagement.UserService.
+      class Service
+        include GRPC::GenericService
+      end
+    end
+  end
+
   module Errors
     StatelyErrorDetails = T.let(::Google::Protobuf::DescriptorPool.generated_pool.lookup("stately.errors.StatelyErrorDetails").msgclass, T.untyped)
   end

data/sig/statelydb.rbs

@@ -496,6 +496,85 @@ module StatelyDB
         def add_jwt_to_grpc_request: (metadata: ::Hash[untyped, untyped]) -> void
       end
 
+      # Result from a token fetch operation
+      class TokenResult
+        # Create a new TokenResult
+        # 
+        # _@param_ `token` — The access token
+        # 
+        # _@param_ `expires_in_secs` — The number of seconds until the token expires
+        def initialize: (token: String, expires_in_secs: Integer) -> void
+
+        # Returns the value of attribute token.
+        attr_reader token: untyped
+
+        # Returns the value of attribute expires_in_secs.
+        attr_reader expires_in_secs: untyped
+      end
+
+      # TokenFetcher is an abstract base class that should be extended
+      # for individual token fetcher implementations
+      class TokenFetcher
+        # Get the current access token
+        # 
+        # _@return_ — The fetched TokenResult
+        def fetch: () -> TokenResult
+
+        # Close the token provider and kill any background operations
+        def close: () -> untyped
+      end
+
+      # Auth0TokenFetcher is a TokenFetcher that fetches tokens from an Auth0 server
+      class Auth0TokenFetcher < StatelyDB::Common::Auth::TokenFetcher
+        # _@param_ `origin` — The origin of the OAuth server
+        # 
+        # _@param_ `audience` — The OAuth Audience for the token
+        # 
+        # _@param_ `client_secret` — The StatelyDB client secret credential
+        # 
+        # _@param_ `client_id` — The StatelyDB client ID credential
+        def initialize: (
+                          origin: String,
+                          audience: String,
+                          client_secret: String,
+                          client_id: String
+                        ) -> void
+
+        # Fetch a new token from auth0
+        # 
+        # _@return_ — The fetched TokenResult
+        def fetch: () -> TokenResult
+
+        def close: () -> untyped
+      end
+
+      # StatelyAccessTokenFetcher is a TokenFetcher that fetches tokens from the StatelyDB API
+      class StatelyAccessTokenFetcher < StatelyDB::Common::Auth::TokenFetcher
+        NON_RETRYABLE_ERRORS: untyped
+        RETRY_ATTEMPTS: untyped
+
+        # _@param_ `origin` — The origin of the OAuth server
+        # 
+        # _@param_ `access_key` — The StatelyDB access key credential
+        # 
+        # _@param_ `base_retry_backoff_secs` — The base backoff time in seconds
+        def initialize: (origin: String, access_key: String, base_retry_backoff_secs: Float) -> void
+
+        # Fetch a new token from the StatelyDB API
+        # 
+        # _@return_ — The fetched TokenResult
+        def fetch: () -> TokenResult
+
+        def close: () -> untyped
+
+        # Check if an error is retryable
+        # 
+        # _@param_ `err` — The error to check
+        # 
+        # _@return_ — True if the error is retryable
+        def self.retryable_error?: (StatelyDB::Error err) -> bool
+      end
+
       # TokenProvider is an abstract base class that should be extended
       # for individual token provider implementations
       class TokenProvider
@@ -514,7 +593,7 @@ module StatelyDB
       # which vends tokens from auth0 with the given client_id and client_secret.
       # It will default to using the values of `STATELY_CLIENT_ID` and `STATELY_CLIENT_SECRET` if
       # no credentials are explicitly passed and will throw an error if none are found.
-      class Auth0TokenProvider < StatelyDB::Common::Auth::TokenProvider
+      class AuthTokenProvider < StatelyDB::Common::Auth::TokenProvider
         # _@param_ `origin` — The origin of the OAuth server
         # 
         # _@param_ `audience` — The OAuth Audience for the token
@@ -522,11 +601,17 @@ module StatelyDB
         # _@param_ `client_secret` — The StatelyDB client secret credential
         # 
         # _@param_ `client_id` — The StatelyDB client ID credential
+        # 
+        # _@param_ `access_key` — The StatelyDB access key credential
+        # 
+        # _@param_ `base_retry_backoff_secs` — The base retry backoff in seconds
         def initialize: (
                           ?origin: String,
                           ?audience: String,
                           ?client_secret: String,
-                          ?client_id: String
+                          ?client_id: String,
+                          ?access_key: String,
+                          ?base_retry_backoff_secs: Float
                         ) -> void
 
         # Close the token provider and kill any background operations
@@ -548,11 +633,17 @@ module StatelyDB
           # _@param_ `client_secret` — The StatelyDB client secret credential
           # 
           # _@param_ `client_id` — The StatelyDB client ID credential
+          # 
+          # _@param_ `access_key` — The StatelyDB access key credential
+          # 
+          # _@param_ `base_retry_backoff_secs` — The base retry backoff in seconds
           def initialize: (
                             origin: String,
                             audience: String,
                             client_secret: String,
-                            client_id: String
+                            client_id: String,
+                            access_key: String,
+                            base_retry_backoff_secs: Float
                           ) -> void
 
           # Initialize the actor. This runs on the actor thread which means
@@ -583,8 +674,22 @@ module StatelyDB
           # 
           # _@return_ — The new access token
           def refresh_token_impl: () -> String
+        end
+
+        # Persistent state for the token provider
+        class TokenState
+          # Create a new TokenState
+          # 
+          # _@param_ `token` — The access token
+          # 
+          # _@param_ `expires_at_unix_secs` — The unix timestamp when the token expires
+          def initialize: (token: String, expires_at_unix_secs: Integer) -> void
 
-          def make_auth0_request: () -> untyped
+          # Returns the value of attribute token.
+          attr_reader token: untyped
+
+          # Returns the value of attribute expires_at_unix_secs.
+          attr_reader expires_at_unix_secs: untyped
         end
       end
     end
@@ -936,6 +1041,22 @@ module Stately
     end
   end
 
+  module Auth
+    GetAuthTokenRequest: untyped
+    GetAuthTokenResponse: untyped
+
+    module AuthService
+      Stub: untyped
+
+      # AuthService is the service for vending access tokens used to connect to
+      # StatelyDB. This API is meant to be used from SDKs. Access Keys are created
+      # and managed from the stately.dbmanagement.UserService.
+      class Service
+        include GRPC::GenericService
+      end
+    end
+  end
+
   module Errors
     StatelyErrorDetails: untyped
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statelydb
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Stately Cloud, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-12 00:00:00.000000000 Z
+date: 2024-12-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -73,6 +73,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - README.md
+- lib/api/auth/get_auth_token_pb.rb
+- lib/api/auth/service_pb.rb
+- lib/api/auth/service_services_pb.rb
 - lib/api/db/continue_list_pb.rb
 - lib/api/db/delete_pb.rb
 - lib/api/db/get_pb.rb
@@ -87,8 +90,9 @@ files:
 - lib/api/db/sync_list_pb.rb
 - lib/api/db/transaction_pb.rb
 - lib/api/errors/error_details_pb.rb
-- lib/common/auth/auth0_token_provider.rb
+- lib/common/auth/auth_token_provider.rb
 - lib/common/auth/interceptor.rb
+- lib/common/auth/token_fetcher.rb
 - lib/common/auth/token_provider.rb
 - lib/common/error_interceptor.rb
 - lib/common/net/conn.rb