takagi 0.1.0 → 1.1.0

data/lib/takagi/coap/registries/base.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+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)
+      # - Thread-safe storage
+      #
+      # 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"}
+      require 'takagi/hooks'
+
+      class Base
+        def self.inherited(subclass)
+          super
+          subclass.instance_variable_set(:@mutex, Mutex.new)
+        end
+
+        class << self
+          # 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 register(value, name, symbol = nil, rfc: nil)
+            @mutex.synchronize do
+              registry[value] = {
+                name: name,
+                symbol: symbol,
+                rfc: rfc
+              }
+
+              # Create constant if symbol provided
+              if symbol
+                const_name = symbol.to_s.upcase
+                const_set(const_name, value) unless const_defined?(const_name, false)
+              end
+
+              # Store reverse lookup
+              reverse_registry[name] = value if name
+              reverse_registry[symbol] = value if symbol
+            end
+
+            Takagi::Hooks.emit(
+              :coap_registry_registered,
+              registry: self,
+              value: value,
+              name: name,
+              symbol: symbol,
+              rfc: rfc
+            )
+          end
+
+          # Get human-readable name for a value
+          #
+          # @param value [Integer] The numeric value
+          # @return [String, nil] The name, or nil if not found
+          def name_for(value)
+            @mutex.synchronize { registry[value]&.dig(:name) }
+          end
+
+          # 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 value_for(key)
+            @mutex.synchronize { reverse_registry[key] }
+          end
+
+          # Get RFC reference for a value
+          #
+          # @param value [Integer] The numeric value
+          # @return [String, nil] The RFC reference, or nil if not found
+          def rfc_for(value)
+            @mutex.synchronize { registry[value]&.dig(:rfc) }
+          end
+
+          # Check if a value is registered
+          #
+          # @param value [Integer] The value to check
+          # @return [Boolean] true if registered
+          def registered?(value)
+            @mutex.synchronize { registry.key?(value) }
+          end
+
+          # Get all registered constants
+          #
+          # @return [Hash] Map of value => name
+          def all
+            @mutex.synchronize { registry.transform_values { |info| info[:name] } }
+          end
+
+          # Iterate over registered values
+          #
+          # @yield [Integer] each registered numeric value
+          # @return [Enumerator] if no block given
+          def each_value(&block)
+            return enum_for(:each_value) unless block_given?
+
+            # Get snapshot to avoid holding lock during iteration
+            snapshot = @mutex.synchronize { registry.keys.dup }
+            snapshot.each(&block)
+          end
+
+          # Get all registered values
+          #
+          # @return [Array<Integer>] Array of all values
+          def values
+            @mutex.synchronize { registry.keys.dup }
+          end
+
+          # Get registry metadata for a value
+          #
+          # @param value [Integer] The numeric value
+          # @return [Hash, nil] Full metadata hash
+          def metadata_for(value)
+            @mutex.synchronize { registry[value]&.dup }
+          end
+
+          # Clear all registrations (useful for testing)
+          def clear!
+            @mutex.synchronize do
+              registry.clear
+              reverse_registry.clear
+              # Remove constants (carefully)
+              constants(false).each do |const_name|
+                remove_const(const_name) if const_name =~ /^[A-Z_]+$/
+              end
+            end
+
+            Takagi::Hooks.emit(:coap_registry_cleared, registry: self)
+          end
+
+          private
+
+          def registry
+            @registry ||= {}
+          end
+
+          def reverse_registry
+            @reverse_registry ||= {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/takagi/coap/registries/content_format.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+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
+        # RFC 7252 §12.3 - Content-Format Registry
+        register(0, 'text/plain', :text_plain, rfc: 'RFC 7252 §12.3')
+        register(40, 'application/link-format', :link_format, rfc: 'RFC 6690')
+        register(41, 'application/xml', :xml, rfc: 'RFC 7252 §12.3')
+        register(42, 'application/octet-stream', :octet_stream, rfc: 'RFC 7252 §12.3')
+        register(47, 'application/exi', :exi, rfc: 'RFC 7252 §12.3')
+        register(50, 'application/json', :json, rfc: 'RFC 7252 §12.3')
+        register(60, 'application/cbor', :cbor, rfc: 'RFC 7049')
+
+        # Get MIME type for a content-format code
+        # @param code [Integer] Content-format code
+        # @return [String, nil] MIME type
+        def self.mime_type_for(code)
+          name_for(code)
+        end
+
+        # 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(mime_type)
+          value_for(mime_type)
+        end
+
+        # Check if format is JSON-based
+        # @param code [Integer] Content-format code
+        # @return [Boolean] true if JSON format
+        def self.json?(code)
+          mime = mime_type_for(code)
+          mime&.include?('json') || false
+        end
+
+        # Check if format is CBOR-based
+        # @param code [Integer] Content-format code
+        # @return [Boolean] true if CBOR format
+        def self.cbor?(code)
+          mime = mime_type_for(code)
+          mime&.include?('cbor') || false
+        end
+
+        # Check if format is text-based
+        # @param code [Integer] Content-format code
+        # @return [Boolean] true if text format
+        def self.text?(code)
+          mime = mime_type_for(code)
+          mime&.start_with?('text/') || false
+        end
+      end
+    end
+  end
+end

data/lib/takagi/coap/registries/message_type.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+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
+        # RFC 7252 §3 - Message Format
+        register(0, 'Confirmable', :confirmable, rfc: 'RFC 7252 §3')
+        register(1, 'Non-confirmable', :non_confirmable, rfc: 'RFC 7252 §3')
+        register(2, 'Acknowledgement', :acknowledgement, rfc: 'RFC 7252 §3')
+        register(3, 'Reset', :reset, rfc: 'RFC 7252 §3')
+
+        # Aliases for convenience
+        CON = CONFIRMABLE
+        NON = NON_CONFIRMABLE
+        ACK = ACKNOWLEDGEMENT
+        RST = RESET
+
+        # Check if type is confirmable
+        # @param type [Integer] Message type
+        # @return [Boolean] true if confirmable
+        def self.confirmable?(type)
+          type == CONFIRMABLE
+        end
+
+        # Check if type is non-confirmable
+        # @param type [Integer] Message type
+        # @return [Boolean] true if non-confirmable
+        def self.non_confirmable?(type)
+          type == NON_CONFIRMABLE
+        end
+
+        # Check if type is acknowledgement
+        # @param type [Integer] Message type
+        # @return [Boolean] true if acknowledgement
+        def self.acknowledgement?(type)
+          type == ACKNOWLEDGEMENT
+        end
+        class << self
+          alias ack? acknowledgement?
+        end
+
+        # Check if type is reset
+        # @param type [Integer] Message type
+        # @return [Boolean] true if reset
+        def self.reset?(type)
+          type == RESET
+        end
+
+        # Check if type is valid
+        # @param type [Integer] Message type
+        # @return [Boolean] true if valid
+        def self.valid?(type)
+          (0..3).include?(type)
+        end
+      end
+    end
+  end
+end

data/lib/takagi/coap/registries/method.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+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
+        # RFC 7252 §5.8 - Method Codes
+        register(0, 'EMPTY', :empty, rfc: 'RFC 7252 §5.8')
+        register(1, 'GET', :get, rfc: 'RFC 7252 §5.8.1')
+        register(2, 'POST', :post, rfc: 'RFC 7252 §5.8.2')
+        register(3, 'PUT', :put, rfc: 'RFC 7252 §5.8.3')
+        register(4, 'DELETE', :delete, rfc: 'RFC 7252 §5.8.4')
+
+        # Check if code is a valid method code
+        # @param code [Integer] Code to check
+        # @return [Boolean] true if valid method
+        def self.valid?(code)
+          (0..31).include?(code) && registered?(code)
+        end
+      end
+    end
+  end
+end

data/lib/takagi/coap/registries/option.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+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
+        # RFC 7252 §5.10.1 - Option Definitions
+        register(1, 'If-Match', :if_match, rfc: 'RFC 7252 §5.10.8.1')
+        register(3, 'Uri-Host', :uri_host, rfc: 'RFC 7252 §5.10.1')
+        register(4, 'ETag', :etag, rfc: 'RFC 7252 §5.10.6')
+        register(5, 'If-None-Match', :if_none_match, rfc: 'RFC 7252 §5.10.8.2')
+        register(6, 'Observe', :observe, rfc: 'RFC 7641 §2')
+        register(7, 'Uri-Port', :uri_port, rfc: 'RFC 7252 §5.10.1')
+        register(8, 'Location-Path', :location_path, rfc: 'RFC 7252 §5.10.7')
+        register(11, 'Uri-Path', :uri_path, rfc: 'RFC 7252 §5.10.1')
+        register(12, 'Content-Format', :content_format, rfc: 'RFC 7252 §5.10.3')
+        register(14, 'Max-Age', :max_age, rfc: 'RFC 7252 §5.10.5')
+        register(15, 'Uri-Query', :uri_query, rfc: 'RFC 7252 §5.10.2')
+        register(17, 'Accept', :accept, rfc: 'RFC 7252 §5.10.4')
+        register(20, 'Location-Query', :location_query, rfc: 'RFC 7252 §5.10.7')
+        register(35, 'Proxy-Uri', :proxy_uri, rfc: 'RFC 7252 §5.10.2')
+        register(39, 'Proxy-Scheme', :proxy_scheme, rfc: 'RFC 7252 §5.10.2')
+        register(60, 'Size1', :size1, rfc: 'RFC 7252 §5.10.9')
+
+        # 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?(number)
+          number.allbits?(1)
+        end
+
+        # Check if an option is unsafe to forward
+        # @param number [Integer] Option number
+        # @return [Boolean] true if unsafe
+        def self.unsafe?(number)
+          number.allbits?(2)
+        end
+
+        # Check if an option has NoCacheKey property
+        # @param number [Integer] Option number
+        # @return [Boolean] true if NoCacheKey
+        def self.no_cache_key?(number)
+          (number & 0x1E) == 0x1C
+        end
+
+        # Check if option number is valid
+        # @param number [Integer] Option number
+        # @return [Boolean] true if valid
+        def self.valid?(number)
+          number.between?(0, 65_535)
+        end
+      end
+    end
+  end
+end

data/lib/takagi/coap/registries/response.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+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
+        # Success 2.xx (RFC 7252 §5.9.1)
+        register(65, '2.01 Created', :created, rfc: 'RFC 7252 §5.9.1.1')
+        register(66, '2.02 Deleted', :deleted, rfc: 'RFC 7252 §5.9.1.2')
+        register(67, '2.03 Valid', :valid, rfc: 'RFC 7252 §5.9.1.3')
+        register(68, '2.04 Changed', :changed, rfc: 'RFC 7252 §5.9.1.4')
+        register(69, '2.05 Content', :content, rfc: 'RFC 7252 §5.9.1.5')
+
+        # Client Error 4.xx (RFC 7252 §5.9.2)
+        register(128, '4.00 Bad Request', :bad_request, rfc: 'RFC 7252 §5.9.2.1')
+        register(129, '4.01 Unauthorized', :unauthorized, rfc: 'RFC 7252 §5.9.2.2')
+        register(130, '4.02 Bad Option', :bad_option, rfc: 'RFC 7252 §5.9.2.3')
+        register(131, '4.03 Forbidden', :forbidden, rfc: 'RFC 7252 §5.9.2.4')
+        register(132, '4.04 Not Found', :not_found, rfc: 'RFC 7252 §5.9.2.5')
+        register(133, '4.05 Method Not Allowed', :method_not_allowed, rfc: 'RFC 7252 §5.9.2.6')
+        register(134, '4.06 Not Acceptable', :not_acceptable, rfc: 'RFC 7252 §5.9.2.7')
+        register(140, '4.12 Precondition Failed', :precondition_failed, rfc: 'RFC 7252 §5.9.2.9')
+        register(141, '4.13 Request Entity Too Large', :request_entity_too_large, rfc: 'RFC 7252 §5.9.2.10')
+        register(143, '4.15 Unsupported Content-Format', :unsupported_content_format, rfc: 'RFC 7252 §5.9.2.11')
+
+        # Server Error 5.xx (RFC 7252 §5.9.3)
+        register(160, '5.00 Internal Server Error', :internal_server_error, rfc: 'RFC 7252 §5.9.3.1')
+        register(161, '5.01 Not Implemented', :not_implemented, rfc: 'RFC 7252 §5.9.3.2')
+        register(162, '5.02 Bad Gateway', :bad_gateway, rfc: 'RFC 7252 §5.9.3.3')
+        register(163, '5.03 Service Unavailable', :service_unavailable, rfc: 'RFC 7252 §5.9.3.4')
+        register(164, '5.04 Gateway Timeout', :gateway_timeout, rfc: 'RFC 7252 §5.9.3.5')
+        register(165, '5.05 Proxying Not Supported', :proxying_not_supported, rfc: 'RFC 7252 §5.9.3.6')
+
+        # Get the response class (2, 4, 5, etc.)
+        # @param code [Integer] Response code
+        # @return [Integer] Class number
+        def self.class_for(code)
+          code / 32
+        end
+
+        # Check if code is a success (2.xx)
+        # @param code [Integer] Response code
+        # @return [Boolean] true if success
+        def self.success?(code)
+          class_for(code) == 2
+        end
+
+        # Check if code is a client error (4.xx)
+        # @param code [Integer] Response code
+        # @return [Boolean] true if client error
+        def self.client_error?(code)
+          class_for(code) == 4
+        end
+
+        # Check if code is a server error (5.xx)
+        # @param code [Integer] Response code
+        # @return [Boolean] true if server error
+        def self.server_error?(code)
+          class_for(code) == 5
+        end
+
+        # Check if code is any error (4.xx or 5.xx)
+        # @param code [Integer] Response code
+        # @return [Boolean] true if error
+        def self.error?(code)
+          client_error?(code) || server_error?(code)
+        end
+
+        # Check if code is a valid response code
+        # @param code [Integer] Code to check
+        # @return [Boolean] true if valid response code
+        def self.valid?(code)
+          code.between?(64, 191) && registered?(code)
+        end
+      end
+    end
+  end
+end

data/lib/takagi/coap/registries/signaling.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Takagi
+  module CoAP
+    module Registries
+      # CoAP Signaling Code Registry (RFC 8323 §5)
+      #
+      # Registry for CoAP over TCP/TLS signaling messages.
+      # Signaling messages use codes in the 7.xx range.
+      #
+      # @example Using signaling codes
+      #   Takagi::CoAP::Registries::Signaling::CSM    # => 225 (7.01)
+      #   Takagi::CoAP::Registries::Signaling::PING   # => 226 (7.02)
+      #
+      # @example Looking up signaling message names
+      #   Takagi::CoAP::Registries::Signaling.name_for(225)  # => "7.01 CSM"
+      class Signaling < Base
+        # RFC 8323 §5.3 - Signaling Codes
+        register(225, '7.01 CSM', :csm, rfc: 'RFC 8323 §5.3.1')          # Capabilities and Settings Message
+        register(226, '7.02 Ping', :ping, rfc: 'RFC 8323 §5.3.2')        # Ping
+        register(227, '7.03 Pong', :pong, rfc: 'RFC 8323 §5.3.3')        # Pong
+        register(228, '7.04 Release', :release, rfc: 'RFC 8323 §5.3.4')  # Release
+        register(229, '7.05 Abort', :abort, rfc: 'RFC 8323 §5.3.5')      # Abort
+
+        # Check if code is a signaling code
+        # @param code [Integer] Code to check
+        # @return [Boolean] true if signaling code (7.xx)
+        def self.signaling?(code)
+          (224..255).include?(code) && registered?(code)
+        end
+      end
+    end
+  end
+end

data/lib/takagi/coap/signaling.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'registries/signaling'
+
+module Takagi
+  module CoAP
+    # Alias for Registries::Signaling
+    Signaling = Registries::Signaling
+  end
+end

data/lib/takagi/coap.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Takagi
+  # CoAP Protocol implementation following RFC 7252 and related RFCs.
+  #
+  # This module provides a registry-based system for CoAP protocol constants.
+  # Plugins and extensions can register additional constants without modifying
+  # core code by using the registries under {Takagi::CoAP::Registries}.
+  #
+  # @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
+
+# Load registries
+require_relative 'coap/registries/base'
+require_relative 'coap/registries/method'
+require_relative 'coap/registries/response'
+require_relative 'coap/registries/option'
+require_relative 'coap/registries/content_format'
+require_relative 'coap/registries/message_type'
+require_relative 'coap/registries/signaling'
+
+require_relative 'coap/code_helpers'