signalwire-sdk 2.0.0

data/lib/signalwire/utils/schema_utils.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require 'json'
+
+module SignalWire
+  module Utils
+    # SchemaValidationError — Ruby port of
+    # signalwire.utils.schema_utils.SchemaValidationError.
+    #
+    # Raised when SWML schema validation of a verb config fails.
+    class SchemaValidationError < StandardError
+      attr_reader :verb_name, :errors
+
+      # Construct a SchemaValidationError. Mirrors Python's
+      # SchemaValidationError(verb_name, errors).
+      def initialize(verb_name, errors)
+        @verb_name = verb_name
+        @errors = errors || []
+        message = "Schema validation failed for '#{verb_name}': #{@errors.join('; ')}"
+        super(message)
+      end
+    end
+
+    # SchemaUtils — Ruby port of signalwire.utils.schema_utils.SchemaUtils.
+    #
+    # Loads the SWML JSON Schema, extracts verb metadata, and validates
+    # either a single verb config or a complete SWML document.
+    #
+    # Construction rules mirror Python:
+    #   - Pass schema_path: nil to use the bundled schema.json.
+    #   - schema_validation: false disables validation (validate_verb returns
+    #     true for every call).
+    #   - The env var SWML_SKIP_SCHEMA_VALIDATION=1/true/yes also disables
+    #     validation regardless of the constructor argument.
+    #
+    # The Ruby port currently ships only the lightweight validator (verb
+    # existence + required-property check). Full JSON Schema validation
+    # can be wired in via the `json_schemer` gem by extending
+    # init_full_validator. The lightweight contract matches Python's
+    # _validate_verb_lightweight() exactly.
+    class SchemaUtils
+      # @return [Hash{String=>Object}] parsed JSON Schema document
+      attr_reader :schema
+
+      # @return [String, nil] resolved schema path (nil = embedded default)
+      attr_reader :schema_path
+
+      # Construct a SchemaUtils.
+      #
+      # @param schema_path [String, nil] path to a schema.json file; nil for
+      #   the bundled copy at lib/signalwire/swml/schema.json.
+      # @param schema_validation [Boolean] enable/disable schema validation.
+      def initialize(schema_path = nil, schema_validation = true)
+        env_skip = env_boolish(ENV.fetch('SWML_SKIP_SCHEMA_VALIDATION', ''))
+        @schema_path = schema_path
+        @validation_enabled = schema_validation && !env_skip
+        @schema = load_schema
+        @verbs = {}
+        extract_verbs
+        init_full_validator if @validation_enabled && !@schema.empty?
+      end
+
+      # Whether full JSON Schema validation is wired up.
+      # Mirrors Python's full_validation_available property.
+      def full_validation_available?
+        !@full_validator.nil?
+      end
+
+      # Read and parse the JSON Schema. Mirrors Python's load_schema().
+      def load_schema
+        path = @schema_path || default_schema_path
+        return {} if path.nil? || !File.exist?(path)
+
+        raw = File.read(path, encoding: 'UTF-8')
+        JSON.parse(raw)
+      rescue JSON::ParserError, Errno::ENOENT
+        {}
+      end
+
+      # Sorted list of all known verb names.
+      # Mirrors Python's get_all_verb_names().
+      def get_all_verb_names
+        @verbs.keys.sort
+      end
+
+      # The properties[verb_name] block for a verb, or {} when unknown.
+      # Mirrors Python's get_verb_properties(verb_name).
+      def get_verb_properties(verb_name)
+        v = @verbs[verb_name]
+        return {} if v.nil?
+
+        outer_props = v['definition']['properties'] rescue nil
+        return {} unless outer_props.is_a?(Hash)
+
+        inner = outer_props[verb_name]
+        return {} unless inner.is_a?(Hash)
+
+        inner
+      end
+
+      # The required list for a verb, or [] when unknown / no required.
+      # Mirrors Python's get_verb_required_properties(verb_name).
+      def get_verb_required_properties(verb_name)
+        inner = get_verb_properties(verb_name)
+        req = inner['required']
+        return [] unless req.is_a?(Array)
+
+        req.select { |x| x.is_a?(String) }
+      end
+
+      # Parameter-definition block used by code-gen tooling.
+      # Mirrors Python's get_verb_parameters(verb_name).
+      def get_verb_parameters(verb_name)
+        inner = get_verb_properties(verb_name)
+        props = inner['properties']
+        return {} unless props.is_a?(Hash)
+
+        props
+      end
+
+      # Validate a verb config against the schema.
+      # Mirrors Python's validate_verb(verb_name, verb_config).
+      #
+      # @return [Array(Boolean, Array<String>)] (valid, errors) tuple.
+      def validate_verb(verb_name, verb_config)
+        return [true, []] unless @validation_enabled
+
+        unless @verbs.key?(verb_name)
+          return [false, ["Unknown verb: #{verb_name}"]]
+        end
+
+        if @full_validator
+          validate_verb_full(verb_name, verb_config)
+        else
+          validate_verb_lightweight(verb_name, verb_config)
+        end
+      end
+
+      # Validate a complete SWML document.
+      # Mirrors Python's validate_document(document). Returns
+      # (false, ['Schema validator not initialized']) when no full
+      # validator is wired in.
+      def validate_document(document)
+        if @full_validator.nil?
+          return [false, ['Schema validator not initialized']]
+        end
+
+        # Reserved for full-validator wiring.
+        [true, []]
+      end
+
+      # Generate a Python-style method signature string for a verb.
+      # Mirrors Python's generate_method_signature(verb_name).
+      def generate_method_signature(verb_name)
+        params = get_verb_parameters(verb_name)
+        required = get_verb_required_properties(verb_name).to_set
+        parts = ['self']
+        keys = params.keys.sort
+        keys.each do |name|
+          t = python_type_annotation(params[name])
+          parts << if required.include?(name)
+                     "#{name}: #{t}"
+                   else
+                     "#{name}: Optional[#{t}] = None"
+                   end
+        end
+        parts << '**kwargs'
+        doc = +"\"\"\"\n        Add the #{verb_name} verb to the current document\n        \n"
+        keys.each do |name|
+          desc = ''
+          d = params[name]
+          if d.is_a?(Hash) && d['description']
+            desc = d['description'].to_s.gsub("\n", ' ').strip
+          end
+          doc << "        Args:\n            #{name}: #{desc}\n"
+        end
+        doc << "        \n        Returns:\n            True if the verb was added successfully, False otherwise\n        \"\"\"\n"
+        "def #{verb_name}(#{parts.join(', ')}) -> bool:\n#{doc}"
+      end
+
+      # Generate a Python-style method body string for a verb.
+      # Mirrors Python's generate_method_body(verb_name).
+      def generate_method_body(verb_name)
+        params = get_verb_parameters(verb_name)
+        keys = params.keys.sort
+        lines = [
+          '        # Prepare the configuration',
+          '        config = {}'
+        ]
+        keys.each do |name|
+          lines << "        if #{name} is not None:"
+          lines << "            config['#{name}'] = #{name}"
+        end
+        lines << '        # Add any additional parameters from kwargs'
+        lines << '        for key, value in kwargs.items():'
+        lines << '            if value is not None:'
+        lines << '                config[key] = value'
+        lines << ''
+        lines << "        # Add the #{verb_name} verb"
+        lines << "        return self.add_verb('#{verb_name}', config)"
+        lines.join("\n")
+      end
+
+      private
+
+      def default_schema_path
+        # Bundled schema lives in lib/signalwire/swml/schema.json
+        File.expand_path('../swml/schema.json', __dir__)
+      end
+
+      def env_boolish(value)
+        %w[1 true yes].include?(value.to_s.strip.downcase)
+      end
+
+      def extract_verbs
+        defs = @schema['$defs']
+        return unless defs.is_a?(Hash)
+
+        swml_method = defs['SWMLMethod']
+        return unless swml_method.is_a?(Hash)
+
+        any_of = swml_method['anyOf']
+        return unless any_of.is_a?(Array)
+
+        any_of.each do |entry|
+          next unless entry.is_a?(Hash)
+
+          ref = entry['$ref']
+          next unless ref.is_a?(String)
+
+          prefix = '#/$defs/'
+          next unless ref.start_with?(prefix)
+
+          schema_name = ref[prefix.length..]
+          defn = defs[schema_name]
+          next unless defn.is_a?(Hash)
+
+          props = defn['properties']
+          next unless props.is_a?(Hash) && !props.empty?
+
+          actual_verb = props.keys.first
+          @verbs[actual_verb] = {
+            'name' => actual_verb,
+            'schema_name' => schema_name,
+            'definition' => defn
+          }
+        end
+      end
+
+      def init_full_validator
+        # Reserved for full-validator wiring (json_schemer gem).
+        @full_validator = nil
+      end
+
+      def validate_verb_full(verb_name, verb_config)
+        # Reserved for full-validator wiring; falls back to lightweight check.
+        validate_verb_lightweight(verb_name, verb_config)
+      end
+
+      def validate_verb_lightweight(verb_name, verb_config)
+        errors = []
+        get_verb_required_properties(verb_name).each do |prop|
+          unless verb_config.key?(prop)
+            errors << "Missing required property '#{prop}' for verb '#{verb_name}'"
+          end
+        end
+        [errors.empty?, errors]
+      end
+
+      def python_type_annotation(defn)
+        return 'Any' unless defn.is_a?(Hash)
+
+        case defn['type']
+        when 'string'  then 'str'
+        when 'integer' then 'int'
+        when 'number'  then 'float'
+        when 'boolean' then 'bool'
+        when 'array'
+          item = 'Any'
+          if defn['items'].is_a?(Hash)
+            item = python_type_annotation(defn['items'])
+          end
+          "List[#{item}]"
+        when 'object'  then 'Dict[str, Any]'
+        else
+          'Any'
+        end
+      end
+    end
+  end
+end
+
+require 'set'

