takagi 0.1.0 → 1.1.0

data/lib/takagi/helpers.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative 'response_builder'
+
+module Takagi
+  # Helper methods for route handlers to improve DX
+  #
+  # Dynamically generates response helper methods from CoAP::Registries::Response registry:
+  # - Success methods (2.xx): created(data = {}), changed(data = {}), etc.
+  # - Error methods (4.xx, 5.xx): bad_request(message = ...), not_found(message = ...), etc.
+  #
+  # @example Success response
+  #   created({ id: 123, name: 'Resource' })
+  #
+  # @example Error response
+  #   bad_request('Invalid input')
+  #   unauthorized({ error: 'Token expired' })
+  module Helpers
+    # Respond with content-format negotiation handled automatically.
+    #
+    # @param payload [Object] The payload to send
+    # @param code [Integer, String, Symbol] CoAP response code (defaults to 2.05 Content)
+    # @param formats [Array<Integer, Symbol, String>, nil] Allowed content-formats (defaults to router default)
+    # @param force [Integer, Symbol, String, nil] Force a specific content-format code
+    # @param options [Hash] Additional CoAP options
+    def respond(payload = {}, code: CoAP::Registries::Response::CONTENT, formats: nil, force: nil, options: {})
+      formats ||= core_content_formats if respond_to?(:core_content_formats, true)
+      ResponseBuilder.respond(request, payload, code: code, formats: formats, force: force, options: options, logger: Takagi.logger)
+    end
+
+    # Returns a JSON response with 2.05 Content status and sets Content-Format to application/json
+    # Similar to Sinatra's json helper, automatically sets the Content-Format option
+    # @param data [Hash] The data to return as JSON
+    # @return [Takagi::Message::Outbound] The response with JSON content-format
+    def json(data = {})
+      respond(data, code: CoAP::Registries::Response.value_for(:content), formats: [Takagi::Router::DEFAULT_CONTENT_FORMAT])
+    end
+
+    # Validates that required parameters are present
+    # @param required_params [Array<Symbol>] List of required parameter names
+    # @raise [StandardError] If any required parameter is missing
+    def validate_params(*required_params)
+      missing = required_params.select { |param| params[param].nil? }
+      return if missing.empty?
+
+      raise ArgumentError, "Missing required parameters: #{missing.join(', ')}"
+    end
+
+    # Halts execution and returns the given response
+    # Useful for early returns
+    # @param response [Takagi::Message::Outbound, Hash] The response to return
+    def halt(response)
+      throw :halt, response
+    end
+
+    # Dynamically generate helper methods from CoAP::Registries::Response registry
+    # Iterate through all registered response codes
+    CoAP::Registries::Response.each_value do |code_number|
+      code_string = CoAP::Registries::Response.name_for(code_number)
+      metadata = CoAP::Registries::Response.metadata_for(code_number)
+      next unless metadata
+
+      symbol = metadata[:symbol]
+      next unless symbol
+
+      method_name = symbol.to_s
+
+      # Determine if this is a success (2.xx) or error (4.xx, 5.xx) response
+      if CoAP::Registries::Response.success?(code_number)
+        # Success methods take optional data hash
+        define_method(method_name) do |data = {}, options = {}|
+          respond(data, code: code_string, options: options)
+        end
+      else
+        # Error methods take optional message (string or hash)
+        default_message = code_string.split(' ', 2)[1] # Extract "Bad Request" from "4.00 Bad Request"
+
+        define_method(method_name) do |message = default_message|
+          data = message.is_a?(Hash) ? message : { error: message }
+          respond(data, code: code_string)
+        end
+      end
+    end
+
+    # Alias for internal_server_error (more concise)
+    alias server_error internal_server_error
+  end
+end

