takagi 0.1.0 → 1.1.0

data/lib/takagi/reactor.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'observable/reactor'
+
+module Takagi
+  # Backward compatibility alias for Observable::Reactor
+  #
+  # @deprecated Use {Observable::Reactor} instead. This alias will be removed in v2.0.0
+  #
+  # The new Observable::Reactor provides:
+  # - Thread pool support for parallel execution
+  # - Event-driven notifications via EventBus
+  # - Hybrid polling + push modes
+  # - Better resource management
+  #
+  # @example Migration
+  #   # Old
+  #   reactor = Takagi::Reactor.new
+  #
+  #   # New
+  #   reactor = Takagi::Observable::Reactor.new(threads: 4)
+  Reactor = Observable::Reactor
+end

data/lib/takagi/reactor_registry.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Takagi
+  # Tracks background reactor instances and controls their lifecycle.
+  #
+  # Uses Registry::Base for thread-safe storage and consistent API.
+  # Reactors are stored with auto-incrementing IDs.
+  #
+  # NOTE: Cannot be moved to Reactor::Registry because Reactor is already a class.
+  # Keeping as ReactorRegistry at top level for now.
+  #
+  # @example Register and manage reactors
+  #   reactor = SomeReactor.new
+  #   id = ReactorRegistry.register(reactor)
+  #   ReactorRegistry.start_all
+  #   ReactorRegistry.stop_all
+  module ReactorRegistry
+    extend Registry::Base
+
+    class << self
+      # Register a reactor instance
+      #
+      # @param reactor [Object] Reactor instance
+      # @return [Integer] Auto-assigned reactor ID
+      def register(reactor)
+        id = next_id
+        super(id, reactor)
+        id
+      end
+
+      # Get all registered reactors
+      #
+      # @return [Array] List of reactor instances
+      def reactors
+        @mutex.synchronize { registry.values }
+      end
+
+      # Start all registered reactors
+      #
+      # @return [void]
+      def start_all
+        reactors.each(&:start)
+      end
+
+      # Stop all registered reactors
+      #
+      # @return [void]
+      def stop_all
+        reactors.each do |reactor|
+          reactor.stop if reactor.respond_to?(:stop)
+        end
+      end
+
+      private
+
+      def next_id
+        @mutex.synchronize do
+          @next_id ||= 0
+          @next_id += 1
+        end
+      end
+    end
+  end
+end

