takagi 0.1.0 → 1.1.0

data/lib/takagi/application.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+module Takagi
+  # Application class for modular controller-based apps
+  #
+  # Application provides a centralized way to mount and manage multiple
+  # controllers, auto-load controller files, and run the server.
+  #
+  # @example Simple application
+  #   class MyApp < Takagi::Application
+  #     configure do
+  #       load_controllers TelemetryController, ConfigController
+  #     end
+  #   end
+  #
+  #   MyApp.run!(port: 5683)
+  #
+  # @example With auto-loading
+  #   class MyApp < Takagi::Application
+  #     configure do
+  #       auto_load 'app/controllers/**/*_controller.rb'
+  #     end
+  #   end
+  #
+  #   MyApp.run!
+  class Application
+    # Internal controller for CoRE Link Format discovery endpoint
+    # Automatically mounted by Application
+    class DiscoveryController < Controller
+      @@app_router = nil
+
+      def self.app_router=(router)
+        @@app_router = router
+      end
+
+      def self.app_router
+        @@app_router
+      end
+
+      configure do
+        mount '/.well-known'
+      end
+
+      get '/core', metadata: {
+        rt: 'core.discovery',
+        if: 'core.rd',
+        ct: Discovery::CoreLinkFormat::CONTENT_FORMAT,
+        discovery: true,
+        title: 'Resource Discovery'
+      } do |req|
+        # Get the composite router from the application
+        app_router = DiscoveryController.app_router
+        payload = Discovery::CoreLinkFormat.generate(router: app_router, request: req)
+        req.to_response(
+          '2.05 Content',
+          payload,
+          options: { CoAP::Registries::Option::CONTENT_FORMAT => Discovery::CoreLinkFormat::CONTENT_FORMAT }
+        )
+      end
+    end
+
+    class << self
+      # Get the application's composite router
+      #
+      # @return [CompositeRouter] The application's router
+      def router
+        @router ||= CompositeRouter.new
+      end
+
+      # Get the application's configuration
+      #
+      # @return [Hash] Configuration hash
+      def config
+        @config ||= {
+          controllers: [],
+          auto_load_patterns: [],
+          allocation_mode: :automatic,  # :manual or :automatic
+          total_threads: nil             # For automatic mode
+        }
+      end
+
+      # Configure the application
+      #
+      # @yield Block for configuration DSL
+      #
+      # @example
+      #   configure do
+      #     load_controllers TelemetryController, ConfigController
+      #     auto_load 'app/controllers/**/*_controller.rb'
+      #   end
+      def configure(&block)
+        ConfigContext.new(self).instance_eval(&block) if block
+      end
+
+      # Load and mount all registered controllers
+      #
+      # @return [void]
+      def load_controllers!
+        # Load auto-discovered controllers
+        auto_load_controllers! if config[:auto_load_patterns].any?
+
+        # Mount discovery controller first (so it's available at /.well-known/core)
+        # Store reference to composite router for discovery endpoint
+        DiscoveryController.app_router = router
+        router.mount(DiscoveryController)
+
+        # Mount all registered controllers
+        config[:controllers].each do |controller_class|
+          router.mount(controller_class)
+        end
+      end
+
+      # Start worker thread pools for all controllers
+      #
+      # Allocates thread pool resources based on allocation_mode:
+      # - :manual - Controllers use their explicit thread_count or profile settings
+      # - :automatic - Divides total_threads proportionally by profile weights
+      #
+      # @return [void]
+      def start_all_workers!
+        # Use app config first, fall back to global config
+        mode = config[:allocation_mode] || Takagi.config.allocation.mode
+        total_threads = config[:total_threads] || Takagi.config.allocation.total_threads
+        controllers_to_allocate = config[:controllers] + [DiscoveryController]
+
+        # Calculate allocations based on mode
+        allocations = Controller::ResourceAllocator.allocate(
+          controllers: controllers_to_allocate,
+          mode: mode,
+          total_threads: total_threads,
+          protocol: :tcp  # TCP uses threads, UDP uses processes
+        )
+
+        # Validate allocations if automatic mode with total_threads specified
+        if mode == :automatic && total_threads
+          Controller::ResourceAllocator.validate!(allocations, total_threads: total_threads)
+        end
+
+        # Start each controller's thread pool
+        allocations.each do |controller_class, allocation|
+          threads = allocation[:threads]
+          next unless threads && threads > 0
+
+          controller_class.start_workers!(
+            threads: threads,
+            name: controller_class.name.split('::').last
+          )
+
+          Takagi.logger.info "Allocated #{threads} threads to #{controller_class.name} (mode: #{mode})"
+        end
+      end
+
+      # Shutdown all controller worker thread pools
+      #
+      # @return [void]
+      def shutdown_all_workers!
+        all_controllers = config[:controllers] + [DiscoveryController]
+
+        all_controllers.each do |controller_class|
+          controller_class.shutdown_workers! if controller_class.workers_running?
+        end
+      end
+
+      # Run the application server
+      #
+      # @param options [Hash] Server options (port, protocols, etc.)
+      # @return [void]
+      #
+      # @example
+      #   MyApp.run!(port: 5683, protocols: [:udp, :tcp])
+      def run!(**options)
+        # Load all controllers
+        load_controllers!
+
+        # Start controller worker pools
+        start_all_workers!
+
+        # Use the composite router instead of global singleton
+        options[:router] = router
+
+        # Delegate to server lifecycle (same as Takagi::Base)
+        Base::ServerLifecycle.run!(**options)
+      end
+
+      # Get all loaded controller classes
+      #
+      # @return [Array<Class>] List of controller classes
+      def controllers
+        config[:controllers]
+      end
+
+      private
+
+      # Auto-load controllers from file patterns
+      #
+      # @return [void]
+      def auto_load_controllers!
+        config[:auto_load_patterns].each do |pattern|
+          Dir.glob(pattern).each do |file|
+            require_relative file
+          end
+        end
+      end
+    end
+
+    # Configuration DSL context for Application
+    class ConfigContext
+      def initialize(app_class)
+        @app = app_class
+      end
+
+      # Load specific controller classes
+      #
+      # @param controllers [Array<Class>] Controller classes to load
+      #
+      # @example
+      #   load_controllers TelemetryController, ConfigController
+      def load_controllers(*controllers)
+        @app.config[:controllers].concat(controllers)
+      end
+
+      # Auto-load controllers from file pattern
+      #
+      # @param pattern [String] Glob pattern for controller files
+      #
+      # @example
+      #   auto_load 'app/controllers/**/*_controller.rb'
+      def auto_load(pattern)
+        @app.config[:auto_load_patterns] << pattern
+      end
+
+      # Configure worker allocation mode
+      #
+      # @param mode [Symbol] :manual or :automatic
+      # @param threads [Integer] Total threads for automatic mode
+      #
+      # @example Manual allocation (controllers specify their own thread counts)
+      #   allocation :manual
+      #
+      # @example Automatic allocation (divide 40 threads among controllers)
+      #   allocation :automatic, threads: 40
+      def allocation(mode, threads: nil)
+        unless [:manual, :automatic].include?(mode)
+          raise ArgumentError, "Invalid allocation mode: #{mode}. Use :manual or :automatic"
+        end
+
+        if mode == :automatic && threads.nil?
+          raise ArgumentError, "Automatic allocation requires threads: parameter"
+        end
+
+        @app.config[:allocation_mode] = mode
+        @app.config[:total_threads] = threads
+      end
+    end
+  end
+end

