takagi 0.1.0 → 1.1.0

data/sig/takagi/discovery/core_link_format.rbs

@@ -0,0 +1,50 @@
+module Takagi
+  module Discovery
+    # Builds CoRE Link Format payloads as defined in RFC 6690.
+    class CoreLinkFormat
+      @router: untyped
+
+      @query: untyped
+
+      CONTENT_FORMAT: 40
+
+      def self.generate: (router: untyped, ?request: untyped?) -> untyped
+
+      def initialize: (untyped router, untyped raw_query) -> void
+
+      def generate: () -> untyped
+
+      private
+
+      attr_reader router: untyped
+
+      attr_reader query: untyped
+
+      def parse_query: (untyped raw_query) -> (::Hash[untyped, untyped] | untyped)
+
+      def filter_resources: (untyped resources) -> untyped
+
+      def matches_filter?: (untyped entry, untyped key, untyped values) -> untyped
+
+      def matches_list_attribute?: (untyped entry, untyped attribute, untyped values) -> untyped
+
+      def matches_numeric_attribute?: (untyped entry, untyped attribute, untyped values) -> untyped
+
+      def matches_string_attribute?: (untyped entry, untyped attribute, untyped values) -> untyped
+
+      def format_entry: (untyped entry) -> ::String
+
+      def normalize_path: (untyped path) -> untyped
+
+      def link_attributes_for: (untyped entry) -> untyped
+
+      def append_attribute: (untyped attrs, untyped name, untyped value) -> (nil | untyped)
+
+      def append_numeric_attribute: (untyped attrs, untyped name, untyped value) -> (nil | untyped)
+
+      def join_attributes: (untyped attrs) -> untyped
+
+      def server_link_entry: () -> (nil | untyped)
+    end
+  end
+end

data/sig/takagi/event_bus/address_prefix.rbs

@@ -0,0 +1,78 @@
+module Takagi
+  class EventBus
+    # EventBus Address Prefix Registry
+    #
+    # Defines which event address prefixes are distributed via CoAP
+    # and which remain local-only.
+    #
+    # Extensible registry allows plugins to register custom prefixes
+    # without modifying core code.
+    #
+    # @example Using predefined prefixes
+    #   AddressPrefix.distributed?('sensor.temperature.room1')  # => true
+    #   AddressPrefix.distributed?('system.startup')            # => false
+    #
+    # @example Registering a custom distributed prefix
+    #   AddressPrefix.register_distributed('custom.', 'Custom Events')
+    #
+    # @example Registering a custom local prefix
+    #   AddressPrefix.register_local('internal.', 'Internal Events')
+    class AddressPrefix
+      self.@distributed: untyped
+
+      self.@local: untyped
+
+      self.@mutex: untyped
+
+      # Register a distributed prefix (events are published via CoAP)
+      # @param prefix [String] Address prefix (e.g., 'sensor.')
+      # @param description [String] Human-readable description
+      # @param rfc [String, nil] Optional RFC reference
+      def self.register_distributed: (untyped prefix, untyped description, ?rfc: untyped?) -> untyped
+
+      # Register a local-only prefix (events stay in-process)
+      # @param prefix [String] Address prefix (e.g., 'system.')
+      # @param description [String] Human-readable description
+      # @param rfc [String, nil] Optional RFC reference
+      def self.register_local: (untyped prefix, untyped description, ?rfc: untyped?) -> untyped
+
+      # Check if address matches a distributed prefix
+      # @param address [String] Event address
+      # @return [Boolean] true if distributed
+      def self.distributed?: (untyped address) -> (false | untyped)
+
+      # Check if address matches a local-only prefix
+      # @param address [String] Event address
+      # @return [Boolean] true if local-only
+      def self.local?: (untyped address) -> untyped
+
+      # Get all distributed prefixes
+      # @return [Hash] Map of prefix => metadata
+      def self.distributed_prefixes: () -> untyped
+
+      # Get all local prefixes
+      # @return [Hash] Map of prefix => metadata
+      def self.local_prefixes: () -> untyped
+
+      # Get all registered prefixes
+      # @return [Hash] Combined map of all prefixes
+      def self.all: () -> untyped
+
+      # Get metadata for a specific prefix
+      # @param prefix [String] The prefix to look up
+      # @return [Hash, nil] Prefix metadata
+      def self.metadata_for: (untyped prefix) -> untyped
+
+      # Unregister a prefix (useful for testing/plugins)
+      # @param prefix [String] The prefix to remove
+      # @return [Boolean] true if was registered
+      def self.unregister: (untyped prefix) -> untyped
+
+      # Clear all registrations (useful for testing)
+      def self.clear!: () -> untyped
+
+      # Initialize default prefixes
+      def self.initialize_defaults!: () -> untyped
+    end
+  end
+end

