takagi 0.1.0 → 1.1.0

data/sig/takagi/event_bus.rbs

@@ -0,0 +1,320 @@
+module Takagi
+  # High-level event distribution with threaded/process async delivery.
+  # Built on top of ObserveRegistry with zero runtime dependencies.
+  #
+  # Supports both CoAP Observe style and Pub/Sub style APIs:
+  #
+  # @example CoAP Observe style
+  #   EventBus.observe('sensor.temperature.room1') { |msg| puts msg.body }
+  #   EventBus.notify('sensor.temperature.room1', { value: 25.5 })
+  #
+  # @example Pub/Sub style (aliases)
+  #   EventBus.consumer('sensor.temperature.room1') { |msg| puts msg.body }
+  #   EventBus.publish('sensor.temperature.room1', { value: 25.5 })
+  #
+  # @example Request-Reply pattern
+  #   reply = EventBus.send_sync('cache.query', { key: 'user:123' }, timeout: 1.0)
+  class EventBus
+    self.@executor: untyped
+
+    self.@handlers: untyped
+
+    self.@consumers: untyped
+
+    self.@handler_store: untyped
+
+    self.@mutex: untyped
+
+    self.@current_states: untyped
+
+    self.@cleanup: untyped
+
+    self.@last_index: untyped
+
+    self.@message_store: untyped
+
+    class Error < StandardError
+    end
+
+    # Event message wrapper (shareable for Ractor)
+    class Message
+      @address: untyped
+
+      @body: untyped
+
+      @headers: untyped
+
+      @reply_address: untyped
+
+      @timestamp: untyped
+
+      attr_reader address: untyped
+
+      attr_reader body: untyped
+
+      attr_reader headers: untyped
+
+      attr_reader reply_address: untyped
+
+      attr_reader timestamp: untyped
+
+      def initialize: (untyped address, untyped body, ?headers: ::Hash[untyped, untyped], ?reply_address: untyped?) -> void
+
+      # Reply to this message (request-reply pattern)
+      def reply: (untyped body, ?headers: ::Hash[untyped, untyped]) -> (nil | untyped)
+
+      private
+
+      def deep_freeze: (untyped obj) -> untyped
+    end
+
+    # Event handler wrapper
+    class Handler
+      @address: untyped
+
+      @block: untyped
+
+      @options: untyped
+
+      @local_only: untyped
+
+      @pool_id: untyped
+
+      attr_reader address: untyped
+
+      attr_reader block: untyped
+
+      attr_reader options: untyped
+
+      attr_reader pool_id: untyped
+
+      def initialize: (untyped address, ?::Hash[untyped, untyped] options) { (?) -> untyped } -> void
+
+      def call: (untyped message) -> untyped
+
+      def local_only?: () -> untyped
+    end
+
+    # Helper method to get configuration with fallback to ENV
+    def self.config_value: (untyped config_key, untyped env_key, untyped default) -> untyped
+
+    # Publish message to all subscribers (pub/sub pattern)
+    # @param address [String] Event address (e.g., "sensor.temperature.room1")
+    # @param body [Object] Message body (must be shareable for Ractors)
+    # @param headers [Hash] Optional message headers
+    # @return [Message] Published message
+    #
+    # @example
+    #   EventBus.publish('sensor.temperature.room1', { value: 25.5, unit: 'C' })
+    def self.publish: (untyped address, ?untyped? body, ?headers: ::Hash[untyped, untyped]) -> untyped
+
+    # Send message to single consumer (point-to-point pattern)
+    # Uses round-robin if multiple consumers registered
+    # @param address [String] Event address
+    # @param body [Object] Message body
+    # @param headers [Hash] Optional headers
+    # @yield [reply_message] Optional reply handler (request-reply pattern)
+    # @return [Message] Sent message
+    #
+    # @example
+    #   EventBus.send('cache.query', { key: 'user:123' }) do |reply|
+    #     puts "Cache value: #{reply.body[:value]}"
+    #   end
+    def self.send: (untyped address, ?untyped? body, ?headers: ::Hash[untyped, untyped]) ?{ (?) -> untyped } -> untyped
+
+    # Synchronous send with timeout (blocking)
+    # @param address [String] Event address
+    # @param body [Object] Message body
+    # @param headers [Hash] Optional headers
+    # @param timeout [Float] Timeout in seconds (default: 1.0)
+    # @return [Message] Reply message
+    # @raise [Timeout::Error] If no reply received within timeout
+    #
+    # @example
+    #   reply = EventBus.send_sync('cache.query', { key: 'user:123' }, timeout: 1.0)
+    #   puts "Cache hit: #{reply.body[:hit]}"
+    def self.send_sync: (untyped address, ?untyped? body, ?headers: ::Hash[untyped, untyped], ?timeout: ::Float) -> untyped
+
+    # Asynchronous send with Future (non-blocking)
+    # @param address [String] Event address
+    # @param body [Object] Message body
+    # @param headers [Hash] Optional headers
+    # @return [Future] Future that will contain reply
+    #
+    # @example
+    #   future = EventBus.send_async('cache.query', { key: 'user:123' })
+    #   # ... do other work ...
+    #   reply = future.value(timeout: 1.0)
+    def self.send_async: (untyped address, ?untyped? body, ?headers: ::Hash[untyped, untyped]) -> untyped
+
+    # Register consumer for address (point-to-point or pub/sub)
+    # @param address [String] Event address or pattern
+    # @param options [Hash] Handler options
+    # @option options [Boolean] :local_only Only receive local messages
+    # @yield [message] Block called when message received
+    # @return [String] Consumer ID (for unregistering)
+    #
+    # @example
+    #   id = EventBus.consumer('sensor.temperature.room1') do |message|
+    #     puts "Temp: #{message.body[:value]}"
+    #   end
+    #   EventBus.unregister(id)
+    def self.consumer: (untyped address, ?::Hash[untyped, untyped] options) ?{ (?) -> untyped } -> untyped
+
+    # Unregister a consumer
+    # @param consumer_id [String] Consumer ID returned from consumer()
+    def self.unregister: (untyped consumer_id) -> (nil | untyped)
+
+    # Subscribe to remote CoAP observable
+    # @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 = EventBus.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 } -> untyped
+
+    alias self.observe self.consumer
+
+    alias self.on self.consumer
+
+    alias self.notify self.publish
+
+    alias self.emit self.publish
+
+    alias self.cancel self.unregister
+
+    alias self.subscribe self.subscribe_remote
+
+    alias self.unsubscribe self.unregister
+
+    # Configure message store (for buffering/replay)
+    # @param store [MessageBuffer, Object] Message store instance (nil to disable)
+    # @return [MessageBuffer, Object, nil] Configured store
+    #
+    # @example Enable default buffering
+    #   EventBus.enable_message_buffering
+    #
+    # @example Custom configuration
+    #   EventBus.configure_message_store(
+    #     MessageBuffer.new(max_messages: 200, ttl: 600)
+    #   )
+    #
+    # @example Custom plugin store
+    #   EventBus.configure_message_store(RedisMessageStore.new)
+    def self.configure_message_store: (untyped store) -> untyped
+
+    # Enable default message buffering
+    # @param max_messages [Integer] Max messages per address
+    # @param ttl [Integer] Time-to-live in seconds
+    # @return [MessageBuffer] Configured buffer
+    def self.enable_message_buffering: (?max_messages: ::Integer, ?ttl: ::Integer) -> untyped
+
+    # Disable message buffering
+    def self.disable_message_buffering: () -> untyped
+
+    # Get current message store
+    # @return [MessageBuffer, Object, nil] Current message store
+    attr_reader self.message_store: untyped
+
+    # Replay buffered messages for an address
+    # @param address [String] Event address
+    # @param since [Time, nil] Return messages since this time (nil = all)
+    # @return [Array<Message>] Buffered messages
+    #
+    # @example Replay all buffered messages
+    #   EventBus.replay('sensor.temperature.room1')
+    #
+    # @example Replay last 60 seconds
+    #   EventBus.replay('sensor.temperature.room1', since: Time.now - 60)
+    def self.replay: (untyped address, ?since: untyped?) -> (::Array[untyped] | untyped)
+
+    # Replay buffered messages to a consumer
+    # Useful for late joiners or reconnecting nodes
+    # @param address [String] Event address
+    # @param since [Time, nil] Replay messages since this time
+    # @yield [message] Block called for each buffered message
+    #
+    # @example Replay to new subscriber
+    #   EventBus.consumer('sensor.temperature.room1') do |msg|
+    #     puts "Temp: #{msg.body[:value]}"
+    #   end
+    #   # Catch up on last 5 minutes
+    #   EventBus.replay_to('sensor.temperature.room1', since: Time.now - 300) do |msg|
+    #     puts "Missed: #{msg.body[:value]}"
+    #   end
+    def self.replay_to: (untyped address, ?since: untyped?) ?{ (?) -> untyped } -> untyped
+
+    # Check if address is distributed via CoAP
+    # Uses AddressPrefix registry for extensibility
+    # @param address [String] Event address
+    # @return [Boolean]
+    def self.distributed?: (untyped address) -> untyped
+
+    # Check if address is local-only
+    # Uses AddressPrefix registry for extensibility
+    # @param address [String] Event address
+    # @return [Boolean]
+    def self.local_only?: (untyped address) -> untyped
+
+    # Get current state for address
+    # @param address [String] Event address
+    # @return [Object, nil] Current state or nil
+    def self.current_state: (untyped address) -> untyped
+
+    # List all registered addresses
+    # @return [Array<String>] Event addresses
+    def self.addresses: () -> untyped
+
+    # Get handler count for address
+    # @param address [String] Event address
+    # @return [Integer] Number of handlers
+    def self.handler_count: (untyped address) -> untyped
+
+    # Get EventBus statistics
+    # @return [Hash] Statistics
+    def self.stats: () -> untyped
+
+    # Start background cleanup
+    def self.start_cleanup: () -> untyped
+
+    # Stop background cleanup
+    def self.stop_cleanup: () -> untyped
+
+    # Shutdown EventBus (cleanup resources)
+    def self.shutdown: () -> untyped
+
+    private
+
+    # Get all handlers for exact address match
+    def self.handlers_for: (untyped address) -> untyped
+
+    # Get handlers matching wildcard patterns
+    # Supports: "sensor.*", "sensor.*.room1"
+    def self.wildcard_handlers: (untyped address) -> untyped
+
+    # Match address parts against pattern
+    def self.match_pattern?: (untyped parts, untyped pattern_parts) -> (false | untyped)
+
+    # Round-robin selection of next handler
+    def self.next_handler_for: (untyped address) -> (nil | untyped)
+
+    public
+
+    def self.handler_for_pool_id: (untyped pool_id) -> untyped
+
+    private
+
+    # Deliver message asynchronously via Ractor pool
+    def self.deliver_async: (untyped handler, untyped message) -> untyped
+
+    # Generate unique reply address
+    def self.generate_reply_address: () -> ::String
+
+    # Log debug message
+    def self.log_debug: (untyped message) -> (nil | untyped)
+  end
+end