data/lib/takagi/base/middleware_management.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Takagi
+  class Base < Router
+    # Manages middleware stack configuration and request processing.
+    #
+    # Extracted from Base class to follow Single Responsibility Principle.
+    # Handles middleware registration and stack initialization.
+    module MiddlewareManagement
+      # Processes a request through the middleware stack
+      #
+      # @param request [Message::Inbound] Incoming CoAP request
+      # @return [Message::Outbound] Response after middleware processing
+      def call(request)
+        middleware_stack.call(request)
+      end
+
+      # Returns the middleware stack instance
+      #
+      # Lazily initializes the middleware stack with default configuration
+      #
+      # @return [MiddlewareStack] The middleware stack instance
+      def middleware_stack
+        @middleware_stack ||= Takagi::MiddlewareStack.load_from_config('', router)
+      end
+
+      # Adds a middleware to the stack
+      #
+      # @param middleware [Object] Middleware instance responding to #call
+      #
+      # @example
+      #   use CustomMiddleware.new
+      #   use Takagi::Middleware::Caching.new(ttl: 300)
+      def use(middleware)
+        middleware_stack.use(middleware)
+      end
+    end
+  end
+end

data/lib/takagi/base/plugin_management.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative '../plugin'
+require_relative '../hooks'
+
+module Takagi
+  class Base < Router
+    # Provides a simple DSL for declaring and enabling plugins on boot.
+    module PluginManagement
+      def plugin(plugin_ref, order: 0, **options)
+        plugins_config << { ref: plugin_ref, options: options, order: order }
+      end
+
+      def enable_plugins!(app: self)
+        load_config_plugins
+        Takagi::Plugin.auto_discover! if Takagi.config.plugins.auto_discover
+
+        merged = merged_plugins
+        merged.each do |entry|
+          mod = resolve_plugin(entry[:ref])
+          info = Takagi::Plugin.register(mod)
+          Takagi::Plugin.enable(info.name, app: app, options: entry[:options])
+        end
+      end
+
+      private
+
+      def plugins_config
+        @plugins_config ||= []
+      end
+
+      def load_config_plugins
+        config_entries = Array(Takagi.config.plugins.enabled)
+        config_entries.each do |entry|
+          if entry.is_a?(Hash)
+            plugins_config << {
+              ref: entry[:name] || entry['name'],
+              options: entry[:options] || entry['options'] || {},
+              order: entry[:order] || entry['order'] || 0
+            }
+          else
+            plugins_config << { ref: entry, options: {}, order: 0 }
+          end
+        end
+      end
+
+      def merged_plugins
+        seen = {}
+        plugins_config.reverse_each do |entry|
+          key = entry[:ref].to_s
+          seen[key] ||= entry
+        end
+        seen.values.reverse.sort_by { |entry| entry[:order] || 0 }
+      end
+
+      def resolve_plugin(ref)
+        return ref if ref.is_a?(Module)
+
+        # Try Takagi::Plugins::<Name>
+        if ref.is_a?(Symbol) || ref.is_a?(String)
+          const_name = ref.to_s.split('_').map(&:capitalize).join
+          begin
+            return Takagi::Plugins.const_get(const_name)
+          rescue NameError
+            # fall through
+          end
+          # Try fully qualified
+          return Object.const_get(ref.to_s)
+        end
+
+        raise ArgumentError, "Unknown plugin reference: #{ref.inspect}"
+      end
+    end
+  end
+end

