env config sample (#49)

* env config sample

* upgrade temporalio dependency

Author: THardy98

README.md

@@ -23,12 +23,14 @@ Prerequisites:
 * [context_propagation](context_propagation) - Use interceptors to propagate thread/fiber local data from clients
   through workflows/activities.
 * [encryption](encryption) - Demonstrates how to make a codec for end-to-end encryption.
+* [env_config](env_config) - Load client configuration from TOML files with programmatic overrides.
 * [message_passing_simple](message_passing_simple) - Simple workflow that accepts signals, queries, and updates.
 * [polling/infrequent](polling/infrequent) - Implement an infrequent polling mechanism using Temporal's automatic Activity Retry feature.
 * [rails_app](rails_app) - Basic Rails API application using Temporal workflows and activities.
 * [saga](saga) - Using undo/compensation using a very simplistic Saga pattern.
 * [sorbet_generic](sorbet_generic) - Proof of concept of how to do _advanced_ Sorbet typing with the SDK.
 * [worker_specific_task_queues](worker_specific_task_queues) - Use a unique Task Queue for each Worker to run a sequence of Activities on the same Worker.
+* [worker_versioning](worker_versioning) - Use the Worker Versioning feature to more easily version your workflows & other code.
 
 ## Development
 

env_config/README.md

@@ -0,0 +1,44 @@
+# Temporal External Client Configuration Samples
+
+This directory contains Ruby samples that demonstrate how to use the Temporal SDK's external client configuration feature. This feature allows you to configure a `Temporalio::Client` using a TOML file and/or programmatic overrides, decoupling connection settings from your application code.
+
+## Prerequisites
+
+To run, first see [README.md](../README.md) for prerequisites.
+
+## Configuration File
+
+The `config.toml` file defines three profiles for different environments:
+
+-   `[profile.default]`: A working configuration for local development.
+-   `[profile.staging]`: A configuration with an intentionally **incorrect** address (`localhost:9999`) to demonstrate how it can be corrected by an override.
+-   `[profile.prod]`: A non-runnable, illustrative-only configuration showing a realistic setup for Temporal Cloud with placeholder credentials. This profile is not used by the samples but serves as a reference.
+
+## Samples
+
+The following Ruby scripts demonstrate different ways to load and use these configuration profiles. Each runnable sample highlights a unique feature.
+
+### `load_from_file.rb`
+
+This sample shows the most common use case: loading the `default` profile from the `config.toml` file.
+
+**To run this sample:**
+
+
+```bash
+bundle exec ruby load_from_file.rb
+```
+
+### `load_profile.rb`
+
+This sample demonstrates loading the `staging` profile by name (which has an incorrect address) and then correcting the address programmatically. This highlights the recommended approach for overriding configuration values at runtime.
+
+**To run this sample:**
+
+```bash
+bundle exec ruby load_profile.rb
+```
+
+## Running the Samples
+
+You can run each sample script directly from the root of the `samples-ruby` repository. Ensure you have the necessary dependencies installed by running `bundle install` from the repository root.

env_config/config.toml

@@ -0,0 +1,40 @@
+# This is a sample configuration file for demonstrating Temporal's environment
+# configuration feature. It defines multiple profiles for different environments,
+# such as local development, production, and staging.
+
+# Default profile for local development
+[profile.default]
+address = "localhost:7233"
+namespace = "default"
+
+# Optional: Add custom gRPC headers
+[profile.default.grpc_meta]
+my-custom-header = "development-value"
+trace-id = "dev-trace-123"
+
+# Staging profile with inline certificate data
+[profile.staging]
+address = "localhost:9999"
+namespace = "staging" 
+
+# An example production profile for Temporal Cloud
+[profile.prod]
+address = "your-namespace.a1b2c.tmprl.cloud:7233"
+namespace = "your-namespace"
+# Replace with your actual Temporal Cloud API key
+api_key = "your-api-key-here"
+
+# TLS configuration for production
+[profile.prod.tls]
+# TLS is auto-enabled when an API key is present, but you can configure it
+# explicitly.
+# disabled = false
+
+# Use certificate files for mTLS. Replace with actual paths.
+client_cert_path = "/etc/temporal/certs/client.pem"
+client_key_path = "/etc/temporal/certs/client.key"
+
+# Custom headers for production
+[profile.prod.grpc_meta]
+environment = "production"
+service-version = "v1.2.3"

env_config/load_from_file.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'temporalio/client'
+require 'temporalio/env_config'
+
+def main
+  puts '--- Loading default profile from config.toml ---'
+
+  # For this sample to be self-contained, we explicitly provide the path to
+  # the config.toml file included in this directory.
+  # By default though, the config.toml file will be loaded from
+  # ~/.config/temporalio/temporal.toml (or the equivalent standard config directory on your OS).
+  config_file = File.join(__dir__, 'config.toml')
+
+  # load_client_connect_options is a helper that loads a profile and prepares
+  # the configuration for Client.connect. By default, it loads the
+  # "default" profile.
+  args, kwargs = Temporalio::EnvConfig::ClientConfig.load_client_connect_options(
+    config_source: Pathname.new(config_file)
+  )
+
+  puts "Loaded 'default' profile from #{config_file}."
+  puts "  Address: #{args[0]}"
+  puts "  Namespace: #{args[1]}"
+  puts "  gRPC Metadata: #{kwargs[:rpc_metadata]}"
+
+  puts "\nAttempting to connect to client..."
+  begin
+    client = Temporalio::Client.connect(*args, **kwargs)
+    puts '✅ Client connected successfully!'
+    sys_info = client.workflow_service.get_system_info(Temporalio::Api::WorkflowService::V1::GetSystemInfoRequest.new)
+    puts "✅ Successfully verified connection to Temporal server!\n#{sys_info}"
+  rescue StandardError => e
+    puts "❌ Failed to connect: #{e}"
+  end
+end
+
+main if $PROGRAM_NAME == __FILE__

env_config/load_profile.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'temporalio/client'
+require 'temporalio/env_config'
+
+def main
+  puts "--- Loading 'staging' profile with programmatic overrides ---"
+
+  config_file = File.join(__dir__, 'config.toml')
+  profile_name = 'staging'
+
+  puts "The 'staging' profile in config.toml has an incorrect address (localhost:9999)."
+  puts "We'll programmatically override it to the correct address."
+
+  # Load the 'staging' profile.
+  args, kwargs = Temporalio::EnvConfig::ClientConfig.load_client_connect_options(
+    profile: profile_name,
+    config_source: Pathname.new(config_file)
+  )
+
+  # Override the target host to the correct address.
+  # This is the recommended way to override configuration values.
+  args[0] = 'localhost:7233'
+
+  puts "\nLoaded '#{profile_name}' profile from #{config_file} with overrides."
+  puts "  Address: #{args[0]} (overridden from localhost:9999)"
+  puts "  Namespace: #{args[1]}"
+
+  puts "\nAttempting to connect to client..."
+  begin
+    client = Temporalio::Client.connect(*args, **kwargs)
+    puts '✅ Client connected successfully!'
+    sys_info = client.workflow_service.get_system_info(Temporalio::Api::WorkflowService::V1::GetSystemInfoRequest.new)
+    puts "✅ Successfully verified connection to Temporal server!\n#{sys_info}"
+  rescue StandardError => e
+    puts "❌ Failed to connect: #{e}"
+  end
+end
+
+main if $PROGRAM_NAME == __FILE__