statelydb 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a723737fdce6e8ad2bec8937cfd79f6d968df0fc3e9e747c64e18af9ce769601
-  data.tar.gz: 1f0279a8b9507f4cffacc360ab82e2289471a40de39bd3891f0c7db5c63877c6
+  metadata.gz: acc7d4cbc70b66408fc0723cb627b291114ea531eabf57491d668bd4be9c6dc6
+  data.tar.gz: 4758fd8040faca40481b98aa713c12f711c353cbdfc2141e604227276da59e9c
 SHA512:
-  metadata.gz: 815835070a91366b18948afe145eb548ae4f6ecbc6559ed3b8193288cd1084b7ac1a416264b0769afea93f4a8c01e17b0474facb46fe90460b0b3db803466428
-  data.tar.gz: e0c75f31911432f2544c4097fbc0c7a1615624257e80495aef9e5b3a0dddc92dd9341683d24416c4a32ab19b8bd34a2d79abb577781d75ee41b55a02f2e2e11c
+  metadata.gz: 9338ba66b860a68ba965534743dc9f119c19d7db3196432f003db98d056a2ac33f4ce600064200b44e61d355750bc1c2ff1ac1fe378ac0618c5716aea19de8f0
+  data.tar.gz: 44c1c821cde2adc873cb223b3459744959dbe4ab625ddf9da76a9f47e7662cdcd028a6a471f0243fdefea30c419e1e8c8c28c251c776b66b8c8168675dbc27c9

data/lib/api/db/put_pb.rb

@@ -7,7 +7,7 @@ require 'google/protobuf'
 require 'api/db/item_pb'
 
 
-descriptor_data = "\n\x0c\x64\x62/put.proto\x12\nstately.db\x1a\rdb/item.proto\"|\n\nPutRequest\x12\x19\n\x08store_id\x18\x01 \x01(\x04R\x07storeId\x12\'\n\x04puts\x18\x02 \x03(\x0b\x32\x13.stately.db.PutItemR\x04puts\x12*\n\x11schema_version_id\x18\x03 \x01(\rR\x0fschemaVersionId\"U\n\x07PutItem\x12$\n\x04item\x18\x01 \x01(\x0b\x32\x10.stately.db.ItemR\x04item\x12$\n\x0emust_not_exist\x18\x03 \x01(\x08R\x0cmustNotExist\"5\n\x0bPutResponse\x12&\n\x05items\x18\x01 \x03(\x0b\x32\x10.stately.db.ItemR\x05itemsBc\n\x0e\x63om.stately.dbB\x08PutProtoP\x01\xa2\x02\x03SDX\xaa\x02\nStately.Db\xca\x02\nStately\\Db\xe2\x02\x16Stately\\Db\\GPBMetadata\xea\x02\x0bStately::Dbb\x06proto3"
+descriptor_data = "\n\x0c\x64\x62/put.proto\x12\nstately.db\x1a\rdb/item.proto\"|\n\nPutRequest\x12\x19\n\x08store_id\x18\x01 \x01(\x04R\x07storeId\x12\'\n\x04puts\x18\x02 \x03(\x0b\x32\x13.stately.db.PutItemR\x04puts\x12*\n\x11schema_version_id\x18\x03 \x01(\rR\x0fschemaVersionId\"\x99\x01\n\x07PutItem\x12$\n\x04item\x18\x01 \x01(\x0b\x32\x10.stately.db.ItemR\x04item\x12\x42\n\x1doverwrite_metadata_timestamps\x18\x02 \x01(\x08R\x1boverwriteMetadataTimestamps\x12$\n\x0emust_not_exist\x18\x03 \x01(\x08R\x0cmustNotExist\"5\n\x0bPutResponse\x12&\n\x05items\x18\x01 \x03(\x0b\x32\x10.stately.db.ItemR\x05itemsBc\n\x0e\x63om.stately.dbB\x08PutProtoP\x01\xa2\x02\x03SDX\xaa\x02\nStately.Db\xca\x02\nStately\\Db\xe2\x02\x16Stately\\Db\\GPBMetadata\xea\x02\x0bStately::Dbb\x06proto3"
 
 pool = Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)

data/lib/common/auth/auth_token_provider.rb

