ibm_appconfiguration_ruby_sdk 0.1.0.pre.rc.0

data/lib/ibm_appconfiguration_ruby_sdk/core/url_builder.rb

@@ -0,0 +1,252 @@
+# Copyright 2026 IBM Corp. All Rights Reserved.
+#
+# 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.
+
+# frozen_string_literal: true
+
+require "singleton"
+
+##
+# This module provides methods to construct headers & different URLs used by the SDK.
+#
+# The UrlBuilder class implements a Singleton pattern to ensure consistent URL
+# configuration across the SDK. It handles:
+# - HTTP/HTTPS endpoints for App Configuration service
+# - WebSocket (WSS) connections for real-time updates
+# - IAM authentication URLs
+# - Support for both public and private endpoints
+# - Environment-specific URL overrides for dev/staging/testing
+#
+##
+class UrlBuilder
+  include Singleton
+
+  # Constants for URL construction
+  HTTPS_PROTOCOL = "https://"
+  WEBSOCKET_PROTOCOL = "wss://"
+  BASE_URL = ".apprapp.cloud.ibm.com"
+  WEBSOCKET_PATH = "/wsfeature"
+  SERVICE_PATH = "/apprapp"
+  PRIVATE_ENDPOINT_PREFIX = "private."
+
+  # IAM URLs
+  IAM_TEST_URL = "iam.test.cloud.ibm.com/identity/token"
+  IAM_PROD_URL = "iam.cloud.ibm.com/identity/token"
+
+  ##
+  # Initialize the UrlBuilder with default values
+  def initialize
+    @region = ""
+    @instance_guid = nil
+    @apikey = nil
+    @override_service_url = nil
+    @use_private_endpoint = false
+    @websocket_full_url = nil
+  end
+
+  ##
+  # Set the region value
+  #
+  # @param value [String] Region name (e.g., 'us-south', 'eu-gb', 'au-syd')
+  # @return [String] the region value
+
+  ##
+  # Get the region value
+  #
+  # @return [String] the region value
+  attr_accessor :region
+
+  ##
+  # Set the service instance GUID
+  #
+  # @param value [String] GUID of the service instance
+  # @return [String] the GUID value
+  def guid=(value)
+    @instance_guid = value
+  end
+
+  ##
+  # Get the service instance GUID
+  #
+  # @return [String] the GUID value
+  def guid
+    @instance_guid
+  end
+
+  ##
+  # Set the API key
+  #
+  # @param value [String] API key of the service instance
+  # @return [String] the API key value
+
+  ##
+  # Get the API key
+  #
+  # @return [String] the API key value
+  attr_accessor :apikey
+
+  ##
+  # Set the overridden base service URL.
+  # Used for testing, development, or staging environments.
+  #
+  # @param value [String] The base service URL
+  # @return [String] the override URL value
+  def base_service_url=(value)
+    @override_service_url = value
+  end
+
+  ##
+  # Alias for base_service_url= to match AppConfiguration usage
+  def set_base_service_url(value)
+    self.base_service_url = value
+  end
+
+  ##
+  # Get the base URL for the App Configuration service instance.
+  # Returns the appropriate URL based on environment and endpoint type.
+  #
+  # @return [String] The base service URL
+  #
+  # @example Production public endpoint
+  #   # Returns: https://us-south.apprapp.cloud.ibm.com
+  #   builder.base_service_url
+  #
+  # @example Production private endpoint
+  #   # Returns: https://private.us-south.apprapp.cloud.ibm.com
+  #   builder.use_private_endpoint = true
+  #   builder.base_service_url
+  #
+  def base_service_url
+    # For dev & stage environments
+    if @override_service_url
+      return add_private_prefix_to_url(@override_service_url) if @use_private_endpoint
+
+      return @override_service_url
+    end
+
+    # For production
+    return "#{HTTPS_PROTOCOL}#{PRIVATE_ENDPOINT_PREFIX}#{@region}#{BASE_URL}" if @use_private_endpoint
+
+    "#{HTTPS_PROTOCOL}#{@region}#{BASE_URL}"
+  end
+
+  ##
+  # Get the IAM (Identity and Access Management) URL for authentication.
+  #
+  # @return [String] The IAM URL
+  #
+  # @example Production IAM URL
+  #   # Returns: https://iam.cloud.ibm.com
+  #   builder.iam_url
+  #
+  # @example Test environment IAM URL
+  #   # Returns: https://iam.test.cloud.ibm.com
+  #   builder.base_service_url = 'https://test.example.com'
+  #   builder.iam_url
+  #
+  def iam_url
+    # For dev & stage environments
+    if @override_service_url
+      return "#{HTTPS_PROTOCOL}#{PRIVATE_ENDPOINT_PREFIX}#{IAM_TEST_URL}" if @use_private_endpoint
+
+      return "#{HTTPS_PROTOCOL}#{IAM_TEST_URL}"
+    end
+
+    # For production
+    return "#{HTTPS_PROTOCOL}#{PRIVATE_ENDPOINT_PREFIX}#{IAM_PROD_URL}" if @use_private_endpoint
+
+    "#{HTTPS_PROTOCOL}#{IAM_PROD_URL}"
+  end
+
+  ##
+  # Set the WebSocket URL with collection and environment IDs.
+  # Constructs the complete WebSocket URL with query parameters.
+  #
+  # @param collection_id [String] The collection ID
+  # @param environment_id [String] The environment ID
+  # @return [String] The constructed WebSocket URL
+  #
+  # @example
+  #   builder.set_websocket_url('collection-1', 'env-prod')
+  #   # Sets: wss://us-south.apprapp.cloud.ibm.com/apprapp/wsfeature?instance_id=...&collection_id=collection-1&environment_id=env-prod
+  #
+  def set_websocket_url(collection_id, environment_id)
+    ws = WEBSOCKET_PROTOCOL.dup
+
+    if @override_service_url
+      # For dev & stage environments
+      temp = @override_service_url.gsub(%r{https?://}, "")
+      ws += PRIVATE_ENDPOINT_PREFIX if @use_private_endpoint
+      ws += temp
+    else
+      # For production
+      ws += PRIVATE_ENDPOINT_PREFIX if @use_private_endpoint
+      ws += @region
+      ws += BASE_URL
+    end
+
+    @websocket_full_url = "#{ws}#{SERVICE_PATH}#{WEBSOCKET_PATH}?" \
+                         "instance_id=#{@instance_guid}&" \
+                         "collection_id=#{collection_id}&" \
+                         "environment_id=#{environment_id}"
+  end
+
+  ##
+  # Get the WebSocket URL.
+  # Must call set_websocket_url first to construct the URL.
+  #
+  # @return [String, nil] The WebSocket URL or nil if not set
+  def websocket_url
+    @websocket_full_url
+  end
+
+  ##
+  # Enable or disable private endpoint usage.
+  # When enabled, all URLs will use IBM Cloud private network routing.
+  #
+  # @param value [Boolean] Set to true to use private endpoints
+  # @return [Boolean] the private endpoint setting
+  #
+  # @example Enable private endpoint
+  #   builder.use_private_endpoint = true
+  #   # All URLs will now include 'private.' prefix
+  #
+  attr_writer :use_private_endpoint
+
+  ##
+  # Check if private endpoint is enabled
+  #
+  # @return [Boolean] true if private endpoint is enabled
+  def use_private_endpoint?
+    @use_private_endpoint
+  end
+
+  private
+
+  ##
+  # Add private endpoint prefix to a URL
+  #
+  # @param url [String] The URL to modify
+  # @return [String] The URL with private prefix added
+  #
+  # @example
+  #   add_private_prefix_to_url('https://example.com')
+  #   # Returns: https://private.example.com
+  #
+  def add_private_prefix_to_url(url)
+    parts = url.split("://")
+    return url if parts.length != 2
+
+    "#{parts[0]}://#{PRIVATE_ENDPOINT_PREFIX}#{parts[1]}"
+  end
+end

data/lib/ibm_appconfiguration_ruby_sdk/version.rb

@@ -0,0 +1,20 @@
+# Copyright 2026 IBM Corp. All Rights Reserved.
+#
+# 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.
+
+# frozen_string_literal: true
+
+module IbmAppconfigurationRubySdk
+  # Version of the IBM Cloud App Configuration Ruby SDK
+  VERSION = "0.1.0-rc.0"
+end

data/lib/ibm_appconfiguration_ruby_sdk.rb

@@ -0,0 +1,20 @@
+# Copyright 2026 IBM Corp. All Rights Reserved.
+#
+# 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.
+
+# frozen_string_literal: true
+
+require_relative "./ibm_appconfiguration_ruby_sdk/app_configuration"
+
+module IbmAppconfigurationRubySdk
+end

data/sig/ibm_appconfiguration_ruby_sdk.rbs

@@ -0,0 +1,4 @@
+module IbmAppconfigurationRubySdk
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,209 @@
+--- !ruby/object:Gem::Specification
+name: ibm_appconfiguration_ruby_sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre.rc.0
+platform: ruby
+authors:
+- IBM Cloud App Configuration
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ibm_cloud_sdk_core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: murmurhash3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: websocket-driver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: IBM Cloud App Configuration SDK is used to perform feature evaluation
+  based on the configuration on IBM Cloud App Configuration service.
+email:
+- mdevsrvs@in.ibm.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- Rakefile
+- examples/README.md
+- examples/app.rb
+- lib/ibm_appconfiguration_ruby_sdk.rb
+- lib/ibm_appconfiguration_ruby_sdk/app_configuration.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/configuration_handler.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/constants.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/file_manager.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/logger.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/retry_manager/background_retry_manager.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/retry_manager/config_fetcher.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/utils.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/websocket_client/connection_manager.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/websocket_client/connectivity.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/websocket_client/driver_socket.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/websocket_client/retry_policy.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/websocket_client/state.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/websocket_client/watchdog.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/internal/websocket_client/websocket_client.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/models/feature.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/models/property.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/models/rule.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/models/secret_property.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/models/segment.rb
+- lib/ibm_appconfiguration_ruby_sdk/configurations/models/segment_rules.rb
+- lib/ibm_appconfiguration_ruby_sdk/core/api_manager.rb
+- lib/ibm_appconfiguration_ruby_sdk/core/metering.rb
+- lib/ibm_appconfiguration_ruby_sdk/core/url_builder.rb
+- lib/ibm_appconfiguration_ruby_sdk/version.rb
+- sig/ibm_appconfiguration_ruby_sdk.rbs
+homepage: https://github.com/IBM/appconfiguration-ruby-sdk
+licenses:
+- Apache-2.0
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/IBM/appconfiguration-ruby-sdk
+  source_code_uri: https://github.com/IBM/appconfiguration-ruby-sdk
+  changelog_uri: https://github.com/IBM/appconfiguration-ruby-sdk/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/IBM/appconfiguration-ruby-sdk/issues
+  documentation_uri: https://github.com/IBM/appconfiguration-ruby-sdk
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: IBM Cloud App Configuration Ruby SDK
+test_files: []