takagi 0.1.0 → 1.1.0

data/ROADMAP.md

@@ -0,0 +1,55 @@
+# Takagi Roadmap
+
+## Takagi 1.0 – Core CoAP Framework (Current Phase)
+**Goal:** A functional CoAP server & client, usable for IoT and edge computing.
+
+**Internal definition:** Sinatra for CoAP
+
+- [x] **Takagi Server** → Routing, dynamic paths (`/devices/:id`), basic message parsing.
+- [x] **Takagi Client** → Enables communication with the Takagi Server.
+- [x] **Basic support for URL ID parameters & payloads.**
+- [x] **Logging and debugging for easier development.**
+- [ ] **Sequel support for seamless storing data from CoAP**
+- [ ] **Better error handling & stability improvements.**
+- [ ] **Extended routing DSL (e.g., wildcards).**
+- [ ] **Tests and RFC compatibility checks.**
+- [ ] **Push Notifications (Observe)** 
+
+---
+
+## Takagi-Device (Spiegel) – IoT Device Management Module (Post-1.0)
+**Goal:** A full-fledged device management system over CoAP.
+
+**Internal definition:** Know everything about your devices like Spike Spiegel about his enemies
+
+- [ ] **Device Registration** → like `/register` endpoint.
+- [ ] **Real-time Monitoring** → like `/status` endpoint.
+- [ ] **Device Authentication** → Basic token-based security.
+- [ ] **Notify clients about state changes trough Observer**
+- [ ] **Define a standardized API for devices.**
+- [ ] **Integrate with more databases (InfluxDB?).**
+- [ ] **Scalability & performance testing.**
+
+---
+
+## Takagi-Sinatra – Web Dashboard
+**Goal:** Web integration visualization & admin panel for IoT device management.
+
+**Internal definition:** Because Takagi and Sinatra would be great duo!
+
+- [ ] **Show online/offline devices.**
+- [ ] **Visualize metrics (battery, signal strength, temperature, etc.).**
+- [ ] **CRUD operations for managing devices.**
+- [ ] **Charts & real-time data streaming.**
+- [ ] **Authentication & user access control.**
+
+---
+
+## Takagi-Zephyr – Embedded Integration with ZephyrOS
+**Goal:** Allow communicate with Takagi on low-power IoT devices with Spiegel management.
+
+**Internal definition:** Because software is not everything.
+
+- [ ] **Develop Spiegel-able library for ZephyrOS**
+- [ ] **Minimalist footprint for embedded systems.**
+- [ ] **Test edge computing use-cases.**

data/Rakefile

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+task default: %i[spec]

data/Steepfile

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# D = Steep::Diagnostic
+#
+# target :lib do
+#   signature "sig"
+#   ignore_signature "sig/test"
+#
+#   check "lib"                       # Directory name
+#   check "path/to/source.rb"         # File name
+#   check "app/models/**/*.rb"        # Glob
+#   # ignore "lib/templates/*.rb"
+#
+#   # library "pathname"              # Standard libraries
+#   # library "strong_json"           # Gems
+#
+#   # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)
+#   # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+#   # configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+#   # configure_code_diagnostics(D::Ruby.silent)       # `silent` diagnostics setting
+#   # configure_code_diagnostics do |hash|             # You can setup everything yourself
+#   #   hash[D::Ruby::NoMethod] = :information
+#   # end
+# end
+
+# target :test do
+#   unreferenced!                     # Skip type checking the `lib` code when types in `test` target is changed
+#   signature "sig/test"              # Put RBS files for tests under `sig/test`
+#   check "test"                      # Type check Ruby scripts under `test`
+#
+#   configure_code_diagnostics(D::Ruby.lenient)      # Weak type checking for test code
+#
+#   # library "pathname"              # Standard libraries
+# end
+
+target :takagi do
+  check 'lib'
+  signature 'sig'
+end

data/bin/takagi-dev

