conjur-api 6.3.0 → 6.3.1.pre.819

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6cd769a0f1013ecd2748b1ad9bd8f57805ae032706fcefc1d5b335aac296761
-  data.tar.gz: 48dedbb4d1e1543a4e7c61233803db4765ca06971470c5a4d81f2bb99b9aab7a
+  metadata.gz: 530b8d1955af810bdfc511cf8b2cde690dfb6a4afc4a7a2505b86a2aa92ece1d
+  data.tar.gz: 6f3ce0a8e7780eef3cfd8d55d174fadcd06593539cae63146bac3ec796cbe510
 SHA512:
-  metadata.gz: 0f3d542b1d470e77a52c729d7a9bcf43c6917599494d431e9f3da1c464413cc21699f52a4d354c74c576b9caf478c807a42cbcca4bf07acd9e87df580d7ab1a9
-  data.tar.gz: 7046f9809eb78899875493c2114a487b7586679e0a617ad85189fc601a38bd07c8ded050cc0d541061fb5e8d39439b0f2883c8758891383f7de552313a3e2d37
+  metadata.gz: 704610d1d7046bbf65619078c5273b1c4680969fa81659575d976fe42b1cc14f4d23d8b0933b0daeb09549b466df13414b166e96860e0fd74bd8a0dac20d906e
+  data.tar.gz: 7391aa9ccdd2f31b38180c8a5d6c78cd7958519af25fae415682e91ecab8d5834d02bd62931cd7fa4728b5665b19ca265f8e1ef88b762a1dbd64b8c983480391

data/CHANGELOG.md

@@ -6,6 +6,18 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## Unreleased
 
+## [6.3.1] - 2026-07-16
+
+### Added
+- Added `Conjur::API#dry_run_policy` for validating a policy load without applying it,
+  reporting what would be created/updated/deleted or, for invalid YAML, the parse errors.
+
+### Changed
+- `Conjur::API#dry_run_policy` and `Conjur::API#fetch_policy` now raise
+  `Conjur::FeatureNotAvailable` when called against CyberArk Secrets Manager, SaaS, or
+  against a Conjur server older than 1.21.1, matching conjur-api-go's behavior for the
+  equivalent methods.
+
 ## [6.3.0] - 2026-07-15
 
 ### Added

data/VERSION

@@ -1 +1 @@
-6.3.0
+6.3.1-819

data/features/load_policy.feature

