takagi 0.1.0 → 1.1.0

data/sig/takagi/coap/registries/base.rbs

@@ -0,0 +1,95 @@
+module Takagi
+  module CoAP
+    module Registries
+      # Base class for extensible constant registries.
+      #
+      # Provides a pattern for registering CoAP protocol constants with:
+      # - Numeric value
+      # - Human-readable name
+      # - Symbol accessor (optional)
+      #
+      # This allows plugins to extend the protocol without modifying core code.
+      #
+      # @example Creating a custom registry
+      #   class MyRegistry < Registries::Base
+      #     register(1, 'First Value', :first)
+      #     register(2, 'Second Value', :second)
+      #   end
+      #
+      #   MyRegistry::FIRST   # => 1
+      #   MyRegistry.name_for(1)  # => "First Value"
+      #   MyRegistry.all      # => {1 => "First Value", 2 => "Second Value"}
+      class Base
+        self.@registry: untyped
+
+        self.@reverse_registry: untyped
+
+        # Register a new constant in the registry
+        #
+        # @param value [Integer] Numeric value of the constant
+        # @param name [String] Human-readable name
+        # @param symbol [Symbol, nil] Optional symbol for constant access
+        # @param rfc [String, nil] Optional RFC reference
+        #
+        # @example
+        #   register(69, '2.05 Content', :content, rfc: 'RFC 7252 §5.9.1.4')
+        def self.register: (untyped value, untyped name, ?untyped? symbol, ?rfc: untyped?) -> untyped
+
+        # Get human-readable name for a value
+        #
+        # @param value [Integer] The numeric value
+        # @return [String, nil] The name, or nil if not found
+        def self.name_for: (untyped value) -> untyped
+
+        # Get numeric value for a name or symbol
+        #
+        # @param key [String, Symbol] The name or symbol
+        # @return [Integer, nil] The value, or nil if not found
+        def self.value_for: (untyped key) -> untyped
+
+        # Get RFC reference for a value
+        #
+        # @param value [Integer] The numeric value
+        # @return [String, nil] The RFC reference, or nil if not found
+        def self.rfc_for: (untyped value) -> untyped
+
+        # Check if a value is registered
+        #
+        # @param value [Integer] The value to check
+        # @return [Boolean] true if registered
+        def self.registered?: (untyped value) -> untyped
+
+        # Get all registered constants
+        #
+        # @return [Hash] Map of value => name
+        def self.all: () -> untyped
+
+        # Iterate over registered values
+        #
+        # @yield [Integer] each registered numeric value
+        # @return [Enumerator] if no block given
+        def self.each_value: () ?{ (?) -> untyped } -> untyped
+
+        # Get all registered values
+        #
+        # @return [Array<Integer>] Array of all values
+        def self.values: () -> untyped
+
+        # Get registry metadata for a value
+        #
+        # @param value [Integer] The numeric value
+        # @return [Hash, nil] Full metadata hash
+        def self.metadata_for: (untyped value) -> untyped
+
+        # Clear all registrations (useful for testing)
+        def self.clear!: () -> untyped
+
+        private
+
+        def self.registry: () -> untyped
+
+        def self.reverse_registry: () -> untyped
+      end
+    end
+  end
+end

data/sig/takagi/coap/registries/content_format.rbs