@@ -13,33 +13,28 @@ require_relative "../../error"
 
 LOGGER = Logger.new($stdout)
 LOGGER.level = Logger::WARN
-DEFAULT_GRANT_TYPE = "client_credentials"
 
 # A module for Stately Cloud auth code
 module StatelyDB
   module Common
     # A module for Stately Cloud auth code
     module Auth
-      # Auth0TokenProvider is an implementation of the TokenProvider abstract base class
-      # 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.
+      # AuthTokenProvider is an implementation of the TokenProvider abstract base class
+      # which vends tokens from the StatelyDB auth API.
+      # It will default to using the value of `STATELY_ACCESS_KEY` if
+      # no credentials are explicitly passed and will throw an error if no credentials are found.
       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] origin The origin of the auth server
         # @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", nil),
-          client_id: ENV.fetch("STATELY_CLIENT_ID", nil),
-          access_key: ENV.fetch("STATELY_ACCESS_KEY", nil)
+          origin: "https://api.stately.cloud",
+          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, access_key: access_key))
+          @actor = Async::Actor.new(Actor.new(origin: origin, 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
@@ -61,32 +56,26 @@ module StatelyDB
         # This is designed to be used with Async::Actor and run on a dedicated thread.
         class Actor
           # @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:,
-            access_key:
-          )
+          # @param [String] access_key The StatelyDB access key credential
+          # @param [Float] base_retry_backoff_secs The base retry backoff in seconds
+          def initialize(origin:, access_key:, base_retry_backoff_secs:)
             super()
 
-            @token_fetcher = nil
-            if !access_key.nil?
-              @token_fetcher = StatelyDB::Common::Auth::StatelyAccessTokenFetcher.new(origin: origin, access_key: access_key)
-            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")
+            if access_key.nil?
+              raise StatelyDB::Error.new(
+                "Unable to find an access key in the STATELY_ACCESS_KEY " \
+                "environment variable. Either pass your credentials in " \
+                "the options when creating a client or set this environment variable.",
+                code: GRPC::Core::StatusCodes::UNAUTHENTICATED,
+                stately_code: "Unauthenticated"
+              )
             end
 
+            @token_fetcher = StatelyDB::Common::Auth::StatelyAccessTokenFetcher.new(
+              origin: origin,
+              access_key: access_key,
+              base_retry_backoff_secs: base_retry_backoff_secs
+            )
             @token_state = nil
             @pending_refresh = nil
           end

data/lib/common/auth/token_fetcher.rb

@@ -37,51 +37,24 @@ module StatelyDB
         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
-            # 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
-
-            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
-        def initialize(origin:, access_key:)
+        # @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,
@@ -91,14 +64,45 @@ module StatelyDB
         # Fetch a new token from the StatelyDB API
         # @return [TokenResult] The fetched TokenResult
         def fetch
-          resp = @stub.get_auth_token(Stately::Auth::GetAuthTokenRequest.new(access_key: @access_key))
-          TokenResult.new(token: resp.auth_token, expires_in_secs: resp.expires_in_s)
+          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/error.rb

@@ -41,9 +41,12 @@ module StatelyDB
           raw_detail = status.details[0]
           if raw_detail.type_url == "type.googleapis.com/stately.errors.StatelyErrorDetails"
             error_details = Stately::Errors::StatelyErrorDetails.decode(raw_detail.value)
+            message = error_details.message
+            rid = error.metadata["st-rid"]
+            message = "#{message} (Request ID: #{rid})" unless rid.nil?
             upstream_cause = error_details.upstream_cause.empty? ? nil : StandardError.new(error_details.upstream_cause) # rubocop:disable Metrics/BlockNesting
-            return new(error_details.message, code: error.code, stately_code: error_details.stately_code,
-                                              cause: upstream_cause)
+            return new(message, code: error.code, stately_code: error_details.stately_code,
+                                cause: upstream_cause)
           end
         end
       end

data/lib/statelydb.rb

@@ -188,12 +188,20 @@ module StatelyDB
     #   `initialValue` field in its key, that initial value will automatically
     #   be chosen not to conflict with existing items, so this condition only
     #   applies to key paths that do not contain the `initialValue` field.
+    # @param overwrite_metadata_timestamps [Boolean] If set to true, the server will
+    #   set the `createdAtTime` and/or `lastModifiedAtTime` fields based on the
+    #   current values in this item (assuming you've mapped them to a field using
+    #   `fromMetadata`). Without this, those fields are always ignored and the
+    #   server sets them to the appropriate times. This option can be useful when
+    #   migrating data from another system.
     # @return [StatelyDB::Item] the item that was stored
     #
     # @example client.data.put(my_item)
     # @example client.data.put(my_item, must_not_exist: true)
-    def put(item, must_not_exist: false)
-      resp = put_batch({ item:, must_not_exist: })
+    def put(item,
+            must_not_exist: false,
+            overwrite_metadata_timestamps: false)
+      resp = put_batch({ item:, must_not_exist:, overwrite_metadata_timestamps: })
 
       # Always return a single Item.
       resp.first
@@ -215,6 +223,7 @@ module StatelyDB
           item = input[:item]
           Stately::Db::PutItem.new(
             item: item.send("marshal_stately"),
+            overwrite_metadata_timestamps: input[:overwrite_metadata_timestamps],
             must_not_exist: input[:must_not_exist]
           )
         else

data/lib/transaction/transaction.rb

@@ -233,6 +233,12 @@ module StatelyDB
       #   `initialValue` field in its key, that initial value will automatically
       #   be chosen not to conflict with existing items, so this condition only
       #   applies to key paths that do not contain the `initialValue` field.
+      # @param overwrite_metadata_timestamps [Boolean] If set to true, the server will
+      #   set the `createdAtTime` and/or `lastModifiedAtTime` fields based on the
+      #   current values in this item (assuming you've mapped them to a field using
+      #   `fromMetadata`). Without this, those fields are always ignored and the
+      #   server sets them to the appropriate times. This option can be useful when
+      #   migrating data from another system.
       # @return [String, Integer] the id of the item
       #
       # @example
@@ -242,8 +248,10 @@ module StatelyDB
       #  results.puts.each do |result|
       #    puts result.key_path
       #  end
-      def put(item, must_not_exist: false)
-        resp = put_batch({ item:, must_not_exist: })
+      def put(item,
+              must_not_exist: false,
+              overwrite_metadata_timestamps: false)
+        resp = put_batch({ item:, must_not_exist:, overwrite_metadata_timestamps: })
         resp.first
       end
 
@@ -269,6 +277,7 @@ module StatelyDB
             item = input[:item]
             Stately::Db::PutItem.new(
               item: item.send("marshal_stately"),
+              overwrite_metadata_timestamps: input[:overwrite_metadata_timestamps],
               must_not_exist: input[:must_not_exist]
             )
           else

data/sig/statelydb.rbi

@@ -313,6 +313,8 @@ module StatelyDB
     # 
     # _@param_ `must_not_exist` — A condition that indicates this item must not already exist at any of its key paths. If there is already an item at one of those paths, the Put operation will fail with a "ConditionalCheckFailed" error. Note that if the item has an `initialValue` field in its key, that initial value will automatically be chosen not to conflict with existing items, so this condition only applies to key paths that do not contain the `initialValue` field.
     # 
+    # _@param_ `overwrite_metadata_timestamps` — If set to true, the server will set the `createdAtTime` and/or `lastModifiedAtTime` fields based on the current values in this item (assuming you've mapped them to a field using `fromMetadata`). Without this, those fields are always ignored and the server sets them to the appropriate times. This option can be useful when migrating data from another system.
+    # 
     # _@return_ — the item that was stored
     # 
     # client.data.put(my_item)
@@ -322,8 +324,8 @@ module StatelyDB
     # client.data.put(my_item, must_not_exist: true)
     # ```ruby
     # ```
-    sig { params(item: StatelyDB::Item, must_not_exist: T::Boolean).returns(StatelyDB::Item) }
-    def put(item, must_not_exist: false); end
+    sig { params(item: StatelyDB::Item, must_not_exist: T::Boolean, overwrite_metadata_timestamps: T::Boolean).returns(StatelyDB::Item) }
+    def put(item, must_not_exist: false, overwrite_metadata_timestamps: false); end
 
     # Put a batch of up to 50 Items into a StatelyDB Store.
     # 
@@ -605,42 +607,24 @@ module StatelyDB
         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
-        sig { params(origin: String, access_key: String).void }
-        def initialize(origin:, access_key:); end
+        # 
+        # _@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
         # 
@@ -650,6 +634,14 @@ module StatelyDB
 
         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
@@ -668,30 +660,18 @@ module StatelyDB
         def close; end
       end
 
-      # Auth0TokenProvider is an implementation of the TokenProvider abstract base class
-      # 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.
+      # AuthTokenProvider is an implementation of the TokenProvider abstract base class
+      # which vends tokens from the StatelyDB auth API.
+      # It will default to using the value of `STATELY_ACCESS_KEY` if
+      # no credentials are explicitly passed and will throw an error if no credentials are found.
       class AuthTokenProvider < StatelyDB::Common::Auth::TokenProvider
-        # _@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
+        # _@param_ `origin` — The origin of the auth server
         # 
         # _@param_ `access_key` — The StatelyDB access key credential
-        sig do
-          params(
-            origin: String,
-            audience: String,
-            client_secret: String,
-            client_id: String,
-            access_key: String
-          ).void
-        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)); end
+        # 
+        # _@param_ `base_retry_backoff_secs` — The base retry backoff in seconds
+        sig { params(origin: String, access_key: String, base_retry_backoff_secs: Float).void }
+        def initialize(origin: "https://api.stately.cloud", 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
@@ -709,21 +689,11 @@ module StatelyDB
         class Actor
           # _@param_ `origin` — The origin of the OAuth server
           # 
-          # _@param_ `audience` — The OAuth Audience for the token
+          # _@param_ `access_key` — The StatelyDB access key credential
           # 
-          # _@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,
-              access_key: T.untyped
-            ).void
-          end
-          def initialize(origin:, audience:, client_secret:, client_id:, access_key:); end
+          # _@param_ `base_retry_backoff_secs` — The base retry backoff 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
 
           # Initialize the actor. This runs on the actor thread which means
           # we can dispatch async operations here.