@@ -0,0 +1,159 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Takagi CLI - Minimal commands for server management and information
+# Project generation and advanced features available in takagi-devtools gem
+
+require_relative '../lib/takagi'
+require_relative '../lib/takagi/branding'
+
+command = ARGV[0]
+args = ARGV[1..]
+
+case command
+when 'server', 's'
+  # Parse options
+  port = 5683
+  protocols = [:udp]
+  banner = true
+  app_file = 'app.rb'
+
+  i = 0
+  while i < args.length
+    case args[i]
+    when '-p', '--port'
+      port = args[i + 1].to_i
+      i += 1
+    when '--tcp'
+      protocols << :tcp unless protocols.include?(:tcp)
+    when '--udp'
+      protocols << :udp unless protocols.include?(:udp)
+    when '--no-banner'
+      banner = false
+    when '-f', '--file'
+      app_file = args[i + 1]
+      i += 1
+    end
+    i += 1
+  end
+
+  # Load the application
+  unless File.exist?(app_file)
+    puts Takagi::Branding.error("Application file not found: #{app_file}")
+    puts Takagi::Branding.info("Create #{app_file} or specify with -f FILE")
+    exit 1
+  end
+
+  puts Takagi::Branding.log("Loading application from #{app_file}...")
+  require File.expand_path(app_file)
+
+  # Find the application class (first class inheriting from Takagi::Base)
+  app_class = ObjectSpace.each_object(Class).find { |klass| klass < Takagi::Base && klass != Takagi::Base }
+
+  unless app_class
+    puts Takagi::Branding.error("No Takagi::Base subclass found in #{app_file}")
+    puts Takagi::Branding.info("Define a class that inherits from Takagi::Base")
+    exit 1
+  end
+
+  # Start the server
+  app_class.run!(port: port, protocols: protocols, banner: banner)
+
+when 'routes', 'r'
+  # Load the application
+  app_file = 'app.rb'
+  args.each_with_index do |arg, i|
+    app_file = args[i + 1] if arg == '-f' || arg == '--file'
+  end
+
+  unless File.exist?(app_file)
+    puts Takagi::Branding.error("Application file not found: #{app_file}")
+    exit 1
+  end
+
+  require File.expand_path(app_file)
+
+  # Find the application class
+  app_class = ObjectSpace.each_object(Class).find { |klass| klass < Takagi::Base && klass != Takagi::Base }
+
+  unless app_class
+    puts Takagi::Branding.error("No Takagi::Base subclass found")
+    exit 1
+  end
+
+  puts Takagi::Branding.section('Registered Routes')
+  puts
+
+  router = app_class.router
+  routes = router.instance_variable_get(:@routes)
+
+  if routes.empty?
+    puts Takagi::Branding.info('No routes registered')
+  else
+    # Group routes by method
+    grouped = routes.values.group_by(&:method).sort_by { |method, _| method }
+
+    grouped.each do |method, entries|
+      entries.each do |entry|
+        metadata_str = if entry.metadata.any?
+                         tags = entry.metadata.map { |k, v| "#{k}:#{v}" }.join(', ')
+                         " [#{tags}]"
+                       else
+                         ''
+                       end
+
+        puts Takagi::Branding.log("#{method.ljust(8)} #{entry.path}#{metadata_str}")
+      end
+    end
+
+    puts
+    puts Takagi::Branding.success("#{routes.size} routes registered")
+  end
+
+when 'version', 'v', '-v', '--version'
+  version = defined?(Takagi::VERSION) ? Takagi::VERSION : '1.0.0'
+  puts Takagi::Branding::LOGO_WITH_NAME + " v#{version}"
+
+when 'help', 'h', '-h', '--help', nil
+  puts <<~HELP
+
+    #{Takagi::Branding::BANNER}
+
+    Usage: takagi COMMAND [options]
+
+    Commands:
+      server, s          Start the Takagi server
+      routes, r          List all registered routes
+      version, v         Show Takagi version
+      help, h            Show this help message
+
+    Server Options:
+      -p, --port PORT    Port to bind to (default: 5683)
+      --tcp              Enable TCP protocol
+      --udp              Enable UDP protocol (default)
+      --no-banner        Disable startup banner
+      -f, --file FILE    Application file (default: app.rb)
+
+    Routes Options:
+      -f, --file FILE    Application file (default: app.rb)
+
+    Examples:
+      takagi server                    # Start server on port 5683 (UDP)
+      takagi server -p 5684            # Start on custom port
+      takagi server --tcp --udp        # Enable both protocols
+      takagi server --no-banner        # No banner
+      takagi routes                    # List all routes
+      takagi version                   # Show version
+
+    For project generation and advanced features, install:
+      gem install takagi-devtools
+
+    #{Takagi::Branding::WAVE_LINE}
+
+  HELP
+
+else
+  puts Takagi::Branding.error("Unknown command: #{command}")
+  puts Takagi::Branding.info("Run 'takagi help' for usage information")
+  exit 1
+end