data/lib/takagi/registry/base.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module Takagi
+  module Registry
+    # Thread-safe base module for implementing registries.
+    #
+    # Provides a consistent API and thread-safety for all registry implementations.
+    # Designed to support the plugin system by allowing safe concurrent access.
+    #
+    # @example Basic usage with class methods
+    #   class MyRegistry
+    #     extend Takagi::Registry::Base
+    #   end
+    #
+    #   MyRegistry.register(:foo, SomeClass)
+    #   MyRegistry.get(:foo)  # => SomeClass
+    #   MyRegistry.registered?(:foo)  # => true
+    #
+    # @example With validation
+    #   class MyRegistry
+    #     extend Takagi::Registry::Base
+    #
+    #     def self.validate_entry!(key, value, **metadata)
+    #       raise ArgumentError, "Invalid value" unless value.respond_to?(:call)
+    #     end
+    #   end
+    #
+    # @example With custom storage structure
+    #   class MyRegistry
+    #     extend Takagi::Registry::Base
+    #
+    #     def self.store_entry(key, value, **metadata)
+    #       registry[key] = { klass: value, options: metadata }
+    #     end
+    #   end
+    module Base
+      # Error raised when a registry entry is not found
+      class NotFoundError < StandardError; end
+
+      # Error raised when a registry entry already exists
+      class AlreadyRegisteredError < StandardError; end
+
+      # Error raised when validation fails
+      class ValidationError < StandardError; end
+
+      def self.extended(base)
+        base.instance_variable_set(:@registry, {})
+        base.instance_variable_set(:@mutex, Mutex.new)
+      end
+
+      # Register a new entry in the registry
+      #
+      # @param key [Object] Unique identifier for the entry
+      # @param value [Object] The value to register
+      # @param metadata [Hash] Optional metadata to store with the entry
+      # @param overwrite [Boolean] Whether to allow overwriting existing entries
+      # @return [void]
+      # @raise [AlreadyRegisteredError] If key already exists and overwrite is false
+      # @raise [ValidationError] If validation fails
+      #
+      # @example
+      #   MyRegistry.register(:udp, UdpTransport, rfc: 'RFC 7252')
+      def register(key, value, overwrite: false, **metadata)
+        validate_entry!(key, value, **metadata) if respond_to?(:validate_entry!, true)
+
+        @mutex.synchronize do
+          if registry.key?(key) && !overwrite
+            # Enhanced error with suggestions
+            error = Errors::RegistryError.already_registered(self.class.name, key)
+            raise AlreadyRegisteredError, error.message
+          end
+
+          store_entry(key, value, **metadata)
+        end
+
+        after_register(key, value, **metadata) if respond_to?(:after_register, true)
+      end
+
+      # Retrieve an entry from the registry
+      #
+      # @param key [Object] The key to look up
+      # @return [Object] The registered value
+      # @raise [NotFoundError] If key is not found
+      #
+      # @example
+      #   transport = MyRegistry.get(:udp)
+      def get(key)
+        value = self[key]
+        unless value
+          # Enhanced error with suggestions
+          available = keys
+          error = Errors::RegistryError.not_found(
+            self.class.name,
+            key,
+            available
+          )
+          raise NotFoundError, error.message
+        end
+
+        value
+      end
+
+      # Retrieve an entry from the registry (returns nil if not found)
+      #
+      # @param key [Object] The key to look up
+      # @return [Object, nil] The registered value or nil
+      #
+      # @example
+      #   transport = MyRegistry[:udp]
+      def [](key)
+        @mutex.synchronize { fetch_entry(key) }
+      end
+
+      # Check if a key is registered
+      #
+      # @param key [Object] The key to check
+      # @return [Boolean] true if registered
+      #
+      # @example
+      #   MyRegistry.registered?(:udp)  # => true
+      def registered?(key)
+        @mutex.synchronize { registry.key?(key) }
+      end
+
+      # Get all registered keys
+      #
+      # @return [Array] List of all keys
+      #
+      # @example
+      #   MyRegistry.keys  # => [:udp, :tcp, :dtls]
+      def keys
+        @mutex.synchronize { registry.keys.dup }
+      end
+      alias all keys
+
+      # Get all entries as a hash
+      #
+      # @return [Hash] Copy of the registry
+      #
+      # @example
+      #   MyRegistry.entries  # => { udp: UdpTransport, tcp: TcpTransport }
+      def entries
+        @mutex.synchronize { registry.dup }
+      end
+
+      # Get metadata for a registered entry
+      #
+      # @param key [Object] The key to look up
+      # @return [Hash, nil] Metadata hash or nil if not found
+      #
+      # @example
+      #   MyRegistry.metadata_for(:udp)  # => { rfc: 'RFC 7252' }
+      def metadata_for(key)
+        @mutex.synchronize { fetch_metadata(key) }
+      end
+
+      # Unregister an entry
+      #
+      # @param key [Object] The key to remove
+      # @return [Object, nil] The removed value or nil if not found
+      #
+      # @example
+      #   MyRegistry.unregister(:udp)
+      def unregister(key)
+        @mutex.synchronize do
+          before_unregister(key) if respond_to?(:before_unregister, true)
+          registry.delete(key)
+        end
+      end
+
+      # Clear all registrations
+      #
+      # Primarily useful for testing. Thread-safe.
+      #
+      # @return [void]
+      #
+      # @example
+      #   MyRegistry.clear!
+      def clear!
+        @mutex.synchronize do
+          before_clear if respond_to?(:before_clear, true)
+          registry.clear
+        end
+      end
+
+      # Get count of registered entries
+      #
+      # @return [Integer] Number of registered entries
+      #
+      # @example
+      #   MyRegistry.count  # => 3
+      def count
+        @mutex.synchronize { registry.size }
+      end
+      alias size count
+
+      # Check if registry is empty
+      #
+      # @return [Boolean] true if no entries registered
+      #
+      # @example
+      #   MyRegistry.empty?  # => false
+      def empty?
+        @mutex.synchronize { registry.empty? }
+      end
+
+      # Iterate over all entries
+      #
+      # @yield [key, value] Each key-value pair
+      # @return [Enumerator] If no block given
+      #
+      # @example
+      #   MyRegistry.each do |key, value|
+      #     puts "#{key}: #{value}"
+      #   end
+      def each(&block)
+        return enum_for(:each) unless block_given?
+
+        # Get snapshot to avoid holding lock during iteration
+        snapshot = @mutex.synchronize { registry.dup }
+        snapshot.each(&block)
+      end
+
+      private
+
+      # Access to the internal registry hash
+      # Must be called within mutex.synchronize block
+      attr_reader :registry
+
+      # Store an entry in the registry (can be overridden)
+      #
+      # @param key [Object] The key
+      # @param value [Object] The value
+      # @param metadata [Hash] Metadata
+      def store_entry(key, value, **metadata)
+        if metadata.empty?
+          registry[key] = value
+        else
+          registry[key] = { value: value, metadata: metadata }
+        end
+      end
+
+      # Fetch an entry from the registry (can be overridden)
+      #
+      # @param key [Object] The key
+      # @return [Object, nil] The value or nil
+      def fetch_entry(key)
+        entry = registry[key]
+        return nil unless entry
+
+        # Handle both simple values and hash-wrapped values
+        entry.is_a?(Hash) && entry.key?(:value) ? entry[:value] : entry
+      end
+
+      # Fetch metadata for an entry (can be overridden)
+      #
+      # @param key [Object] The key
+      # @return [Hash, nil] The metadata or nil
+      def fetch_metadata(key)
+        entry = registry[key]
+        return nil unless entry
+        return nil unless entry.is_a?(Hash)
+
+        entry[:metadata]
+      end
+    end
+  end
+end