data/sig/takagi/event_bus/async_executor.rbs

@@ -0,0 +1,88 @@
+module Takagi
+  class EventBus
+    module AsyncExecutor
+      # Thread-based executor (default fallback)
+      class ThreadExecutor
+        @size: untyped
+
+        @queue: untyped
+
+        @threads: untyped
+
+        @shutdown: untyped
+
+        attr_reader size: untyped
+
+        def initialize: (size: untyped) -> void
+
+        def post: (untyped handler, untyped message) -> untyped
+
+        def register_handler: (untyped _handler) -> nil
+
+        def unregister_handler: (untyped _handler) -> nil
+
+        def shutdown: () -> (nil | untyped)
+
+        def running?: () -> untyped
+
+        def stats: () -> { mode: :threads, size: untyped }
+
+        private
+
+        def start_workers: () -> untyped
+      end
+
+      # Process-based executor for multi-reactor workloads
+      class ProcessExecutor
+        @processes: untyped
+
+        @threads: untyped
+
+        @mutex: untyped
+
+        @jobs: untyped
+
+        @next_index: untyped
+
+        @needs_restart: untyped
+
+        Job: untyped
+
+        def initialize: (processes: untyped, threads: untyped) -> void
+
+        def post: (untyped handler, untyped message) -> untyped
+
+        # Mark for restart so new handlers are visible in workers
+        def register_handler: (untyped _handler) -> untyped
+
+        def unregister_handler: (untyped _handler) -> untyped
+
+        def shutdown: () -> untyped
+
+        def stats: () -> { mode: :processes, size: untyped }
+
+        private
+
+        def ensure_running: () -> (nil | untyped)
+
+        def mark_restart_needed: () -> untyped
+
+        def restart_workers_locked: () -> untyped
+
+        def shutdown_workers: () -> untyped
+
+        def spawn_workers_locked: () -> (nil | untyped)
+
+        def fork_worker: (untyped index) -> untyped
+
+        def run_worker: (untyped reader, untyped index) -> untyped
+
+        def dispatch: (untyped handler, untyped message) -> (nil | untyped)
+
+        def select_job: () -> untyped
+
+        def reopen_worker: (untyped index) -> untyped
+      end
+    end
+  end
+end

data/sig/takagi/event_bus/coap_bridge.rbs

