legate 0.1.0

data/examples/advanced/auth/openweather_api.rb

@@ -0,0 +1,251 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example of using Legate::Auth with OpenWeatherMap API
+#
+# This example demonstrates different ways to authenticate with OpenWeatherMap API
+# using both direct Excon calls and Legate::Auth middleware.
+#
+# Usage:
+#   ruby examples/advanced/auth/openweather_api.rb
+
+require 'bundler/setup'
+require 'legate'
+require 'legate/auth' # Explicitly require the auth module
+require 'json'
+require 'excon'
+require 'legate/session_service/in_memory'
+require 'uri'
+
+# Enable debug mode
+ENV['DEBUG'] = 'true'
+
+# API Key for OpenWeatherMap
+OPENWEATHER_API_KEY = ENV['API_KEY']
+
+puts 'OpenWeatherMap API Authentication Example'
+puts '----------------------------------------'
+puts "API Key: #{OPENWEATHER_API_KEY[0..5]}...#{OPENWEATHER_API_KEY[-4..-1]}"
+
+# Create session service for token storage
+session_service = Legate::SessionService::InMemory.new
+
+# Create a basic token store for caching
+token_store = Legate::Auth::TokenStore.new(session_service)
+
+# Create the ApiKey scheme for our OpenWeatherMap API
+api_key_scheme = Legate::Auth::Schemes::ApiKey.new
+
+# Create the credential to use with the scheme
+api_key_credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: OPENWEATHER_API_KEY,
+  location: 'query',
+  name: 'appid'
+)
+
+puts "\nDEMO 1: Direct API call with Excon (no Legate middleware)"
+puts '------------------------------------------------------'
+
+begin
+  # Make a direct Excon request to the OpenWeatherMap API
+  url = 'https://api.openweathermap.org/data/2.5/weather?q=London,uk&units=metric'
+
+  # Manually add the API key to the URL
+  url_with_key = "#{url}&appid=#{OPENWEATHER_API_KEY}"
+
+  puts "Making request to: #{url_with_key.gsub(OPENWEATHER_API_KEY, 'API_KEY_REDACTED')}"
+
+  response = Excon.get(url_with_key,
+                       connect_timeout: 30,
+                       read_timeout: 30,
+                       write_timeout: 30)
+
+  puts "Response Status: #{response.status}"
+
+  if response.status == 200
+    weather_data = JSON.parse(response.body)
+    puts "Location: #{weather_data['name']}, #{weather_data['sys']['country']}"
+    puts "Weather: #{weather_data['weather'][0]['main']} - #{weather_data['weather'][0]['description']}"
+    puts "Temperature: #{weather_data['main']['temp']}°C (Feels like: #{weather_data['main']['feels_like']}°C)"
+    puts "Humidity: #{weather_data['main']['humidity']}%"
+    puts "Wind: #{weather_data['wind']['speed']} m/s"
+  else
+    puts "Error: #{response.status} - #{response.body}"
+  end
+rescue StandardError => e
+  puts "Request Error: #{e.message}"
+  puts e.backtrace.join("\n") if ENV['DEBUG']
+end
+
+puts "\nDEMO 2: Using Legate::Auth to apply authentication manually"
+puts '------------------------------------------------------'
+
+begin
+  # Create a request hash (without authentication)
+  request = {
+    method: :get,
+    path: '/data/2.5/weather',
+    query: {
+      q: 'Paris,fr',
+      units: 'metric'
+    },
+    headers: {}
+  }
+
+  # Use Legate::Auth::ToolIntegration to apply authentication to the request
+  puts "Applying authentication with params: #{request.inspect}"
+  request_with_auth = Legate::Auth::ToolIntegration.apply_authentication(
+    request,
+    api_key_scheme,
+    api_key_credential,
+    token_store
+  )
+
+  puts "Authentication applied: #{request_with_auth.inspect}"
+
+  # Extract the query parameters - we need to handle this manually
+  query_params = request_with_auth[:query]
+
+  # Add appid parameter manually if it's not already present
+  query_hash = if query_params.is_a?(Hash)
+                 # If it's already a hash, we can use it directly
+                 query_params
+               elsif query_params.is_a?(String)
+                 # Parse the query string into a hash
+                 params = {}
+                 URI.decode_www_form(query_params).each do |key, value|
+                   params[key] = value
+                 end
+                 params
+               else
+                 # Default to an empty hash if we can't parse it
+                 { q: 'Paris,fr', units: 'metric' }
+               end
+
+  # Make sure the API key is in the query parameters
+  query_hash['appid'] ||= OPENWEATHER_API_KEY
+
+  # Construct the full URL from the request with proper query params
+  base_url = 'https://api.openweathermap.org'
+  path = request_with_auth[:path]
+
+  # Convert the hash to a query string
+  query_string = URI.encode_www_form(query_hash)
+
+  # Full URL
+  full_url = "#{base_url}#{path}?#{query_string}"
+  puts "Request URL with auth applied: #{full_url.gsub(OPENWEATHER_API_KEY, 'API_KEY_REDACTED')}"
+
+  # Make the request
+  response = Excon.get(full_url,
+                       connect_timeout: 30,
+                       read_timeout: 30,
+                       write_timeout: 30)
+
+  puts "Response Status: #{response.status}"
+
+  if response.status == 200
+    weather_data = JSON.parse(response.body)
+    puts "Location: #{weather_data['name']}, #{weather_data['sys']['country']}"
+    puts "Weather: #{weather_data['weather'][0]['main']} - #{weather_data['weather'][0]['description']}"
+    puts "Temperature: #{weather_data['main']['temp']}°C (Feels like: #{weather_data['main']['feels_like']}°C)"
+    puts "Humidity: #{weather_data['main']['humidity']}%"
+    puts "Wind: #{weather_data['wind']['speed']} m/s"
+  else
+    puts "Error: #{response.status} - #{response.body}"
+  end
+rescue StandardError => e
+  puts "Request Error: #{e.message}"
+  puts e.backtrace.join("\n") if ENV['DEBUG']
+end
+
+puts "\nDEMO 3: Using API Key directly with Excon"
+puts '-------------------------------------'
+
+begin
+  # Create a request with direct query params approach
+  puts 'Making direct query parameter request...'
+
+  # Use a direct approach without middleware
+  query_params = {
+    q: 'Tokyo,jp',
+    units: 'metric',
+    appid: OPENWEATHER_API_KEY
+  }
+
+  # Create the connection
+  connection = Excon.new('https://api.openweathermap.org',
+                         connect_timeout: 10,
+                         read_timeout: 10,
+                         write_timeout: 10)
+
+  # Make the request directly
+  response = connection.request(
+    method: :get,
+    path: '/data/2.5/weather',
+    query: query_params
+  )
+
+  puts "Response Status: #{response.status}"
+
+  if response.status == 200
+    weather_data = JSON.parse(response.body)
+    puts "Location: #{weather_data['name']}, #{weather_data['sys']['country']}"
+    puts "Weather: #{weather_data['weather'][0]['main']} - #{weather_data['weather'][0]['description']}"
+    puts "Temperature: #{weather_data['main']['temp']}°C (Feels like: #{weather_data['main']['feels_like']}°C)"
+    puts "Humidity: #{weather_data['main']['humidity']}%"
+    puts "Wind: #{weather_data['wind']['speed']} m/s"
+  else
+    puts "Error: #{response.status} - #{response.body}"
+  end
+rescue StandardError => e
+  puts "Request Error: #{e.message}"
+  puts e.backtrace.join("\n") if ENV['DEBUG']
+end
+
+puts "\nDEMO 4: Using Legate::Auth middleware (with fixed implementation)"
+puts '---------------------------------------------------------'
+
+begin
+  puts 'Creating connection with Legate::Auth middleware...'
+
+  # Use the fixed middleware via Legate::Auth.create_api_key_connection
+  connection = Legate::Auth.create_api_key_connection(
+    'https://api.openweathermap.org',
+    api_key: OPENWEATHER_API_KEY,
+    location: 'query',
+    name: 'appid',
+    token_store: token_store
+  )
+
+  puts 'Connection created. Making request to get weather for New York...'
+
+  # Make the request through the middleware
+  response = connection.request(
+    method: :get,
+    path: '/data/2.5/weather',
+    query: {
+      q: 'New York,us',
+      units: 'metric'
+    }
+  )
+
+  puts "Response Status: #{response.status}"
+
+  if response.status == 200
+    weather_data = JSON.parse(response.body)
+    puts "Location: #{weather_data['name']}, #{weather_data['sys']['country']}"
+    puts "Weather: #{weather_data['weather'][0]['main']} - #{weather_data['weather'][0]['description']}"
+    puts "Temperature: #{weather_data['main']['temp']}°C (Feels like: #{weather_data['main']['feels_like']}°C)"
+    puts "Humidity: #{weather_data['main']['humidity']}%"
+    puts "Wind: #{weather_data['wind']['speed']} m/s"
+  else
+    puts "Error: #{response.status} - #{response.body}"
+  end
+rescue StandardError => e
+  puts "Request Error: #{e.message}"
+  puts e.backtrace.join("\n") if ENV['DEBUG']
+end
+
+puts "\nExample complete."

