takagi 0.1.0 → 1.1.0

data/lib/takagi/router/route_matcher.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Takagi
+  class Router
+    # Handles dynamic route matching with parameter extraction.
+    #
+    # Extracted from Router to follow Single Responsibility Principle.
+    # Manages matching URL patterns with dynamic segments (e.g., /users/:id)
+    # and extracting parameters from matched routes.
+    class RouteMatcher
+      # @param logger [Logger] Logger instance for debugging
+      def initialize(logger)
+        @logger = logger
+      end
+
+      # Matches dynamic routes that contain parameters (e.g., `/users/:id`)
+      #
+      # @param routes [Hash] Map of route keys to RouteEntry objects
+      # @param method [String] HTTP method
+      # @param path [String] Request path
+      # @return [Array(RouteEntry, Hash), Array(nil, Hash)] Matched route entry and parameters, or [nil, {}]
+      def match(routes, method, path)
+        matched_route = locate_dynamic_route(routes, method, path)
+        return matched_route if matched_route
+
+        @logger.debug 'No route matched!'
+        [nil, {}]
+      end
+
+      private
+
+      # Locates a dynamic route by iterating through all routes
+      #
+      # @param routes [Hash] All registered routes
+      # @param method [String] HTTP method to match
+      # @param path [String] Request path to match
+      # @return [Array(RouteEntry, Hash), nil] Matched entry and params, or nil
+      def locate_dynamic_route(routes, method, path)
+        routes.each_value do |entry|
+          route_method = entry.method
+          route_path = entry.path
+          next unless route_method == method
+
+          params = extract_dynamic_params(route_path, path)
+          next unless params
+
+          @logger.debug "Match found! Params: #{params.inspect}"
+          return [entry, params]
+        end
+        nil
+      end
+
+      # Extracts dynamic parameters from a route pattern
+      #
+      # Compares route pattern (e.g., /users/:id) with actual path (e.g., /users/123)
+      # and extracts parameter values.
+      #
+      # @param route_path [String] Route pattern with :param segments
+      # @param path [String] Actual request path
+      # @return [Hash, nil] Extracted parameters or nil if no match
+      def extract_dynamic_params(route_path, path)
+        route_parts = route_path.split('/')
+        path_parts = path.split('/')
+        return unless route_parts.length == path_parts.length
+
+        params = {}
+        matched = true
+
+        route_parts.each_with_index do |part, index|
+          if part.start_with?(':')
+            params[part[1..].to_sym] = path_parts[index]
+          elsif part != path_parts[index]
+            @logger.debug "No Match found! Params: #{params.inspect} to #{path}"
+            matched = false
+            break
+          end
+        end
+
+        matched ? params : nil
+      end
+    end
+  end
+end

data/lib/takagi/router.rb

@@ -1,47 +1,306 @@
 # frozen_string_literal: true
 
+require 'forwardable'
+require_relative 'core/attribute_set'
+require_relative 'helpers'
+require_relative 'router/route_matcher'
+require_relative 'router/metadata_extractor'
+require_relative 'hooks'
+
 module Takagi
   class Router