@@ -973,6 +943,8 @@ module StatelyDB
       # 
       # _@param_ `must_not_exist` — A condition that indicates this item must not already exist at any of its key paths. If there is already an item at one of those paths, the Put operation will fail with a "ConditionalCheckFailed" error. Note that if the item has an `initialValue` field in its key, that initial value will automatically be chosen not to conflict with existing items, so this condition only applies to key paths that do not contain the `initialValue` field.
       # 
+      # _@param_ `overwrite_metadata_timestamps` — If set to true, the server will set the `createdAtTime` and/or `lastModifiedAtTime` fields based on the current values in this item (assuming you've mapped them to a field using `fromMetadata`). Without this, those fields are always ignored and the server sets them to the appropriate times. This option can be useful when migrating data from another system.
+      # 
       # _@return_ — the id of the item
       # 
       # ```ruby
@@ -980,8 +952,8 @@ module StatelyDB
       #   txn.put(my_item)
       # end
       # ```
-      sig { params(item: StatelyDB::Item, must_not_exist: T::Boolean).returns(T.any(String, Integer)) }
-      def put(item, must_not_exist: false); end
+      sig { params(item: StatelyDB::Item, must_not_exist: T::Boolean, overwrite_metadata_timestamps: T::Boolean).returns(T.any(String, Integer)) }
+      def put(item, must_not_exist: false, overwrite_metadata_timestamps: false); end
 
       # Put a batch of up to 50 Items into a StatelyDB Store. Results are not
       # returned until the transaction is committed and will be available in the

