kinetic_sdk 7.0.0.rc2 → 7.0.0.rc4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d17b093333b568589b62518a2d39f94d34bc0a82833a18df3aa0fae4c9e4d913
-  data.tar.gz: e90ffa58599c343b80e7907102f3a7f858035f1150de4a8fd0a3f5b151dcf66a
+  metadata.gz: 0ab81a960e1aebbf2e7cd839fdf3fd60c33ca71e985e0c6530c7e84ca8e8ec6f
+  data.tar.gz: d485a88f2085aa142c0015c2899999d46c403f66b8b460efffb0918730ca51aa
 SHA512:
-  metadata.gz: 78a37fe4b1776e46ebe64d64e4c779967cec791292474378155cca09a835a5041e12deea60ba28d7f713621ded57f2dfeb99b50cd14e9d5b802354a885a9bb70
-  data.tar.gz: c3f15b84bbb614618944866ab1f3d5f59eea9875a1ef23a3e4452079eca425e9d5a0eae872345606e063d6be3b35654791b348ba4019a382646afd44afde1637
+  metadata.gz: dbd1dbf0607dc20f54e2cbea981496d1fbc8088c8b00fa8ce6483317577fe15bff2b8ae3328d7e797506dea4db66a9cc5c6d3b3ca491bdc99a0ff6fd144e9725
+  data.tar.gz: 86092ddc85c919ace2d1bb3133c8feb9aa320969162e471cc100617b81fef05fa0dc5b644c770dbb1a41ebc8c4b6e8aa53586bcc31463b966caef2fb44aa74fe

data/CHANGELOG.md

@@ -1,6 +1,70 @@
 # Change Log
 
 
+## [7.0.0.rc4](https://github.com/kineticdata/kinetic-sdk-rb/tree/7.0.0.rc4) (2026-09-01)
+
+**Breaking changes:**
+
+- `jwt_token` now uses the OAuth 2.0 `client_credentials` grant, a single POST to
+  `/{space_slug}/app/oauth2/token`. Kinetic Platform 7 runs a standards compliant
+  authorization server in which `/app/oauth2/authorize` is an interactive endpoint
+  requiring a browser session, consent, a registered redirect_uri and PKCE, so the
+  previous authorization-code flow returned `400`. The response shape is unchanged:
+  callers reading `jwt_response.content["access_token"]` are unaffected.
+- `jwt_code` has been removed. It drove the authorization-code flow that no longer
+  applies to machine to machine clients.
+- The OAuth client used by the SDK must be registered in the space as a **confidential**
+  client (or with no `clientType`, which defaults to confidential). Public clients and
+  the built in system client register only the `authorization_code` grant and are
+  rejected by the token endpoint.
+
+**Fixed bugs:**
+
+- The OAuth routes are now space scoped (`/{space_slug}/app/oauth2/...`) when the SDK is
+  built from an `:app_server_url` plus a `:space_slug`. The authorization server resolves
+  the space from the request path and rejects requests made outside a space context.
+- OAuth failures now report the `error` and `error_description` from a JSON error, or the
+  `X-Kinetic-CID` correlation id when Core answers with its generic HTML error page,
+  instead of dumping the inspected response object.
+
+**Implemented enhancements:**
+
+- Added the `:oauth_scope` option, defaulting to `full`. Valid scopes are `full`, `read`,
+  `write`, `admin`, `submissions` and `submissions:read`.
+- Added specs covering the token exchange, scope configuration, and the failure modes for
+  both the Integrator and Discussions SDKs.
+
+
+## [7.0.0.rc3](https://github.com/kineticdata/kinetic-sdk-rb/tree/7.0.0.rc3) (2026-09-01)
+
+**Fixed bugs:**
+
+- Fixed a crash in `import_trees` and `import_trees_threaded` that aborted template installs
+  with `NoMethodError: undefined method 'document' for an instance of File`. The tree
+  comparison introduced in 7.x passed a raw `File` handle to `REXML::XPath.first`, which
+  requires a parsed document.
+- Removed the tree comparison entirely, restoring the unconditional import behavior of 5.0.29.
+  The comparison identified trees by a `//definitionId` element that exists only in routine
+  exports, never in the tree exports `import_trees` reads, so it could not succeed. See the
+  specs in `spec/kinetic_sdk/task/trees_spec.rb`.
+- The per-tree and per-routine rescues in the threaded importers no longer discard exceptions
+  silently; failures are logged and propagated.
+- `trees.rb` now requires `rexml/document` explicitly rather than relying on load order.
+
+**Implemented enhancements:**
+
+- Added rspec and the first unit test coverage, run with `bundle exec rspec` or `rake spec`.
+
+
+## [7.0.0.rc2](https://github.com/kineticdata/kinetic-sdk-rb/tree/7.0.0.rc2) (2026-09-01)
+
+**Fixed bugs:**
+
+- Declared `concurrent-ruby` and `rexml` as runtime dependencies. Both were required by the
+  library but missing from the gemspec, so the published gem could fail to load.
+- Pinned `BUNDLED WITH` to a concrete Bundler version; the range value broke `bundle install`.
+
+
 ## [7.0.0-rc1](https://github.com/kineticdata/kinetic-sdk-rb/tree/7.0.0-rc1) (2026-08-31)
 
 **Breaking changes:**