-    @@routes = {}
+    DEFAULT_CONTENT_FORMAT = Takagi::CoAP::Registries::ContentFormat::JSON
+
+    class << self
+      # Global singleton instance for backward compatibility with Takagi::Base
+      # New code should create Router instances directly
+      #
+      # @return [Router] The global router instance
+      def instance
+        @instance ||= new
+      end
+
+      # Reset the global instance (primarily for testing)
+      #
+      # @return [void]
+      def reset!
+        @instance = nil
+        # Ensure Takagi::Base fetches a fresh router after reset
+        Takagi::Base.instance_variable_set(:@router, nil) if defined?(Takagi::Base)
+      end
+    end
+
+    # Represents a registered route with its handler and CoRE Link Format metadata
+    class RouteEntry
+      attr_reader :method, :path, :block, :receiver, :attribute_set
+
+      def initialize(method:, path:, block:, metadata: {}, receiver: nil)
+        @method = method
+        @path = path
+        @block = block
+        @receiver = receiver
+        @attribute_set = Core::AttributeSet.new(metadata)
+      end
+
+      # Returns the underlying metadata hash for backward compatibility
+      def metadata
+        @attribute_set.metadata
+      end
+
+      # Configure CoRE Link Format attributes using DSL block
+      #
+      # @example
+      #   entry.configure_attributes do
+      #     rt 'sensor'
+      #     obs true
+      #     ct 'application/json'
+      #   end
+      def configure_attributes(&block)
+        @attribute_set.core(&block)
+        @attribute_set.apply!
+      end
+
+      # Support for dup operation (used in discovery)
+      def initialize_copy(original)
+        super
+        @attribute_set = Core::AttributeSet.new(original.metadata.dup)
+      end
+    end
+
+    # Provides the execution context for route handlers, exposing helper
+    # methods for configuring CoRE Link Format attributes via a small DSL.
+    class RouteContext
+      extend Forwardable
+      include Takagi::Helpers
+
+      attr_reader :request, :params
+
+      # Delegate CoRE attribute methods to @core_attributes
+      def_delegators :@core_attributes, :core, :metadata, :attribute
+      def_delegators :@core_attributes, :ct, :sz, :title, :obs, :rt, :interface
+
+      # Aliases for common methods
+      alias content_format ct
+      alias observable obs
+      alias if_ interface
+
+      def initialize(entry, request, params, receiver)
+        @entry = entry
+        @request = request
+        @params = params
+        @receiver = receiver
+        # Create a fresh AttributeSet for this request to avoid cross-request state sharing
+        # Initialize it with a copy of the entry's current metadata
+        @core_attributes = Core::AttributeSet.new(@entry.metadata.dup)
+      end
+
+      def run(block)
+        return unless block
+
+        args = case block.arity
+               when 0 then []
+               when 1 then [request]
+               else
+                 [request, params]
+               end
+        args = [request, params] if block.arity.negative?
+
+        # Support halt for early returns
+        result = catch(:halt) do
+          instance_exec(*args, &block)
+        end
+
+        result
+      ensure
+        @core_attributes.apply!
+      end
+
+      private
+
+      # Returns content-format(s) declared for this route (CoRE `ct` metadata).
+      # Used by response helpers to align runtime negotiation with discovery data.
+      def core_content_formats
+        formats = @entry&.metadata&.[](:ct)
+        Array(formats).compact unless formats.nil?
+      end
+
+      # Delegates method calls to the receiver (application instance)
+      # This allows route handlers to call application methods within their blocks
+      # Example: get '/users' do; fetch_users; end - calls application's fetch_users method
+      def method_missing(name, ...)
+        if @receiver.respond_to?(name)
+          @receiver.public_send(name, ...)
+        else
+          super
+        end
+      end
+
+      # Required pair for method_missing to properly support respond_to?
+      def respond_to_missing?(name, include_private = false)
+        @receiver.respond_to?(name, include_private) || super
+      end
+    end
 
-    def self.get(path, &block)
-      @@routes["GET #{path}"] = block
+    def initialize
+      @routes = {}
+      @routes_mutex = Mutex.new # Protects route modifications in multithreaded environments
+      @logger = Takagi.logger
+      @route_matcher = RouteMatcher.new(@logger)
+      @metadata_extractor = MetadataExtractor.new(@logger)
     end
 
-    def self.post(path, &block)
-      @@routes["POST #{path}"] = block
+    # Registers a new route for a given HTTP method and path
+    # @param method [String] The HTTP method (GET, POST, etc.)
+    # @param path [String] The URL path, can include dynamic segments like `:id`
+    # @param block [Proc] The handler to be executed when the route is matched
+    def add_route(method, path, metadata: {}, &block)
+      @routes_mutex.synchronize do
+        entry = build_route_entry(method, path, metadata, block)
+        @routes["#{method} #{path}"] = entry
+        @logger.debug "Add new route: #{method} #{path}"
+
+        # Extract metadata from core blocks inside the handler
+        extract_metadata_from_handler(entry) if block
+
+        Takagi::Hooks.emit(
+          :router_route_added,
+          method: method,
+          path: path,
+          entry: entry
+        )
+      end
     end
 
-    def self.find_route(method, path)
-      return @@routes["#{method} #{path}"], {} if @@routes.key?("#{method} #{path}")
+    # Dynamically define route registration methods from CoAP::Registries::Method registry
+    # Generates: get, post, put, delete, fetch, etc.
+    CoAP::Registries::Method.all.each_value do |method_name|
+      method_string = method_name.split.first # Extract 'GET' from 'GET'
+      method_symbol = method_string.downcase.to_sym
 
-      match_dynamic_route(method, path)
+      define_method(method_symbol) do |path, metadata: {}, &block|
+        add_route(method_string, path, metadata: metadata, &block)
+      end
     end
 