data/lib/signalwire/utils/serverless.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../core/logging_config'
+
+# Cross-language SDK contract: SignalWire::Utils.is_serverless_mode
+# mirrors signalwire.utils.is_serverless_mode in the Python reference.
+# Returns true when running inside any short-lived / event-driven
+# environment (i.e. not 'server').
+
+module SignalWire
+  module Utils
+    module_function
+
+    # @return [Boolean] true unless the detected mode is 'server'.
+    def is_serverless_mode
+      SignalWire::Core::LoggingConfig.get_execution_mode != 'server'
+    end
+  end
+end

data/lib/signalwire/utils/url_validator.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require 'ipaddr'
+require 'resolv'
+require 'uri'
+
+require_relative '../logging'
+
+module SignalWire
+  module Utils
+    # SSRF-prevention guard for user-supplied URLs.
+    #
+    # Mirrors Python's signalwire.utils.url_validator.validate_url:
+    # rejects non-http(s) schemes, missing hostnames, and any URL whose
+    # hostname resolves to a private / loopback / link-local / cloud-
+    # metadata IP.  When +allow_private+ is true, OR the
+    # +SWML_ALLOW_PRIVATE_URLS+ env var is set to "1", "true" or "yes"
+    # (case-insensitive), the IP-blocklist check is skipped.
+    #
+    # The method UrlValidator.validate_url projects onto the Python free
+    # function signalwire.utils.url_validator.validate_url via
+    # scripts/enumerate_signatures.py.
+    module UrlValidator
+      # Cross-port SSRF block list.  Order matches the Python reference.
+      BLOCKED_NETWORKS = %w[
+        10.0.0.0/8
+        172.16.0.0/12
+        192.168.0.0/16
+        127.0.0.0/8
+        169.254.0.0/16
+        0.0.0.0/8
+        ::1/128
+        fc00::/7
+        fe80::/10
+      ].freeze
+
+      LOG = SignalWire::Logging.logger('signalwire.url_validator')
+
+      # Pluggable resolver hook. Tests inject a lambda to keep the suite
+      # hermetic; production calls Resolv.getaddresses. Underscore prefix
+      # keeps it out of the public surface inventory — the Python
+      # reference only exposes ``validate_url`` at this module level.
+      def self._resolver
+        @_resolver
+      end
+
+      def self._resolver=(value)
+        @_resolver = value
+      end
+
+      # Validate that a URL is safe to fetch.
+      #
+      # @param url [String] URL to validate
+      # @param allow_private [Boolean] when true, bypass the IP-blocklist check
+      # @return [Boolean] true if the URL is safe to fetch
+      def self.validate_url(url, allow_private = false)
+        parsed = URI.parse(url)
+
+        scheme = (parsed.scheme || '').downcase
+        unless %w[http https].include?(scheme)
+          LOG.warn("URL rejected: invalid scheme #{parsed.scheme}")
+          return false
+        end
+
+        hostname = parsed.host
+        if hostname.nil? || hostname.empty?
+          LOG.warn('URL rejected: no hostname')
+          return false
+        end
+
+        # URI keeps brackets in host for IPv6 literals; strip them.
+        if hostname.start_with?('[') && hostname.end_with?(']')
+          hostname = hostname[1..-2]
+        end
+
+        if allow_private || _env_allows_private?
+          return true
+        end
+
+        ips = _resolve(hostname)
+        if ips.nil? || ips.empty?
+          LOG.warn("URL rejected: could not resolve hostname #{hostname}")
+          return false
+        end
+
+        ips.each do |ip_str|
+          ip = begin
+            IPAddr.new(ip_str)
+          rescue IPAddr::InvalidAddressError
+            next
+          end
+          BLOCKED_NETWORKS.each do |cidr|
+            net = IPAddr.new(cidr)
+            if net.include?(ip)
+              LOG.warn("URL rejected: #{hostname} resolves to blocked IP #{ip_str} (in #{cidr})")
+              return false
+            end
+          end
+        end
+
+        true
+      rescue URI::InvalidURIError, IPAddr::InvalidAddressError => e
+        LOG.warn("URL validation error: #{e.message}")
+        false
+      end
+
+      def self._env_allows_private?
+        v = (ENV['SWML_ALLOW_PRIVATE_URLS'] || '').downcase
+        %w[1 true yes].include?(v)
+      end
+      private_class_method :_env_allows_private?
+
+      # @param hostname [String]
+      # @return [Array<String>, nil]
+      def self._resolve(hostname)
+        if _resolver
+          return _resolver.call(hostname)
+        end
+        # Literal IP shortcut (covers tests that pass IP-as-hostname URLs).
+        begin
+          IPAddr.new(hostname)
+          return [hostname]
+        rescue IPAddr::InvalidAddressError
+          # not a literal IP — fall through to DNS
+        end
+        Resolv.getaddresses(hostname)
+      rescue StandardError
+        nil
+      end
+      private_class_method :_resolve
+    end
+  end
+end