data/Rakefile

@@ -7,7 +7,19 @@ YARD::Rake::YardocTask.new do |t|
   t.stats_options = %w( --list-undoc )
 end
 
+# Run the specs. Guarded so the Rakefile still loads (and `rake build` still
+# works) in an environment where the development dependencies are absent.
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+  desc "Run the specs (rspec is not installed)"
+  task :spec do
+    abort "rspec is not available. Run `bundle install` first."
+  end
+end
+
 # Generate Yard documentation
 task :doc => [:yard]
 task :rdoc => [:yard]
-task :default => [:doc]
+task :default => [:spec, :doc]

data/kinetic_sdk.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", ">= 1.17"
   spec.add_development_dependency "rake", ">= 13.0.1"
   spec.add_development_dependency "yard", "~> 0.9.45"
+  spec.add_development_dependency "rspec", "~> 3.13"
 
   spec.metadata["yard.run"] = "yri"
 end

data/lib/kinetic_sdk/core/core-sdk.rb

@@ -14,7 +14,8 @@ module KineticSdk
     include KineticSdk::Utils::KineticExportUtils
 
     attr_reader :api_url, :username, :options, :password, :proxy_url,
-                :space_slug, :server, :version, :logger
+                :space_slug, :server, :version, :logger, :oauth_url,
+                :oauth_scope
 
     # Initalize the Core SDK with the web server URL, the space user
     # username and password, along with any custom option values.
@@ -55,6 +56,8 @@ module KineticSdk
     #   * :max_redirects (Fixnum) (_defaults to: 5_) maximum number of redirects to follow
     #   * :ssl_ca_file (String) full path to PEM certificate used to verify the server
     #   * :ssl_verify_mode (String) (_defaults to: none_) - none | peer
+    #   * :oauth_scope (String) (_defaults to: full_) scope requested when retrieving a
+    #     JWT - full | read | write | admin | submissions | submissions:read
     #
     # Example: using a configuration file
     #
@@ -154,12 +157,17 @@ module KineticSdk
         @server = options[:app_server_url].chomp('/')
         @api_url = @server + (@space_slug.nil? ? "/app/api/v1" : "/#{@space_slug}/app/api/v1")
         @proxy_url = @space_slug.nil? ? nil : "#{@server}/#{@space_slug}/app/components"
+        # The authorization server resolves the space from the request path, so the
+        # OAuth routes must be space scoped exactly like the API routes.
+        @oauth_url = @server + (@space_slug.nil? ? "/app/oauth2" : "/#{@space_slug}/app/oauth2")
       else
         raise StandardError.new "The :space_slug option is required when using the :space_server_url option" if @space_slug.nil?
         @server = options[:space_server_url].chomp('/')
         @api_url = "#{@server}/app/api/v1"
         @proxy_url = "#{@server}/app/components"
+        @oauth_url = "#{@server}/app/oauth2"
       end
+      @oauth_scope = @options[:oauth_scope] || @options["oauth_scope"] || "full"
       @version = 1
     end
 

data/lib/kinetic_sdk/core/lib/jwt.rb

@@ -1,55 +1,79 @@
 module KineticSdk
   class Core
 
