statelydb 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1d7563d7f40d84bdc1ef3dacff41707ed1d915b638223d33b488ca4c7de531f
-  data.tar.gz: dd682b92fbc100505e15820c5415acadc9defc6bc2f2d0dad5b5797deddbf24b
+  metadata.gz: 1f23ab192f6828001354306b8ad34133ec3d2ffd190b984317b21cdd37f13260
+  data.tar.gz: 4748c4cb64afcec1ae6855b13eb77431686c5969519676ba76b312e13af328c6
 SHA512:
-  metadata.gz: c0f27aa770fdf0c7b3386ac37862226cb4b5215766d265e47c82323b2157966e6ce0d87b5e4081d8d9dcd549f45cd0f6527203b0025b0e6c62ce0780c81dae74
-  data.tar.gz: de86db0a2a0227e6bec231d11c378bffff42fa7911ccc0874bd3ed97fae7f73d0ac29ce55b31817f75bfa82c0b63daa79dabd28276a66e17e2748770450f6243
+  metadata.gz: b0fa966836be47eaa591ab5d88b10107471a28b0d4b05f4fb34d655a14826ae77f11bcf45096eb40c9c90acfdf4aba8b1c78cc849340fae79afd230608635812
+  data.tar.gz: 5911f73934190cbd9bdb415241f332bd740a4e073bbde7b2bb5f4a7fc8e91fcaccf18f246a3633be8d4401065f777a75a88243f8126b628163737b2f5bb3e070