data/sig/takagi/helpers.rbs

@@ -0,0 +1,34 @@
+module Takagi
+  # Helper methods for route handlers to improve DX
+  #
+  # Dynamically generates response helper methods from CoAP::Registries::Response registry:
+  # - Success methods (2.xx): created(data = {}), changed(data = {}), etc.
+  # - Error methods (4.xx, 5.xx): bad_request(message = ...), not_found(message = ...), etc.
+  #
+  # @example Success response
+  #   created({ id: 123, name: 'Resource' })
+  #
+  # @example Error response
+  #   bad_request('Invalid input')
+  #   unauthorized({ error: 'Token expired' })
+  module Helpers
+    # Returns a JSON response with 2.05 Content status and sets Content-Format to application/json
+    # Similar to Sinatra's json helper, automatically sets the Content-Format option
+    # @param data [Hash] The data to return as JSON
+    # @return [Takagi::Message::Outbound] The response with JSON content-format
+    def json: (?::Hash[untyped, untyped] data) -> Message::Outbound
+
+    # Validates that required parameters are present
+    # @param required_params [Array<Symbol>] List of required parameter names
+    # @raise [StandardError] If any required parameter is missing
+    def validate_params: (*untyped required_params) -> (nil | untyped)
+
+    # Halts execution and returns the given response
+    # Useful for early returns
+    # @param response [Takagi::Message::Outbound, Hash] The response to return
+    def halt: (untyped response) -> untyped
+
+    # Alias for internal_server_error (more concise)
+    alias server_error internal_server_error
+  end
+end