-    # Gets an authentication token
+    # Gets an authentication token using the OAuth 2.0 client credentials grant.
+    #
+    # Kinetic Platform 7 runs a standards compliant authorization server, in which
+    # `/app/oauth2/authorize` is an interactive endpoint: it expects an authenticated
+    # browser session, a consent round trip, a registered redirect_uri, and PKCE. A
+    # machine to machine client cannot drive it, and should not try - it exchanges its
+    # own credentials for a token directly at the token endpoint instead.
+    #
+    # The OAuth client must be registered in the space as a confidential client (or with
+    # no clientType, which defaults to confidential) so that it carries the
+    # `client_credentials` grant. Public clients and the built in system client support
+    # only `authorization_code`, and will be rejected here.
     #
     # @param client_id [String] the oauth client id
     # @param client_secret [String] the oauth client secret
-    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
+    # @param headers [Hash] additional headers to send. The Accept, Authorization and
+    #   Content-Type headers required by the token endpoint always take precedence.
+    # @param scope [String] scope to request, defaults to the +:oauth_scope+ option (+full+)
     # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
-    def jwt_token(client_id, client_secret, headers = default_headers)
-      # retrieve the jwt code
-      jwt_code = jwt_code(client_id, headers)
-      # retrieve the jwt token
+    def jwt_token(client_id, client_secret, headers = {}, scope = oauth_scope)
       @logger.info("Retrieving JWT authorization token")
-      url = "#{@server}/app/oauth2/token?grant_type=authorization_code&response_type=token&client_id=#{client_id}&code=#{jwt_code}"
-      token_headers = header_accept_json.merge(header_basic_auth(client_id, client_secret))
-      response = post(url, {}, token_headers, { :max_redirects => 0 })
+      url = "#{@oauth_url}/token"
+
+      # The required headers are merged last so that a caller passing the SDK default
+      # headers cannot replace the client's basic authentication with the user's.
+      token_headers = headers
+        .merge(header_accept_json)
+        .merge(header_basic_auth(client_id, client_secret))
+        .merge({ "Content-Type" => "application/x-www-form-urlencoded" })
+
+      payload = { "grant_type" => "client_credentials" }
+      payload["scope"] = scope unless scope.nil? || scope.to_s.empty?
 
-      if response.status == 401
-        raise StandardError.new "#{response.message}, the oauth client id and secret are invalid."
-      elsif response.status == 200
+      # Redirects are not followed: the token endpoint has no reason to redirect, and
+      # following one would forward the client credentials to another host.
+      response = post(url, URI.encode_www_form(payload), token_headers, { :max_redirects => 0 })
+
+      case response.status
+      when 200
         response
+      when 401
+        raise StandardError.new(
+          "Unable to retrieve token: #{oauth_error_message(response)}. The oauth client id " \
+          "and secret are invalid, or no such client is registered in this space."
+        )
       else
-        raise StandardError.new "Unable to retrieve token: #{response}"
+        raise StandardError.new("Unable to retrieve token: #{oauth_error_message(response)}")
       end
     end
 
-    # Gets an authentication code.
+    private
+
+    # Builds an actionable message from an OAuth error response.
     #
-    # This method should really never need to be called externally.
+    # The authorization server answers most failures with a JSON OAuth error, but falls
+    # back to Core's generic HTML error page for others. That page carries no error code,
+    # only a correlation id in the X-Kinetic-CID response header, which is what is needed
+    # to find the matching entry in the server log.
     #
-    # @param client_id [String]
-    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
-    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
-    def jwt_code(client_id, headers = default_headers)
-      @logger.info("Retrieving JWT authorization code")
-      url = "#{@server}/app/oauth2/authorize?grant_type=authorization_code&response_type=code&client_id=#{client_id}"
-      response = post(url, {}, headers, { :max_redirects => -1 })
-
-      if response.status == 401
-        raise StandardError.new "#{response.message}: #{response.content["error"]}"
-      elsif response.status == 302 || response.status == 303
-        location = response.headers["location"]
-        if location.nil?
-          raise StandardError.new "Unable to retrieve code: #{response.inspect}"
-        elsif !location.include?("?code=")
-          raise StandardError.new "Unable to retrieve code, the authorize endpoint redirected to #{location} without an authorization code."
-        else
-          location.split("?code=").last.split("#/").first
-        end
+    # @param response [KineticSdk::Utils::KineticHttpResponse] the failed response
+    # @return [String] a single line description of the failure
+    def oauth_error_message(response)
+      content = response.content.is_a?(Hash) ? response.content : {}
+      if content["error"]
+        message = "#{response.status} #{content["error"]}"
+        message += " - #{content["error_description"]}" if content["error_description"]
+        message
       else