data/lib/takagi/base/reactor_management.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Takagi
+  class Base < Router
+    # Manages reactor registration and lifecycle for observable/observer patterns.
+    #
+    # Supports both inline reactor definitions and file-based reactor classes.
+    # Provides DSL for defining observables and observers.
+    module ReactorManagement
+      # Defines a reactor using a DSL block (inline definition)
+      #
+      # The block is evaluated in the context of a new Reactor instance,
+      # allowing you to define observables and observers inline.
+      #
+      # @param threads [Integer] Number of threads for the reactor (default: 2)
+      # @param name [String] Optional name for the reactor
+      # @param interval [Float] Default polling interval in seconds (default: 1.0)
+      # @yield Block defining reactor configuration
+      #
+      # @example Event-driven observable
+      #   reactor threads: 4 do
+      #     observable '/temperature' do |emitter|
+      #       emitter.on_event('sensor.temp.changed')
+      #     end
+      #   end
+      #
+      # @example Polling observable
+      #   reactor do
+      #     observable_polling '/status', interval: 5.0 do
+      #       { status: check_status, uptime: uptime }
+      #     end
+      #   end
+      #
+      # @example Remote observation
+      #   reactor do
+      #     observe 'coap://sensor:5683/temp' do |data|
+      #       process_temperature(data)
+      #     end
+      #   end
+      def reactor(threads: 2, name: nil, interval: 1.0, &block)
+        reactor_name = name || "#{self.name.split('::').last.downcase}-reactor"
+        reactor_instance = Takagi::Observable::Reactor.new(
+          threads: threads,
+          name: reactor_name,
+          interval: interval
+        )
+        reactor_instance.instance_eval(&block)
+
+        # Register with Observable::Registry
+        Takagi::Observable::Registry.register(reactor_name.to_sym, reactor_instance)
+
+        reactor_instance
+      end
+
+      # Registers a file-based reactor class instance
+      #
+      # Use this to register reactors defined in separate files (e.g., app/reactors/).
+      # The reactor class should inherit from Takagi::Observable::Reactor.
+      #
+      # @param name [Symbol] Unique identifier for the reactor
+      # @param klass_or_instance [Class, Reactor] Reactor class or instance
+      #
+      # @example Register reactor class
+      #   class IotReactor < Takagi::Observable::Reactor
+      #     def initialize
+      #       super(threads: 8, name: 'iot')
+      #       setup_device_observables
+      #     end
+      #   end
+      #
+      #   use_reactor :iot, IotReactor
+      #
+      # @example Register reactor instance
+      #   use_reactor :sensors, SensorReactor.new
+      def use_reactor(name, klass_or_instance)
+        reactor_instance = if klass_or_instance.is_a?(Class)
+                             klass_or_instance.new
+                           else
+                             klass_or_instance
+                           end
+
+        Takagi::Observable::Registry.register(name.to_sym, reactor_instance)
+        reactor_instance
+      end
+
+      # Starts all registered reactors
+      #
+      # Called automatically by server lifecycle management during boot.
+      # Can be called manually if needed.
+      #
+      # @return [void]
+      def start_reactors
+        Takagi::Observable::Registry.start_all
+      end
+
+      # Stops all registered reactors
+      #
+      # @return [void]
+      def stop_reactors
+        Takagi::Observable::Registry.stop_all
+      end
+    end
+  end
+end

