takagi 0.1.0 → 1.1.0

data/lib/takagi/observer/registry.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative '../hooks'
+
+module Takagi
+  module Observer
+    # Keeps track of observers and broadcasts state changes to interested parties.
+    #
+    # NOTE: This registry intentionally does NOT use Registry::Base because:
+    # 1. It stores arrays of subscriptions per path (not simple key-value pairs)
+    # 2. It has complex domain logic (delta checking, notifications, cleanup)
+    # 3. It needs fine-grained mutex control for notify operations
+    # 4. The API is fundamentally different (subscribe/notify vs register/get)
+    #
+    # This is already thread-safe with its own @mutex implementation.
+    class Registry
+      @subscriptions = {}
+      @mutex = Mutex.new
+
+      class << self
+        attr_reader :subscriptions
+
+        def subscribe(path, subscriber)
+          entry = subscriber.dup
+          entry[:created_at] ||= Time.now
+          entry[:last_notified_at] ||= nil
+
+          @mutex.synchronize do
+            @subscriptions[path] ||= []
+            @subscriptions[path] << entry
+          end
+
+          Takagi::Hooks.emit(:observe_subscribed, path: path, subscription: entry)
+
+          entry
+        end
+
+        def unsubscribe(path, token)
+          @mutex.synchronize do
+            return unless @subscriptions[path]
+
+            @subscriptions[path].reject! { |s| s[:token] == token }
+          end
+
+          Takagi::Hooks.emit(:observe_unsubscribed, path: path, token: token)
+        end
+
+        def notify(path, new_value)
+          # Get a snapshot of subscribers to avoid holding the lock during notification
+          subscribers = @mutex.synchronize { @subscriptions[path]&.dup }
+          return unless subscribers
+
+          Takagi.logger.debug "Notify called for: #{path}"
+          Takagi.logger.debug "Subscriptions count: #{subscribers.size}"
+
+          Takagi::Hooks.emit(:observe_notify_start, path: path, subscribers: subscribers&.size || 0, value: new_value)
+
+          subscribers.each do |subscription|
+            next unless should_notify?(subscription, new_value)
+
+            deliver_notification(subscription, path, new_value)
+            update_sequence(subscription, new_value)
+            subscription[:last_notified_at] = Time.now
+
+            Takagi::Hooks.emit(:observer_notification, path: path, subscription: subscription)
+          end
+
+          Takagi::Hooks.emit(:observe_notify_end, path: path, delivered: subscribers&.size || 0, value: new_value)
+        end
+
+        def sender
+          @sender ||= Takagi::Observer::Sender.new
+        end
+
+        def subscription_paths
+          @mutex.synchronize { @subscriptions.keys.dup }
+        end
+
+        def cleanup_stale_observers(max_age:, now: Time.now)
+          cutoff = now - max_age
+          cleaned = 0
+
+          @mutex.synchronize do
+            @subscriptions.each do |path, subscribers|
+              subscribers.reject! do |subscription|
+                stale = stale_subscription?(subscription, cutoff)
+                cleaned += 1 if stale
+                stale
+              end
+              @subscriptions.delete(path) if subscribers.empty?
+            end
+          end
+
+          cleaned
+        end
+
+        private
+
+        def should_notify?(subscription, new_value)
+          return true unless subscription[:delta] && subscription[:last_value]
+
+          delta_exceeded?(subscription[:last_value], new_value, subscription[:delta])
+        end
+
+        def delta_exceeded?(last_value, new_value, threshold)
+          (last_value - new_value).abs >= threshold
+        rescue StandardError
+          true
+        end
+
+        def deliver_notification(subscription, path, new_value)
+          if subscription[:handler]
+            Takagi.logger.debug "Calling local handler for #{path}"
+            subscription[:handler].call(new_value, nil)
+          else
+            Takagi.logger.debug "Sending packet to #{subscription[:address]}:#{subscription[:port]}"
+            sender.send_packet(subscription, new_value)
+          end
+        end
+
+        def update_sequence(subscription, new_value)
+          subscription[:last_value] = new_value
+          subscription[:last_seq] = (subscription[:last_seq] || 0) + 1
+        end
+
+        def stale_subscription?(subscription, cutoff)
+          return false if subscription[:handler]
+
+          last_activity = subscription[:last_notified_at] || subscription[:created_at]
+          return false unless last_activity
+
+          last_activity < cutoff
+        end
+      end
+    end
+  end
+end