data/examples/advanced/auth/openweather_tool.rb

@@ -0,0 +1,153 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example of using Legate::Auth with OpenWeatherMap API using the tool-based approach
+# and proper authentication handling through HttpClient.
+#
+# Usage:
+#   ruby examples/advanced/auth/openweather_tool.rb
+
+require 'bundler/setup'
+require 'legate'
+require 'legate/auth'
+require 'json'
+# API Key for OpenWeatherMap
+OPENWEATHER_API_KEY = ENV['API_KEY']
+
+puts 'OpenWeatherMap API Tool-Based Authentication Example'
+puts '------------------------------------------------'
+puts "API Key: #{OPENWEATHER_API_KEY[0..5]}...#{OPENWEATHER_API_KEY[-4..-1]}"
+
+# First, let's create a tool class for OpenWeather API
+module Legate
+  module Tools
+    class OpenWeather < Legate::Tool
+      include Legate::Tools::Base::HttpClient
+
+      # Tool metadata
+      tool_description 'Fetches weather data from OpenWeatherMap API'
+
+      parameter :city,
+                type: :string,
+                description: 'The city to get weather for',
+                required: true
+
+      parameter :country_code,
+                type: :string,
+                description: 'The country code (e.g., uk, us, jp)',
+                required: true
+
+      parameter :units,
+                type: :string,
+                description: 'The units to use (metric or imperial)',
+                required: false
+
+      def initialize(options = {})
+        super()
+        @auth_scheme = options[:auth_scheme]
+        @auth_credential = options[:auth_credential]
+        setup_http_client(
+          base_url: 'https://api.openweathermap.org',
+          options: {
+            connect_timeout: 3,
+            read_timeout: 3,
+            write_timeout: 3
+          }
+        )
+      end
+
+      private
+
+      def perform_execution(params, _context)
+        # Extract parameters
+        city = params[:city]
+        country_code = params[:country_code]
+        units = params.fetch(:units, 'metric')
+
+        # Prepare query parameters
+        query = {
+          q: "#{city},#{country_code}",
+          units: units
+        }
+
+        # If we have auth credentials, let them be applied through the auth scheme
+        if @auth_scheme && @auth_credential
+          request = { query: query }
+          modified_request = @auth_scheme.apply_to_request(request, @auth_credential)
+          query = modified_request[:query]
+        end
+
+        # Make the request using HttpClient's helper
+        response = http_get('/data/2.5/weather', query: query)
+
+        # Parse and return the response
+        begin
+          data = JSON.parse(response.body)
+          { status: :success, result: data }
+        rescue JSON::ParserError => e
+          raise Legate::ToolError, "Failed to parse API response: #{e.message}"
+        end
+      end
+    end
+  end
+end
+
+puts "\nDEMO 1: Using OpenWeather Tool with API Key Authentication"
+puts '-----------------------------------------------------'
+
+begin
+  # Create an API Key scheme
+  scheme = Legate::Auth::Schemes::ApiKey.new
+
+  # Create a credential with the API key
+  credential = Legate::Auth::Credential.new(
+    auth_type: :api_key,
+    api_key: OPENWEATHER_API_KEY,
+    location: 'query',
+    name: 'appid'
+  )
+
+  # Create our OpenWeather tool instance with authentication
+  weather_tool = Legate::Tools::OpenWeather.new(
+    auth_scheme: scheme,
+    auth_credential: credential
+  )
+
+  # Example cities to check weather for
+  cities = [
+    { city: 'London', country: 'uk' },
+    { city: 'Tokyo', country: 'jp' },
+    { city: 'New York', country: 'us' }
+  ]
+
+  # Get weather for each city
+  cities.each do |location|
+    puts "\nChecking weather for #{location[:city]}, #{location[:country].upcase}..."
+
+    begin
+      result = weather_tool.execute(
+        city: location[:city],
+        country_code: location[:country]
+      )
+
+      if result[:status] == :success
+        weather_data = result[:result]
+        puts "Location: #{weather_data['name']}, #{weather_data['sys']['country']}"
+        puts "Weather: #{weather_data['weather'][0]['main']} - #{weather_data['weather'][0]['description']}"
+        puts "Temperature: #{weather_data['main']['temp']}°C (Feels like: #{weather_data['main']['feels_like']}°C)"
+        puts "Humidity: #{weather_data['main']['humidity']}%"
+        puts "Wind: #{weather_data['wind']['speed']} m/s"
+      else
+        puts "Error: #{result[:error_message]}"
+      end
+    rescue StandardError => e
+      puts "Error getting weather for #{location[:city]}: #{e.message}"
+      puts e.backtrace.join("\n") if ENV['DEBUG']
+    end
+  end
+rescue StandardError => e
+  puts "Error: #{e.message}"
+  puts e.backtrace.join("\n") if ENV['DEBUG']
+end
+
+puts "\nExample complete."