data/sig/takagi/initializer.rbs

@@ -0,0 +1,9 @@
+module Takagi
+  # Let's do some initialization
+  class Initializer
+    # Runs the initialization logic (e.g., loading configurations, setting up databases)
+    def self.run!: () -> untyped
+
+    def self.load_initializers: () -> untyped
+  end
+end

data/sig/takagi/logger.rbs

@@ -0,0 +1,17 @@
+module Takagi
+  class Logger
+    @logger: untyped
+
+    def initialize: (?log_output: untyped, ?level: untyped) -> void
+
+    def set_level: (untyped level) -> untyped
+
+    def info: (untyped message) -> untyped
+
+    def warn: (untyped message) -> untyped
+
+    def debug: (untyped message) -> untyped
+
+    def error: (untyped message) -> untyped
+  end
+end

data/sig/takagi/message/base.rbs

@@ -0,0 +1,64 @@
+module Takagi
+  module Message
+    # Base class for message
+    class Base
+      @data: untyped
+
+      @logger: untyped
+
+      @version: untyped
+
+      @type: untyped
+
+      @code: untyped
+
+      @message_id: untyped
+
+      @token: untyped
+
+      @options: untyped
+
+      @payload: untyped
+
+      attr_reader version: untyped
+
+      attr_reader type: untyped
+
+      attr_reader token: untyped
+
+      attr_reader message_id: untyped
+
+      attr_reader payload: untyped
+
+      attr_reader options: untyped
+
+      attr_reader code: untyped
+
+      def initialize: (?untyped? data) -> void
+
+      # Convert CoAP code number to method name using registry
+      # @param code [Integer] CoAP code number
+      # @return [String] Method name (e.g., 'GET', 'OBSERVE')
+      def coap_code_to_method: (untyped code) -> ("OBSERVE" | untyped)
+
+      # Convert method name to CoAP code number using registry
+      # @param method [String, Symbol] Method name (e.g., 'GET', :post)
+      # @return [Integer] CoAP code number
+      def coap_method_to_code: (untyped method) -> untyped
+
+      private
+
+      def parse: (untyped data) -> untyped
+
+      def parse_options: (untyped bytes) -> untyped
+
+      def extract_payload: (untyped data) -> (nil | untyped)
+
+      def decode_extended_value: (untyped bytes, untyped position, untyped raw_value) -> untyped
+
+      def store_option: (untyped options, untyped option_number, untyped value) -> untyped
+
+      def coerce_option_value: (untyped value) -> untyped
+    end
+  end
+end