@@ -0,0 +1,93 @@
+module Takagi
+  class EventBus
+    # CoAP Observe integration - maps events to CoAP resources
+    # Thread-safe with Mutex for resource registration
+    #
+    # Maps EventBus addresses to CoAP observable resources:
+    # - "sensor.temperature.room1" -> "/events/sensor/temperature/room1"
+    #
+    # @example
+    #   CoAPBridge.register_observable_resource('sensor.temp.room1', app)
+    #   CoAPBridge.publish_to_observers('sensor.temp.room1', message)
+    class CoAPBridge
+      self.@registered_resources: untyped
+
+      self.@mutex: untyped
+
+      # Convert event address to CoAP path
+      # @param address [String] Event address (e.g., "sensor.temperature.room1")
+      # @return [String] CoAP path (e.g., "/events/sensor/temperature/room1")
+      #
+      # @example
+      #   CoAPBridge.address_to_path('sensor.temperature.room1')
+      #   # => "/events/sensor/temperature/room1"
+      def self.address_to_path: (untyped address) -> ::String
+
+      # Convert CoAP path to event address
+      # @param path [String] CoAP path (e.g., "/events/sensor/temperature/room1")
+      # @return [String] Event address (e.g., "sensor.temperature.room1")
+      #
+      # @example
+      #   CoAPBridge.path_to_address('/events/sensor/temperature/room1')
+      #   # => "sensor.temperature.room1"
+      def self.path_to_address: (untyped path) -> untyped
+
+      # Auto-register observable CoAP resource (thread-safe)
+      # Creates a CoAP observable endpoint that returns current state
+      #
+      # Uses AddressPrefix registry to determine if address should be distributed
+      #
+      # @param address [String] Event address
+      # @param app [Class] Application class (must respond to #observable)
+      # @return [Boolean] True if registered, false if already exists
+      #
+      # @example
+      #   CoAPBridge.register_observable_resource('sensor.temp.room1', MyApp)
+      def self.register_observable_resource: (untyped address, untyped app) -> (false | untyped)
+
+      # Publish event to all CoAP observers
+      # Notifies all observers subscribed via CoAP Observe
+      #
+      # @param address [String] Event address
+      # @param message [EventBus::Message] Event message
+      #
+      # @example
+      #   message = EventBus::Message.new('sensor.temp.room1', { value: 25.5 })
+      #   CoAPBridge.publish_to_observers('sensor.temp.room1', message)
+      def self.publish_to_observers: (untyped address, untyped message) -> untyped
+
+      # Subscribe to remote event via CoAP Observe
+      # @param address [String] Event address
+      # @param node_url [String] Remote node URL (e.g., 'coap://building-a:5683')
+      # @yield [message] Block called when remote notification received
+      # @return [String] Subscription ID
+      #
+      # @example
+      #   id = CoAPBridge.subscribe_remote('sensor.temp.buildingA', 'coap://building-a:5683') do |msg|
+      #     puts "Remote temp: #{msg.body[:value]}"
+      #   end
+      def self.subscribe_remote: (untyped address, untyped node_url) -> untyped
+
+      # Check if resource is registered
+      # @param address [String] Event address
+      # @return [Boolean]
+      def self.registered?: (untyped address) -> untyped
+
+      # Get all registered resource addresses
+      # @return [Array<String>]
+      def self.registered_addresses: () -> untyped
+
+      # Get count of registered resources
+      # @return [Integer]
+      def self.registered_count: () -> untyped
+
+      # Unregister a resource (for testing)
+      # @param address [String] Event address
+      # @return [Boolean] True if was registered, false otherwise
+      def self.unregister: (untyped address) -> untyped
+
+      # Clear all registrations (for testing)
+      def self.clear: () -> untyped
+    end
+  end
+end

data/sig/takagi/event_bus/future.rbs

@@ -0,0 +1,78 @@
+module Takagi
+  class EventBus
+    # Future for sync/async request-reply pattern (pure Ruby)
+    # Uses ConditionVariable for efficient waiting
+    #
+    # @example Blocking wait
+    #   future = Future.new
+    #   Thread.new { future.set_value(42) }
+    #   value = future.value(timeout: 1.0) # => 42
+    #
+    # @example Non-blocking check
+    #   future = Future.new
+    #   future.completed? # => false
+    #   future.set_value(42)
+    #   future.completed? # => true
+    #
+    # @example Error propagation
+    #   future = Future.new
+    #   future.set_error(StandardError.new("Failed"))
+    #   future.value # raises StandardError
+    class Future
+      @mutex: untyped
+
+      @condition: untyped
+
+      @value: untyped
+
+      @completed: untyped
+
+      @error: untyped
+
+      # Initialize a new Future
+      def initialize: () -> void
+
+      # Set the successful value of the Future
+      # @param value [Object] The value to set
+      # @raise [RuntimeError] If already completed
+      def set_value: (untyped value) -> untyped
+
+      # Set the error state of the Future
+      # @param error [Exception] The error to set
+      # @raise [RuntimeError] If already completed
+      def set_error: (untyped error) -> untyped
+
+      # Get the value of the Future (blocking)
+      # @param timeout [Float, nil] Timeout in seconds (nil = wait forever)
+      # @return [Object] The value
+      # @raise [Timeout::Error] If timeout expires before completion
+      # @raise [Exception] The error if Future completed with error
+      def value: (?timeout: untyped?) -> untyped
+
+      # Check if Future is completed
+      # @return [Boolean]
+      def completed?: () -> untyped
+
+      # Check if Future completed with error
+      # @return [Boolean]
+      def error?: () -> untyped
+
+      # Check if Future completed successfully
+      # @return [Boolean]
+      def success?: () -> untyped
+
+      # Get the error if present
+      # @return [Exception, nil]
+      def error: () -> untyped
+
+      # Try to get value without blocking
+      # @return [Object, nil] Value if completed, nil otherwise
+      def try_value: () -> untyped
+
+      # Wait for completion without returning value
+      # @param timeout [Float, nil] Timeout in seconds
+      # @return [Boolean] True if completed, false if timeout
+      def wait: (?timeout: untyped?) -> untyped
+    end
+  end
+end