@@ -0,0 +1,47 @@
+module Takagi
+  module CoAP
+    module Registries
+      # CoAP Content-Format Registry (RFC 7252 §12.3)
+      #
+      # Extensible registry for CoAP content-format codes.
+      # Plugins can register custom content formats without modifying core code.
+      #
+      # @example Using predefined formats
+      #   Takagi::CoAP::Registries::ContentFormat::JSON          # => 50
+      #   Takagi::CoAP::Registries::ContentFormat::TEXT_PLAIN    # => 0
+      #
+      # @example Registering a custom format
+      #   Takagi::CoAP::Registries::ContentFormat.register(65000, 'application/custom', :custom)
+      #   Takagi::CoAP::Registries::ContentFormat::CUSTOM  # => 65000
+      #
+      # @example Looking up format names
+      #   Takagi::CoAP::Registries::ContentFormat.name_for(50)  # => "application/json"
+      class ContentFormat < Base
+        # Get MIME type for a content-format code
+        # @param code [Integer] Content-format code
+        # @return [String, nil] MIME type
+        def self.mime_type_for: (untyped code) -> untyped
+
+        # Get content-format code for a MIME type
+        # @param mime_type [String] MIME type
+        # @return [Integer, nil] Content-format code
+        def self.code_for_mime: (untyped mime_type) -> untyped
+
+        # Check if format is JSON-based
+        # @param code [Integer] Content-format code
+        # @return [Boolean] true if JSON format
+        def self.json?: (untyped code) -> untyped
+
+        # Check if format is CBOR-based
+        # @param code [Integer] Content-format code
+        # @return [Boolean] true if CBOR format
+        def self.cbor?: (untyped code) -> untyped
+
+        # Check if format is text-based
+        # @param code [Integer] Content-format code
+        # @return [Boolean] true if text format
+        def self.text?: (untyped code) -> untyped
+      end
+    end
+  end
+end

data/sig/takagi/coap/registries/message_type.rbs

@@ -0,0 +1,53 @@
+module Takagi
+  module CoAP
+    module Registries
+      # CoAP Message Type Registry (RFC 7252 §3)
+      #
+      # Extensible registry for CoAP message types.
+      #
+      # @example Using predefined types
+      #   Takagi::CoAP::Registries::MessageType::CONFIRMABLE  # => 0
+      #   Takagi::CoAP::Registries::MessageType::ACK          # => 2
+      #
+      # @example Looking up type names
+      #   Takagi::CoAP::Registries::MessageType.name_for(0)  # => "Confirmable"
+      class MessageType < Base
+        # Aliases for convenience
+        CON: untyped
+
+        NON: untyped
+
+        ACK: untyped
+
+        RST: untyped
+
+        # Check if type is confirmable
+        # @param type [Integer] Message type
+        # @return [Boolean] true if confirmable
+        def self.confirmable?: (untyped type) -> untyped
+
+        # Check if type is non-confirmable
+        # @param type [Integer] Message type
+        # @return [Boolean] true if non-confirmable
+        def self.non_confirmable?: (untyped type) -> untyped
+
+        # Check if type is acknowledgement
+        # @param type [Integer] Message type
+        # @return [Boolean] true if acknowledgement
+        def self.acknowledgement?: (untyped type) -> untyped
+
+        alias self.ack? self.acknowledgement?
+
+        # Check if type is reset
+        # @param type [Integer] Message type
+        # @return [Boolean] true if reset
+        def self.reset?: (untyped type) -> untyped
+
+        # Check if type is valid
+        # @param type [Integer] Message type
+        # @return [Boolean] true if valid
+        def self.valid?: (untyped type) -> untyped
+      end
+    end
+  end
+end

data/sig/takagi/coap/registries/method.rbs

@@ -0,0 +1,27 @@
+module Takagi
+  module CoAP
+    module Registries
+      # CoAP Method Code Registry (RFC 7252 §12.1.1)
+      #
+      # Extensible registry for CoAP request method codes.
+      # Plugins can register custom methods without modifying core code.
+      #
+      # @example Using predefined methods
+      #   Takagi::CoAP::Registries::Method::GET    # => 1
+      #   Takagi::CoAP::Registries::Method::POST   # => 2
+      #
+      # @example Registering a custom method
+      #   Takagi::CoAP::Registries::Method.register(5, 'FETCH', :fetch, rfc: 'RFC 8132')
+      #   Takagi::CoAP::Registries::Method::FETCH  # => 5
+      #
+      # @example Looking up method names
+      #   Takagi::CoAP::Registries::Method.name_for(1)  # => "GET"
+      class Method < Base
+        # Check if code is a valid method code
+        # @param code [Integer] Code to check
+        # @return [Boolean] true if valid method
+        def self.valid?: (untyped code) -> untyped
+      end
+    end
+  end
+end

