takagi 0.1.0 → 1.1.0

data/lib/takagi/client.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'forwardable'
+require_relative 'client_base'
+require_relative 'message/retransmission_manager'
+
+module Takagi
+  # Unified Takagi Client for communicating with Takagi servers over CoAP.
+  #
+  # Supports multiple protocols (UDP, TCP) with automatic protocol detection
+  # based on URI scheme or explicit protocol parameter.
+  #
+  # @example Block-based with protocol auto-detection (recommended)
+  #   Takagi::Client.new('coap://localhost:5683') do |client|
+  #     client.get('/temperature')
+  #   end
+  #
+  # @example Block-based with explicit protocol
+  #   Takagi::Client.new('localhost:5683', protocol: :tcp) do |client|
+  #     client.get('/temperature')
+  #   end
+  #
+  # @example Manual lifecycle management
+  #   client = Takagi::Client.new('coap://localhost:5683')
+  #   begin
+  #     client.get('/temperature')
+  #   ensure
+  #     client.close
+  #   end
+  class Client < ClientBase
+    extend Forwardable
+
+    # Delegate public methods to the implementation
+    def_delegators :@impl, :server_uri, :timeout, :callbacks, :closed?
+    def_delegators :@impl, :get, :post, :put, :delete, :on
+    def_delegators :@impl, :get_json, :post_json, :put_json, :close
+
+    # Creates a new client and optionally yields it to a block.
+    #
+    # @param server_uri [String] URL of the Takagi server (e.g., 'coap://localhost:5683', 'localhost:5683')
+    # @param timeout [Integer] Maximum time to wait for a response
+    # @param protocol [Symbol, nil] Protocol to use (:udp, :tcp, or nil for auto-detection from URI)
+    # @param use_retransmission [Boolean] Enable RFC 7252 §4.2 compliant retransmission for UDP (default: true)
+    # @yield [client] Optionally yields the client to a block and auto-closes afterward
+    # @return [Client, Object] Returns the client instance, or the block's return value if a block is given
+    #
+    # @example Protocol auto-detection from URI
+    #   client = Takagi::Client.new('coap://localhost:5683')      # Uses UDP
+    #   client = Takagi::Client.new('coap+tcp://localhost:5683')  # Uses TCP
+    #
+    # @example Explicit protocol specification
+    #   client = Takagi::Client.new('localhost:5683', protocol: :tcp)
+    #   client = Takagi::Client.new('localhost:5683', protocol: :udp)
+    #
+    # @example With block (auto-close)
+    #   Takagi::Client.new('coap://localhost:5683') do |client|
+    #     client.get('/resource')
+    #   end
+    def initialize(server_uri, timeout: 5, protocol: nil, use_retransmission: true)
+      # Detect protocol from URI if not explicitly specified
+      @protocol = protocol || detect_protocol(server_uri)
+
+      # Delegate to the appropriate client implementation
+      @impl = create_client_impl(server_uri, timeout, use_retransmission)
+
+      # If a block is given, yield and auto-close
+      return unless block_given?
+
+      begin
+        yield(self)
+      ensure
+        close
+      end
+    end
+
+    private
+
+    # Detects the protocol from the URI scheme using transport registry
+    # @param uri_string [String] The URI to parse
+    # @return [Symbol] :tcp or :udp
+    def detect_protocol(uri_string)
+      uri = URI(uri_string.start_with?('coap') ? uri_string : "coap://#{uri_string}")
+
+      # NEW: Use transport registry to find transport for scheme
+      transport = Takagi::Network::Registry.for_scheme(uri.scheme)
+
+      if transport
+        # Map transport class to symbol
+        case transport.scheme
+        when 'coap+tcp', 'coaps+tcp'
+          :tcp
+        else
+          :udp
+        end
+      else
+        :udp # Default to UDP if transport not found
+      end
+    rescue URI::InvalidURIError, Takagi::Network::Registry::TransportNotFoundError
+      :udp # Default to UDP if URI parsing fails or transport not found
+    end
+
+    # Creates the appropriate client implementation based on protocol
+    # @param server_uri [String] Server URI
+    # @param timeout [Integer] Request timeout
+    # @param use_retransmission [Boolean] Enable retransmission for UDP
+    # @return [UdpClient, TcpClient] The client implementation
+    def create_client_impl(server_uri, timeout, use_retransmission)
+      # Normalize URI to include scheme if not present
+      normalized_uri = normalize_uri(server_uri)
+
+      case @protocol
+      when :tcp
+        require_relative 'tcp_client'
+        TcpClient.new(normalized_uri, timeout: timeout)
+      when :udp
+        UdpClient.new(normalized_uri, timeout: timeout, use_retransmission: use_retransmission)
+      else
+        raise ArgumentError, "Unknown protocol: #{@protocol}. Use :udp or :tcp"
+      end
+    end
+
+    # Normalizes URI to include appropriate scheme
+    # @param uri_string [String] The URI string
+    # @return [String] Normalized URI with scheme
+    def normalize_uri(uri_string)
+      return uri_string if uri_string.start_with?('coap')
+
+      scheme = @protocol == :tcp ? 'coap+tcp' : 'coap'
+      "#{scheme}://#{uri_string}"
+    end
+  end
+
+  # UDP-specific client implementation (internal)
+  # Users should use Takagi::Client with protocol: :udp instead
+  class UdpClient < ClientBase
+    # Initializes the UDP client
+    # @param server_uri [String] URL of the Takagi server
+    # @param timeout [Integer] Maximum time to wait for a response
+    # @param use_retransmission [Boolean] Enable RFC 7252 §4.2 compliant retransmission (default: true)
+    def initialize(server_uri, timeout: 5, use_retransmission: true)
+      super(server_uri, timeout: timeout)
+      @use_retransmission = use_retransmission
+
+      return unless @use_retransmission
+
+      @retransmission_manager = Takagi::Message::RetransmissionManager.new
+      @retransmission_manager.start
+    end
+
+    protected
+
+    # Stops the retransmission manager thread
+    def cleanup_resources
+      @retransmission_manager&.stop
+      super
+    end
+
+    private
+
+    # Executes a request to the server using Takagi::Message::Request
+    # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+    # @param path [String] Resource path
+    # @param payload [String] (optional) Data for POST/PUT requests
+    # @param options [Hash] (optional) CoAP options { option_number => value }
+    # @param type [Integer, nil] (optional) CoAP message type
+    # @param callback [Proc] (optional) Callback function for processing the response
+    def request(method, path, payload = nil, options: {}, type: nil, &callback)
+      uri = URI.join(server_uri.to_s, path)
+      message = Takagi::Message::Request.new(
+        method: method,
+        uri: uri,
+        payload: payload,
+        type: type,
+        options: options
+      )
+
+      if @use_retransmission
+        request_with_retransmission(message, uri, &callback)
+      else
+        request_simple(message, uri, &callback)
+      end
+    end
+
+    # Simple request without retransmission (legacy mode)
+    def request_simple(message, uri, &callback)
+      socket = UDPSocket.new
+      socket.send(message.to_bytes, 0, uri.host, uri.port || 5683)
+
+      unless socket.wait_readable(@timeout)
+        puts 'TakagiClient Error: Request timeout'
+        return
+      end
+
+      response, = socket.recvfrom(1024)
+      deliver_raw_response(response, &callback)
+    rescue StandardError => e
+      puts "TakagiClient Error: #{e.message}"
+    ensure
+      socket&.close unless socket&.closed?
+    end
+
+    # RFC 7252 §4.2 compliant request with automatic retransmission
+    def request_with_retransmission(message, uri, &callback)
+      socket = UDPSocket.new
+      state = send_with_retransmission(message, socket, uri)
+      socket.close
+      handle_response_state(state, &callback)
+    rescue StandardError => e
+      puts "TakagiClient Error: #{e.message}"
+    end
+
+    def send_with_retransmission(message, socket, uri)
+      state = { response_received: false, response_data: nil, error: nil }
+
+      @retransmission_manager.send_confirmable(
+        message.message_id, message.to_bytes, socket, uri.host, uri.port || 5683
+      ) { |resp, err| update_state(state, resp, err) }
+
+      wait_for_response(message, socket, state)
+      state
+    end
+
+    def wait_for_response(message, socket, state)
+      start_time = Time.now
+      check_socket_for_response(message, socket, state) until state[:response_received] || (Time.now - start_time) > @timeout
+    end
+
+    def check_socket_for_response(message, socket, state)
+      return unless socket.wait_readable(0.1)
+
+      state[:response_data], = socket.recvfrom(1024)
+      @retransmission_manager.handle_response(message.message_id, state[:response_data])
+      state[:response_received] = true
+    rescue StandardError => e
+      update_state(state, nil, e.message)
+    end
+
+    def update_state(state, response_data, error)
+      state[:response_data] = response_data
+      state[:error] = error
+      state[:response_received] = true
+    end
+
+    def handle_response_state(state, &callback)
+      if state[:response_received] && !state[:error]
+        deliver_response(state[:response_data], &callback)
+      elsif state[:error]
+        puts "TakagiClient Error: #{state[:error]}"
+      else
+        puts 'TakagiClient Error: Request timeout'
+      end
+    end
+
+    def deliver_raw_response(response, &callback)
+      if callback
+        callback.call(response)
+      elsif @callbacks[:response]
+        @callbacks[:response].call(response)
+      else
+        puts response
+      end
+    end
+  end
+end