data/sig/statelydb.rbs

@@ -267,6 +267,8 @@ module StatelyDB
     # 
     # _@param_ `must_not_exist` — A condition that indicates this item must not already exist at any of its key paths. If there is already an item at one of those paths, the Put operation will fail with a "ConditionalCheckFailed" error. Note that if the item has an `initialValue` field in its key, that initial value will automatically be chosen not to conflict with existing items, so this condition only applies to key paths that do not contain the `initialValue` field.
     # 
+    # _@param_ `overwrite_metadata_timestamps` — If set to true, the server will set the `createdAtTime` and/or `lastModifiedAtTime` fields based on the current values in this item (assuming you've mapped them to a field using `fromMetadata`). Without this, those fields are always ignored and the server sets them to the appropriate times. This option can be useful when migrating data from another system.
+    # 
     # _@return_ — the item that was stored
     # 
     # client.data.put(my_item)
@@ -276,7 +278,7 @@ module StatelyDB
     # client.data.put(my_item, must_not_exist: true)
     # ```ruby
     # ```
-    def put: (StatelyDB::Item item, ?must_not_exist: bool) -> StatelyDB::Item
+    def put: (StatelyDB::Item item, ?must_not_exist: bool, ?overwrite_metadata_timestamps: bool) -> StatelyDB::Item
 
     # Put a batch of up to 50 Items into a StatelyDB Store.
     # 