data/sig/takagi/event_bus/lru_cache.rbs

@@ -0,0 +1,86 @@
+module Takagi
+  class EventBus
+    # Thread-safe LRU cache with TTL (pure Ruby)
+    # Zero runtime dependencies
+    #
+    # Features:
+    # - Least Recently Used eviction when at capacity
+    # - Time-To-Live (TTL) based expiration
+    # - Thread-safe with Mutex
+    #
+    # @example
+    #   cache = LRUCache.new(max_size: 1000, ttl: 3600)
+    #   cache.set('key', 'value')
+    #   cache.get('key') # => 'value'
+    #   cache.size # => 1
+    class LRUCache
+      @max_size: untyped
+
+      @ttl: untyped
+
+      @cache: untyped
+
+      @access_order: untyped
+
+      @timestamps: untyped
+
+      @mutex: untyped
+
+      attr_reader max_size: untyped
+
+      attr_reader ttl: untyped
+
+      # Initialize LRU cache
+      # @param max_size [Integer] Maximum number of entries (default: 1000)
+      # @param ttl [Integer] Time-to-live in seconds (default: 3600)
+      def initialize: (?::Integer max_size, ?::Integer ttl) -> void
+
+      # Get value from cache
+      # @param key [Object] Cache key
+      # @return [Object, nil] Cached value or nil if not found/expired
+      def get: (untyped key) -> untyped
+
+      # Set value in cache
+      # @param key [Object] Cache key
+      # @param value [Object] Value to cache
+      def set: (untyped key, untyped value) -> untyped
+
+      # Delete entry from cache
+      # @param key [Object] Cache key
+      # @return [Object, nil] Deleted value or nil
+      def delete: (untyped key) -> untyped
+
+      # Clear all entries
+      def clear: () -> untyped
+
+      # Get number of entries in cache
+      # @return [Integer] Cache size
+      def size: () -> untyped
+
+      # Check if cache is empty
+      # @return [Boolean]
+      def empty?: () -> untyped
+
+      # Check if key exists in cache
+      # @param key [Object] Cache key
+      # @return [Boolean]
+      def key?: (untyped key) -> untyped
+
+      # Get all keys in cache
+      # @return [Array] Cache keys
+      def keys: () -> untyped
+
+      # Get cache statistics
+      # @return [Hash] Statistics
+      def stats: () -> untyped
+
+      private
+
+      # Remove expired entries based on TTL
+      def cleanup_expired: () -> untyped
+
+      # Evict least recently used entry
+      def evict_oldest: () -> (nil | untyped)
+    end
+  end
+end

data/sig/takagi/event_bus/message_buffer.rbs