data/lib/takagi/hooks.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Takagi
+  # Lightweight hook dispatcher used by the plugin system to observe internal events.
+  #
+  # Hooks are intentionally simple: subscribe with a callable, emit with a hash payload.
+  # Errors in subscribers are caught and logged to avoid cascading failures.
+  module Hooks
+    @subscribers = Hash.new { |h, k| h[k] = [] } # Fallback when EventBus unavailable
+    @mutex = Mutex.new
+
+    class << self
+      # Register a handler for a given event symbol.
+      #
+      # @param event [Symbol] event name
+      # @param handler [#call] callable that receives payload hash
+      # @yield [Hash] payload if block given instead of handler
+      # @return [#call] the handler reference (useful for unsubscribe)
+      def subscribe(event, handler = nil, &block)
+        callback = handler || block
+        raise ArgumentError, 'handler or block required' unless callback
+
+        if event_bus_ready?
+          Takagi::EventBus.consumer(hook_address(event), local_only: true) do |message|
+            callback.call(message.body)
+          end
+        else
+          @mutex.synchronize { @subscribers[event] << callback }
+          callback
+        end
+      end
+
+      # Remove a previously registered handler.
+      #
+      # @param event [Symbol]
+      # @param handler [#call]
+      def unsubscribe(event, handler)
+        if event_bus_ready?
+          Takagi::EventBus.unregister(handler)
+        else
+          @mutex.synchronize { @subscribers[event].delete(handler) }
+        end
+      end
+
+      # Emit an event with a payload hash to all subscribers.
+      #
+      # @param event [Symbol]
+      # @param payload [Hash]
+      def emit(event, payload = {})
+        if event_bus_ready?
+          Takagi::EventBus.publish(hook_address(event), payload, freeze_body: false, scope: Takagi::EventBus::Scope::LOCAL)
+        else
+          handlers = @mutex.synchronize { @subscribers[event].dup }
+          return if handlers.empty?
+
+          handlers.each do |handler|
+            handler.call(payload)
+          rescue StandardError => e
+            begin
+              Takagi.logger.warn("Hook #{event} handler error: #{e.message}")
+            rescue StandardError
+              # Logger may not be initialized yet; swallow errors silently.
+            end
+          end
+        end
+      end
+
+      def hook_address(event)
+        "hooks.#{event}"
+      end
+
+      def event_bus_ready?
+        return false unless defined?(Takagi::EventBus)
+
+        executor = Takagi::EventBus.instance_variable_get(:@executor) rescue nil
+        return false if executor && executor.respond_to?(:running?) && !executor.running?
+
+        true
+      end
+    end
+  end
+end

data/lib/takagi/initializer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Takagi
+  # Let's do some initialization
+  class Initializer
+    # Runs the initialization logic (e.g., loading configurations, setting up databases)
+    def self.run!
+      load_initializers
+    end
+
+    def self.load_initializers
+      initializer_glob = File.expand_path('../../config/initializers/**/*.rb', __dir__)
+      Dir.glob(initializer_glob).each do |initializer|
+        require initializer
+      end
+    end
+  end
+end

data/lib/takagi/logger.rb

@@ -4,22 +4,31 @@ require 'logger'
 
 module Takagi
   class Logger
-    @logger = ::Logger.new($stdout)
-    @logger.level = ::Logger::INFO
+    # Default is INFO (production-friendly). Set the
+    # `TAKAGI_LOG_LEVEL` env var or pass a takagi.yml `logger:` block
+    # to see the verbose DEBUG noise.
+    def initialize(log_output: $stdout, level: ::Logger::INFO)
+      @logger = ::Logger.new(log_output)
+      @logger.level = level
+    end
 
-    def self.set_level(level)
+    def set_level(level)
       @logger.level = level
     end
 
-    def self.info(message)
+    def info(message)
       @logger.info(message)
     end
 
-    def self.debug(message)
+    def warn(message)
+      @logger.warn(message)
+    end
+
+    def debug(message)
       @logger.debug(message)
     end
 
-    def self.error(message)
+    def error(message)
       @logger.error(message)
     end
   end

