ruby-utcp 1.1.0

data/lib/utcp/utils.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module UTCP
+  module ModelSerialization
+    def to_json(*arguments)
+      to_h.to_json(*arguments)
+    end
+
+    def ==(other)
+      other.instance_of?(self.class) && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, to_h].hash
+    end
+  end
+
+  module Utils
+    module_function
+
+    def stringify_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, item), copy| copy[key.to_s] = stringify_keys(item) }
+      when Array
+        value.map { |item| stringify_keys(item) }
+      else
+        value
+      end
+    end
+
+    def symbolize_keys(value)
+      value.each_with_object({}) { |(key, item), copy| copy[key.to_sym] = item }
+    end
+
+    def deep_copy(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, item), copy| copy[key] = deep_copy(item) }
+      when Array
+        value.map { |item| deep_copy(item) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
+
+    def compact_hash(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        result[key] = value unless value.nil?
+      end
+    end
+
+    def required_string!(value, field)
+      return value if value.is_a?(String) && !value.empty?
+
+      raise ValidationError.new("must be a non-empty String", path: field)
+    end
+
+    def optional_string!(value, field)
+      return nil if value.nil?
+      return value if value.is_a?(String)
+
+      raise ValidationError.new("must be a String", path: field)
+    end
+
+    def hash!(value, field)
+      return value if value.is_a?(Hash)
+
+      raise ValidationError.new("must be an object", path: field)
+    end
+
+    def array!(value, field)
+      return value if value.is_a?(Array)
+
+      raise ValidationError.new("must be an array", path: field)
+    end
+
+    def parse_document(content, source: nil)
+      JSON.parse(content)
+    rescue JSON::ParserError => json_error
+      begin
+        parsed = YAML.safe_load(content, permitted_classes: [], permitted_symbols: [], aliases: false)
+        raise ValidationError, "document is empty" if parsed.nil?
+
+        parsed
+      rescue Psych::Exception, ValidationError => yaml_error
+        label = source ? " #{source}" : ""
+        raise SerializerValidationError,
+              "Could not parse#{label} as JSON or safe YAML: #{json_error.message}; #{yaml_error.message}"
+      end
+    end
+
+    def load_document(path)
+      parse_document(File.read(path, mode: "r:bom|utf-8"), source: path)
+    rescue Errno::ENOENT => error
+      raise ValidationError, "File not found: #{path} (#{error.message})"
+    rescue Errno::EACCES => error
+      raise ValidationError, "Cannot read file: #{path} (#{error.message})"
+    end
+
+    def json_value(value)
+      case value
+      when String, Numeric, TrueClass, FalseClass, NilClass
+        value
+      when Hash, Array
+        value
+      else
+        value.to_s
+      end
+    end
+  end
+end

data/lib/utcp/variables.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module UTCP
+  class VariableLoader
+    attr_reader :variable_loader_type
+
+    def self.from_h(value, root_dir: Dir.pwd)
+      return value if value.respond_to?(:get)
+
+      data = Utils.stringify_keys(Utils.hash!(value, "variable loader"))
+      case data["variable_loader_type"]
+      when "dotenv"
+        DotenvVariableLoader.new(
+          env_file_path: data["env_file_path"] || ".env",
+          root_dir: root_dir
+        )
+      else
+        raise ValidationError.new(
+          "unsupported variable loader type #{data['variable_loader_type'].inspect}",
+          path: "variable_loader_type"
+        )
+      end
+    end
+
+    def initialize(variable_loader_type)
+      @variable_loader_type = variable_loader_type
+    end
+
+    def get(_key)
+      raise NotImplementedError
+    end
+  end
+
+  class DotenvVariableLoader < VariableLoader
+    attr_reader :env_file_path
+
+    def initialize(env_file_path: ".env", root_dir: Dir.pwd)
+      super("dotenv")
+      @env_file_path = File.expand_path(env_file_path, root_dir)
+      @variables = nil
+      @mutex = Mutex.new
+    end
+
+    def get(key)
+      load_variables.fetch(key.to_s, nil)
+    end
+
+    def reload!
+      @mutex.synchronize { @variables = nil }
+      self
+    end
+
+    def to_h
+      { "variable_loader_type" => variable_loader_type, "env_file_path" => env_file_path }
+    end
+
+    private
+
+    def load_variables
+      @mutex.synchronize do
+        @variables ||= parse_file
+      end
+    end
+
+    def parse_file
+      return {} unless File.file?(env_file_path)
+
+      File.readlines(env_file_path, chomp: true).each_with_object({}) do |line, values|
+        stripped = line.strip
+        next if stripped.empty? || stripped.start_with?("#")
+
+        stripped = stripped.sub(/\Aexport\s+/, "")
+        key, raw = stripped.split("=", 2)
+        next unless raw && key.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+
+        values[key] = parse_value(raw.strip)
+      end
+    end
+
+    def parse_value(raw)
+      if raw.length >= 2 && raw.start_with?("'") && raw.end_with?("'")
+        raw[1..-2]
+      elsif raw.length >= 2 && raw.start_with?("\"") && raw.end_with?("\"")
+        raw[1..-2].gsub(/\\n/, "\n").gsub(/\\r/, "\r").gsub(/\\t/, "\t").gsub(/\\\"/, "\"")
+      else
+        raw.sub(/\s+#.*\z/, "")
+      end
+    end
+  end
+
+  class VariableSubstitutor
+    VARIABLE_PATTERN = /\$\{([A-Za-z0-9_]+)\}|\$([A-Za-z0-9_]+)/.freeze
+    JSON_REF_PATTERN = /\$ref(?![A-Za-z0-9_])/.freeze
+
+    def substitute(value, config, namespace = nil)
+      validate_namespace!(namespace)
+      case value
+      when String
+        return value if value.match?(JSON_REF_PATTERN)
+
+        value.gsub(VARIABLE_PATTERN) do
+          key = Regexp.last_match(1) || Regexp.last_match(2)
+          next Regexp.last_match(0) if key.match?(/\ACMD_\d+_OUTPUT\z/)
+
+          resolve(key, config, namespace)
+        end
+      when Hash
+        value.each_with_object({}) do |(key, item), result|
+          result[key] = substitute(item, config, namespace)
+        end
+      when Array
+        value.map { |item| substitute(item, config, namespace) }
+      else
+        value
+      end
+    end
+
+    def find_required_variables(value, namespace = nil)
+      validate_namespace!(namespace)
+      names = collect_required_variables(value)
+      names.map { |name| namespace ? "#{encoded_namespace(namespace)}_#{name}" : name }.uniq
+    end
+
+    private
+
+    def resolve(key, config, namespace)
+      candidates = namespace ? ["#{encoded_namespace(namespace)}_#{key}", key] : [key]
+      candidates.each do |candidate|
+        direct = config.variables[candidate]
+        return direct.to_s unless direct.nil?
+
+        config.load_variables_from.each do |loader|
+          loaded = loader.get(candidate)
+          return loaded.to_s unless loaded.nil?
+        end
+
+        environment = ENV[candidate]
+        return environment unless environment.nil?
+      end
+
+      raise VariableNotFoundError, candidates.first
+    end
+
+    def collect_required_variables(value)
+      case value
+      when String
+        return [] if value.match?(JSON_REF_PATTERN)
+
+        value.scan(VARIABLE_PATTERN).map { |groups| groups.compact.first }
+             .reject { |name| name.match?(/\ACMD_\d+_OUTPUT\z/) }
+      when Hash
+        value.values.flat_map { |item| collect_required_variables(item) }
+      when Array
+        value.flat_map { |item| collect_required_variables(item) }
+      else
+        []
+      end
+    end
+
+    def encoded_namespace(namespace)
+      namespace.to_s.gsub("_", "__")
+    end
+
+    def validate_namespace!(namespace)
+      return if namespace.nil? || namespace.to_s.match?(/\A[[:alnum:]_]+\z/)
+
+      raise ArgumentError, "variable namespace may only contain letters, numbers, and underscores"
+    end
+  end
+end

data/lib/utcp/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module UTCP
+  VERSION = "1.1.0"
+end
+

data/lib/utcp.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "utcp/version"
+require_relative "utcp/errors"
+require_relative "utcp/utils"
+require_relative "utcp/registry"
+require_relative "utcp/models"
+require_relative "utcp/repository"
+require_relative "utcp/variables"
+require_relative "utcp/config"
+require_relative "utcp/serializer"
+require_relative "utcp/protocols/base"
+require_relative "utcp/openapi_converter"
+require_relative "utcp/migration"
+require_relative "utcp/protocols/http"
+require_relative "utcp/protocols/http_stream_support"
+require_relative "utcp/protocols/sse"
+require_relative "utcp/protocols/streamable_http"
+require_relative "utcp/protocols/cli"
+require_relative "utcp/protocols/text"
+require_relative "utcp/protocols/file"
+require_relative "utcp/protocols/websocket"
+require_relative "utcp/protocols/graphql"
+require_relative "utcp/protocols/grpc"
+require_relative "utcp/protocols/socket_support"
+require_relative "utcp/protocols/tcp"
+require_relative "utcp/protocols/udp"
+require_relative "utcp/protocols/mcp"
+require_relative "utcp/protocols/webrtc"
+require_relative "utcp/client"
+
+module UTCP
+  register_auth("api_key", ApiKeyAuth)
+  register_auth("basic", BasicAuth)
+  register_auth("oauth2", OAuth2Auth)
+
+  register_call_template("http", HttpCallTemplate)
+  register_call_template("sse", SseCallTemplate)
+  register_call_template("streamable_http", StreamableHttpCallTemplate)
+  register_call_template("http_stream", StreamableHttpCallTemplate)
+  register_call_template("cli", CliCallTemplate)
+  register_call_template("websocket", WebSocketCallTemplate)
+  register_call_template("grpc", GrpcCallTemplate)
+  register_call_template("graphql", GraphQLCallTemplate)
+  register_call_template("tcp", TcpCallTemplate)
+  register_call_template("udp", UdpCallTemplate)
+  register_call_template("webrtc", WebRtcCallTemplate)
+  register_call_template("mcp", McpCallTemplate)
+  register_call_template("text", TextCallTemplate)
+  register_call_template("file", FileCallTemplate)
+
+  register_protocol("http", HTTPProtocol.new)
+  register_protocol("sse", SSEProtocol.new)
+  streamable_http_protocol = StreamableHTTPProtocol.new
+  register_protocol("streamable_http", streamable_http_protocol)
+  register_protocol("http_stream", streamable_http_protocol)
+  register_protocol("cli", CLIProtocol.new)
+  register_protocol("websocket", WebSocketProtocol.new)
+  register_protocol("grpc", GRPCProtocol.new)
+  register_protocol("graphql", GraphQLProtocol.new)
+  register_protocol("tcp", TCPProtocol.new)
+  register_protocol("udp", UDPProtocol.new)
+  register_protocol("webrtc", WebRTCProtocol.new)
+  register_protocol("mcp", MCPProtocol.new)
+  register_protocol("text", TextProtocol.new)
+  register_protocol("file", FileProtocol.new)
+end
+
+# Conventional Ruby casing alias for applications that do not preserve acronyms.
+Utcp = UTCP unless defined?(Utcp)

data/proto/utcp.proto

@@ -0,0 +1,31 @@
+syntax = "proto3";
+
+package grpcpb;
+
+// Minimal UTCP gRPC contract used by the Ruby client and example servers.
+message Empty {}
+
+message Tool {
+  string name = 1;
+  string description = 2;
+}
+
+message Manual {
+  string version = 1;
+  repeated Tool tools = 2;
+}
+
+message ToolCallRequest {
+  string tool = 1;
+  string args_json = 2;
+}
+
+message ToolCallResponse {
+  string result_json = 1;
+}
+
+service UTCPService {
+  rpc GetManual(Empty) returns (Manual);
+  rpc CallTool(ToolCallRequest) returns (ToolCallResponse);
+  rpc CallToolStream(ToolCallRequest) returns (stream ToolCallResponse);
+}

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: ruby-utcp
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- ruby-utcp contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14.0'
+description: Discover, search, and call UTCP 1.1 tools over pluggable native protocols.
+email:
+- maintainers@utcp.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- Makefile
+- README.md
+- examples/basic.rb
+- examples/cli.rb
+- examples/generated/__init__.py
+- examples/generated/utcp_pb2.py
+- examples/generated/utcp_pb2_grpc.py
+- examples/graphql.rb
+- examples/grpc.rb
+- examples/grpc_python.py
+- examples/http.rb
+- examples/mcp.rb
+- examples/servers/graphql_server.rb
+- examples/servers/grpc_server.py
+- examples/servers/grpc_server.rb
+- examples/servers/http_helpers.rb
+- examples/servers/http_server.rb
+- examples/servers/mcp_stdio_server.rb
+- examples/servers/requirements-grpc.txt
+- examples/servers/sse_server.rb
+- examples/servers/streamable_http_server.rb
+- examples/servers/tcp_server.rb
+- examples/servers/udp_server.rb
+- examples/servers/webrtc_server.rb
+- examples/servers/websocket_server.rb
+- examples/sse.rb
+- examples/streamable_http.rb
+- examples/tcp.rb
+- examples/text.rb
+- examples/udp.rb
+- examples/webrtc.rb
+- examples/websocket.rb
+- lib/ruby-utcp.rb
+- lib/utcp.rb
+- lib/utcp/client.rb
+- lib/utcp/config.rb
+- lib/utcp/errors.rb
+- lib/utcp/migration.rb
+- lib/utcp/models.rb
+- lib/utcp/openapi_converter.rb
+- lib/utcp/protocols/base.rb
+- lib/utcp/protocols/cli.rb
+- lib/utcp/protocols/file.rb
+- lib/utcp/protocols/graphql.rb
+- lib/utcp/protocols/grpc.rb
+- lib/utcp/protocols/http.rb
+- lib/utcp/protocols/http_stream_support.rb
+- lib/utcp/protocols/mcp.rb
+- lib/utcp/protocols/socket_support.rb
+- lib/utcp/protocols/sse.rb
+- lib/utcp/protocols/streamable_http.rb
+- lib/utcp/protocols/tcp.rb
+- lib/utcp/protocols/text.rb
+- lib/utcp/protocols/udp.rb
+- lib/utcp/protocols/webrtc.rb
+- lib/utcp/protocols/websocket.rb
+- lib/utcp/registry.rb
+- lib/utcp/repository.rb
+- lib/utcp/serializer.rb
+- lib/utcp/utils.rb
+- lib/utcp/variables.rb
+- lib/utcp/version.rb
+- proto/utcp.proto
+homepage: https://www.utcp.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.utcp.io
+  source_code_uri: https://github.com/universal-tool-calling-protocol/ruby-utcp
+  documentation_uri: https://www.utcp.io/implementation
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: A Ruby implementation of the Universal Tool Calling Protocol
+test_files: []