data/sig/takagi/message/deduplication_cache.rbs

@@ -0,0 +1,49 @@
+module Takagi
+  module Message
+    # Implements message deduplication as per RFC 7252 Section 4.4
+    #
+    # The server MUST detect duplicates by matching both Message ID and source endpoint.
+    # When a duplicate CON message is received, the server MUST resend the cached response.
+    #
+    # Cache entries expire after EXCHANGE_LIFETIME (247 seconds per RFC 7252 §4.8.2)
+    class DeduplicationCache
+      @cache: untyped
+
+      @mutex: untyped
+
+      # RFC 7252 §4.8.2: EXCHANGE_LIFETIME = 247 seconds
+      EXCHANGE_LIFETIME: 247
+
+      # Entry contains the cached response and metadata
+      CacheEntry: untyped
+
+      def initialize: () -> void
+
+      # Check if message is a duplicate and return cached response if available
+      # @param message_id [Integer] The CoAP Message ID
+      # @param source_endpoint [String] Source IP:Port identifier
+      # @return [String, nil] Cached response data or nil if not a duplicate
+      def check_duplicate: (untyped message_id, untyped source_endpoint) -> untyped
+
+      # Store a response for future duplicate detection
+      # @param message_id [Integer] The CoAP Message ID
+      # @param source_endpoint [String] Source IP:Port identifier
+      # @param response_data [String] The serialized response to cache
+      def store_response: (untyped message_id, untyped source_endpoint, untyped response_data) -> untyped
+
+      # Clear all cache entries (useful for testing)
+      def clear: () -> untyped
+
+      # Get cache statistics
+      def stats: () -> untyped
+
+      private
+
+      def cache_key: (untyped message_id, untyped source_endpoint) -> ::String
+
+      # Remove expired entries to prevent unbounded memory growth
+      # RFC 7252 §4.8.2: entries older than EXCHANGE_LIFETIME should be discarded
+      def cleanup_expired_entries: () -> untyped
+    end
+  end
+end