data/docs/FIRST_PLUGIN_GUIDE.md

@@ -0,0 +1,224 @@
+# First Plugin Guide
+
+Build a Takagi plugin that adds routes, content-formats, and even transports, without touching core code.
+
+## Plugin contract (what you implement)
+- Module (ideally `Takagi::Plugins::<Name>`) with `.apply(app, opts = {})`.
+- Optional lifecycle: `.before_apply(app, opts)`, `.after_apply(app, opts)`, `.before_unload(app)`, `.shutdown(app)`.
+- Optional metadata via `.metadata` hash: `{ name:, description:, requires:, dependencies: [] }`.
+- Optional config schema via `.config_schema` hash: keys → rules (`:type`, `:required`, `:default`, `:enum`, `:range`, `:validate` proc).
+- Optional route prefix isolation via `metadata[:route_prefix]` to auto-prefix routes registered by the plugin.
+- Enable via `plugin :name, opts` in your app + `enable_plugins!`, or via config (`Takagi.config.plugins.enabled`). Auto-discovery will pick up `Takagi::Plugins::*` and gems named `takagi-plugin-*`.
+  - You can order plugins with `plugin :name, order: 10` (lower runs first).
+
+## Minimal skeleton
+```ruby
+# lib/takagi/plugins/hello.rb
+module Takagi
+  module Plugins
+    module Hello
+      def self.metadata
+        { name: :hello, description: 'Adds /hello endpoint' }
+      end
+
+      def self.config_schema
+        { greeting: { type: :string, default: 'Hello' } }
+      end
+
+      # Optional: isolate routes under /hello
+      def self.metadata
+        { name: :hello, route_prefix: '/hello' }
+      end
+
+      def self.apply(app, opts = {})
+        greeting = opts[:greeting] || 'Hello'
+        app.get '/hello' do
+          respond message: "#{greeting}, CoAP!"
+        end
+      end
+    end
+  end
+end
+```
+
+Enable it:
+```ruby
+class MyAPI < Takagi::Base
+  plugin :hello, greeting: 'Ahoy'
+end
+MyAPI.enable_plugins!
+```
+Or via config: add `{ name: :hello, options: { greeting: 'Hi' } }` to `Takagi.config.plugins.enabled`.
+
+## Add a new content-format + serializer
+```ruby
+module Takagi
+  module Plugins
+    module SenmlCbor
+      def self.metadata
+        { name: :senml_cbor, description: 'SenML CBOR support', version: '1.0.0' }
+      end
+
+      def self.apply(_app, _opts = {})
+        serializer = Class.new(Takagi::Serialization::Base) do
+          def encode(data) CBOR.encode(data) end
+          def decode(bytes) CBOR.decode(bytes) end
+          def content_type; 'application/senml+cbor'; end
+          def content_format_code; 112; end # example code
+        end
+
+        Takagi::Serialization::Registry.register(serializer.new.content_format_code, serializer)
+        Takagi::CoAP::Registries::ContentFormat.register(serializer.new.content_format_code, serializer.new.content_type, :senml_cbor)
+      end
+    end
+  end
+end
+```
+Use it in routes by setting `ct:` metadata or `respond(payload, force: 112)`; `respond` negotiates with `Accept` and returns `4.06/4.15` when unsupported.
+
+## Add a new protocol/transport
+```ruby
+module Takagi
+  module Plugins
+    module Quic
+      def self.metadata
+        { name: :quic, description: 'CoAP over QUIC' }
+      end
+
+      def self.apply(app, opts = {})
+        Takagi::Server::Registry.register(:quic, Takagi::Server::Quic, rfc: 'RFC xxxx')
+        Takagi::Network::Registry.register(:quic, Takagi::Network::Quic)
+        # Optionally auto-enable:
+        app.run!(protocols: (opts[:protocols] || [:udp, :tcp, :quic]))
+      end
+    end
+  end
+end
+```
+Implement `Takagi::Server::Quic` and `Takagi::Network::Quic` similar to UDP/TCP classes.
+
+## Plugin-specific controllers/routes
+Add routes directly in `.apply`:
+```ruby
+def self.apply(app, _opts = {})
+  app.get '/plugin/info', metadata: { ct: Takagi::CoAP::Registries::ContentFormat::JSON } do
+    respond name: 'my_plugin', version: '1.0.0'
+  end
+end
+```
+If you want a dedicated controller class, subclass `Takagi::Base` or `Takagi::Controller` and register its routes inside `.apply`.
+
+## Register new CoAP codes/options (if needed)
+- Methods: `Takagi::CoAP::Registries::Method.register(7, 'CUSTOM', :custom)`
+- Responses: `Takagi::CoAP::Registries::Response.register(231, '7.07 Custom', :custom)` (helper methods are generated).
+- Options: `Takagi::CoAP::Registries::Option.register(65000, 'Plugin-Option', :plugin_option)`
+
+## Hooks and events
+Hooks emitted during plugin lifecycle: `:plugin_registered`, `:plugin_enabling`, `:plugin_enabled`, `:plugin_disabling`, `:plugin_disabled`, `:plugin_error` (see `docs/HOOKS.md`). Subscribe if you need side effects/logging. You can also publish EventBus events under `plugin.*` if needed.
+
+### Lifecycle hooks (and when to use them)
+- `:plugin_registered` — after a plugin module is registered. Use to log or audit availability.
+- `:plugin_enabling` — before `.apply` runs. Use to perform pre-flight checks or metrics.
+- `:plugin_enabled` — after `.apply` completes. Use to announce availability (e.g., publish `plugin.started`).
+- `:plugin_disabling` — before shutdown/unload. Use to stop background work or flush buffers.
+- `:plugin_disabled` — after shutdown/unload. Use to log or emit “stopped” events.
+- `:plugin_error` — when any lifecycle step raises. Use to alert/rollback.
+
+Subscribe via `Takagi::Hooks.on(:event_name) { |payload| ... }` (see `docs/HOOKS.md`).
+
+### Other useful hooks (see `docs/HOOKS.md` for payloads)
+- Router/routes: `:router_route_added` — track dynamic route registration (metrics/debug).
+- Middleware: `:middleware_before_call`, `:middleware_after_call` — wrap/measure middleware execution.
+- Response build: `:before_response_build`, `:after_response_build` — observe how results become responses.
+- Server lifecycle: `:server_starting`, `:server_stopped` — start/stop transport-adjacent resources.
+- Worker lifecycle: `:controller_workers_started`, `:controller_workers_stopped` — manage thread-bound resources.
+- Observe: `:observe_subscribed`, `:observe_unsubscribed`, `:observe_notify_start`, `:observe_notify_end` — instrument CoAP Observe flows.
+- CoAP registries: `:coap_registry_registered`, `:coap_registry_cleared` — react to new methods/options/content-formats.
+
+### Hook payloads and quick examples
+Subscribe with `Takagi::Hooks.on(:hook) { |p| ... }`, emit with `Takagi::Hooks.emit(:hook, payload)`.
+
+- `:coap_registry_registered` — keys: `registry`, `value`, `name`, `symbol`, `rfc`.  
+  Example: `Takagi::Hooks.on(:coap_registry_registered) { |p| Takagi.logger.info("Registry #{p[:registry]} added #{p[:name]} (#{p[:value]})") }`
+- `:coap_registry_cleared` — keys: `registry`.  
+  Example: `Takagi::Hooks.on(:coap_registry_cleared) { |p| Takagi.logger.warn("Registry cleared: #{p[:registry]}") }`
+- `:router_route_added` — keys: `method`, `path`, `entry`.  
+  Example: `Takagi::Hooks.on(:router_route_added) { |p| Takagi.logger.info("Route #{p[:method]} #{p[:path]} added") }`
+- `:middleware_before_call` — keys: `request`.  
+  Example: `Takagi::Hooks.on(:middleware_before_call) { |p| metrics.increment(:mw_in) }`
+- `:middleware_after_call` — keys: `request`, `response`.  
+  Example: `Takagi::Hooks.on(:middleware_after_call) { |p| metrics.timing(:mw_latency, Time.now - p[:request].started_at) if p[:request].respond_to?(:started_at) }`
+- `:before_response_build` — keys: `inbound`, `result`.  
+  Example: `Takagi::Hooks.on(:before_response_build) { |p| Takagi.logger.debug("Building response from #{p[:result].class}") }`
+- `:after_response_build` — keys: `inbound`, `response`, `result`.  
+  Example: `Takagi::Hooks.on(:after_response_build) { |p| metrics.increment(:responses) }`
+- `:server_starting` — keys: `protocol`, `port`.  
+  Example: `Takagi::Hooks.on(:server_starting) { |p| Takagi.logger.info("Starting #{p[:protocol]} on #{p[:port]}") }`
+- `:server_stopped` — keys: `protocol`, `port`.  
+  Example: `Takagi::Hooks.on(:server_stopped) { |p| Takagi.logger.info("Stopped #{p[:protocol]} on #{p[:port]}") }`
+- `:controller_workers_started` — keys: `controller`, `name`, `threads`.  
+  Example: `Takagi::Hooks.on(:controller_workers_started) { |p| metrics.gauge(:worker_threads, p[:threads]) }`
+- `:controller_workers_stopped` — keys: `controller`.  
+  Example: `Takagi::Hooks.on(:controller_workers_stopped) { |p| Takagi.logger.info("Workers stopped for #{p[:controller]}") }`
+- `:observe_subscribed` — keys: `path`, `subscription`.  
+  Example: `Takagi::Hooks.on(:observe_subscribed) { |p| metrics.increment(:observe_subscriptions) }`
+- `:observe_unsubscribed` — keys: `path`, `token`.  
+  Example: `Takagi::Hooks.on(:observe_unsubscribed) { |p| metrics.increment(:observe_unsubscriptions) }`
+- `:observe_notify_start` — keys: `path`, `subscribers`, `value`.  
+  Example: `Takagi::Hooks.on(:observe_notify_start) { |p| metrics.gauge(:observers, p[:subscribers].size) }`
+- `:observe_notify_end` — keys: `path`, `delivered`, `value`.  
+  Example: `Takagi::Hooks.on(:observe_notify_end) { |p| metrics.increment(:observe_notifications, p[:delivered]) }`
+- `:plugin_registered` — keys: `name`, `metadata`.  
+  Example: `Takagi::Hooks.on(:plugin_registered) { |p| Takagi.logger.info("Plugin registered: #{p[:name]}") }`
+- `:plugin_enabling` — keys: `name`, `metadata`, `options`.  
+  Example: `Takagi::Hooks.on(:plugin_enabling) { |p| audit("enable #{p[:name]}", p[:options]) }`
+- `:plugin_enabled` — keys: `name`, `metadata`.  
+  Example: `Takagi::Hooks.on(:plugin_enabled) { |p| EventBus.publish('plugin.started', p) if defined?(EventBus) }`
+- `:plugin_disabling` — keys: `name`, `metadata`.  
+  Example: `Takagi::Hooks.on(:plugin_disabling) { |p| audit("disable #{p[:name]}") }`
+- `:plugin_disabled` — keys: `name`, `metadata`.  
+  Example: `Takagi::Hooks.on(:plugin_disabled) { |p| Takagi.logger.info("Plugin disabled: #{p[:name]}") }`
+- `:plugin_error` — keys: `name`, `metadata`, `error`.  
+  Example: `Takagi::Hooks.on(:plugin_error) { |p| Takagi.logger.error("Plugin error #{p[:name]}: #{p[:error]}") }`
+
+### Hook call order (lifecycle sketch)
+```
+Plugin enable:
+  plugin_registered (when module is registered)
+  plugin_enabling
+    before_apply (optional, plugin hook)
+    apply        (plugin logic runs)
+    after_apply  (optional, plugin hook)
+  plugin_enabled
+  plugin_error (on any failure above)
+
+Plugin disable:
+  plugin_disabling
+    before_unload (optional)
+    shutdown      (optional)
+  plugin_disabled
+  plugin_error (on failure)
+
+Server/workers:
+  server_starting -> controller_workers_started -> ...runtime... -> controller_workers_stopped -> server_stopped
+
+Request/response:
+  middleware_before_call -> ...handler... -> before_response_build -> after_response_build -> middleware_after_call
+
+Routes/registries:
+  router_route_added (when route registered)
+  coap_registry_registered (when registry extended)
+  coap_registry_cleared (mostly in tests/reset)
+
+Observe:
+  observe_subscribed / observe_unsubscribed
+  observe_notify_start -> observe_notify_end
+```
+
+## Checklist
+1) Create `Takagi::Plugins::YourPlugin` with `.apply`.
+2) (Optional) Add serializers/content-formats; register in both `Serialization::Registry` and `CoAP::Registries::ContentFormat`.
+3) (Optional) Add transport: register server + network transport.
+4) Add routes (or a controller) using `respond`, set `ct` metadata so discovery and negotiation stay aligned; use `route_prefix` if you want isolation.
+5) Declare metadata/config schema; handle dependencies/`requires`/dependency versions.
+6) Enable via `plugin :your_plugin, options, order: X` and call `enable_plugins!` (or rely on auto-discovery/config).