data/lib/takagi/observer/sender.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Takagi
+  module Observer
+    # Dispatches outbound notifications to subscribed observers.
+    # Supports multiple transports (UDP, TCP, etc.) via transport registry.
+    class Sender
+      def initialize(transport: :udp)
+        @transport = transport
+        # NEW: Use transport registry to get appropriate sender
+        transport_class = Takagi::Network::Registry.get(@transport)
+        transport_impl = transport_class.new
+        @sender = transport_impl.create_sender
+      rescue Takagi::Network::Registry::TransportNotFoundError
+        # Fallback to UDP if transport not found
+        Takagi.logger.warn "Transport #{@transport} not found, using UDP"
+        @sender = Takagi::Network::UdpSender.instance
+      end
+
+      def send_packet(subscriber, value)
+        # Get transport from subscriber metadata, or use instance default
+        transport = subscriber[:transport] || @transport
+
+        message = Takagi::Message::Outbound.new(
+          code: '2.05',
+          payload: value.to_s,
+          token: subscriber[:token],
+          message_id: rand(0..0xFFFF),
+          type: 1, # NON
+          transport: transport
+        )
+
+        @sender.transmit(message, subscriber[:address], subscriber[:port])
+      rescue StandardError => e
+        Takagi.logger.error "Observer Notify Error: #{e.message}"
+      end
+    end
+  end
+end

data/lib/takagi/observer/watcher.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Takagi
+  module Observer
+    # Periodically notifies observers by re-running registered handlers.
+    class Watcher
+      def initialize(interval: 1)
+        @interval = interval
+        @running = false
+        @thread = nil
+      end
+
+      def start
+        return @thread if @running
+
+        @running = true
+        @thread = Thread.new do
+          while @running
+            Takagi::ObserveRegistry.subscription_paths.each do |path|
+              observable_route = Takagi::Base.router.find_observable(path)
+              next unless observable_route
+
+              handler = observable_route.block
+              current_value = handler.call(nil)
+
+              Takagi::ObserveRegistry.notify(path, current_value)
+            end
+            sleep @interval
+          end
+          @thread
+        rescue StandardError => e
+          Takagi.logger.error "Observer Watcher Error: #{e.message}"
+        end
+      end
+
+      def stop
+        @running = false
+        @thread&.wakeup if @thread&.alive?
+        @thread&.join(2) # Wait max 2 seconds
+      end
+    end
+  end
+end