data/lib/takagi/base/server_lifecycle.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative '../branding'
+
+module Takagi
+  class Base < Router
+    # Manages server lifecycle operations: booting, running, and spawning servers.
+    #
+    # Extracted from Base class to follow Single Responsibility Principle.
+    # Handles configuration loading, server instantiation, and process management.
+    module ServerLifecycle
+      # Boots the application by loading configuration and running initializers
+      #
+      # @param config_path [String] Path to configuration file
+      def boot!(config_path: 'config/takagi.yml')
+        Takagi.config.load_file(config_path) if File.exist?(config_path)
+        Takagi::Initializer.run!
+      end
+
+      # Runs the server in the foreground (blocking)
+      #
+      # @param port [Integer, nil] Port to bind to (uses config if nil)
+      # @param config_path [String] Path to configuration file
+      # @param protocols [Array<Symbol>, nil] Protocols to enable (uses config if nil)
+      # @param router [Router, CompositeRouter, nil] Custom router (uses global if nil)
+      # @param banner [Boolean] Show startup banner (default: true)
+      def run!(port: nil, config_path: 'config/takagi.yml', protocols: nil, router: nil, banner: true)
+        boot!(config_path: config_path)
+        enable_plugins!(app: self)
+
+        # Show startup banner
+        if banner
+          print_startup_banner(
+            port: port || Takagi.config.port,
+            protocols: protocols || Takagi.config.protocols,
+            router: router || self.router  # Pass router to banner
+          )
+        end
+
+        selected_port = port || Takagi.config.port
+        servers = build_servers(protocols || Takagi.config.protocols, selected_port, router: router)
+        run_servers(servers)
+      end
+
+      # Spawns servers in background threads
+      #
+      # @param port [Integer] Port to bind to
+      # @param protocols [Array<Symbol>, nil] Protocols to enable (uses config if nil)
+      # @return [Server, Multi] The spawned server instance
+      def spawn!(port: 5683, protocols: nil)
+        protos = if protocols
+                   Array(protocols)
+                 else
+                   Takagi.config.protocols
+                 end.map(&:to_sym)
+
+        servers = protos.map do |proto|
+          # Temporary backward compatibility - will use registry after transition
+          proto == :tcp ? Takagi::Server::Tcp.new(port: port) : Takagi::Server::Udp.new(port: port)
+        end
+
+        if servers.length == 1
+          server = servers.first
+          thread = Thread.new { server.run! }
+          # Store thread reference on the server instance for cleanup
+          server.instance_variable_set(:@server_thread, thread)
+          server
+        else
+          multi = Takagi::Server::Multi.new(servers)
+          thread = Thread.new { multi.run! }
+          # Store thread reference on the multi instance for cleanup
+          multi.instance_variable_set(:@server_thread, thread)
+          multi
+        end
+      end
+
+      private
+
+      # Prints startup banner with Takagi branding
+      #
+      # @param port [Integer] Port server will bind to
+      # @param protocols [Array<Symbol>] Protocols being enabled
+      # @param router [Router] Router instance to count routes from
+      def print_startup_banner(port:, protocols:, router:)
+        # Print banner
+        Branding.print_banner(compact: false)
+
+        # Version info
+        version = defined?(Takagi::VERSION) ? Takagi::VERSION : '0.1.0'
+        Branding.print_version(version)
+
+        puts
+        puts Branding.section('Starting Server')
+
+        # Server info
+        puts Branding.log("Port: #{port}")
+        puts Branding.log("Protocols: #{protocols.map(&:to_s).map(&:upcase).join(', ')}")
+        puts Branding.log("Threads: #{Takagi.config.threads}")
+        puts Branding.log("Processes: #{Takagi.config.processes}") if Takagi.config.processes > 0
+
+        # Route count
+        route_count = router.instance_variable_get(:@routes)&.size || 0
+        puts Branding.log("Routes registered: #{route_count}")
+
+        puts
+        puts Branding.success('Server starting...')
+        puts Branding.info('Press Ctrl+C to shutdown')
+        puts
+        puts Branding::WAVE_LINE
+        puts
+      end
+
+      # Builds server instances for the given protocols
+      #
+      # @param protocols [Array<Symbol>] Protocol identifiers
+      # @param port [Integer] Port to bind to
+      # @param router [Router, CompositeRouter, nil] Custom router (uses global if nil)
+      # @return [Array<Server>] Array of server instances
+      def build_servers(protocols, port, router: nil)
+        threads = Takagi.config.threads
+        processes = Takagi.config.processes
+        Array(protocols).map(&:to_sym).map do |protocol|
+          instantiate_server(protocol, port, threads: threads, processes: processes, router: router)
+        end
+      end
+
+      # Instantiates a server for the given protocol using ServerRegistry
+      #
+      # @param protocol [Symbol] Protocol identifier (:udp, :tcp, etc.)
+      # @param port [Integer] Port to bind to
+      # @param threads [Integer] Number of worker threads
+      # @param processes [Integer] Number of worker processes (UDP only)
+      # @param router [Router, CompositeRouter, nil] Custom router (uses global if nil)
+      # @return [Server] Server instance
+      def instantiate_server(protocol, port, threads:, processes:, router: nil)
+        options = { port: port }
+        options[:worker_threads] = threads
+        options[:router] = router if router
+
+        # UDP requires worker_processes, TCP doesn't use it
+        options[:worker_processes] = processes if protocol == :udp
+        Takagi.logger.debug("Instantiating server for #{protocol} on port #{port} with #{options}")
+        Server::Registry.build(protocol, **options)
+      end
+
+      # Runs servers (single or multi-protocol)
+      #
+      # @param servers [Array<Server>] Server instances to run
+      def run_servers(servers)
+        return servers.first.run! if servers.length == 1
+
+        Takagi::Server::Multi.new(servers).run!
+      end
+    end
+  end
+end