data/examples/advanced/auth/query_param_middleware_test.rb

@@ -0,0 +1,138 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test focusing on query parameter handling in middleware
+#
+# Usage:
+#   ruby examples/advanced/auth/query_param_middleware_test.rb
+
+require 'bundler/setup'
+require 'json'
+require 'excon'
+require 'uri'
+
+# Middleware that correctly adds a query parameter
+class QueryParamMiddleware < Excon::Middleware::Base
+  def initialize(stack)
+    puts 'QueryParamMiddleware initialized'
+    @stack = stack
+    @api_key = 'test-api-key-123'
+    @api_key_name = 'apikey'
+    super(stack)
+  end
+
+  def request_call(datum)
+    puts 'QueryParamMiddleware request_call invoked'
+    puts "  Method: #{datum[:method]}, Path: #{datum[:path]}"
+    puts "  Original query: #{datum[:query].inspect}"
+    puts "  Connect timeout: #{datum[:connect_timeout]}"
+    puts "  Read timeout: #{datum[:read_timeout]}"
+    puts "  Write timeout: #{datum[:write_timeout]}"
+
+    # Add API key to query parameters
+    query = datum[:query] || {}
+
+    # Convert query to Hash if it's a string
+    if query.is_a?(String)
+      params = {}
+      URI.decode_www_form(query).each do |key, value|
+        params[key] = value
+      end
+      query = params
+    end
+
+    # Add API key parameter
+    query[@api_key_name] = @api_key
+
+    # Update the datum with the modified query
+    datum[:query] = query
+
+    # Debug the updated query
+    puts "  Modified query: #{datum[:query].inspect}"
+
+    # Continue with the middleware stack - pass through the modified datum
+    @stack.request_call(datum)
+  end
+
+  def response_call(datum)
+    puts 'QueryParamMiddleware response_call invoked'
+    # Pass the datum through unmodified
+    @stack.response_call(datum)
+  end
+end
+
+puts 'Query Parameter Middleware Test'
+puts '----------------------------'
+
+puts "\nTest 1: Direct API call with Excon"
+puts '-------------------------------'
+
+begin
+  # Make a direct Excon request
+  url = 'https://httpbin.org/get?test=value'
+
+  puts "Making direct request to: #{url}"
+
+  # Create the connection with normal timeouts
+  response = Excon.get(url,
+                       connect_timeout: 10,
+                       read_timeout: 10,
+                       write_timeout: 10)
+
+  puts "Response Status: #{response.status}"
+
+  if response.status == 200
+    data = JSON.parse(response.body)
+    puts "Data received: #{data['args'].inspect}"
+  else
+    puts "Error: #{response.status} - #{response.body}"
+  end
+rescue StandardError => e
+  puts "Request Error: #{e.message}"
+  puts e.backtrace.join("\n")
+end
+
+puts "\nTest 2: Query Parameter Middleware"
+puts '-------------------------------'
+
+begin
+  # Create a connection with our custom middleware
+  connection = Excon.new('https://httpbin.org',
+                         middlewares: [
+                           Excon::Middleware::ResponseParser,
+                           Excon::Middleware::Expects,
+                           Excon::Middleware::Idempotent,
+                           Excon::Middleware::Instrumentor,
+                           Excon::Middleware::Mock,
+                           QueryParamMiddleware # Our query parameter middleware
+                         ],
+                         connect_timeout: 10,
+                         read_timeout: 10,
+                         write_timeout: 10)
+
+  puts 'Connection created with query parameter middleware'
+  puts 'Making request...'
+
+  # Make the request
+  response = connection.request(
+    method: :get,
+    path: '/get',
+    query: {
+      test: 'value'
+    }
+  )
+
+  puts "Response Status: #{response.status}"
+
+  if response.status == 200
+    data = JSON.parse(response.body)
+    puts "Data received: #{data['args'].inspect}"
+  else
+    puts "Error: #{response.status} - #{response.body}"
+  end
+rescue StandardError => e
+  puts "Request Error: #{e.message}"
+  puts e.backtrace.join("\n")
+end
+
+puts "\nTest complete."