@@ -0,0 +1,133 @@
+module Takagi
+  class EventBus
+    # Bounded message buffer for distributed addresses
+    # Stores recent messages in a ring buffer per address for replay on reconnection
+    #
+    # Features:
+    # - Bounded memory (max messages per address)
+    # - TTL-based expiration
+    # - Thread-safe
+    # - Zero external dependencies
+    # - Only buffers distributed addresses
+    #
+    # @example
+    #   buffer = MessageBuffer.new(max_messages: 100, ttl: 300)
+    #   buffer.store(address, message)
+    #   messages = buffer.replay(address, since: Time.now - 60)
+    class MessageBuffer
+      @max_messages: untyped
+
+      @ttl: untyped
+
+      @buffers: untyped
+
+      @mutex: untyped
+
+      @enabled: untyped
+
+      @cleanup_thread: untyped
+
+      # Ring buffer for a single address
+      class RingBuffer
+        @max_size: untyped
+
+        @messages: untyped
+
+        @mutex: untyped
+
+        def initialize: (untyped max_size) -> void
+
+        def push: (untyped message) -> untyped
+
+        def messages_since: (?untyped? timestamp) -> untyped
+
+        def all_messages: () -> untyped
+
+        def size: () -> untyped
+
+        def clear: () -> untyped
+
+        def empty?: () -> untyped
+
+        # Clean expired messages based on TTL
+        def clean_expired: (untyped ttl) -> untyped
+      end
+
+      # @param max_messages [Integer] Maximum messages per address (default: 100)
+      # @param ttl [Integer] Time-to-live in seconds (default: 300 = 5 minutes)
+      def initialize: (?max_messages: ::Integer, ?ttl: ::Integer) -> void
+
+      # Store a message in the buffer
+      # Only stores distributed addresses to conserve memory
+      #
+      # @param address [String] Event address
+      # @param message [Message] Event message
+      def store: (untyped address, untyped message) -> (nil | untyped)
+
+      # Store a failed delivery for retry
+      # Used by CoAPBridge when network delivery fails
+      #
+      # @param address [String] Event address
+      # @param message [Message] Event message
+      # @param destination [String] Failed destination (for logging)
+      def store_failed: (untyped address, untyped message, ?untyped? destination) -> (nil | untyped)
+
+      # Replay messages for an address since a given timestamp
+      #
+      # @param address [String] Event address
+      # @param since [Time, nil] Return messages since this time (nil = all messages)
+      # @return [Array<Message>] Buffered messages
+      #
+      # @example Replay last 60 seconds
+      #   messages = buffer.replay('sensor.temperature.room1', since: Time.now - 60)
+      def replay: (untyped address, ?since: untyped?) -> untyped
+
+      # Get all buffered messages for an address
+      #
+      # @param address [String] Event address
+      # @return [Array<Message>] All buffered messages
+      def all: (untyped address) -> untyped
+
+      # Get buffer size for an address
+      #
+      # @param address [String] Event address
+      # @return [Integer] Number of buffered messages
+      def size: (untyped address) -> untyped
+
+      # Get total number of buffered messages across all addresses
+      #
+      # @return [Integer] Total buffered messages
+      def total_size: () -> untyped
+
+      # Clear buffer for an address
+      #
+      # @param address [String] Event address
+      def clear: (untyped address) -> untyped
+
+      # Clear all buffers
+      def clear_all: () -> untyped
+
+      # Enable message buffering
+      def enable: () -> untyped
+
+      # Disable message buffering
+      def disable: () -> untyped
+
+      # Check if buffering is enabled
+      def enabled?: () -> untyped
+
+      # Get statistics about buffering
+      #
+      # @return [Hash] Buffer statistics
+      def stats: () -> untyped
+
+      # Shutdown cleanup thread
+      def shutdown: () -> untyped
+
+      private
+
+      # Start background thread to clean expired messages
+      def start_cleanup_thread: () -> untyped
+    end
+  end
+end

data/sig/takagi/event_bus/observer_cleanup.rbs

@@ -0,0 +1,62 @@
+module Takagi
+  class EventBus
+    # Background thread for stale observer cleanup
+    #
+    # Periodically cleans up stale observers from the ObserveRegistry.
+    # Observers are considered stale if they haven't received notifications
+    # for longer than max_age seconds.
+    #
+    # @example
+    #   cleanup = ObserverCleanup.new(interval: 60, max_age: 600)
+    #   cleanup.start
+    #   # ... cleanup runs in background ...
+    #   cleanup.stop
+    class ObserverCleanup
+      @interval: untyped
+
+      @max_age: untyped
+
+      @running: untyped
+
+      @thread: untyped
+
+      @mutex: untyped
+
+      @stats: untyped
+
+      attr_reader interval: untyped
+
+      attr_reader max_age: untyped
+
+      # Initialize observer cleanup
+      # @param interval [Integer] Cleanup interval in seconds (default: 60)
+      # @param max_age [Integer] Max observer age in seconds (default: 600)
+      def initialize: (?interval: ::Integer, ?max_age: ::Integer) -> void
+
+      # Start the cleanup thread
+      def start: () -> (nil | untyped)
+
+      # Stop the cleanup thread
+      def stop: () -> (nil | untyped)
+
+      # Check if cleanup is running
+      # @return [Boolean]
+      def running?: () -> untyped
+
+      # Get cleanup statistics
+      # @return [Hash] Statistics
+      def stats: () -> untyped
+
+      # Force a cleanup run (for testing)
+      def cleanup_now: () -> untyped
+
+      private
+
+      # Main cleanup loop
+      def run_cleanup_loop: () -> untyped
+
+      # Cleanup stale observers from ObserveRegistry
+      def cleanup_stale_observers: () -> untyped
+    end
+  end
+end