data/sig/takagi/coap/registries/option.rbs

@@ -0,0 +1,43 @@
+module Takagi
+  module CoAP
+    module Registries
+      # CoAP Option Number Registry (RFC 7252 §5.10)
+      #
+      # Extensible registry for CoAP option numbers.
+      # Plugins can register custom options without modifying core code.
+      #
+      # @example Using predefined options
+      #   Takagi::CoAP::Registries::Option::URI_PATH         # => 11
+      #   Takagi::CoAP::Registries::Option::CONTENT_FORMAT   # => 12
+      #
+      # @example Registering a custom option
+      #   Takagi::CoAP::Registries::Option.register(65000, 'Custom-Option', :custom_option)
+      #   Takagi::CoAP::Registries::Option::CUSTOM_OPTION  # => 65000
+      #
+      # @example Looking up option names
+      #   Takagi::CoAP::Registries::Option.name_for(11)  # => "Uri-Path"
+      class Option < Base
+        # Check if an option is critical
+        # Critical options must be understood by the recipient
+        # @param number [Integer] Option number
+        # @return [Boolean] true if critical
+        def self.critical?: (untyped number) -> untyped
+
+        # Check if an option is unsafe to forward
+        # @param number [Integer] Option number
+        # @return [Boolean] true if unsafe
+        def self.unsafe?: (untyped number) -> untyped
+
+        # Check if an option has NoCacheKey property
+        # @param number [Integer] Option number
+        # @return [Boolean] true if NoCacheKey
+        def self.no_cache_key?: (untyped number) -> untyped
+
+        # Check if option number is valid
+        # @param number [Integer] Option number
+        # @return [Boolean] true if valid
+        def self.valid?: (untyped number) -> untyped
+      end
+    end
+  end
+end

data/sig/takagi/coap/registries/response.rbs

@@ -0,0 +1,52 @@
+module Takagi
+  module CoAP
+    module Registries
+      # CoAP Response Code Registry (RFC 7252 §12.1.2)
+      #
+      # Extensible registry for CoAP response codes.
+      # Plugins can register custom response codes without modifying core code.
+      #
+      # @example Using predefined codes
+      #   Takagi::CoAP::Registries::Response::CONTENT    # => 69 (2.05)
+      #   Takagi::CoAP::Registries::Response::NOT_FOUND  # => 132 (4.04)
+      #
+      # @example Registering a custom code
+      #   Takagi::CoAP::Registries::Response.register(231, '7.07 Custom', :custom)
+      #   Takagi::CoAP::Registries::Response::CUSTOM  # => 231
+      #
+      # @example Looking up code names
+      #   Takagi::CoAP::Registries::Response.name_for(69)  # => "2.05 Content"
+      class Response < Base
+        # Get the response class (2, 4, 5, etc.)
+        # @param code [Integer] Response code
+        # @return [Integer] Class number
+        def self.class_for: (untyped code) -> untyped
+
+        # Check if code is a success (2.xx)
+        # @param code [Integer] Response code
+        # @return [Boolean] true if success
+        def self.success?: (untyped code) -> untyped
+
+        # Check if code is a client error (4.xx)
+        # @param code [Integer] Response code
+        # @return [Boolean] true if client error
+        def self.client_error?: (untyped code) -> untyped
+
+        # Check if code is a server error (5.xx)
+        # @param code [Integer] Response code
+        # @return [Boolean] true if server error
+        def self.server_error?: (untyped code) -> untyped
+
+        # Check if code is any error (4.xx or 5.xx)
+        # @param code [Integer] Response code
+        # @return [Boolean] true if error
+        def self.error?: (untyped code) -> untyped
+
+        # Check if code is a valid response code
+        # @param code [Integer] Code to check
+        # @return [Boolean] true if valid response code
+        def self.valid?: (untyped code) -> untyped
+      end
+    end
+  end
+end