data/lib/takagi/response_builder.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative 'hooks'
+require_relative 'serialization'
+
+module Takagi
+  # Builds CoAP responses from middleware results
+  class ResponseBuilder
+    DEFAULT_RESPONSE_CODE = CoAP::Registries::Response::CONTENT
+
+    # Builds a response from the middleware result
+    #
+    # @param inbound_request [Takagi::Message::Inbound] The original request
+    # @param result [Takagi::Message::Outbound, Hash, Object] The middleware result
+    # @param logger [Logger, nil] Optional logger for debugging
+    # @return [Takagi::Message::Outbound] The response message
+    def self.build(inbound_request, result, logger: nil)
+      Takagi::Hooks.emit(:before_response_build, inbound: inbound_request, result: result)
+
+      case result
+      when Takagi::Message::Outbound
+        response = result
+      when Hash, String
+        logger&.debug("Returned #{result.class} as response")
+        response = respond(inbound_request, result, logger: logger)
+      else
+        logger&.warn("Middleware returned non-Hash: #{result.inspect}")
+        response = inbound_request.to_response('5.00 Internal Server Error', { error: 'Internal Server Error' })
+      end
+
+      Takagi::Hooks.emit(:after_response_build, inbound: inbound_request, response: response, result: result)
+      response
+    end
+
+    # Build a CoAP response with content-format negotiation.
+    #
+    # @param inbound_request [Takagi::Message::Inbound] The original request
+    # @param payload [Object] The payload to serialize
+    # @param code [Integer, String, Symbol] CoAP response code (default 2.05 Content)
+    # @param formats [Array<Integer, Symbol, String>, nil] Allowed content-format codes
+    # @param force [Integer, Symbol, String, nil] Force a specific content-format code
+    # @param options [Hash] Additional CoAP options
+    # @param logger [Logger, nil] Logger for debug output
+    # @return [Takagi::Message::Outbound]
+    def self.respond(inbound_request, payload, code: DEFAULT_RESPONSE_CODE, formats: nil, force: nil, options: {}, logger: nil)
+      requested_formats = formats || inbound_request&.content_format
+      allowed_formats = normalize_formats(requested_formats)
+      forced_format = normalize_format(force)
+      accept_format = normalize_format(extract_accept(inbound_request))
+
+      selected_format = select_format(allowed_formats, accept_format, forced_format, logger)
+
+      case selected_format
+      when :not_acceptable
+        return inbound_request.to_response(CoAP::Registries::Response::NOT_ACCEPTABLE, { error: 'Not Acceptable' })
+      when :unsupported
+        return inbound_request.to_response(CoAP::Registries::Response::UNSUPPORTED_CONTENT_FORMAT, { error: 'Unsupported Content-Format' })
+      end
+
+      content_options = (options || {}).dup
+      if selected_format
+        content_options[CoAP::Registries::Option::CONTENT_FORMAT] ||= [selected_format]
+      end
+
+      inbound_request.to_response(code, payload, options: content_options)
+    end
+
+    class << self
+      private
+
+      def normalize_formats(formats)
+        list = Array(formats || default_format)
+        normalized = list.map { |fmt| normalize_format(fmt) }.compact
+        normalized.empty? ? [default_format] : normalized
+      end
+
+      def select_format(allowed_formats, accept_format, forced_format, logger)
+        if forced_format
+          return :unsupported unless Serialization::Registry.supports?(forced_format)
+
+          return forced_format
+        end
+
+        if accept_format
+          if Serialization::Registry.supports?(accept_format) && allowed_formats.include?(accept_format)
+            return accept_format
+          end
+
+          logger&.debug("Accept format #{accept_format.inspect} not supported")
+          return :not_acceptable
+        end
+
+        allowed_formats.find { |fmt| Serialization::Registry.supports?(fmt) } || default_format
+      end
+
+      def normalize_format(format)
+        return nil if format.nil?
+        return format if format.is_a?(Integer)
+        return format.content_format_code if format.respond_to?(:content_format_code)
+
+        if format.is_a?(Array)
+          return normalize_format(format.first)
+        end
+
+        if format.is_a?(Symbol) || format.is_a?(String)
+          registry_value = CoAP::Registries::ContentFormat.value_for(format) ||
+                           CoAP::Registries::ContentFormat.value_for(format.to_s.downcase.to_sym)
+          return registry_value if registry_value
+        end
+
+        if format.is_a?(String)
+          decoded = decode_content_format_bytes(format)
+          return decoded if decoded
+        end
+
+        nil
+      end
+
+      def decode_content_format_bytes(value)
+        bytes = value.b.bytes
+        return nil if bytes.empty? || bytes.length > 2
+
+        bytes.reduce(0) { |acc, byte| (acc << 8) | byte }
+      end
+
+      def extract_accept(inbound_request)
+        return unless inbound_request.respond_to?(:accept)
+
+        inbound_request.accept
+      end
+
+      def default_format
+        if defined?(Takagi::Router::DEFAULT_CONTENT_FORMAT)
+          Takagi::Router::DEFAULT_CONTENT_FORMAT
+        else
+          CoAP::Registries::ContentFormat::JSON
+        end
+      end
+    end
+  end
+end