data/sig/takagi/message/inbound.rbs

@@ -0,0 +1,76 @@
+module Takagi
+  module Message
+    # Class for inbound message that is coming to server
+    class Inbound < Base
+      @method: untyped
+
+      @response_code: untyped
+
+      @uri: untyped
+
+      attr_reader method: untyped
+
+      attr_reader uri: untyped
+
+      attr_reader response_code: untyped
+
+      def initialize: (untyped data) -> void
+
+      def to_response: (untyped code, untyped payload, ?options: ::Hash[untyped, untyped]) -> untyped
+
+      def parse_coap_uri: () -> untyped
+
+      # Get CoAP option by number
+      # @param option_number [Integer] The CoAP option number
+      # @return [Object, nil] The option value
+      def option: (untyped option_number) -> untyped
+
+      # Check if request has a specific CoAP option
+      # @param option_number [Integer] The CoAP option number
+      # @return [Boolean]
+      def option?: (untyped option_number) -> untyped
+
+      # Get Accept option
+      # @return [Integer, nil] The Accept content format
+      def accept: () -> untyped
+
+      # Check if request accepts a specific content format
+      # @param format [String, Integer] Format name or number
+      # @return [Boolean]
+      def accept?: (untyped format) -> (false | untyped)
+
+      # Get Content-Format option
+      # @return [Integer, nil] The Content-Format
+      def content_format: () -> untyped
+
+      # Get query parameters as a hash
+      # @return [Hash<String, String>]
+      def query_params: () -> (::Hash[untyped, untyped] | untyped)
+
+      # Check if request is a GET
+      # @return [Boolean]
+      def get?: () -> untyped
+
+      # Check if request is a POST
+      # @return [Boolean]
+      def post?: () -> untyped
+
+      # Check if request is a PUT
+      # @return [Boolean]
+      def put?: () -> untyped
+
+      # Check if request is a DELETE
+      # @return [Boolean]
+      def delete?: () -> untyped
+
+      # Check if request is an OBSERVE
+      # @return [Boolean]
+      def observe?: () -> untyped
+
+      private
+
+      # Convert content format name to number using CoAP registry
+      def content_format_to_number: (untyped format) -> untyped
+    end
+  end
+end

data/sig/takagi/message/outbound.rbs

@@ -0,0 +1,48 @@
+module Takagi
+  module Message
+    # Class for outbound message that is coming from server
+    class Outbound < Base
+      @code: untyped
+
+      @token: untyped
+
+      @message_id: untyped
+
+      @type: untyped
+
+      @options: untyped
+
+      @payload: untyped
+
+      def initialize: (code: untyped, payload: untyped, ?token: untyped?, ?message_id: untyped?, ?type: untyped, ?options: ::Hash[untyped, untyped]) -> void
+
+      def to_bytes: () -> untyped
+
+      private
+
+      def with_error_handling: () { () -> untyped } -> untyped
+
+      def log_generation: () -> untyped
+
+      def build_header: () -> untyped
+
+      def token_bytes: () -> untyped
+
+      def build_options_section: () -> untyped
+
+      def build_payload_section: () -> untyped
+
+      def log_final_packet: (untyped packet) -> untyped
+
+      def normalize_options: (untyped options) -> untyped
+
+      def flattened_options: () -> untyped
+
+      def encode_option_value: (untyped value) -> untyped
+
+      def encode_integer_option_value: (untyped value) -> untyped
+
+      def encode_option_header_value: (untyped value) -> untyped
+    end
+  end
+end

data/sig/takagi/message/request.rbs

@@ -0,0 +1,32 @@
+module Takagi
+  module Message
+    # Encodes outbound CoAP request envelopes used when observing remote peers.
+    class Request < Base
+      @method: untyped
+
+      @uri: untyped
+
+      @token: untyped
+
+      @observe: untyped
+
+      @message_id: untyped
+
+      @payload: untyped
+
+      attr_reader message_id: untyped
+
+      def initialize: (method: untyped, uri: untyped, ?payload: untyped?, ?token: untyped?, **untyped options) -> void
+
+      def to_bytes: () -> untyped
+
+      private
+
+      def encode_options: () -> untyped
+
+      def encode_option: (untyped option_number, untyped value, untyped last_option_number) -> untyped
+
+      def encode_extended: (untyped val) -> untyped
+    end
+  end
+end