data/sig/takagi/coap.rbs

@@ -0,0 +1,24 @@
+module Takagi
+  # CoAP Protocol implementation following RFC 7252 and related RFCs.
+  #
+  # This module provides a registry-based system for CoAP protocol constants,
+  # allowing plugins and extensions to register additional constants without
+  # modifying core code.
+  #
+  # @example Registering a custom response code
+  #   Takagi::CoAP::Registries::Response.register(231, '7.01 Custom Code', :custom_code)
+  #
+  # @example Using registered constants
+  #   code = Takagi::CoAP::Registries::Response::CONTENT  # => 69
+  #   Takagi::CoAP::Registries::Response.name_for(69)     # => "2.05 Content"
+  module CoAP
+    # Default CoAP port (RFC 7252 §6.1)
+    DEFAULT_PORT: 5683
+
+    # Default CoAPS (secure) port (RFC 7252 §6.2)
+    DEFAULT_SECURE_PORT: 5684
+
+    # CoAP version (RFC 7252 §3)
+    VERSION: 1
+  end
+end

data/sig/takagi/composite_router.rbs

@@ -0,0 +1,46 @@
+# Takagi::CompositeRouter - Routes requests to mounted controllers
+module Takagi
+  class CompositeRouter
+    # Represents a mounted controller
+    class MountedController < Struct[untyped]
+      attr_accessor controller_class: singleton(Controller)
+      attr_accessor mount_path: String
+      attr_accessor router: Router
+      attr_accessor nested_controllers: Array[singleton(Controller)]
+
+      # Check if this mount handles the given path
+      def handles?: (String path) -> bool
+
+      # Strip mount prefix from path
+      def relative_path: (String path) -> String
+    end
+
+    def initialize: () -> void
+
+    # Mount a controller at a path
+    def mount: (singleton(Controller) controller_class, ?at: String?) -> void
+
+    # Find a route handler
+    def find_route: (String method, String path) -> [Proc?, Hash[Symbol, String]]
+
+    # Get all routes from all controllers
+    def all_routes: () -> Array[String]
+
+    # Get link format entries from all controllers
+    def link_format_entries: () -> Array[Router::RouteEntry]
+
+    # Get all mounted controllers
+    def mounted_controllers: () -> Array[MountedController]
+
+    private
+
+    # Find the mounted controller for a path
+    def find_mounted_controller: (String path) -> MountedController?
+
+    # Recursively mount nested controllers
+    def mount_nested_controllers: (MountedController parent) -> void
+
+    attr_reader mounted: Array[MountedController]
+    attr_reader logger: Logger
+  end
+end

data/sig/takagi/config.rbs