data/lib/takagi/router/metadata_extractor.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module Takagi
+  class Router
+    # Handles metadata extraction from route handlers at boot time.
+    #
+    # Extracted from Router to follow Single Responsibility Principle.
+    # Executes route handlers in a special context to capture CoRE Link Format
+    # metadata defined via core blocks.
+    class MetadataExtractor
+      # @param logger [Logger] Logger instance for debugging
+      def initialize(logger)
+        @logger = logger
+      end
+
+      # Executes route handler in metadata extraction mode to capture core block attributes
+      # This allows defining metadata inline with the handler for better DX
+      #
+      # @param entry [RouteEntry] The route entry to extract metadata from
+      def extract(entry)
+        # Skip metadata extraction for discovery routes to avoid deadlock
+        # Discovery routes access the router itself, which would cause a deadlock
+        # since we're already holding the routes_mutex. These routes declare
+        # their metadata explicitly via the metadata: parameter instead.
+        if entry.metadata[:discovery]
+          @logger.debug "Skipping metadata extraction for discovery route: #{entry.method} #{entry.path}"
+          return
+        end
+
+        # Create a mock request object that will be passed to the handler
+        mock_request = MetadataExtractionRequest.new
+
+        # Create a special extraction context that uses the entry's AttributeSet directly
+        # (This is safe because it runs once at boot time, not during concurrent requests)
+        context = MetadataExtractionContext.new(entry, mock_request, {}, entry.receiver)
+
+        # Execute the handler block - it may call core { ... } which updates the attribute_set
+        begin
+          context.run(entry.block)
+        rescue StandardError => e
+          # If the handler fails during metadata extraction (e.g., tries to access real data),
+          # that's okay - we only care about core blocks which should not throw errors
+          @logger.debug "Metadata extraction for #{entry.method} #{entry.path} encountered: #{e.message}"
+        end
+
+        # Apply any changes made by core blocks
+        entry.attribute_set.apply!
+      end
+
+      # Special context for boot-time metadata extraction
+      # Uses entry's AttributeSet directly (safe because boot-time is single-threaded)
+      #
+      # Note: This class inherits from Takagi::Router::RouteContext, but since this file
+      # is loaded before RouteContext is defined, we define it as a placeholder here
+      # and will reopen it after Router is loaded.
+      class MetadataExtractionContext
+        include Takagi::Helpers
+        extend Forwardable
+
+        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
+
+        def initialize(entry, request, params, receiver)
+          @entry = entry
+          @request = request
+          @params = params
+          @receiver = receiver
+          # Use entry's AttributeSet directly for boot-time extraction
+          # This is safe because metadata extraction runs once at boot time (single-threaded)
+          @core_attributes = @entry.attribute_set
+        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
+
+        # Delegates method calls to the receiver (application instance)
+        def method_missing(name, ...)
+          if @receiver.respond_to?(name)
+            @receiver.public_send(name, ...)
+          else
+            super
+          end
+        end
+
+        # Required pair for method_missing
+        def respond_to_missing?(name, include_private = false)
+          @receiver.respond_to?(name, include_private) || super
+        end
+      end
+
+      # Mock request object used during metadata extraction
+      # Provides minimal interface to prevent errors when handlers are executed at boot time
+      class MetadataExtractionRequest
+        def to_response(*_args)
+          nil # Ignore response generation during metadata extraction
+        end
+
+        def method_missing(_name, *_args, &_block)
+          nil # Return nil for any method calls to prevent errors
+        end
+
+        def respond_to_missing?(_name, _include_private = false)
+          true # Pretend to respond to everything
+        end
+      end
+    end
+  end
+end