-    def self.match_dynamic_route(method, path)
-      @@routes.each do |route_key, block|
-        route_method, route_path = route_key.split(" ", 2)
-        next unless route_method == method
+    # Registers a OBSERVE route
+    # @param path [String] The URL path
+    # @param block [Proc] The handler function
+    def observable(path, metadata: {}, &block)
+      observable_metadata = { obs: true, rt: 'core#observable', if: 'takagi.observe' }
+      add_route('OBSERVE', path, metadata: observable_metadata.merge(metadata), &block)
+    end
+
+    def all_routes
+      @routes.values.map { |entry| "#{entry.method} #{entry.path}" }
+    end
 
-        route_parts = route_path.split("/")
-        path_parts = path.split("/")
-        next unless route_parts.length == path_parts.length
+    def find_observable(path)
+      @routes.values.find { |entry| entry.method == 'OBSERVE' && entry.path == path }
+    end
 
+    # Finds a registered route for a given method and path
+    # @param method [String] HTTP method
+    # @param path [String] URL path
+    # @return [Proc, Hash] The matching handler and extracted parameters
+    def find_route(method, path)
+      @routes_mutex.synchronize do
+        @logger.debug "Routes: #{@routes.inspect}"
+        @logger.debug "Looking for route: #{method} #{path}"
+        entry = @routes["#{method} #{path}"]
         params = {}
-        match = route_parts.each_with_index.all? do |part, index|
-          if part.start_with?(":")
-            param_name = part[1..]
-            params[param_name.to_sym] = path_parts[index]
-            true
-          else
-            part == path_parts[index]
-          end
+
+        return wrap_block(entry), params if entry
+
+        @logger.debug '[Debug] Find dynamic route'
+        entry, params = match_dynamic_route(method, path)
+
+        return wrap_block(entry), params if entry
+
+        [nil, {}]
+      end
+    end
+
+    def link_format_entries
+      @routes_mutex.synchronize do
+        @routes.values.reject { |entry| entry.metadata[:discovery] }.map(&:dup)
+      end
+    end
+
+    # Applies CoRE metadata outside the request cycle. Useful for boot time
+    # configuration where the DSL block does not have a live request object.
+    def configure_core(method, path, &block)
+      return unless block
+
+      @routes_mutex.synchronize do
+        entry = @routes["#{method} #{path}"]
+        unless entry
+          @logger.warn "configure_core skipped: #{method} #{path} not registered"
+          return
         end
 
-        return [block, params] if match
+        entry.configure_attributes(&block)
       end
+    end
+
+    private
+
+    def wrap_block(entry)
+      block = entry&.block
+      return nil unless block
+
+      lambda do |req, params = {}|
+        context = RouteContext.new(entry, req, params, entry.receiver)
+        context.run(block)
+      end
+    end
+
+    # Matches dynamic routes that contain parameters (e.g., `/users/:id`)
+    # Delegates to RouteMatcher for the actual matching logic
+    # @param method [String] HTTP method
+    # @param path [String] Request path
+    # @return [Array(RouteEntry, Hash)] Matched route entry and extracted parameters
+    def match_dynamic_route(method, path)
+      @route_matcher.match(@routes, method, path)
+    end
+
+    def build_route_entry(method, path, metadata, block)
+      RouteEntry.new(
+        method: method,
+        path: path,
+        block: block,
+        metadata: normalize_metadata(method, path, metadata),
+        receiver: block&.binding&.receiver
+      )
+    end
+
+    # Normalizes route metadata with sensible defaults for CoRE Link Format
+    #
+    # @param method [String] HTTP-like method (GET, POST, OBSERVE, etc.)
+    # @param path [String] Route path
+    # @param metadata [Hash, nil] User-provided metadata
+    # @return [Hash] Normalized metadata with defaults applied
+    def normalize_metadata(method, path, metadata)
+      normalized = (metadata || {}).transform_keys(&:to_sym)
+      normalized[:rt] ||= default_resource_type(method)
+      normalized[:if] ||= default_interface(method)
+      normalized[:ct] = DEFAULT_CONTENT_FORMAT unless normalized.key?(:ct)
+      normalized[:title] ||= "#{method} #{path}"
+      normalized
+    end
+
+    def default_resource_type(method)
+      method == 'OBSERVE' ? 'core#observable' : 'core#endpoint'
+    end
+
+    def default_interface(method)
+      method == 'OBSERVE' ? 'takagi.observe' : "takagi.#{method.downcase}"
+    end
 
-      [nil, {}]
+    # Executes route handler in metadata extraction mode to capture core block attributes
+    # Delegates to MetadataExtractor for the actual extraction logic
+    # @param entry [RouteEntry] The route entry to extract metadata from
+    def extract_metadata_from_handler(entry)
+      @metadata_extractor.extract(entry)
     end
   end
 end