data/lib/takagi/message/base.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Takagi
+  module Message
+    # Base class for message
+    class Base
+      attr_reader :version, :type, :token, :message_id, :payload, :options, :code
+
+      def initialize(data = nil, transport: :udp)
+        @transport = transport
+        if data.is_a?(String) || data.is_a?(IO)
+          case transport
+          when :tcp
+            parse_tcp(data)
+          else
+            parse(data)
+          end
+        end
+        @data = data
+        @logger = Takagi.logger
+      end
+
+      # Convert CoAP code number to method name using registry
+      # @param code [Integer] CoAP code number
+      # @return [String] Method name (e.g., 'GET', 'OBSERVE')
+      def coap_code_to_method(code)
+        # Check if it's an OBSERVE request (GET with Observe option)
+        if code == CoAP::Registries::Method::GET && @options && @options[CoAP::Registries::Option::OBSERVE]
+          'OBSERVE'
+        else
+          # Use CoAP registry to convert code to string
+          CoAP::CodeHelpers.to_string(code)
+        end
+      end
+
+      # Convert method name to CoAP code number using registry
+      # @param method [String, Symbol] Method name (e.g., 'GET', :post)
+      # @return [Integer] CoAP code number
+      def coap_method_to_code(method)
+        CoAP::CodeHelpers.to_numeric(method)
+      end
+
+      private
+
+      # Parse TCP CoAP message (RFC 8323 §3.2)
+      # Format: Len+TKL (1 byte) | Code (1 byte) | Token (TKL bytes) | Options | Payload
+      def parse_tcp(data)
+        bytes = data.bytes
+        first_byte = bytes[0]
+
+        # First byte contains length nibble (upper 4 bits) and TKL (lower 4 bits)
+        # But the length nibble is only used for framing, not parsing the message itself
+        token_length = first_byte & 0b1111
+
+        @code = bytes[1]
+        @token = token_length.positive? ? bytes[2, token_length].pack('C*') : ''.b
+
+        # Parse options starting after code + token
+        @options = parse_options(bytes[(2 + token_length)..])
+        @payload = extract_payload(data)
+
+        # TCP CoAP doesn't have version, type, or message_id
+        @version = nil
+        @type = nil
+        @message_id = nil
+      end
+
+      def parse(data)
+        bytes = data.bytes
+        @version = (bytes[0] >> 6) & 0b11
+        @type    = (bytes[0] >> 4) & 0b11
+        token_length = bytes[0] & 0b1111
+        @code = bytes[1]
+        @message_id = bytes[2..3].pack('C*').unpack1('n')
+        @token   = token_length.positive? ? bytes[4, token_length].pack('C*') : ''.b
+        @options = parse_options(bytes[(4 + token_length)..])
+        @payload = extract_payload(data)
+      end
+
+      def parse_options(bytes)
+        options = {}
+        position = 0
+        last_option_number = 0
+
+        while position < bytes.length && bytes[position] != 0xFF
+          byte = bytes[position]
+          position += 1
+
+          delta_raw = (byte >> 4) & 0x0F
+          length_raw = byte & 0x0F
+
+          delta, position = decode_extended_value(bytes, position, delta_raw)
+          length, position = decode_extended_value(bytes, position, length_raw)
+
+          option_number = last_option_number + delta
+          value = bytes[position, length].pack('C*')
+          position += length
+
+          store_option(options, option_number, value)
+
+          last_option_number = option_number
+        end
+
+        Takagi.logger.debug "Parsed CoAP options: #{options.inspect}"
+        options
+      end
+
+      def extract_payload(data)
+        Takagi.logger.debug "Extracting payload: #{data.inspect}"
+        payload_start = data.index("\xFF".b)
+        return nil unless payload_start
+
+        payload = data[(payload_start + 1)..].dup.force_encoding('ASCII-8BIT')
+        utf8 = payload.dup.force_encoding('UTF-8')
+        utf8.valid_encoding? ? utf8 : payload
+      end
+
+      def decode_extended_value(bytes, position, raw_value)
+        case raw_value
+        when 13
+          [bytes[position] + 13, position + 1]
+        when 14
+          extended = bytes[position, 2].pack('C*').unpack1('n') + 269
+          [extended, position + 2]
+        else
+          [raw_value, position]
+        end
+      end
+
+      def store_option(options, option_number, value)
+        formatted = coerce_option_value(value)
+
+        # Uri-Path (11) and Uri-Query (15) are always stored as arrays
+        case option_number
+        when CoAP::Registries::Option::URI_PATH, CoAP::Registries::Option::URI_QUERY
+          options[option_number] ||= []
+          options[option_number] << formatted
+        else
+          options[option_number] = if options.key?(option_number)
+                                     Array(options[option_number]) << formatted
+                                   else
+                                     formatted
+                                   end
+        end
+      end
+
+      def coerce_option_value(value)
+        ascii = value.dup.force_encoding('ASCII-8BIT')
+        return ascii.force_encoding('UTF-8') if ascii.valid_encoding?
+
+        ascii
+      end
+    end
+  end
+end