data/docs/HOOKS.md

@@ -0,0 +1,31 @@
+# Hooks for Plugins (EventBus-backed)
+
+Hooks are published on the EventBus under `hooks.<event>` and delivered to local consumers. Subscribe with `Takagi::Hooks.subscribe(event) { |payload| ... }` (internally uses `EventBus.consumer`), emit with `Takagi::Hooks.emit(event, payload)`. Payloads are sent with `freeze_body: false` to avoid freezing mutable objects; keep payloads small and serializable for future clustering.
+
+Current events and payloads:
+- `:coap_registry_registered` — { registry:, value:, name:, symbol:, rfc: }
+- `:coap_registry_cleared` — { registry: }
+- `:router_route_added` — { method:, path:, entry: }
+- `:middleware_before_call` — { request: }
+- `:middleware_after_call` — { request:, response: }
+- `:before_response_build` — { inbound:, result: }
+- `:after_response_build` — { inbound:, response:, result: }
+- `:server_starting` — { protocol:, port: }
+- `:server_stopped` — { protocol:, port: }
+- `:controller_workers_started` — { controller:, name:, threads: }
+- `:controller_workers_stopped` — { controller: }
+- `:observe_subscribed` — { path:, subscription: }
+- `:observe_unsubscribed` — { path:, token: }
+- `:observe_notify_start` — { path:, subscribers:, value: }
+- `:observe_notify_end` — { path:, delivered:, value: }
+- `:plugin_registered` — { name:, metadata: }
+- `:plugin_enabling` — { name:, metadata:, options: }
+- `:plugin_enabled` — { name:, metadata: }
+- `:plugin_disabling` — { name:, metadata: }
+- `:plugin_disabled` — { name:, metadata: }
+- `:plugin_error` — { name:, metadata:, error: }
+
+Notes:
+- Handlers are executed in-process; errors are logged and swallowed.
+- EventBus forwarding publishes to `hooks.<event>` by default when EventBus is loaded.
+- Hook payloads are simple hashes to keep them Ractor-friendly later.