@@ -524,36 +526,17 @@ module StatelyDB
         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
-        def initialize: (origin: String, access_key: String) -> void
+        # 
+        # _@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
         # 
@@ -561,6 +544,13 @@ module StatelyDB
         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
@@ -577,27 +567,17 @@ module StatelyDB
         def close: () -> untyped
       end
 
-      # Auth0TokenProvider is an implementation of the TokenProvider abstract base class
-      # 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.
+      # AuthTokenProvider is an implementation of the TokenProvider abstract base class
+      # which vends tokens from the StatelyDB auth API.
+      # It will default to using the value of `STATELY_ACCESS_KEY` if
+      # no credentials are explicitly passed and will throw an error if no credentials are found.
       class AuthTokenProvider < StatelyDB::Common::Auth::TokenProvider
-        # _@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
+        # _@param_ `origin` — The origin of the auth server
         # 
         # _@param_ `access_key` — The StatelyDB access key credential
-        def initialize: (
-                          ?origin: String,
-                          ?audience: String,
-                          ?client_secret: String,
-                          ?client_id: String,
-                          ?access_key: String
-                        ) -> void
+        # 
+        # _@param_ `base_retry_backoff_secs` — The base retry backoff in seconds
+        def initialize: (?origin: String, ?access_key: String, ?base_retry_backoff_secs: Float) -> void
 
         # Close the token provider and kill any background operations
         # This just invokes the close method on the actor which should do the cleanup
@@ -613,18 +593,10 @@ module StatelyDB
         class Actor
           # _@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_ `access_key` — The StatelyDB access key credential
           # 
-          # _@param_ `client_id` — The StatelyDB client ID credential
-          def initialize: (
-                            origin: String,
-                            audience: String,
-                            client_secret: String,
-                            client_id: String,
-                            access_key: untyped
-                          ) -> void
+          # _@param_ `base_retry_backoff_secs` — The base retry backoff in seconds
+          def initialize: (origin: String, access_key: String, base_retry_backoff_secs: Float) -> void
 
           # Initialize the actor. This runs on the actor thread which means
           # we can dispatch async operations here.
@@ -838,6 +810,8 @@ module StatelyDB
       # 
       # _@param_ `must_not_exist` — A condition that indicates this item must not already exist at any of its key paths. If there is already an item at one of those paths, the Put operation will fail with a "ConditionalCheckFailed" error. Note that if the item has an `initialValue` field in its key, that initial value will automatically be chosen not to conflict with existing items, so this condition only applies to key paths that do not contain the `initialValue` field.
       # 
+      # _@param_ `overwrite_metadata_timestamps` — If set to true, the server will set the `createdAtTime` and/or `lastModifiedAtTime` fields based on the current values in this item (assuming you've mapped them to a field using `fromMetadata`). Without this, those fields are always ignored and the server sets them to the appropriate times. This option can be useful when migrating data from another system.
+      # 
       # _@return_ — the id of the item
       # 
       # ```ruby
@@ -845,7 +819,7 @@ module StatelyDB
       #   txn.put(my_item)
       # end
       # ```
-      def put: (StatelyDB::Item item, ?must_not_exist: bool) -> (String | Integer)
+      def put: (StatelyDB::Item item, ?must_not_exist: bool, ?overwrite_metadata_timestamps: bool) -> (String | Integer)
 
       # Put a batch of up to 50 Items into a StatelyDB Store. Results are not
       # returned until the transaction is committed and will be available in the

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statelydb
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Stately Cloud, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-12 00:00:00.000000000 Z
+date: 2024-12-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async