-        raise StandardError.new "Unable to retrieve code #{response.inspect}"
+        message = "#{response.status} #{response.message}"
+        headers = response.headers
+        correlation_id = headers.is_a?(Hash) ? headers["x-kinetic-cid"] : nil
+        message += " (correlation id #{correlation_id})" if correlation_id
+        message
       end
     end
   end

data/lib/kinetic_sdk/task/lib/trees.rb

@@ -1,3 +1,5 @@
+require 'rexml/document'
+
 module KineticSdk
   class Task
     # Delete a tree.
@@ -146,12 +148,7 @@ module KineticSdk
       @logger.info("Importing all Trees from Export Directory")
       Dir["#{@options[:export_directory]}/sources/**/*.xml"].sort.each do |file|
         tree_file = File.new(file, "rb")
-        match = compare_trees(tree_file)
-        if !match
-          import_tree(tree_file, force_overwrite, headers)
-        else
-          #Matching trees, skipping
-        end
+        import_tree(tree_file, force_overwrite, headers)
       end
     end
     def import_trees_threaded(force_overwrite=false, headers=header_basic_auth)
@@ -164,48 +161,18 @@ module KineticSdk
       Dir["#{@options[:export_directory]}/sources/**/*.xml"].sort.each do |file|
         promises << Concurrent::Promise.execute(executor: pool) do
           begin
-
             tree_file = File.new(file, "rb")
-            match = compare_trees(tree_file)
-            if !match
-              import_tree(tree_file, force_overwrite, headers)
-            else
-              #Matching trees, skipping
-            end
-          rescue
+            import_tree(tree_file, force_overwrite, headers)
+          rescue => e
+            @logger.error("Failed to import Tree #{file}: #{e.class}: #{e.message}")
+            raise
           end
-      
         end
       end
       promises.each(&:wait!)
       pool.shutdown
       pool.wait_for_termination        
     end
-    # Import a tree
-    #
-    # If the tree already exists on the server, this will fail unless forced
-    # to overwrite.
-    #
-    # The source named in the tree content must also exist on the server, or
-    # the import will fail.
-    #
-    # @param tree [String] content from tree file
-    # @param force_overwrite [Boolean] whether to overwrite a tree if it exists, default is false
-    # @param headers [Hash] hash of headers to send, default is basic authentication
-    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
-    def compare_trees(tree, headers=header_basic_auth)
-      definitionId = REXML::XPath.first(tree, "//definitionId")&.text
-      @logger.info("Querying for Tree #{definitionId}")
-      response = find_tree(definitionId, { "include" => "details,export" })
-      @logger.info("Comparing new and old tree")
-      prev_tree = response.content
-      if prev_tree == tree
-        return true
-      else
-        return false
-      end
-    end
-
     # Import a routine
     #
     # If the routine already exists on the server, this will fail unless
@@ -248,9 +215,11 @@ module KineticSdk
       Dir["#{@options[:export_directory]}/routines/*.xml"].sort.each do |file|
         promises << Concurrent::Promise.execute(executor: pool) do
           begin
-          routine_file = File.new(file, "rb")
-          import_routine(routine_file, force_overwrite, headers)
-          rescue
+            routine_file = File.new(file, "rb")
+            import_routine(routine_file, force_overwrite, headers)
+          rescue => e
+            @logger.error("Failed to import Routine #{file}: #{e.class}: #{e.message}")
+            raise
           end
         end
       end

data/lib/kinetic_sdk/version.rb

@@ -3,5 +3,5 @@ module KineticSdk
   # Version of Kinetic SDK
   #
   # @return [String] Version of the SDK
-  VERSION = "7.0.0.rc2"
+  VERSION = "7.0.0.rc4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kinetic_sdk
 version: !ruby/object:Gem::Version
-  version: 7.0.0.rc2
+  version: 7.0.0.rc4
 platform: ruby
 authors:
 - Kinetic Data
@@ -122,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.9.45
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
 description:
 email:
 - support@kineticdata.com