@@ -92,3 +92,40 @@ Feature: Load a policy.
     $conjur.fetch_policy 'fetch-policy-json', return_json: true
     """
     Then the result should contain "fetch-policy-json-group"
+
+  Scenario: A dry run reports what a policy load would do without applying it.
+    Given I run the code:
+    """
+    $conjur.load_policy 'root', <<-POLICY
+    - !policy
+      id: dry-run-policy
+      body: []
+    POLICY
+    """
+    Then I can run the code:
+    """
+    $conjur.dry_run_policy 'dry-run-policy', <<-POLICY
+    - !group dry-run-group
+    POLICY
+    """
+    Then the JSON should have "status"
+    Then I can run the code:
+    """
+    $conjur.fetch_policy 'dry-run-policy'
+    """
+    Then the result should not contain "dry-run-group"
+
+  Scenario: A dry run reports errors for invalid policy YAML without applying it.
+    Given I run the code:
+    """
+    $conjur.load_policy 'root', <<-POLICY
+    - !policy
+      id: dry-run-invalid-policy
+      body: []
+    POLICY
+    """
+    Then I can run the code:
+    """
+    $conjur.dry_run_policy 'dry-run-invalid-policy', "- !group [invalid"
+    """
+    Then the JSON should have "errors"

data/features/step_definitions/result_steps.rb

@@ -6,6 +6,10 @@ Then(/^the result should contain "([^"]+)"$/) do |expected|
   expect(@result.to_s).to include(expected)
 end
 
+Then(/^the result should not contain "([^"]+)"$/) do |expected|
+  expect(@result.to_s).not_to include(expected)
+end
+
 Then(/^the providers list contains service id "([^"]+)"$/) do |service_id|
   expect(@result.map{ |x| x["service_id"]}).to include(service_id)
 end

data/lib/conjur/api/policies.rb

@@ -20,6 +20,7 @@
 #
 require 'conjur/policy_load_result'
 require 'conjur/policy'
+require 'conjur/saas'
 
 module Conjur
   class API
@@ -51,6 +52,29 @@ module Conjur
       PolicyLoadResult.new JSON.parse(request.send(method, policy))
     end
 
+    # Validate a policy load without applying it to the server, reporting what
+    # would change.
+    #
+    # @param id [String] id of the policy to load.
+    # @param policy [String] YAML-formatted policy definition.
+    # @param account [String] Conjur organization account
+    # @param method [Symbol] Policy load method to use: {POLICY_METHOD_POST} (default), {POLICY_METHOD_PATCH}, or {POLICY_METHOD_PUT}.
+    # @return [Hash] the dry run result, with keys such as "status", "created", "updated",
+    #   "deleted", and "errors". Invalid policy YAML is reported in the result rather than
+    #   raised, with "status" set to "Invalid YAML" and details in "errors". This applies
+    #   only to the 422 response the server uses for invalid YAML; other error responses
+    #   (e.g. 403 for insufficient privileges, 400 for bad request params) have a different
+    #   body shape and are raised as the corresponding RestClient exception.
+    # @raise [Conjur::FeatureNotAvailable] if the appliance is CyberArk Secrets Manager, SaaS,
+    #   or the Conjur server is older than 1.21.1.
+    def dry_run_policy id, policy, account: Conjur.configuration.account, method: POLICY_METHOD_POST
+      verify_policy_dry_run_support!
+      request = url_for(:policies_dry_run_policy, credentials, account, id)
+      JSON.parse(request.send(method, policy))
+    rescue RestClient::UnprocessableEntity => e
+      JSON.parse(e.response.body)
+    end
+
     # Fetch the current policy data from the server.
     #
     # @param id [String] id of the policy to fetch.
@@ -59,7 +83,10 @@ module Conjur
     # @param depth [Integer, nil] Maximum depth of the returned policy tree (nil for the full tree).
     # @param limit [Integer, nil] Maximum number of policy objects to return (nil for no limit).
     # @return [String] the policy document, formatted as YAML or JSON.
+    # @raise [Conjur::FeatureNotAvailable] if the appliance is CyberArk Secrets Manager, SaaS,
+    #   or the Conjur server is older than 1.21.1.
     def fetch_policy id, account: Conjur.configuration.account, return_json: false, depth: nil, limit: nil
+      verify_policy_dry_run_support!
       options = {}
       options[:depth] = depth if depth
       options[:limit] = limit if limit
@@ -69,5 +96,15 @@ module Conjur
     end
 
     #@!endgroup
+
+    private
+
+    def verify_policy_dry_run_support!
+      if Conjur::Saas.appliance_url?(Conjur.configuration.appliance_url)
+        raise Conjur::FeatureNotAvailable, "Policy dry run and fetch are not supported in CyberArk Secrets Manager, SaaS"
+      end
+
+      verify_min_server_version!('1.21.1')
+    end
   end
 end

data/lib/conjur/api/router.rb

@@ -148,6 +148,13 @@ module Conjur
         )['policies'][fully_escape account]['policy'][fully_escape id]
       end
 
+      def policies_dry_run_policy credentials, account, id
+        RestClient::Resource.new(
+          Conjur.configuration.core_url,
+          Conjur.configuration.create_rest_client_options(credentials)
+        )['policies'][fully_escape account]['policy'][fully_escape id]['?dryRun=true']
+      end
+
       def policies_fetch_policy credentials, account, id, options = {}
         RestClient::Resource.new(
           Conjur.configuration.core_url,
@@ -275,6 +282,20 @@ module Conjur
         )['whoami']
       end
 
+      def server_info
+        RestClient::Resource.new(
+          Conjur.configuration.core_url,
+          Conjur.configuration.rest_client_options
+        )['info']
+      end
+
+      def server_root
+        RestClient::Resource.new(
+          Conjur.configuration.core_url,
+          Conjur.configuration.rest_client_options
+        )['/']
+      end
+
       private
 
       def resource_annotations resource

data/lib/conjur/api/server_version.rb

@@ -0,0 +1,50 @@
+require 'json'
+require 'conjur/api/router'
+
+module Conjur
+  class API
+    #@!group Server version
+
+    # Retrieve the Conjur server version.
+    #
+    # Queries the '/info' endpoint (available on Conjur Enterprise), falling back to
+    # the root endpoint (available on Conjur OSS, and as a legacy fallback on
+    # Enterprise) if '/info' is unavailable or its response can't be parsed. The
+    # result is memoized on this instance.
+    #
+    # @return [String] the server version, e.g. "1.21.1.1-25".
+    # @raise [Conjur::FeatureNotAvailable] if the version can't be determined from
+    #   either endpoint.
+    def server_version
+      return @server_version if @server_version
+
+      @server_version = version_from_info || version_from_root ||
+        raise(Conjur::FeatureNotAvailable, "Unable to determine Conjur server version")
+    end
+
+    #@!endgroup
+
+    private
+
+    def version_from_info
+      body = JSON.parse(Router.server_info.get.body)
+      body.dig('services', 'possum', 'version')
+    rescue RestClient::Exception, JSON::ParserError
+      nil
+    end
+
+    def version_from_root
+      response = Router.server_root.get
+      content_type = response.headers[:content_type].to_s
+
+      if content_type.include?('application/json')
+        JSON.parse(response.body)['version']
+      else
+        match = response.body.match(%r{<d[dt]>\s*Version\s*(?:</d[dt]>\s*<dd>\s*)?([^\s<]+)\s*</dd>})
+        match && match[1]
+      end
+    rescue RestClient::Exception, JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/conjur/api/version_check.rb

@@ -0,0 +1,34 @@
+module Conjur
+  class API
+    #@!group Server version
+
+    # Verify that the Conjur server version is at least `min_version`.
+    #
+    # Conjur versions carry a build suffix after a hyphen (e.g. "1.21.1.1-25")
+    # which is not part of the comparable version, so it's stripped before comparing.
+    #
+    # @param min_version [String] the minimum required version, e.g. "1.21.1".
+    # @return [true] if the server version is sufficient.
+    # @raise [Conjur::FeatureNotAvailable] if the server version is unparseable or
+    #   lower than `min_version`.
+    def verify_min_server_version!(min_version)
+      detected = server_version.split('-').first
+
+      begin
+        detected_version = Gem::Version.new(detected)
+        required_version = Gem::Version.new(min_version)
+      rescue ArgumentError
+        raise Conjur::FeatureNotAvailable, "Unable to parse Conjur server version #{server_version.inspect}"
+      end
+
+      if detected_version < required_version
+        raise Conjur::FeatureNotAvailable,
+          "Conjur server version #{server_version} is less than the minimum required version #{min_version}"
+      end
+
+      true
+    end
+
+    #@!endgroup
+  end
+end

data/lib/conjur/api.rb

@@ -42,6 +42,8 @@ require 'conjur/api/resources'
 require 'conjur/api/pubkeys'
 require 'conjur/api/variables'
 require 'conjur/api/policies'
+require 'conjur/api/server_version'
+require 'conjur/api/version_check'
 require 'conjur/api/host_factories'
 require 'conjur/api/ldap_sync'
 require 'conjur/host'

data/lib/conjur/saas.rb

@@ -0,0 +1,39 @@
+require 'uri'
+
+module Conjur
+  # Detects whether a Conjur appliance URL points at CyberArk Secrets Manager, SaaS.
+  # SaaS appliances do not expose the '/info' or root version endpoints used to
+  # determine server version, so features that depend on those endpoints must be
+  # rejected outright for SaaS rather than attempting a version check.
+  module Saas
+    # Hostname suffixes used by CyberArk Secrets Manager, SaaS appliances.
+    SUFFIXES = %w[
+      .cyberark.cloud
+      .integration-cyberark.cloud
+      .test-cyberark.cloud
+      .dev-cyberark.cloud
+      .cyberark-everest-integdev.cloud
+      .cyberark-everest-pre-prod.cloud
+      .sandbox-cyberark.cloud
+      .pt-cyberark.cloud
+    ].freeze
+
+    HOSTNAME_PATTERN = /(\.secretsmgr|-secretsmanager)(#{SUFFIXES.map { |s| Regexp.escape(s) }.join('|')})\z/.freeze
+
+    # Returns true if `url` is a CyberArk Secrets Manager, SaaS appliance URL.
+    #
+    # @param url [String, nil] the appliance URL to check.
+    # @return [Boolean]
+    def self.appliance_url?(url)
+      return false unless url
+
+      uri = URI.parse(url)
+      return false unless uri.scheme == 'https'
+      return false unless uri.host
+
+      !!(uri.host.downcase =~ HOSTNAME_PATTERN)
+    rescue URI::InvalidURIError, ArgumentError
+      false
+    end
+  end
+end

data/spec/api/policies_spec.rb

@@ -10,7 +10,23 @@ describe "Conjur::API#fetch_policy", api: :dummy do
     allow(api).to receive(:credentials).and_return('the-credentials')
   end
 
+  it "raises FeatureNotAvailable for a SaaS appliance" do
+    allow(Conjur.configuration).to receive(:appliance_url).and_return('https://x.secretsmgr.cyberark.cloud')
+
+    expect { api.fetch_policy('root', account: 'the-account') }.to raise_error(Conjur::FeatureNotAvailable, /SaaS/)
+  end
+
+  it "raises FeatureNotAvailable for a server older than 1.21.1" do
+    allow(Conjur.configuration).to receive(:appliance_url).and_return('https://conjur.example.com')
+    allow(api).to receive(:server_version).and_return('1.20.0')
+
+    expect { api.fetch_policy('root', account: 'the-account') }.to raise_error(Conjur::FeatureNotAvailable, /1\.21\.1/)
+  end
+
   it "fetches the policy as YAML by default" do
+    allow(Conjur.configuration).to receive(:appliance_url).and_return('https://conjur.example.com')
+    allow(api).to receive(:server_version).and_return('1.21.1')
+
     resource = instance_double(RestClient::Resource, "policy resource")
     allow(api).to receive(:url_for)
       .with(:policies_fetch_policy, 'the-credentials', 'the-account', 'root', {})
@@ -24,6 +40,9 @@ describe "Conjur::API#fetch_policy", api: :dummy do
   end
 
   it "fetches the policy as JSON when requested" do
+    allow(Conjur.configuration).to receive(:appliance_url).and_return('https://conjur.example.com')
+    allow(api).to receive(:server_version).and_return('1.21.1')
+
     resource = instance_double(RestClient::Resource, "policy resource")
     allow(api).to receive(:url_for)
       .with(:policies_fetch_policy, 'the-credentials', 'the-account', 'root', { depth: 2, limit: 100 })
@@ -38,3 +57,102 @@ describe "Conjur::API#fetch_policy", api: :dummy do
     ).to eq('[{"id":"cucumber:host:foo"}]')
   end
 end
+
+describe "Conjur::API#dry_run_policy", api: :dummy do
+  let(:api) { Conjur::API.new_from_key('user', 'pass') }
+
+  before do
+    allow(api).to receive(:credentials).and_return('the-credentials')
+  end
+
+  it "raises FeatureNotAvailable for a SaaS appliance" do
+    allow(Conjur.configuration).to receive(:appliance_url).and_return('https://x.secretsmgr.cyberark.cloud')
+
+    expect { api.dry_run_policy('root', 'policy body', account: 'the-account') }.to raise_error(Conjur::FeatureNotAvailable, /SaaS/)
+  end
+
+  it "raises FeatureNotAvailable for a server older than 1.21.1" do
+    allow(Conjur.configuration).to receive(:appliance_url).and_return('https://conjur.example.com')
+    allow(api).to receive(:server_version).and_return('1.20.0')
+
+    expect { api.dry_run_policy('root', 'policy body', account: 'the-account') }.to raise_error(Conjur::FeatureNotAvailable, /1\.21\.1/)
+  end
+
+  it "validates a policy load without applying it, defaulting to POST" do
+    allow(Conjur.configuration).to receive(:appliance_url).and_return('https://conjur.example.com')
+    allow(api).to receive(:server_version).and_return('1.21.1')
+
+    resource = instance_double(RestClient::Resource, "policy resource")
+    allow(api).to receive(:url_for)
+      .with(:policies_dry_run_policy, 'the-credentials', 'the-account', 'root')
+      .and_return(resource)
+
+    allow(resource).to receive(:post).with('policy body').and_return(
+      '{"status":"Valid YAML","created":{"items":[]},"updated":{"before":{"items":[]},"after":{"items":[]}},"deleted":{"items":[]}}'
+    )
+
+    result = api.dry_run_policy('root', 'policy body', account: 'the-account')
+
+    expect(result['status']).to eq('Valid YAML')
+  end
+
+  it "supports POLICY_METHOD_PUT" do
+    allow(Conjur.configuration).to receive(:appliance_url).and_return('https://conjur.example.com')
+    allow(api).to receive(:server_version).and_return('1.21.1')
+
+    resource = instance_double(RestClient::Resource, "policy resource")
+    allow(api).to receive(:url_for)
+      .with(:policies_dry_run_policy, 'the-credentials', 'the-account', 'root')
+      .and_return(resource)
+
+    allow(resource).to receive(:put).with('policy body').and_return(
+      '{"status":"Valid YAML"}'
+    )
+
+    result = api.dry_run_policy(
+      'root', 'policy body', account: 'the-account', method: Conjur::API::POLICY_METHOD_PUT
+    )
+
+    expect(result['status']).to eq('Valid YAML')
+  end
+
+  it "reports invalid policy YAML instead of raising" do
+    allow(Conjur.configuration).to receive(:appliance_url).and_return('https://conjur.example.com')
+    allow(api).to receive(:server_version).and_return('1.21.1')
+
+    resource = instance_double(RestClient::Resource, "policy resource")
+    allow(api).to receive(:url_for)
+      .with(:policies_dry_run_policy, 'the-credentials', 'the-account', 'root')
+      .and_return(resource)
+
+    response_body = '{"status":"Invalid YAML","errors":[{"line":1,"column":10,"message":"bad yaml"}]}'
+    response = instance_double(RestClient::Response, "error response", body: response_body, code: 422)
+    exception = RestClient::UnprocessableEntity.new(response)
+    allow(exception).to receive(:response).and_return(response)
+    allow(resource).to receive(:post).with('- !group [invalid').and_raise(exception)
+
+    result = api.dry_run_policy('root', '- !group [invalid', account: 'the-account')
+
+    expect(result['status']).to eq('Invalid YAML')
+    expect(result['errors'].first['message']).to eq('bad yaml')
+  end
+
+  it "raises for other error responses instead of returning them as a result" do
+    allow(Conjur.configuration).to receive(:appliance_url).and_return('https://conjur.example.com')
+    allow(api).to receive(:server_version).and_return('1.21.1')
+
+    resource = instance_double(RestClient::Resource, "policy resource")
+    allow(api).to receive(:url_for)
+      .with(:policies_dry_run_policy, 'the-credentials', 'the-account', 'root')
+      .and_return(resource)
+
+    response = instance_double(RestClient::Response, "error response", body: '{"error":"forbidden"}', code: 403)
+    exception = RestClient::Forbidden.new(response)
+    allow(exception).to receive(:response).and_return(response)
+    allow(resource).to receive(:post).with('policy body').and_raise(exception)
+
+    expect {
+      api.dry_run_policy('root', 'policy body', account: 'the-account')
+    }.to raise_error(RestClient::Forbidden)
+  end
+end

data/spec/api/router_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'conjur/api/router'
+
+describe Conjur::API::Router do
+  before do
+    allow(Conjur.configuration).to receive(:core_url).and_return('http://core.example.com')
+  end
+
+  describe ".server_info" do
+    it "builds an unauthenticated resource for the info endpoint" do
+      resource = Conjur::API::Router.server_info
+
+      expect(resource.url).to eq('http://core.example.com/info')
+      expect(resource.options[:headers]).not_to have_key(:authorization)
+    end
+  end
+
+  describe ".server_root" do
+    it "builds an unauthenticated resource for the root endpoint" do
+      resource = Conjur::API::Router.server_root
+
+      expect(resource.url).to eq('http://core.example.com/')
+    end
+  end
+
+  describe ".policies_load_policy" do
+    it "builds a resource with no trailing slash or query string" do
+      resource = Conjur::API::Router.policies_load_policy({}, 'the-account', 'root')
+
+      expect(resource.url).to eq('http://core.example.com/policies/the-account/policy/root')
+    end
+  end
+
+  describe ".policies_dry_run_policy" do
+    it "builds a resource with the dryRun query string" do
+      resource = Conjur::API::Router.policies_dry_run_policy({}, 'the-account', 'root')
+
+      expect(resource.url).to eq('http://core.example.com/policies/the-account/policy/root/?dryRun=true')
+    end
+  end
+end

data/spec/api/server_version_spec.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'conjur/api/server_version'
+
+describe "Conjur::API#server_version", api: :dummy do
+  let(:info_resource) { instance_double(RestClient::Resource, "info resource") }
+  let(:root_resource) { instance_double(RestClient::Resource, "root resource") }
+
+  before do
+    allow(Conjur::API::Router).to receive(:server_info).and_return(info_resource)
+    allow(Conjur::API::Router).to receive(:server_root).and_return(root_resource)
+  end
+
+  it "returns the possum service version from the /info endpoint" do
+    body = {
+      "services" => { "possum" => { "version" => "1.21.1.1-25" } }
+    }.to_json
+    allow(info_resource).to receive(:get).and_return(
+      instance_double(RestClient::Response, "info response", body: body)
+    )
+
+    expect(api.server_version).to eq("1.21.1.1-25")
+  end
+
+  it "falls back to root when /info responds 404 (OSS)" do
+    response = instance_double(RestClient::Response, "404 response", body: '', code: 404)
+    allow(info_resource).to receive(:get).and_raise(RestClient::NotFound.new(response))
+
+    root_body = { "version" => "1.20.0" }.to_json
+    allow(root_resource).to receive(:get).and_return(
+      instance_double(RestClient::Response, "root response", body: root_body, headers: { content_type: 'application/json' })
+    )
+
+    expect(api.server_version).to eq("1.20.0")
+  end
+
+  it "falls back to root when /info responds 500 (not just 404/401)" do
+    response = instance_double(RestClient::Response, "500 response", body: '', code: 500)
+    allow(info_resource).to receive(:get).and_raise(RestClient::InternalServerError.new(response))
+
+    root_body = { "version" => "1.20.0" }.to_json
+    allow(root_resource).to receive(:get).and_return(
+      instance_double(RestClient::Response, "root response", body: root_body, headers: { content_type: 'application/json' })
+    )
+
+    expect(api.server_version).to eq("1.20.0")
+  end
+
+  it "parses a JSON root response even when Content-Type includes a charset" do
+    allow(info_resource).to receive(:get).and_raise(RestClient::NotFound.new(instance_double(RestClient::Response, body: '', code: 404)))
+
+    root_body = { "version" => "1.20.0" }.to_json
+    allow(root_resource).to receive(:get).and_return(
+      instance_double(RestClient::Response, "root response", body: root_body, headers: { content_type: 'application/json; charset=utf-8' })
+    )
+
+    expect(api.server_version).to eq("1.20.0")
+  end
+
+  it "parses an HTML root response when Content-Type is not JSON" do
+    allow(info_resource).to receive(:get).and_raise(RestClient::NotFound.new(instance_double(RestClient::Response, body: '', code: 404)))
+
+    root_body = "<html><body><dd>Version 1.19.0-359</dd></body></html>"
+    allow(root_resource).to receive(:get).and_return(
+      instance_double(RestClient::Response, "root response", body: root_body, headers: { content_type: 'text/html' })
+    )
+
+    expect(api.server_version).to eq("1.19.0-359")
+  end
+
+  it "parses an HTML root response with the Version label and value in separate tags" do
+    allow(info_resource).to receive(:get).and_raise(RestClient::NotFound.new(instance_double(RestClient::Response, body: '', code: 404)))
+
+    root_body = "<html><body><dt>Version</dt><dd>1.28.0-1443</dd></body></html>"
+    allow(root_resource).to receive(:get).and_return(
+      instance_double(RestClient::Response, "root response", body: root_body, headers: { content_type: 'text/html' })
+    )
+
+    expect(api.server_version).to eq("1.28.0-1443")
+  end
+
+  it "raises FeatureNotAvailable when neither endpoint yields a version" do
+    allow(info_resource).to receive(:get).and_raise(RestClient::NotFound.new(instance_double(RestClient::Response, body: '', code: 404)))
+    allow(root_resource).to receive(:get).and_raise(RestClient::InternalServerError.new(instance_double(RestClient::Response, body: '', code: 500)))
+
+    expect { api.server_version }.to raise_error(Conjur::FeatureNotAvailable, /Unable to determine Conjur server version/)
+  end
+
+  it "memoizes a successful lookup" do
+    body = { "services" => { "possum" => { "version" => "1.21.1" } } }.to_json
+    allow(info_resource).to receive(:get).and_return(
+      instance_double(RestClient::Response, "info response", body: body)
+    )
+
+    api.server_version
+    api.server_version
+
+    expect(info_resource).to have_received(:get).once
+  end
+
+  it "does not memoize a failed lookup, retrying on the next call" do
+    allow(info_resource).to receive(:get).and_raise(RestClient::NotFound.new(instance_double(RestClient::Response, body: '', code: 404)))
+    allow(root_resource).to receive(:get).and_raise(RestClient::InternalServerError.new(instance_double(RestClient::Response, body: '', code: 500)))
+
+    expect { api.server_version }.to raise_error(Conjur::FeatureNotAvailable)
+    expect { api.server_version }.to raise_error(Conjur::FeatureNotAvailable)
+
+    expect(info_resource).to have_received(:get).twice
+  end
+end

data/spec/api/version_check_spec.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'conjur/api/version_check'
+
+describe "Conjur::API#verify_min_server_version!", api: :dummy do
+  it "passes when the server version equals the minimum" do
+    allow(api).to receive(:server_version).and_return("1.21.1")
+
+    expect(api.verify_min_server_version!("1.21.1")).to be true
+  end
+
+  it "passes when the server version is greater than the minimum" do
+    allow(api).to receive(:server_version).and_return("1.22.0")
+
+    expect(api.verify_min_server_version!("1.21.1")).to be true
+  end
+
+  it "passes when a Conjur build suffix is present and the base version is sufficient" do
+    allow(api).to receive(:server_version).and_return("1.21.1.1-25")
+
+    expect(api.verify_min_server_version!("1.21.1")).to be true
+  end
+
+  it "raises when the server version is less than the minimum" do
+    allow(api).to receive(:server_version).and_return("1.20.0")
+
+    expect { api.verify_min_server_version!("1.21.1") }.to raise_error(
+      Conjur::FeatureNotAvailable, /1\.20\.0.*1\.21\.1|1\.21\.1.*1\.20\.0/
+    )
+  end
+
+  it "raises FeatureNotAvailable (not ArgumentError) for an unparseable server version" do
+    allow(api).to receive(:server_version).and_return("development")
+
+    expect { api.verify_min_server_version!("1.21.1") }.to raise_error(
+      Conjur::FeatureNotAvailable, /Unable to parse Conjur server version/
+    )
+  end
+end

data/spec/unit/saas_spec.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'conjur/saas'
+
+describe Conjur::Saas do
+  describe ".appliance_url?" do
+    it "matches a .secretsmgr SaaS hostname" do
+      expect(Conjur::Saas.appliance_url?("https://myorg.secretsmgr.cyberark.cloud")).to be true
+    end
+
+    it "matches a -secretsmanager SaaS hostname" do
+      expect(Conjur::Saas.appliance_url?("https://myorg-secretsmanager.dev-cyberark.cloud")).to be true
+    end
+
+    it "matches with additional subdomains before the prefix" do
+      expect(Conjur::Saas.appliance_url?("https://tenant.myorg.secretsmgr.sandbox-cyberark.cloud")).to be true
+    end
+
+    it "does not match a plain appliance URL" do
+      expect(Conjur::Saas.appliance_url?("https://conjur.example.com/api")).to be false
+    end
+
+    it "does not match when the scheme is not https" do
+      expect(Conjur::Saas.appliance_url?("http://myorg.secretsmgr.cyberark.cloud")).to be false
+    end
+
+    it "does not match a nil url" do
+      expect(Conjur::Saas.appliance_url?(nil)).to be false
+    end
+
+    it "does not raise for a malformed url and returns false" do
+      expect(Conjur::Saas.appliance_url?("not a url with spaces")).to be false
+    end
+
+    it "does not match a relative or opaque url with no host" do
+      expect(Conjur::Saas.appliance_url?("mailto:someone@example.com")).to be false
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: conjur-api
 version: !ruby/object:Gem::Version
-  version: 6.3.0
+  version: 6.3.1.pre.819
 platform: ruby
 authors:
 - CyberArk Maintainers
@@ -350,7 +350,9 @@ files:
 - lib/conjur/api/resources.rb
 - lib/conjur/api/roles.rb
 - lib/conjur/api/router.rb
+- lib/conjur/api/server_version.rb
 - lib/conjur/api/variables.rb
+- lib/conjur/api/version_check.rb
 - lib/conjur/base.rb
 - lib/conjur/base_object.rb
 - lib/conjur/build_object.rb
@@ -378,6 +380,7 @@ files:
 - lib/conjur/role.rb
 - lib/conjur/role_grant.rb
 - lib/conjur/routing.rb
+- lib/conjur/saas.rb
 - lib/conjur/user.rb
 - lib/conjur/variable.rb
 - lib/conjur/webservice.rb
@@ -385,6 +388,9 @@ files:
 - spec/.conjurrc
 - spec/api/host_factories_spec.rb
 - spec/api/policies_spec.rb
+- spec/api/router_spec.rb
+- spec/api/server_version_spec.rb
+- spec/api/version_check_spec.rb
 - spec/api_spec.rb
 - spec/authn_cert_spec.rb
 - spec/base_object_spec.rb
@@ -405,6 +411,7 @@ files:
 - spec/spec_helper.rb
 - spec/ssl_spec.rb
 - spec/unit/policy_load_result_spec.rb
+- spec/unit/saas_spec.rb
 - spec/uri_escape_spec.rb
 - test.sh
 - tmp/.keep
@@ -460,6 +467,9 @@ test_files:
 - spec/.conjurrc
 - spec/api/host_factories_spec.rb
 - spec/api/policies_spec.rb
+- spec/api/router_spec.rb
+- spec/api/server_version_spec.rb
+- spec/api/version_check_spec.rb
 - spec/api_spec.rb
 - spec/authn_cert_spec.rb
 - spec/base_object_spec.rb
@@ -480,4 +490,5 @@ test_files:
 - spec/spec_helper.rb
 - spec/ssl_spec.rb
 - spec/unit/policy_load_result_spec.rb
+- spec/unit/saas_spec.rb
 - spec/uri_escape_spec.rb