data/lib/takagi/client_base.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'json'
+
+module Takagi
+  # Base class for Takagi clients, providing common functionality
+  # for both UDP (CoAP) and TCP (CoAP over TCP) clients.
+  #
+  # This class defines the common interface and lifecycle management
+  # that all Takagi clients should follow.
+  class ClientBase
+    attr_reader :server_uri, :timeout, :callbacks
+
+    # Initializes the base client
+    # @param server_uri [String] URL of the Takagi server
+    # @param timeout [Integer] Maximum time to wait for a response
+    def initialize(server_uri, timeout: 5)
+      @server_uri = URI(server_uri)
+      @timeout = timeout
+      @callbacks = {}
+      @closed = false
+    end
+
+    # Registers a callback for a given event
+    # @param event [Symbol] Event name (e.g., :response)
+    # @param callback [Proc] Callback function to handle the event
+    def on(event, &callback)
+      @callbacks[event] = callback
+    end
+
+    # Sends a GET request
+    # @param path [String] Resource path
+    # @param options [Hash] CoAP options (e.g. { 17 => 50 } for Accept=application/json)
+    # @param type [Integer, nil] CoAP message type (CON/NON/ACK/RST). Defaults to CON.
+    # @param callback [Proc] (optional) Callback function for processing the response
+    def get(path, options: {}, type: nil, &block)
+      request(:get, path, nil, options: options, type: type, &block)
+    end
+
+    # Sends a POST request
+    # @param path [String] Resource path
+    # @param payload [String, Hash] Data to send (Hash is JSON-encoded automatically)
+    # @param options [Hash] CoAP options (e.g. { 12 => 50 } for Content-Format=application/json)
+    # @param type [Integer, nil] CoAP message type
+    # @param callback [Proc] (optional) Callback function for processing the response
+    def post(path, payload = nil, options: {}, type: nil, &block)
+      request(:post, path, payload, options: options, type: type, &block)
+    end
+
+    # Sends a PUT request
+    # @param path [String] Resource path
+    # @param payload [String, Hash] Data to send
+    # @param options [Hash] CoAP options
+    # @param type [Integer, nil] CoAP message type
+    # @param callback [Proc] (optional) Callback function for processing the response
+    def put(path, payload = nil, options: {}, type: nil, &block)
+      request(:put, path, payload, options: options, type: type, &block)
+    end
+
+    # Sends a DELETE request
+    # @param path [String] Resource path
+    # @param options [Hash] CoAP options
+    # @param type [Integer, nil] CoAP message type
+    # @param callback [Proc] (optional) Callback function for processing the response
+    def delete(path, options: {}, type: nil, &block)
+      request(:delete, path, nil, options: options, type: type, &block)
+    end
+
+    # Sends an OBSERVE request (RFC 7641). The Observe option is added automatically;
+    # additional CoAP options can be supplied via `options:`.
+    # @param path [String] Resource path
+    # @param options [Hash] CoAP options (Observe is injected automatically)
+    # @param callback [Proc] (optional) Callback function for processing notifications
+    def observe(path, options: {}, &block)
+      merged = { Takagi::CoAP::Registries::Option::OBSERVE => 0 }.merge(options)
+      request(:get, path, nil, options: merged, &block)
+    end
+
+    # Sends a POST request with JSON payload (convenience method)
+    # @param path [String] Resource path
+    # @param data [Hash, Array] Data to encode as JSON
+    # @param options [Hash] CoAP options
+    # @param callback [Proc] (optional) Callback function for processing the response
+    def post_json(path, data, options: {}, &block)
+      cf = Takagi::CoAP::Registries::ContentFormat::JSON
+      merged = { Takagi::CoAP::Registries::Option::CONTENT_FORMAT => cf }.merge(options)
+      request(:post, path, JSON.generate(data), options: merged, &block)
+    end
+
+    # Sends a PUT request with JSON payload (convenience method)
+    def put_json(path, data, options: {}, &block)
+      cf = Takagi::CoAP::Registries::ContentFormat::JSON
+      merged = { Takagi::CoAP::Registries::Option::CONTENT_FORMAT => cf }.merge(options)
+      request(:put, path, JSON.generate(data), options: merged, &block)
+    end
+
+    # Sends a GET request and automatically parses JSON response (convenience method)
+    def get_json(path, options: {}, &block)
+      cf = Takagi::CoAP::Registries::ContentFormat::JSON
+      merged = { Takagi::CoAP::Registries::Option::ACCEPT => cf }.merge(options)
+      if block_given?
+        get(path, options: merged) do |response|
+          data = response.is_a?(String) ? parse_json_response(response) : response.json
+          block.call(data)
+        end
+      else
+        result = nil
+        get(path, options: merged) { |response| result = response.is_a?(String) ? parse_json_response(response) : response.json }
+        result
+      end
+    end
+
+    # Closes the client and releases any resources.
+    # This should be called when the client is no longer needed to prevent
+    # resource leaks in long-running processes.
+    #
+    # Subclasses should override this method to perform specific cleanup
+    # and then call super.
+    def close
+      return if @closed
+
+      cleanup_resources
+      @closed = true
+    end
+
+    # Check if the client has been closed
+    # @return [Boolean] true if the client is closed
+    def closed?
+      @closed
+    end
+
+    # Creates a new client and yields it to the block, ensuring it's closed afterward.
+    # This is the recommended way to use clients to prevent resource leaks.
+    #
+    # @param server_uri [String] URL of the Takagi server
+    # @param timeout [Integer] Maximum time to wait for a response
+    # @param options [Hash] Additional options passed to the subclass constructor
+    # @yield [client] Gives the client to the block
+    # @return [Object] The return value of the block
+    #
+    # @example
+    #   Takagi::Client.open('coap://localhost:5683') do |client|
+    #     client.get('/temperature')
+    #   end
+    def self.open(server_uri, timeout: 5, **options, &block)
+      client = new(server_uri, timeout: timeout, **options)
+      block.call(client)
+    ensure
+      client&.close
+    end
+
+    protected
+
+    # Subclasses must implement this method to perform the actual request
+    # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+    # @param path [String] Resource path
+    # @param payload [String] (optional) Data for POST/PUT requests
+    # @param options [Hash] (optional) CoAP options { option_number => value }
+    # @param type [Integer, nil] (optional) CoAP message type
+    # @param callback [Proc] (optional) Callback function for processing the response
+    def request(_method, _path, _payload = nil, options: {}, type: nil, &_callback)
+      raise NotImplementedError, "#{self.class} must implement #request"
+    end
+
+    # Subclasses can override this to perform specific cleanup
+    # Called by #close before marking the client as closed
+    def cleanup_resources
+      # Default: no-op
+    end
+
+    # Delivers a response using the callback or registered callback
+    # Wraps raw response data in a Response object for convenience
+    # @param response_data [String] The response data to deliver
+    # @param callback [Proc] Optional callback for this specific request
+    def deliver_response(response_data, &callback)
+      # Wrap response in Response object for better DX
+      require_relative 'client/response'
+      response = Client::Response.new(response_data)
+
+      return callback.call(response) if callback
+      return @callbacks[:response].call(response) if @callbacks[:response]
+
+      # Default: print response details
+      if response.success?
+        puts "[#{response.code_name}] #{response.payload}"
+      else
+        puts "[ERROR #{response.code_name}] #{response.payload}"
+      end
+    end
+
+    # Helper to parse JSON response from raw data
+    # @param response_data [String] Raw response data
+    # @return [Hash, Array, nil] Parsed JSON or nil
+    def parse_json_response(response_data)
+      inbound = Takagi::Message::Inbound.new(response_data)
+      return nil unless inbound.payload
+
+      JSON.parse(inbound.payload)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/takagi/coap/code_helpers.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Takagi
+  module CoAP
+    # Utility methods for working with CoAP codes.
+    #
+    # Provides conversion between different code representations and
+    # lookups across all registries.
+    module CodeHelpers
+      # Convert a code to its human-readable string representation
+      #
+      # @param code [Integer, String, Symbol] Code to convert
+      # @return [String] Human-readable code string
+      #
+      # @example
+      #   CodeHelpers.to_string(69)      # => "2.05 Content"
+      #   CodeHelpers.to_string(:get)    # => "GET"
+      #   CodeHelpers.to_string("2.05")  # => "2.05 Content"
+      def self.to_string(code)
+        case code
+        when Integer
+          # Try method registry first
+          if code < 32
+            Registries::Method.name_for(code) || numeric_to_string(code)
+          # Try signaling registry for 7.xx codes
+          elsif code >= 224
+            Registries::Signaling.name_for(code) || numeric_to_string(code)
+          # Try response registry
+          elsif code >= 64
+            Registries::Response.name_for(code) || numeric_to_string(code)
+          else
+            numeric_to_string(code)
+          end
+        when Symbol
+          # Try method registry
+          Registries::Method.value_for(code)&.then { |v| Registries::Method.name_for(v) } ||
+            # Try response registry
+            Registries::Response.value_for(code)&.then { |v| Registries::Response.name_for(v) } ||
+            code.to_s
+        when String
+          # If already in dotted format, try to lookup
+          if code =~ /^(\d)\.(\d{2})$/
+            val = string_to_numeric(code)
+            Registries::Response.name_for(val) || code
+          else
+            code
+          end
+        else
+          code.to_s
+        end
+      end
+
+      # Convert a code to its numeric representation
+      #
+      # @param code [Integer, String, Symbol] Code to convert
+      # @return [Integer] Numeric code
+      #
+      # @example
+      #   CodeHelpers.to_numeric(:get)       # => 1
+      #   CodeHelpers.to_numeric("2.05")     # => 69
+      #   CodeHelpers.to_numeric("2.05 Content")   # => 69
+      #   CodeHelpers.to_numeric(:content)   # => 69
+      def self.to_numeric(code)
+        case code
+        when Integer
+          code
+        when Symbol
+          Registries::Method.value_for(code) || Registries::Response.value_for(code) || Registries::Signaling.value_for(code) || 0
+        when String
+          # Handle "2.05" or "2.05 Content" formats
+          if code =~ /^(\d)\.(\d{2})/
+            string_to_numeric("#{::Regexp.last_match(1)}.#{::Regexp.last_match(2)}")
+          else
+            Registries::Method.value_for(code.downcase.to_sym) ||
+              Registries::Response.value_for(code.downcase.to_sym) ||
+              0
+          end
+        else
+          0
+        end
+      end
+
+      # Convert numeric code to dotted string format (e.g., 69 => "2.05")
+      #
+      # @param code [Integer] Numeric code
+      # @return [String] Dotted format string
+      def self.numeric_to_string(code)
+        class_num = code / 32
+        detail_num = code % 32
+        "#{class_num}.#{detail_num.to_s.rjust(2, '0')}"
+      end
+
+      # Convert dotted string to numeric code (e.g., "2.05" => 69)
+      #
+      # @param code_string [String] Dotted format string
+      # @return [Integer] Numeric code
+      def self.string_to_numeric(code_string)
+        return 0 unless code_string =~ /^(\d)\.(\d{2})$/
+
+        class_num = ::Regexp.last_match(1).to_i
+        detail_num = ::Regexp.last_match(2).to_i
+        (class_num * 32) + detail_num
+      end
+
+      # Check if a code represents success
+      #
+      # @param code [Integer, String, Symbol] Code to check
+      # @return [Boolean] true if success code (2.xx)
+      def self.success?(code)
+        numeric = to_numeric(code)
+        Registries::Response.success?(numeric)
+      end
+
+      # Check if a code represents an error
+      #
+      # @param code [Integer, String, Symbol] Code to check
+      # @return [Boolean] true if error code (4.xx or 5.xx)
+      def self.error?(code)
+        numeric = to_numeric(code)
+        Registries::Response.error?(numeric)
+      end
+
+      # Check if a code represents a client error
+      #
+      # @param code [Integer, String, Symbol] Code to check
+      # @return [Boolean] true if client error (4.xx)
+      def self.client_error?(code)
+        numeric = to_numeric(code)
+        Registries::Response.client_error?(numeric)
+      end
+
+      # Check if a code represents a server error
+      #
+      # @param code [Integer, String, Symbol] Code to check
+      # @return [Boolean] true if server error (5.xx)
+      def self.server_error?(code)
+        numeric = to_numeric(code)
+        Registries::Response.server_error?(numeric)
+      end
+
+      # Lookup code in all registries
+      #
+      # @param code [Integer, String, Symbol] Code to lookup
+      # @return [Hash, nil] Registry information
+      def self.lookup(code)
+        numeric = to_numeric(code)
+        return nil if numeric.zero?
+
+        {
+          value: numeric,
+          string: numeric_to_string(numeric),
+          name: to_string(numeric),
+          type: code_type(numeric),
+          rfc: find_rfc(numeric)
+        }
+      end
+
+      # Get the type of code (method, response, or unknown)
+      #
+      # @param code [Integer] Numeric code
+      # @return [Symbol] :method, :response, or :unknown
+      def self.code_type(code)
+        if code < 32
+          :method
+        elsif code.between?(64, 191)
+          :response
+        elsif code.between?(224, 255)
+          :signaling
+        else
+          :unknown
+        end
+      end
+
+      # Find RFC reference for a code
+      #
+      # @param code [Integer] Numeric code
+      # @return [String, nil] RFC reference
+      def self.find_rfc(code)
+        Registries::Method.rfc_for(code) || Registries::Response.rfc_for(code) || Registries::Signaling.rfc_for(code)
+      end
+
+      # Get all registered codes across all registries
+      #
+      # @return [Hash] Map of value => name for all codes
+      def self.all
+        Registries::Method.all.merge(Registries::Response.all)
+      end
+    end
+  end
+end