data/examples/client_lifecycle_example.rb

@@ -0,0 +1,118 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example demonstrating the unified Takagi::Client API with multiple protocols
+#
+# This example shows the new unified API that supports:
+# 1. Protocol auto-detection from URI scheme
+# 2. Explicit protocol specification
+# 3. Block-based auto-close pattern (recommended)
+# 4. Manual lifecycle management
+
+require_relative '../lib/takagi'
+
+puts "Demonstrating Unified Takagi::Client API\n\n"
+
+# Pattern 1: Protocol auto-detection from URI
+puts 'Pattern 1: Protocol Auto-Detection from URI'
+puts '=' * 50
+
+# UDP client (coap:// scheme)
+puts 'Creating UDP client from coap:// URI:'
+client_udp = Takagi::Client.new('coap://localhost:5683')
+puts '  Protocol: UDP (auto-detected)'
+puts "  Implementation: #{client_udp.instance_variable_get(:@impl).class}"
+client_udp.close
+
+# TCP client (coap+tcp:// scheme)
+puts "\nCreating TCP client from coap+tcp:// URI:"
+client_tcp = Takagi::Client.new('coap+tcp://localhost:5683')
+puts '  Protocol: TCP (auto-detected)'
+puts "  Implementation: #{client_tcp.instance_variable_get(:@impl).class}"
+client_tcp.close
+puts
+
+# Pattern 2: Explicit protocol specification
+puts 'Pattern 2: Explicit Protocol Specification'
+puts '=' * 50
+
+# Explicitly specify TCP
+puts 'Creating TCP client with protocol parameter:'
+client = Takagi::Client.new('localhost:5683', protocol: :tcp)
+puts '  Protocol: TCP (explicit)'
+puts "  Implementation: #{client.instance_variable_get(:@impl).class}"
+client.close
+
+# Explicitly specify UDP
+puts "\nCreating UDP client with protocol parameter:"
+client = Takagi::Client.new('localhost:5683', protocol: :udp)
+puts '  Protocol: UDP (explicit)'
+puts "  Implementation: #{client.instance_variable_get(:@impl).class}"
+client.close
+puts
+
+# Pattern 3: Block-based auto-close (RECOMMENDED)
+puts 'Pattern 3: Block-Based Auto-Close (RECOMMENDED)'
+puts '=' * 50
+initial_threads = Thread.list.size
+puts "Initial thread count: #{initial_threads}"
+
+Takagi::Client.new('coap://localhost:5683') do |_client|
+  puts "Inside block. Thread count: #{Thread.list.size}"
+  puts 'Client protocol: UDP'
+  # Use the client...
+  # client.get('/resource')
+end
+
+sleep 0.2 # Give thread time to stop
+puts "After block. Thread count: #{Thread.list.size}"
+puts
+
+# Pattern 4: Multiple protocols with thread leak prevention
+puts 'Pattern 4: Multiple Protocols - Thread Leak Test'
+puts '=' * 50
+initial_threads = Thread.list.size
+puts "Initial thread count: #{initial_threads}"
+
+# Create and close multiple clients with different protocols
+3.times do |i|
+  Takagi::Client.new('coap://localhost:5683') do |_client|
+    # UDP client work...
+  end
+  puts "  UDP Client #{i + 1} closed"
+end
+
+2.times do |i|
+  Takagi::Client.new('localhost:5683', protocol: :tcp) do |_client|
+    # TCP client work...
+  end
+  puts "  TCP Client #{i + 1} closed"
+end
+
+sleep 0.5 # Give threads time to stop
+final_threads = Thread.list.size
+puts "Final thread count: #{final_threads}"
+puts "Thread leak prevented: #{final_threads <= initial_threads + 1 ? 'YES ✓' : 'NO ✗'}"
+puts
+
+# Pattern 5: Error handling with auto-close
+puts 'Pattern 5: Auto-Close Even With Errors'
+puts '=' * 50
+begin
+  Takagi::Client.new('coap://localhost:5683') do |clnt|
+    puts "Inside block. Client open: #{!clnt.closed?}"
+    raise 'Simulated error'
+  end
+rescue StandardError => e
+  puts "Caught error: #{e.message}"
+  puts 'Client was still closed despite error'
+end
+puts
+
+puts "\nSummary of New Unified API:"
+puts '- Single Takagi::Client class for all protocols'
+puts '- Auto-detects protocol from URI scheme (coap:// = UDP, coap+tcp:// = TCP)'
+puts '- Explicit protocol selection with protocol: parameter'
+puts '- Block-based initialization for automatic cleanup'
+puts '- Consistent API across UDP and TCP transports'
+puts '- Thread-safe with proper resource cleanup'