data/lib/signalwire/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SignalWire
+  VERSION = '2.0.0'
+end

data/lib/signalwire.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative 'signalwire/version'
+require_relative 'signalwire/logging'
+require_relative 'signalwire/core/logging_config'
+require_relative 'signalwire/utils/serverless'
+require_relative 'signalwire/utils/schema_utils'
+require_relative 'signalwire/runtime'
+require_relative 'signalwire/swml/document'
+require_relative 'signalwire/swml/schema'
+require_relative 'signalwire/swml/service'
+require_relative 'signalwire/swaig/function_result'
+require_relative 'signalwire/security/session_manager'
+require_relative 'signalwire/contexts/context_builder'
+require_relative 'signalwire/pom/prompt_object_model'
+require_relative 'signalwire/datamap/data_map'
+require_relative 'signalwire/skills/skill_base'
+require_relative 'signalwire/skills/skill_manager'
+require_relative 'signalwire/skills/skill_registry'
+require_relative 'signalwire/agent/agent_base'
+require_relative 'signalwire/serverless/lambda_handler'
+
+module SignalWire
+  # Top-level convenience entry points — mirror Python's
+  # ``signalwire/__init__.py`` factory + skill registry helpers.
+
+  module_function
+
+  # Construct a {SignalWire::REST::RestClient} instance.
+  #
+  # Mirrors Python's top-level ``signalwire.RestClient(*args, **kwargs)``
+  # factory — a thin wrapper that lazy-imports
+  # ``signalwire.rest.RestClient`` and instantiates it. Supports both
+  # positional credentials (matching Go-style ``RestClient(project,
+  # token, host)``) and keyword credentials (Ruby-idiomatic).
+  #
+  # @param args [Array<String>] Positional credentials (compat shim).
+  # @param kwargs [Hash] Keyword credentials forwarded to the constructor.
+  # @return [SignalWire::REST::RestClient]
+  def RestClient(*args, **kwargs)
+    require_relative 'signalwire/rest/rest_client'
+    if args.length >= 3 && kwargs.empty?
+      REST::RestClient.new(project: args[0], token: args[1], host: args[2])
+    elsif !args.empty? && kwargs.empty?
+      raise ArgumentError, 'positional form requires (project, token, host)'
+    else
+      REST::RestClient.new(**kwargs)
+    end
+  end
+
+  # Register a custom skill class with the global skill registry.
+  #
+  # Mirrors Python's ``signalwire.register_skill(skill_class)`` — the
+  # Ruby singleton registry stores factories by name. The class is
+  # expected to expose a ``::skill_name`` (or ``SKILL_NAME`` constant)
+  # so we can derive the registration key.
+  #
+  # @param skill_class [Class] A subclass of {SignalWire::Skills::SkillBase}
+  # @return [void]
+  def register_skill(skill_class)
+    require_relative 'signalwire/skills/skill_registry'
+    name = if skill_class.respond_to?(:skill_name)
+             skill_class.skill_name
+           elsif skill_class.const_defined?(:SKILL_NAME)
+             skill_class.const_get(:SKILL_NAME)
+           else
+             raise ArgumentError,
+                   "skill class #{skill_class} must define ::skill_name or SKILL_NAME"
+           end
+    Skills::SkillRegistry.register_skill(name, ->(params) { skill_class.new(params) })
+  end
+
+  # Add a directory to search for skills.
+  #
+  # Mirrors Python's ``signalwire.add_skill_directory(path)`` — delegates
+  # to the singleton {SignalWire::Skills::SkillRegistry} instance so
+  # third-party skill collections can be registered by path. Subsequent
+  # calls accumulate (de-duplicated) into a shared external paths list.
+  #
+  # @param path [String] absolute or relative path to a skill directory.
+  # @return [void]
+  # @raise [ArgumentError] when the path doesn't exist or isn't a directory.
+  def add_skill_directory(path)
+    require_relative 'signalwire/skills/skill_registry'
+    _signalwire_singleton_registry.add_skill_directory(path)
+  end
+
+  # Get complete schema for all available skills, including parameter metadata.
+  #
+  # Mirrors Python's ``signalwire.list_skills_with_params()``. Keys are
+  # skill names; values describe metadata + parameter schema. Useful for
+  # GUI configuration tools, API documentation, or programmatic skill
+  # discovery.
+  #
+  # @return [Hash{String => Hash}]
+  def list_skills_with_params
+    require_relative 'signalwire/skills/skill_registry'
+    if Skills::SkillRegistry.respond_to?(:get_all_skills_schema)
+      Skills::SkillRegistry.get_all_skills_schema
+    else
+      # Fallback: list_skills returns names; pair them with empty params.
+      Skills::SkillRegistry.list_skills.each_with_object({}) do |name, h|
+        h[name] = { 'name' => name, 'parameters' => {} }
+      end
+    end
+  end
+
+  # Singleton SkillRegistry instance used by the top-level helpers.
+  # Internal — exposed only so the helpers can share state across calls.
+  def _signalwire_singleton_registry
+    @_signalwire_singleton_registry ||= Skills::SkillRegistry.new
+  end
+  private_class_method :_signalwire_singleton_registry
+end