data/lib/takagi/message/deduplication_cache.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Takagi
+  module Message
+    # Implements message deduplication as per RFC 7252 Section 4.4
+    #
+    # The server MUST detect duplicates by matching both Message ID and source endpoint.
+    # When a duplicate CON message is received, the server MUST resend the cached response.
+    #
+    # Cache entries expire after EXCHANGE_LIFETIME (247 seconds per RFC 7252 §4.8.2)
+    class DeduplicationCache
+      # RFC 7252 §4.8.2: EXCHANGE_LIFETIME = 247 seconds
+      EXCHANGE_LIFETIME = 247
+
+      # Entry contains the cached response and metadata
+      CacheEntry = Struct.new(:response_data, :timestamp, :source_key) do
+        def expired?(current_time)
+          current_time - timestamp > EXCHANGE_LIFETIME
+        end
+      end
+
+      def initialize
+        @cache = {}
+        @mutex = Mutex.new
+      end
+
+      # Check if message is a duplicate and return cached response if available
+      # @param message_id [Integer] The CoAP Message ID
+      # @param source_endpoint [String] Source IP:Port identifier
+      # @return [String, nil] Cached response data or nil if not a duplicate
+      def check_duplicate(message_id, source_endpoint)
+        @mutex.synchronize do
+          cleanup_expired_entries
+          key = cache_key(message_id, source_endpoint)
+          entry = @cache[key]
+          entry&.response_data
+        end
+      end
+
+      # Store a response for future duplicate detection
+      # @param message_id [Integer] The CoAP Message ID
+      # @param source_endpoint [String] Source IP:Port identifier
+      # @param response_data [String] The serialized response to cache
+      def store_response(message_id, source_endpoint, response_data)
+        @mutex.synchronize do
+          key = cache_key(message_id, source_endpoint)
+          @cache[key] = CacheEntry.new(
+            response_data,
+            Time.now.to_f,
+            source_endpoint
+          )
+        end
+      end
+
+      # Clear all cache entries (useful for testing)
+      def clear
+        @mutex.synchronize { @cache.clear }
+      end
+
+      # Get cache statistics
+      def stats
+        @mutex.synchronize do
+          {
+            size: @cache.size,
+            entries: @cache.keys
+          }
+        end
+      end
+
+      private
+
+      def cache_key(message_id, source_endpoint)
+        "#{source_endpoint}:#{message_id}"
+      end
+
+      # Remove expired entries to prevent unbounded memory growth
+      # RFC 7252 §4.8.2: entries older than EXCHANGE_LIFETIME should be discarded
+      def cleanup_expired_entries
+        current_time = Time.now.to_f
+        @cache.delete_if { |_key, entry| entry.expired?(current_time) }
+      end
+    end
+  end
+end