data/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 Stately Cloud, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -8,13 +8,6 @@ This is the Ruby SDK for [StatelyDB](https://stately.cloud).
 
 We're still in an invite-only preview mode - if you're interested, please reach out to [preview@stately.cloud](mailto:preview@stately.cloud?subject=Early%20Access%20Program).
 
-When you join the preview program, we'll set you up with a few bits of information:
-
-1. `STATELY_CLIENT_ID` - a client identifier so we know what client you are.
-2. `STATELY_CLIENT_SECRET` - a sensitive secret that lets your applications authenticate with the API.
-3. A store ID that identifies which store in your organization you're using.
-4. Access to our in-depth [Getting Started Guide].
-
 Begin by following our [Getting Started Guide] which will help you define, generate, and publish a DB schema so that it can be used.
 
 ##### Install the SDK
@@ -32,8 +25,8 @@ Create an authenticated client, then import your item types from your generated
 require_relative 'schema/stately'
 
 def put_my_item
-    # Create a client. This will use the environment variables
-    # STATELY_CLIENT_ID and STATELY_CLIENT_SECRET for your client.
+    # Create a client. This will use the environment variable
+    # STATELY_ACCESS_KEY to read your access key
     client = StatelyDB::Client.new(store_id: <my-store-id>)
 
     # Instantiate an item from your schema

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,36 +13,27 @@ 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] endpoint The endpoint 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),
+          endpoint: "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,
-                                              base_retry_backoff_secs: base_retry_backoff_secs))
+          @actor = Async::Actor.new(Actor.new(endpoint:, access_key:, 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
@@ -63,38 +54,27 @@ module StatelyDB
         # Actor for managing the token refresh
         # 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
+          # @param [String] endpoint The endpoint of the OAuth 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:,
-            audience:,
-            client_secret:,
-            client_id:,
-            access_key:,
-            base_retry_backoff_secs:
-          )
+          def initialize(endpoint:, 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, base_retry_backoff_secs: base_retry_backoff_secs
+            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"
               )
-            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_fetcher = StatelyDB::Common::Auth::StatelyAccessTokenFetcher.new(
+              endpoint: endpoint,
+              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,42 +37,6 @@ 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
-            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 = [
@@ -84,14 +48,14 @@ module StatelyDB
         ].freeze
         RETRY_ATTEMPTS = 10
 
-        # @param [String] origin The origin of the OAuth server
+        # @param [String] endpoint The endpoint 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:)
+        def initialize(endpoint:, 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)
+          @channel = Common::Net.new_channel(endpoint:)
           error_interceptor = Common::ErrorInterceptor.new
           @stub = Stately::Auth::AuthService::Stub.new(nil, nil, channel_override: @channel,
                                                                  interceptors: [error_interceptor])

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/key_path.rb

@@ -58,7 +58,7 @@ module StatelyDB
         [value].pack("m0").tr("=", "").tr("+/", "-_")
       else
         # Any other value is just converted to a string
-        value.to_s
+        value.to_s.gsub("/", "%/")
       end
     end
   end

data/lib/statelydb.rb

@@ -28,11 +28,14 @@ module StatelyDB
     # @param token_provider [Common::Auth::TokenProvider] the token provider to use for authentication.
     # @param endpoint [String] the endpoint to connect to.
     # @param region [String] the region to connect to.
+    # @param no_auth [Boolean] Indicates that the client should not attempt to get
+    #     an auth token. This is used when talking to the Stately BYOC Data Plane on localhost.
     def initialize(store_id:,
                    schema:,
                    token_provider: Common::Auth::AuthTokenProvider.new,
                    endpoint: nil,
-                   region: nil)
+                   region: nil,
+                   no_auth: false)
       if store_id.nil?
         raise StatelyDB::Error.new("store_id is required",
                                    code: GRPC::Core::StatusCodes::INVALID_ARGUMENT,
@@ -46,13 +49,14 @@ module StatelyDB
 
       endpoint = self.class.make_endpoint(endpoint:, region:)
       @channel = Common::Net.new_channel(endpoint:)
-      @token_provider = token_provider
+      # Make sure to use the correct endpoint for the default token provider
+      @token_provider = token_provider || Common::Auth::AuthTokenProvider.new(endpoint:)
 
-      auth_interceptor = Common::Auth::Interceptor.new(token_provider:)
-      error_interceptor = Common::ErrorInterceptor.new
+      interceptors = [Common::ErrorInterceptor.new]
+      interceptors << Common::Auth::Interceptor.new(token_provider:) unless no_auth
 
-      @stub = Stately::Db::DatabaseService::Stub.new(nil, nil, channel_override: @channel,
-                                                               interceptors: [error_interceptor, auth_interceptor])
+      @stub = Stately::Db::DatabaseService::Stub.new(nil, nil,
+                                                     channel_override: @channel, interceptors:)
       @store_id = store_id.to_i
       @schema = schema
       @allow_stale = false
@@ -188,12 +192,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 +227,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

@@ -204,16 +204,19 @@ module StatelyDB
     # _@param_ `endpoint` — the endpoint to connect to.
     # 
     # _@param_ `region` — the region to connect to.
+    # 
+    # _@param_ `no_auth` — Indicates that the client should not attempt to get an auth token. This is used when talking to the Stately BYOC Data Plane on localhost.
     sig do
       params(
         store_id: Integer,
         schema: Module,
         token_provider: Common::Auth::TokenProvider,
         endpoint: T.nilable(String),
-        region: T.nilable(String)
+        region: T.nilable(String),
+        no_auth: T::Boolean
       ).void
     end
-    def initialize(store_id:, schema:, token_provider: Common::Auth::AuthTokenProvider.new, endpoint: nil, region: nil); end
+    def initialize(store_id:, schema:, token_provider: Common::Auth::AuthTokenProvider.new, endpoint: nil, region: nil, no_auth: false); end
 
     # _@return_ — nil
     sig { void }
@@ -313,6 +316,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 +327,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,35 +610,6 @@ 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([
@@ -645,13 +621,13 @@ module StatelyDB
 ].freeze, T.untyped)
         RETRY_ATTEMPTS = T.let(10, T.untyped)
 
-        # _@param_ `origin` — The origin of the OAuth server
+        # _@param_ `endpoint` — The endpoint 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
+        sig { params(endpoint: String, access_key: String, base_retry_backoff_secs: Float).void }
+        def initialize(endpoint:, access_key:, base_retry_backoff_secs:); end
 
         # Fetch a new token from the StatelyDB API
         # 
@@ -687,33 +663,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_ `endpoint` — The endpoint of the auth server
         # 
         # _@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,
-            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", nil), client_id: ENV.fetch("STATELY_CLIENT_ID", nil), access_key: ENV.fetch("STATELY_ACCESS_KEY", nil), base_retry_backoff_secs: 1); end
+        sig { params(endpoint: String, access_key: String, base_retry_backoff_secs: Float).void }
+        def initialize(endpoint: "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
@@ -729,28 +690,13 @@ module StatelyDB
         # Actor for managing the token refresh
         # This is designed to be used with Async::Actor and run on a dedicated thread.
         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_ `client_id` — The StatelyDB client ID credential
+          # _@param_ `endpoint` — The endpoint of the OAuth server
           # 
           # _@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,
-              access_key: String,
-              base_retry_backoff_secs: Float
-            ).void
-          end
-          def initialize(origin:, audience:, client_secret:, client_id:, access_key:, base_retry_backoff_secs:); end
+          sig { params(endpoint: String, access_key: String, base_retry_backoff_secs: Float).void }
+          def initialize(endpoint:, access_key:, base_retry_backoff_secs:); end
 
           # Initialize the actor. This runs on the actor thread which means
           # we can dispatch async operations here.
@@ -1000,6 +946,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
@@ -1007,8 +955,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

@@ -170,12 +170,15 @@ module StatelyDB
     # _@param_ `endpoint` — the endpoint to connect to.
     # 
     # _@param_ `region` — the region to connect to.
+    # 
+    # _@param_ `no_auth` — Indicates that the client should not attempt to get an auth token. This is used when talking to the Stately BYOC Data Plane on localhost.
     def initialize: (
                       store_id: Integer,
                       schema: Module,
                       ?token_provider: Common::Auth::TokenProvider,
                       ?endpoint: String?,
-                      ?region: String?
+                      ?region: String?,
+                      ?no_auth: bool
                     ) -> void
 
     # _@return_ — nil
@@ -267,6 +270,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 +281,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,41 +529,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_ `endpoint` — The endpoint 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
+        def initialize: (endpoint: String, access_key: String, base_retry_backoff_secs: Float) -> void
 
         # Fetch a new token from the StatelyDB API
         # 
@@ -589,30 +570,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_ `endpoint` — The endpoint of the auth server
         # 
         # _@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,
-                          ?access_key: String,
-                          ?base_retry_backoff_secs: Float
-                        ) -> void
+        def initialize: (?endpoint: 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
@@ -626,25 +594,12 @@ module StatelyDB
         # Actor for managing the token refresh
         # This is designed to be used with Async::Actor and run on a dedicated thread.
         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_ `client_id` — The StatelyDB client ID credential
+          # _@param_ `endpoint` — The endpoint of the OAuth server
           # 
           # _@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,
-                            access_key: String,
-                            base_retry_backoff_secs: Float
-                          ) -> void
+          def initialize: (endpoint: 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.
@@ -858,6 +813,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
@@ -865,7 +822,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.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Stately Cloud, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-13 00:00:00.000000000 Z
+date: 2025-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -72,6 +72,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE.txt
 - README.md
 - lib/api/auth/get_auth_token_pb.rb
 - lib/api/auth/service_pb.rb