data/examples/advanced/auth/service_account.rb

@@ -0,0 +1,135 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example of using the ServiceAccount authentication with automatic token exchange and refresh
+#
+# This example demonstrates how to authenticate using a service account JSON key file
+# and make requests that are automatically authenticated.
+#
+# Usage:
+#   ruby examples/advanced/auth/service_account.rb [path/to/service_account_key.json]
+
+require 'bundler/setup'
+require 'legate'
+require 'json'
+require 'fileutils'
+
+# Check if a service account key file was provided
+key_file_path = ARGV[0] || ENV['SERVICE_ACCOUNT_KEY_FILE']
+unless key_file_path
+  puts 'Error: Please provide a service account key JSON file as an argument'
+  puts 'Usage: ruby examples/advanced/auth/service_account.rb [path/to/service_account_key.json]'
+  puts 'Alternatively, set the SERVICE_ACCOUNT_KEY_FILE environment variable'
+  exit 1
+end
+
+# Ensure the key file exists
+unless File.exist?(key_file_path)
+  puts "Error: Service account key file not found: #{key_file_path}"
+  exit 1
+end
+
+# Load the service account key file
+begin
+  service_account_key = JSON.parse(File.read(key_file_path))
+  puts "Loaded service account key for: #{service_account_key['client_email']}"
+rescue JSON::ParserError => e
+  puts "Error parsing service account key file: #{e.message}"
+  exit 1
+end
+
+# Create the Auth::Credential for the service account
+# You can use either the raw JSON key or the individual components
+credential = if ENV['USE_RAW_JSON'] == 'true'
+               Legate::Auth::Credential.new(
+                 auth_type: :service_account,
+                 service_account_key: File.read(key_file_path)
+               )
+             else
+               Legate::Auth::Credential.new(
+                 auth_type: :service_account,
+                 client_email: service_account_key['client_email'],
+                 private_key: service_account_key['private_key'],
+                 token_uri: service_account_key['token_uri']
+               )
+             end
+
+# Create a Google Service Account scheme with the appropriate scopes
+# You can use other service account implementations as well
+scheme = Legate::Auth::Schemes::GoogleServiceAccount.new(
+  scopes: ['https://www.googleapis.com/auth/cloud-platform']
+  # Optional custom audience if needed:
+  # audience: 'https://your-api.example.com'
+)
+
+# Create a session service to manage authentication state
+session_service = Legate::SessionService::InMemory.new
+
+# Create a token store (optional but recommended for caching tokens)
+token_store = Legate::Auth::TokenStore.new(session_service: session_service)
+
+# Create the service account coordinator
+coordinator = Legate::Auth::Coordinators::ServiceAccountCoordinator.new(
+  scheme: scheme,
+  credential: credential,
+  session_service: session_service,
+  token_store: token_store
+)
+
+# Authenticate and get the token
+begin
+  token = Legate::Auth.authenticate_with_coordinator(coordinator)
+  puts 'Successfully authenticated with service account'
+  puts "Access token: #{token.access_token[0..10]}... (expires in #{token[:expires_in]} seconds)"
+rescue Legate::Auth::Error => e
+  puts "Authentication failed: #{e.message}"
+  exit 1
+end
+
+# Example of making an authenticated request with the token
+require 'faraday'
+
+puts "\nMaking an authenticated request..."
+conn = Faraday.new(url: 'https://www.googleapis.com/storage/v1') do |builder|
+  builder.request :authorization, 'Bearer', token.access_token
+  builder.request :json
+  builder.response :json
+  builder.adapter Faraday.default_adapter
+end
+
+# Example: List Google Cloud Storage buckets
+begin
+  response = conn.get('b', { project: service_account_key['project_id'] })
+
+  if response.success?
+    puts "Request succeeded with status: #{response.status}"
+    puts "Found #{response.body['items']&.length || 0} buckets"
+
+    if response.body['items']&.any?
+      puts "\nBucket names:"
+      response.body['items'].each do |bucket|
+        puts "- #{bucket['name']}"
+      end
+    end
+  else
+    puts "Request failed with status: #{response.status}"
+    puts "Error: #{response.body['error']&.dig('message') || response.body.inspect}"
+  end
+rescue StandardError => e
+  puts "Request failed: #{e.message}"
+end
+
+puts "\nToken refresh demonstration:"
+puts "Current token will expire in #{token[:expires_in]} seconds"
+puts 'Explicitly refreshing token...'
+
+# Example of refreshing a token
+begin
+  refreshed_token = coordinator.refresh(token)
+  puts 'Token refreshed successfully'
+  puts "New access token: #{refreshed_token.access_token[0..10]}... (expires in #{refreshed_token[:expires_in]} seconds)"
+rescue Legate::Auth::Error => e
+  puts "Token refresh failed: #{e.message}"
+end
+
+puts "\nDemonstration completed successfully!"