data/lib/takagi/serialization/base.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Takagi
+  module Serialization
+    # Base interface for all content-format serializers
+    #
+    # Serializers implement encoding/decoding logic for specific content-formats.
+    # Each serializer handles one CoAP content-format (MIME type).
+    #
+    # @example Implementing a custom serializer
+    #   class XmlSerializer < Takagi::Serialization::Base
+    #     def encode(data)
+    #       # Convert Ruby object to XML bytes
+    #     end
+    #
+    #     def decode(bytes)
+    #       # Parse XML bytes to Ruby object
+    #     end
+    #
+    #     def content_type
+    #       'application/xml'
+    #     end
+    #
+    #     def content_format_code
+    #       41  # CoAP XML content-format
+    #     end
+    #   end
+    #
+    # @abstract Subclass and implement all methods
+    class Base
+      # Encode Ruby object to bytes
+      #
+      # @param data [Object] Ruby object to encode
+      # @return [String] Binary string (ASCII-8BIT encoding)
+      # @raise [EncodeError] if encoding fails
+      #
+      # @example
+      #   serializer.encode({ temp: 25 })  # => "\x{...}"
+      def encode(data)
+        raise NotImplementedError, "#{self.class}#encode must be implemented"
+      end
+
+      # Decode bytes to Ruby object
+      #
+      # @param bytes [String] Binary string to decode
+      # @return [Object] Decoded Ruby object
+      # @raise [DecodeError] if decoding fails
+      #
+      # @example
+      #   serializer.decode("\x{...}")  # => { temp: 25 }
+      def decode(bytes)
+        raise NotImplementedError, "#{self.class}#decode must be implemented"
+      end
+
+      # MIME type this serializer handles
+      #
+      # @return [String] MIME type (e.g., 'application/json')
+      #
+      # @example
+      #   serializer.content_type  # => 'application/json'
+      def content_type
+        raise NotImplementedError, "#{self.class}#content_type must be implemented"
+      end
+
+      # CoAP content-format code
+      #
+      # @return [Integer] CoAP content-format code from RFC 7252 §12.3
+      #
+      # @example
+      #   serializer.content_format_code  # => 50 (JSON)
+      def content_format_code
+        raise NotImplementedError, "#{self.class}#content_format_code must be implemented"
+      end
+
+      # Check if this serializer can handle binary data
+      #
+      # @return [Boolean] true if binary format
+      def binary?
+        false
+      end
+
+      # Human-readable name for this serializer
+      #
+      # @return [String] Serializer name
+      def name
+        self.class.name.split('::').last.sub(/Serializer$/, '')
+      end
+    end
+
+    # Raised when encoding fails
+    class EncodeError < StandardError; end
+
+    # Raised when decoding fails
+    class DecodeError < StandardError; end
+
+    # Raised when content-format is not registered
+    class UnknownFormatError < StandardError; end
+
+    # Raised when serializer implementation is invalid
+    class InvalidSerializerError < StandardError; end
+  end
+end