data/lib/takagi/message/inbound.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Takagi
+  module Message
+    # Class for inbound message that is coming to server
+    class Inbound < Base
+      attr_reader :method, :uri, :response_code
+
+      def initialize(data, transport: :udp)
+        super(data, transport: transport)
+        @method = coap_code_to_method(@code)
+        @response_code = coap_code_to_method(@code) if @code >= CoAP::Registries::Response::CREATED # Response
+        @uri = parse_coap_uri
+        @logger.debug "CoAP Options: #{@options.inspect}"
+        @logger.debug "Parsed CoAP URI: #{@uri}"
+      end
+
+      def to_response(code, payload, options: {})
+        # For TCP transport, type is not used (RFC 8323)
+        response_type = if @transport == :tcp
+                          0  # No type field in TCP CoAP
+                        else
+                          case @type
+                          when CoAP::Registries::MessageType::CON then CoAP::Registries::MessageType::ACK  # CON → ACK
+                          when CoAP::Registries::MessageType::NON then CoAP::Registries::MessageType::NON  # NON → NON
+                          else CoAP::Registries::MessageType::RST # fallback → RST
+                          end
+                        end
+
+        Outbound.new(
+          code: code,
+          payload: payload,
+          token: @token,
+          message_id: @message_id,
+          type: response_type,
+          options: options,
+          transport: @transport
+        )
+      end
+
+      def parse_coap_uri
+        options = @options || {}
+        @logger.debug "Options received by parse_coap_uri: #{options.inspect}"
+
+        host = options[CoAP::Registries::Option::URI_HOST] || 'localhost'
+        path_segments = Array(options[CoAP::Registries::Option::URI_PATH]).flatten
+        query_segments = Array(options[CoAP::Registries::Option::URI_QUERY]).flatten
+
+        path = path_segments.empty? ? '/' : "/#{path_segments.join('/')}"
+        query = query_segments.empty? ? nil : query_segments.join('&')
+        URI::Generic.build(scheme: 'coap', host: host, path: path, query: query)
+      end
+
+      # DX Helpers for request inspection
+
+      # Get CoAP option by number
+      # @param option_number [Integer] The CoAP option number
+      # @return [Object, nil] The option value
+      def option(option_number)
+        @options[option_number]
+      end
+
+      # Check if request has a specific CoAP option
+      # @param option_number [Integer] The CoAP option number
+      # @return [Boolean]
+      def option?(option_number)
+        @options.key?(option_number)
+      end
+
+      # Get Accept option
+      # @return [Integer, nil] The Accept content format
+      def accept
+        option(CoAP::Registries::Option::ACCEPT)
+      end
+
+      # Check if request accepts a specific content format
+      # @param format [String, Integer] Format name or number
+      # @return [Boolean]
+      def accept?(format)
+        return false unless accept
+
+        format_number = format.is_a?(Integer) ? format : content_format_to_number(format)
+        accept == format_number
+      end
+
+      # Get Content-Format option
+      # @return [Integer, nil] The Content-Format
+      def content_format
+        option(CoAP::Registries::Option::CONTENT_FORMAT)
+      end
+
+      # Get query parameters as a hash
+      # @return [Hash<String, String>]
+      def query_params
+        return {} unless @uri.query
+
+        @uri.query.split('&').each_with_object({}) do |param, hash|
+          key, value = param.split('=', 2)
+          hash[key] = value || ''
+        end
+      end
+
+      # Check if request is a GET
+      # @return [Boolean]
+      def get?
+        method == 'GET'
+      end
+
+      # Check if request is a POST
+      # @return [Boolean]
+      def post?
+        method == 'POST'
+      end
+
+      # Check if request is a PUT
+      # @return [Boolean]
+      def put?
+        method == 'PUT'
+      end
+
+      # Check if request is a DELETE
+      # @return [Boolean]
+      def delete?
+        method == 'DELETE'
+      end
+
+      # Check if request is an OBSERVE
+      # @return [Boolean]
+      def observe?
+        method == 'OBSERVE'
+      end
+
+      private
+
+      # Convert content format name to number using CoAP registry
+      def content_format_to_number(format)
+        formats = {
+          'text/plain' => CoAP::Registries::ContentFormat::TEXT_PLAIN,
+          'application/link-format' => CoAP::Registries::ContentFormat::LINK_FORMAT,
+          'application/json' => CoAP::Registries::ContentFormat::JSON,
+          'application/cbor' => CoAP::Registries::ContentFormat::CBOR
+        }
+        formats[format.to_s.downcase] || CoAP::Registries::ContentFormat::JSON
+      end
+    end
+  end
+end