@@ -0,0 +1,134 @@
+module Takagi
+  # Stores runtime configuration loaded from YAML or manual overrides.
+  class Config
+    @custom: untyped
+
+    @server_name: untyped
+
+    @logger: untyped
+
+    @port: untyped
+
+    @bind_address: untyped
+
+    @auto_migrate: untyped
+
+    @threads: untyped
+
+    @processes: untyped
+
+    @protocols: untyped
+
+    @observability: untyped
+
+    @event_bus: untyped
+
+    @router: untyped
+
+    @middleware: untyped
+
+    Observability: untyped
+
+    EventBusConfig: untyped
+
+    RouterConfig: untyped
+
+    MiddlewareConfig: untyped
+
+    attr_accessor port: untyped
+
+    attr_accessor bind_address: untyped
+
+    attr_accessor logger: untyped
+
+    attr_accessor observability: untyped
+
+    attr_accessor auto_migrate: untyped
+
+    attr_accessor custom: untyped
+
+    attr_accessor processes: untyped
+
+    attr_accessor threads: untyped
+
+    attr_accessor protocols: untyped
+
+    attr_accessor server_name: untyped
+
+    attr_accessor event_bus: untyped
+
+    attr_accessor router: untyped
+
+    attr_accessor middleware: untyped
+
+    def initialize: () -> void
+
+    def []: (untyped key) -> untyped
+
+    def []=: (untyped key, untyped value) -> untyped
+
+    def method_missing: (untyped name, *untyped args) { (?) -> untyped } -> untyped
+
+    def respond_to_missing?: (untyped name, ?bool include_private) -> untyped
+
+    def load_file: (untyped path) -> untyped
+
+    private
+
+    def apply_basic_settings: (untyped data) -> untyped
+
+    def apply_logger: (untyped data) -> (nil | untyped)
+
+    def apply_observability: (untyped data) -> (nil | untyped)
+
+    def apply_event_bus: (untyped data) -> (nil | untyped)
+
+    def apply_router: (untyped data) -> (nil | untyped)
+
+    def apply_middleware: (untyped data) -> (nil | untyped)
+
+    def apply_custom_settings: (untyped data) -> untyped
+
+    def load_yaml: (untyped path) -> untyped
+
+    def resolve_logger_output: (untyped target) -> untyped
+
+    def resolve_logger_level: (untyped level) -> untyped
+
+    def set_server_defaults: () -> untyped
+
+    def set_observability_defaults: () -> untyped
+
+    def set_event_bus_defaults: () -> untyped
+
+    def set_router_defaults: () -> untyped
+
+    def set_middleware_defaults: () -> untyped
+
+    def assign_setting: (untyped data, untyped key) { (untyped) -> untyped } -> (nil | untyped)
+
+    def assign_processes: (untyped data) -> (nil | untyped)
+
+    def assign_protocols: (untyped protocols) -> (nil | untyped)
+
+    def assign_event_bus_core: (untyped event_bus_data) -> untyped
+
+    def assign_message_buffer_settings: (untyped event_bus_data) -> untyped
+
+    def assign_event_bus_setting: (untyped event_bus_data, untyped key) -> (nil | untyped)
+
+    # Parse middleware entry from YAML config
+    # Supports both simple strings and hash with options
+    #
+    # @example Simple string
+    #   "Logging"
+    #
+    # @example Hash with options
+    #   { name: "Caching", options: { ttl: 300 } }
+    def parse_middleware_entry: (untyped entry) -> untyped
+
+    # Default middleware stack
+    # Returns an array of middleware configurations
+    def default_middleware_stack: () -> ::Array[{ name: "Debugging", options: ::Hash[untyped, untyped] }]
+  end
+end

data/sig/takagi/controller.rbs