data/lib/takagi/serialization/cbor_serializer.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Takagi
+  module Serialization
+    # CBOR serializer (RFC 8949)
+    #
+    # Handles application/cbor content-format (code 60).
+    # Encodes Ruby objects to CBOR binary format and decodes CBOR to Ruby objects.
+    #
+    # Uses Takagi's built-in CBOR implementation for zero external dependencies.
+    #
+    # @example Encoding
+    #   serializer = CborSerializer.new
+    #   bytes = serializer.encode({ temp: 25 })  # => "\xA1dtemp\x18\x19"
+    #
+    # @example Decoding
+    #   data = serializer.decode("\xA1dtemp\x18\x19")  # => { "temp" => 25 }
+    class CborSerializer < Base
+      # Encode Ruby object to CBOR bytes
+      #
+      # @param data [Object] Ruby object to encode
+      # @return [String] CBOR binary string
+      # @raise [EncodeError] if encoding fails
+      #
+      # @example Hash encoding
+      #   encode({ temp: 25 })  # => CBOR bytes
+      #
+      # @example Array encoding
+      #   encode([1, 2, 3])  # => CBOR bytes
+      #
+      # @example Supported types
+      #   - Integer (signed/unsigned, up to 64-bit)
+      #   - Float (64-bit IEEE 754)
+      #   - String (UTF-8)
+      #   - Array
+      #   - Hash
+      #   - true, false, nil
+      #   - Time (as timestamp)
+      def encode(data)
+        return ''.b if data.nil? || data == ''
+
+        CBOR::Encoder.encode(data)
+      rescue CBOR::EncodeError => e
+        raise EncodeError, "CBOR encoding failed: #{e.message}"
+      rescue StandardError => e
+        raise EncodeError, "CBOR encoding error: #{e.message}"
+      end
+
+      # Decode CBOR bytes to Ruby object
+      #
+      # @param bytes [String] CBOR binary data
+      # @return [Object] Decoded Ruby object (Hash, Array, Integer, etc.)
+      # @raise [DecodeError] if decoding fails
+      #
+      # @example Object decoding
+      #   decode(cbor_bytes)  # => { "temp" => 25 }
+      #
+      # @example Array decoding
+      #   decode(cbor_bytes)  # => [1, 2, 3]
+      def decode(bytes)
+        return nil if bytes.nil? || bytes.empty?
+
+        CBOR::Decoder.decode(bytes)
+      rescue CBOR::DecodeError => e
+        raise DecodeError, "CBOR decoding failed: #{e.message}"
+      rescue StandardError => e
+        raise DecodeError, "CBOR decoding error: #{e.message}"
+      end
+
+      # MIME type for CBOR
+      #
+      # @return [String] 'application/cbor'
+      def content_type
+        'application/cbor'
+      end
+
+      # CoAP content-format code for CBOR
+      #
+      # @return [Integer] 60 (RFC 7049)
+      def content_format_code
+        CoAP::Registries::ContentFormat::CBOR
+      end
+
+      # CBOR is a binary format
+      #
+      # @return [Boolean] true
+      def binary?
+        true
+      end
+    end
+  end
+end

data/lib/takagi/serialization/json_serializer.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Takagi
+  module Serialization
+    # JSON serializer (RFC 8259)
+    #
+    # Handles application/json content-format (code 50).
+    # Encodes Ruby objects to JSON and decodes JSON to Ruby objects.
+    #
+    # @example Encoding
+    #   serializer = JsonSerializer.new
+    #   bytes = serializer.encode({ temp: 25 })  # => "{\"temp\":25}"
+    #
+    # @example Decoding
+    #   data = serializer.decode("{\"temp\":25}")  # => { "temp" => 25 }
+    class JsonSerializer < Base
+      # Encode Ruby object to JSON bytes
+      #
+      # @param data [Object] Ruby object to encode
+      # @return [String] JSON string as binary
+      # @raise [EncodeError] if encoding fails
+      #
+      # @example Hash encoding
+      #   encode({ temp: 25 })  # => "{\"temp\":25}"
+      #
+      # @example Array encoding
+      #   encode([1, 2, 3])  # => "[1,2,3]"
+      #
+      # @example String pass-through
+      #   encode("hello")  # => "hello"
+      def encode(data)
+        return ''.b if data.nil? || data == ''
+
+        result = case data
+                 when String
+                   # Already a string, assume it's valid
+                   data
+                 when Hash, Array
+                   # Structured data - convert to JSON
+                   JSON.generate(data)
+                 else
+                   # Other objects - try to_json
+                   data.to_json
+                 end
+
+        result.b
+      rescue StandardError => e
+        raise EncodeError, "JSON encoding failed: #{e.message}"
+      end
+
+      # Decode JSON bytes to Ruby object
+      #
+      # @param bytes [String] JSON bytes to decode
+      # @return [Object, nil] Decoded Ruby object (Hash, Array, String, etc.) or nil if invalid
+      #
+      # @example Object decoding
+      #   decode("{\"temp\":25}")  # => { "temp" => 25 }
+      #
+      # @example Array decoding
+      #   decode("[1,2,3]")  # => [1, 2, 3]
+      #
+      # @example Invalid JSON
+      #   decode("{invalid}")  # => nil
+      def decode(bytes)
+        return nil if bytes.nil? || bytes.empty?
+
+        JSON.parse(bytes)
+      rescue JSON::ParserError => e
+        nil  # Return nil for invalid JSON
+      end
+
+      # MIME type for JSON
+      #
+      # @return [String] 'application/json'
+      def content_type
+        'application/json'
+      end
+
+      # CoAP content-format code for JSON
+      #
+      # @return [Integer] 50 (RFC 7252 §12.3)
+      def content_format_code
+        CoAP::Registries::ContentFormat::JSON
+      end
+
+      # JSON is text-based, not binary
+      #
+      # @return [Boolean] false
+      def binary?
+        false
+      end
+    end
+  end
+end