data/lib/takagi/plugin.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require 'rubygems'
+require_relative 'hooks'
+
+module Takagi
+  # Plugin manager: registers plugins, validates metadata/config, resolves dependencies, and emits lifecycle events.
+  class Plugin
+    PluginInfo = Struct.new(:name, :module, :enabled, :metadata, :dependencies, :requires, keyword_init: true)
+
+    @registry = {}
+    @mutex = Mutex.new
+
+    class << self
+      attr_reader :registry
+
+      # Register a plugin module that responds to .apply(app, opts = {}) and .metadata
+      def register(plugin_module)
+        metadata = safe_metadata(plugin_module)
+        raw_name = metadata[:name] || plugin_module.name&.split('::')&.last || "plugin_#{plugin_module.object_id}"
+        name = raw_name.to_sym
+
+        @mutex.synchronize do
+          # Return existing info if already registered
+          return @registry[name] if @registry.key?(name)
+
+          deps = Array(metadata[:dependencies]).map { |dep| normalize_dependency(dep) }
+          requires = metadata[:requires]
+
+          info = PluginInfo.new(
+            name: name.to_sym,
+            module: plugin_module,
+            enabled: false,
+            metadata: metadata,
+            dependencies: deps,
+            requires: requires
+          )
+
+          @registry[name.to_sym] = info
+          Takagi::Hooks.emit(:plugin_registered, name: name, metadata: metadata)
+          info
+        end
+      end
+
+      # Enable a plugin by name. Optionally pass options to apply.
+      def enable(name, app:, options: {})
+        info = @mutex.synchronize { @registry[name.to_sym] }
+        raise ArgumentError, "Plugin #{name} not registered" unless info
+        return info if info.enabled
+
+        validate_version!(info)
+        resolve_dependencies!(info, app: app)
+
+        validated_options = validate_config!(info.module, options, plugin_name: info.name)
+
+        app_for_plugin = wrap_app_with_prefix(app, info)
+
+        Takagi::Hooks.emit(:plugin_enabling, name: name, metadata: info.metadata, options: validated_options)
+        plugin = info.module
+        plugin.before_apply(app_for_plugin, validated_options) if plugin.respond_to?(:before_apply)
+        plugin.apply(app_for_plugin, validated_options)
+        plugin.after_apply(app_for_plugin, validated_options) if plugin.respond_to?(:after_apply)
+
+        info.enabled = true
+        Takagi::Hooks.emit(:plugin_enabled, name: name, metadata: info.metadata)
+        info
+      rescue StandardError => e
+        Takagi::Hooks.emit(:plugin_error, name: name, metadata: info&.metadata, error: e)
+        raise
+      end
+
+      def disable(name, app:)
+        info = @mutex.synchronize { @registry[name.to_sym] }
+        return unless info&.enabled
+
+        Takagi::Hooks.emit(:plugin_disabling, name: name, metadata: info.metadata)
+        plugin = info.module
+        plugin.before_unload(app) if plugin.respond_to?(:before_unload)
+        plugin.shutdown(app) if plugin.respond_to?(:shutdown)
+        info.enabled = false
+        Takagi::Hooks.emit(:plugin_disabled, name: name, metadata: info.metadata)
+        info
+      rescue StandardError => e
+        Takagi::Hooks.emit(:plugin_error, name: name, metadata: info&.metadata, error: e)
+        raise
+      end
+
+      def unregister(name)
+        @mutex.synchronize { @registry.delete(name.to_sym) }
+      end
+
+      def list
+        @mutex.synchronize { @registry.values.map { |info| { name: info.name, enabled: info.enabled, metadata: info.metadata } } }
+      end
+
+      # Auto-discover plugins under Takagi::Plugins namespace and takagi-plugin-* gems
+      def auto_discover!
+        discover_namespace_plugins
+        discover_gem_plugins
+      end
+
+      private
+
+      def wrap_app_with_prefix(app, info)
+        prefix = info.metadata[:route_prefix]
+        return app unless prefix
+
+        RoutePrefixProxy.new(app, prefix)
+      end
+
+      def safe_metadata(mod)
+        mod.respond_to?(:metadata) ? (mod.metadata || {}) : {}
+      rescue StandardError
+        {}
+      end
+
+      def validate_version!(info)
+        return unless info.requires && defined?(Takagi::VERSION)
+
+        # naive comparison; assumes semver strings
+        required = info.requires
+        current = Gem::Version.new(Takagi::VERSION) rescue nil
+        required_version = Gem::Version.new(required) rescue nil
+        return unless current && required_version
+
+        if current < required_version
+          raise ArgumentError, "Plugin #{info.name} requires Takagi #{required} but current is #{Takagi::VERSION}"
+        end
+      end
+
+      def resolve_dependencies!(info, app:)
+        return if info.dependencies.nil? || info.dependencies.empty?
+
+        info.dependencies.each do |dep_name|
+          dep_key = dep_name[:name]
+          dep = @mutex.synchronize { @registry[dep_key] }
+          raise ArgumentError, "Plugin #{info.name} missing dependency #{dep_key}" unless dep
+
+          if dep_name[:version] && dep.metadata[:version]
+            requirement = Gem::Requirement.new(dep_name[:version])
+            dep_version = Gem::Version.new(dep.metadata[:version])
+            unless requirement.satisfied_by?(dep_version)
+              raise ArgumentError, "Plugin #{info.name} requires #{dep_key} #{dep_name[:version]}, found #{dep.metadata[:version]}"
+            end
+          end
+
+          enable(dep.name, app: app) unless dep.enabled
+        end
+      end
+
+      def validate_config!(plugin_mod, options, plugin_name:)
+        return options unless plugin_mod.respond_to?(:config_schema)
+
+        schema = plugin_mod.config_schema || {}
+        opts = symbolize_keys(options || {})
+        validated = {}
+
+        schema.each do |key, rules|
+          value = opts.key?(key) ? opts[key] : rules[:default]
+
+          if value.nil? && rules[:required]
+            raise ArgumentError, "Missing required config for #{key} in plugin #{plugin_name}"
+          end
+
+          unless value.nil?
+            expected = rules[:type]
+            validate_type!(key, value, expected, plugin_name: plugin_name) if expected
+            validate_enum!(key, value, rules[:enum], plugin_name: plugin_name) if rules[:enum]
+            validate_range!(key, value, rules[:range], plugin_name: plugin_name) if rules[:range]
+            if rules[:validate].respond_to?(:call)
+              raise ArgumentError, "Invalid value for #{key} in plugin #{plugin_name}" unless rules[:validate].call(value)
+            end
+          end
+
+          validated[key] = value
+        end
+
+        # Pass through extra keys
+        opts.each do |k, v|
+          validated[k] = v unless validated.key?(k)
+        end
+
+        validated
+      end
+
+      def validate_type!(key, value, expected, plugin_name:)
+        ok = case expected
+             when :string then value.is_a?(String)
+             when :integer then value.is_a?(Integer)
+             when :boolean then value == true || value == false
+             when :hash then value.is_a?(Hash)
+             when :array then value.is_a?(Array)
+             else true
+             end
+        raise ArgumentError, "Invalid type for #{key} in plugin #{plugin_name}: expected #{expected}, got #{value.class}" unless ok
+      end
+
+      def validate_enum!(key, value, enum, plugin_name:)
+        return unless enum
+        raise ArgumentError, "Invalid value for #{key} in plugin #{plugin_name}: #{value}, expected one of #{enum.inspect}" unless enum.include?(value)
+      end
+
+      def validate_range!(key, value, range, plugin_name:)
+        return unless range && value.is_a?(Numeric)
+        raise ArgumentError, "Value for #{key} in plugin #{plugin_name} out of range #{range}" unless range.cover?(value)
+      end
+
+      def symbolize_keys(hash)
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+
+      def discover_namespace_plugins
+        return unless defined?(Takagi::Plugins)
+
+        Takagi::Plugins.constants.each do |const|
+          mod = Takagi::Plugins.const_get(const)
+          next unless mod.is_a?(Module)
+          next unless mod.respond_to?(:apply)
+
+          register(mod) unless @registry.key?(infer_name(mod))
+        end
+      rescue StandardError
+        nil
+      end
+
+      def discover_gem_plugins
+        specs = Gem::Specification.each.select { |s| s.name.start_with?('takagi-plugin-') }
+        specs.each do |spec|
+          begin
+            require spec.name
+          rescue LoadError => e
+            Takagi::Hooks.emit(:plugin_error, name: spec.name, metadata: nil, error: e)
+            next
+          end
+
+          mod = infer_module_from_gem(spec)
+          register(mod) if mod && mod.respond_to?(:apply) && !@registry.key?(infer_name(mod))
+        end
+      end
+
+      def infer_name(mod)
+        if mod.respond_to?(:metadata) && mod.metadata && mod.metadata[:name]
+          mod.metadata[:name].to_sym
+        elsif mod.name
+          mod.name.split('::').last.downcase.to_sym
+        end
+      end
+
+      def infer_module_from_gem(spec)
+        return unless defined?(Takagi::Plugins)
+
+        suffix = spec.name.sub(/^takagi-plugin-/, '')
+        const_name = suffix.split(/[-_]/).map(&:capitalize).join
+        Takagi::Plugins.const_get(const_name)
+      rescue NameError
+        nil
+      end
+
+      def normalize_dependency(dep)
+        return { name: dep.to_sym } unless dep.is_a?(Hash)
+
+        {
+          name: (dep[:name] || dep['name']).to_sym,
+          version: dep[:version] || dep['version']
+        }
+      end
+    end
+  end
+end
+
+# Wraps the app to prefix routes registered by a plugin.
+class Takagi::Plugin::RoutePrefixProxy
+  ROUTE_METHODS = %i[get post put delete fetch observable observe].freeze
+
+  def initialize(app, prefix)
+    @app = app
+    @prefix = normalize_prefix(prefix)
+  end
+
+  ROUTE_METHODS.each do |method_name|
+    define_method(method_name) do |path, *args, **kwargs, &block|
+      prefixed_path = prefix_path(path)
+      @app.public_send(method_name, prefixed_path, *args, **kwargs, &block)
+    end
+  end
+
+  def method_missing(name, *args, **kwargs, &block)
+    if @app.respond_to?(name)
+      @app.public_send(name, *args, **kwargs, &block)
+    else
+      super
+    end
+  end
+
+  def respond_to_missing?(name, include_private = false)
+    @app.respond_to?(name, include_private) || super
+  end
+
+  private
+
+  def prefix_path(path)
+    return path unless path.is_a?(String)
+
+    "#{@prefix}#{path}".gsub(%r{//+}, '/')
+  end
+
+  def normalize_prefix(prefix)
+    str = prefix.to_s
+    return '' if str.empty?
+
+    str.start_with?('/') ? str : "/#{str}"
+  end
+end

data/lib/takagi/profiles.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Takagi
+  # Load profiles for different IoT/CoAP use cases
+  #
+  # Provides predefined configurations for common scenarios to simplify
+  # performance tuning without manual process/thread configuration.
+  #
+  # @example Using a profile
+  #   class TelemetryController < Takagi::Controller
+  #     configure do
+  #       profile :high_throughput
+  #     end
+  #   end
+  #
+  # @example Profile with overrides
+  #   class TelemetryController < Takagi::Controller
+  #     configure do
+  #       profile :high_throughput
+  #       set :processes, 16  # Override default
+  #     end
+  #   end
+  module Profiles
+    # Predefined load profiles for common IoT scenarios
+    PROFILES = {
+      # For devices with minimal traffic (single worker)
+      # Use case: Status endpoints, health checks on constrained devices
+      minimal: {
+        processes: 1,
+        threads: 1,
+        description: 'Single-threaded, lowest resource usage for constrained devices'
+      }.freeze,
+
+      # For typical low-traffic device endpoints
+      # Use case: Configuration, device status, infrequent queries
+      low_traffic: {
+        processes: 1,
+        threads: 2,
+        description: 'Configuration, status endpoints with light traffic'
+      }.freeze,
+
+      # For observable endpoints with long-lived connections
+      # Use case: CoAP Observe, streaming sensor data, push notifications
+      long_lived: {
+        processes: 2,
+        threads: 8,
+        description: 'Observable resources, long-lived connections (CoAP Observe)'
+      }.freeze,
+
+      # For high-volume sensor data ingestion
+      # Use case: Telemetry, sensor data from many devices, high req/sec
+      high_throughput: {
+        processes: 8,
+        threads: 4,
+        description: 'High-volume sensor telemetry and data ingestion'
+      }.freeze,
+
+      # For firmware updates, images, large file transfers
+      # Use case: OTA updates, firmware downloads, large payloads
+      large_payloads: {
+        processes: 2,
+        threads: 2,
+        buffer_size: 10 * 1024 * 1024, # 10MB
+        description: 'Firmware updates, file transfers, large payloads'
+      }.freeze,
+
+      # Custom configuration (must specify all parameters)
+      # Use case: Fine-tuned performance for specific requirements
+      custom: {
+        processes: nil,
+        threads: nil,
+        description: 'User-defined custom configuration'
+      }.freeze
+    }.freeze
+
+    class << self
+      # Get a profile by name
+      #
+      # @param name [Symbol] Profile name
+      # @return [Hash, nil] Profile configuration or nil if not found
+      #
+      # @example
+      #   Profiles.get(:high_throughput)
+      #   # => { processes: 8, threads: 4, description: '...' }
+      def get(name)
+        PROFILES[name]&.dup # Return copy to prevent modification
+      end
+
+      # Check if a profile exists
+      #
+      # @param name [Symbol] Profile name
+      # @return [Boolean] true if profile exists
+      #
+      # @example
+      #   Profiles.exists?(:high_throughput)  # => true
+      #   Profiles.exists?(:unknown)          # => false
+      def exists?(name)
+        PROFILES.key?(name)
+      end
+
+      # Get all available profile names
+      #
+      # @return [Array<Symbol>] List of profile names
+      #
+      # @example
+      #   Profiles.available
+      #   # => [:minimal, :low_traffic, :long_lived, :high_throughput, :large_payloads, :custom]
+      def available
+        PROFILES.keys
+      end
+
+      # Get human-readable summary of all profiles
+      #
+      # @return [String] Formatted summary
+      #
+      # @example
+      #   puts Profiles.summary
+      def summary
+        lines = ['Available Load Profiles:']
+        PROFILES.each do |name, config|
+          lines << ''
+          lines << "  #{name}:"
+          lines << "    Description: #{config[:description]}"
+          lines << "    Processes: #{config[:processes] || 'custom'}"
+          lines << "    Threads: #{config[:threads] || 'custom'}"
+          lines << "    Buffer Size: #{config[:buffer_size]}" if config[:buffer_size]
+        end
+        lines.join("\n")
+      end
+
+      # Validate profile configuration
+      #
+      # @param name [Symbol] Profile name
+      # @param config [Hash] Configuration to validate
+      # @raise [ArgumentError] if profile is invalid
+      #
+      # @return [void]
+      def validate!(name, config = nil)
+        config ||= get(name)
+
+        raise ArgumentError, "Unknown profile: #{name}" unless exists?(name)
+
+        if name == :custom
+          raise ArgumentError, 'Custom profile requires :processes' unless config[:processes]
+          raise ArgumentError, 'Custom profile requires :threads' unless config[:threads]
+        end
+
+        if config[:processes] && config[:processes] < 1
+          raise ArgumentError, 'Processes must be >= 1'
+        end
+
+        if config[:threads] && config[:threads] < 1
+          raise ArgumentError, 'Threads must be >= 1'
+        end
+      end
+
+      # Apply a profile to a configuration hash
+      #
+      # @param name [Symbol] Profile name
+      # @param overrides [Hash] Optional overrides
+      # @return [Hash] Merged configuration
+      #
+      # @example
+      #   Profiles.apply(:high_throughput, processes: 16)
+      #   # => { processes: 16, threads: 4, description: '...' }
+      def apply(name, overrides = {})
+        profile = get(name)
+        raise ArgumentError, "Unknown profile: #{name}" unless profile
+
+        merged = profile.merge(overrides)
+        validate!(name, merged)
+        merged
+      end
+    end
+  end
+end