@@ -0,0 +1,73 @@
+# Takagi::Controller - Base class for modular controllers
+module Takagi
+  class Controller
+    # Controller configuration hash
+    type config_hash = {
+      mount_path: String?,
+      nested_from: singleton(Controller)?,
+      nested_controllers: Array[singleton(Controller)],
+      profile: Symbol?,
+      processes: Integer?,
+      threads: Integer?
+    }
+
+    # Get the controller's isolated router
+    def self.router: () -> Router
+
+    # Get the controller's configuration
+    def self.config: () -> config_hash
+
+    # Configure the controller
+    def self.configure: () { (ConfigContext) -> void } -> void
+
+    # Register a route
+    def self.add_route: (String method, String path, ?metadata: Hash[Symbol, untyped]) { (Message::Inbound, Hash[Symbol, String]) -> untyped } -> void
+
+    # HTTP/CoAP method shortcuts (get, post, put, delete, etc.)
+    def self.get: (String path, ?metadata: Hash[Symbol, untyped]) { (Message::Inbound, Hash[Symbol, String]) -> untyped } -> void
+    def self.post: (String path, ?metadata: Hash[Symbol, untyped]) { (Message::Inbound, Hash[Symbol, String]) -> untyped } -> void
+    def self.put: (String path, ?metadata: Hash[Symbol, untyped]) { (Message::Inbound, Hash[Symbol, String]) -> untyped } -> void
+    def self.delete: (String path, ?metadata: Hash[Symbol, untyped]) { (Message::Inbound, Hash[Symbol, String]) -> untyped } -> void
+    def self.patch: (String path, ?metadata: Hash[Symbol, untyped]) { (Message::Inbound, Hash[Symbol, String]) -> untyped } -> void
+    def self.fetch: (String path, ?metadata: Hash[Symbol, untyped]) { (Message::Inbound, Hash[Symbol, String]) -> untyped } -> void
+    def self.ipatch: (String path, ?metadata: Hash[Symbol, untyped]) { (Message::Inbound, Hash[Symbol, String]) -> untyped } -> void
+
+    # Observable route registration
+    def self.observable: (String path, ?metadata: Hash[Symbol, untyped]) { (Message::Inbound, Hash[Symbol, String]) -> untyped } -> void
+
+    # Get the full mount path
+    def self.mount_path: () -> String?
+
+    # Check if mounted
+    def self.mounted?: () -> bool
+
+    # Get nested controllers
+    def self.nested_controllers: () -> Array[singleton(Controller)]
+
+    # Get profile name
+    def self.profile_name: () -> Symbol?
+
+    # Get effective process count
+    def self.process_count: () -> Integer?
+
+    # Get effective thread count
+    def self.thread_count: () -> Integer?
+
+    # Configuration DSL context
+    class ConfigContext
+      def initialize: (singleton(Controller) controller_class) -> void
+
+      # Set mount path
+      def mount: (String path, ?nested_from: singleton(Controller)?) -> void
+
+      # Nest child controllers
+      def nest: (*singleton(Controller) controllers) -> void
+
+      # Set load profile
+      def profile: (Symbol name) -> void
+
+      # Set configuration value
+      def set: (Symbol key, untyped value) -> void
+    end
+  end
+end

data/sig/takagi/core/attribute_set.rbs

@@ -0,0 +1,57 @@
+module Takagi
+  module Core
+    # Encapsulates CoRE Link Format attribute handling for a single route.
+    # The DSL is shared between request-time handlers and boot-time helpers,
+    # so changes applied here are idempotent and safe to call repeatedly.
+    class AttributeSet
+      @metadata: untyped
+
+      @overrides: untyped
+
+      CONTENT_FORMATS: { "text/plain" => 0, "application/link-format" => 40, "application/xml" => 41, "application/octet-stream" => 42, "application/exi" => 47, "application/json" => 50, "application/cbor" => 60 }
+
+      REMOVE: untyped
+
+      attr_reader metadata: untyped
+
+      def initialize: (untyped metadata) -> void
+
+      # Evaluates a block that configures any mix of CoRE attributes.
+      # Accepts the same DSL as the runtime helpers exposed in RouteContext.
+      def core: () ?{ (?) -> untyped } -> (untyped | nil)
+
+      def ct: (untyped value) -> untyped
+
+      alias content_format ct
+
+      def sz: (untyped value) -> untyped
+
+      def title: (untyped value) -> untyped
+
+      def obs: (?bool value) -> untyped
+
+      alias observable obs
+
+      def rt: (*untyped values) -> untyped
+
+      def interface: (*untyped values) -> untyped
+
+      alias if_ interface
+
+      def attribute: (untyped name, untyped value) -> untyped
+
+      # Persists staged attribute overrides back onto the route metadata.
+      # Invoked automatically after request handling, but also exposed so
+      # callers (e.g. Takagi::Router#configure_core) can persist updates.
+      def apply!: () -> (nil | untyped)
+
+      private
+
+      def assign_list: (untyped key, untyped values) -> (nil | untyped)
+
+      def metadata_override: (untyped key, untyped value) -> untyped
+
+      def normalize_content_format: (untyped value) -> untyped
+    end
+  end
+end