tsikol 0.1.0

data/docs/api/resource.md

@@ -0,0 +1,651 @@
+# Resource API Reference
+
+The `Tsikol::Resource` class provides the foundation for creating resources that expose read-only data to AI assistants.
+
+## Class: Tsikol::Resource
+
+### Class Methods
+
+#### `.uri(path = nil)`
+
+Set or get the resource URI.
+
+```ruby
+class SystemStatus < Tsikol::Resource
+  uri "system/status"
+end
+```
+
+#### `.description(text = nil)`
+
+Set or get the resource description.
+
+```ruby
+class ConfigResource < Tsikol::Resource
+  uri "config"
+  description "Application configuration values"
+end
+```
+
+### Instance Methods
+
+#### `#read`
+
+Main method to implement resource logic. Must return a string (usually JSON).
+
+```ruby
+class VersionResource < Tsikol::Resource
+  uri "version"
+  description "Current application version"
+  
+  def read
+    {
+      version: "1.0.0",
+      build: "2024.01.15",
+      git_commit: ENV['GIT_COMMIT'] || "unknown"
+    }.to_json
+  end
+end
+```
+
+#### `#uri`
+
+Get the resource URI (instance method).
+
+```ruby
+resource = SystemStatus.new
+resource.uri  # => "system/status"
+```
+
+#### `#set_server(server)`
+
+Called when resource is registered with a server. Override to access server features.
+
+```ruby
+def set_server(server)
+  @server = server
+  @start_time = Time.now
+  
+  # Enable logging if available
+  if @server.logging_enabled?
+    define_singleton_method(:log) do |level, message, data: nil|
+      @server.log(level, message, data: data)
+    end
+  end
+end
+```
+
+### Resource Registration
+
+Resources can be registered in several ways:
+
+#### Class Registration
+
+```ruby
+server.register_resource_class(SystemStatus)
+# or
+server.resource SystemStatus
+```
+
+#### Instance Registration
+
+```ruby
+resource = SystemStatus.new
+server.register_resource_instance(resource)
+```
+
+#### Inline Registration
+
+```ruby
+server.register_resource("time") do
+  Time.now.iso8601
+end
+# or
+server.resource "time" do
+  Time.now.iso8601
+end
+```
+
+### URI Patterns
+
+Resources use URI-style paths for organization:
+
+```ruby
+# Top-level resource
+class RootConfig < Tsikol::Resource
+  uri "config"
+end
+
+# Nested resource
+class DatabaseConfig < Tsikol::Resource
+  uri "config/database"
+end
+
+# Deep nesting
+class UserPreferences < Tsikol::Resource
+  uri "users/current/preferences"
+end
+```
+
+### Dynamic Resources
+
+Resources can return different data based on context:
+
+```ruby
+class MetricsResource < Tsikol::Resource
+  uri "metrics"
+  description "Real-time system metrics"
+  
+  def read
+    {
+      timestamp: Time.now.iso8601,
+      cpu_usage: current_cpu_usage,
+      memory_usage: current_memory_usage,
+      active_connections: connection_count,
+      request_rate: calculate_request_rate
+    }.to_json
+  end
+  
+  private
+  
+  def current_cpu_usage
+    # Implementation specific
+    "#{rand(0..100)}%"
+  end
+  
+  def current_memory_usage
+    # Get actual memory usage
+    rss = `ps -o rss= -p #{Process.pid}`.to_i
+    "#{(rss / 1024.0).round(2)}MB"
+  end
+  
+  def connection_count
+    Thread.list.select(&:alive?).count
+  end
+  
+  def calculate_request_rate
+    # Calculate from server metrics
+    @server.respond_to?(:request_count) ? @server.request_count : 0
+  end
+end
+```
+
+### Resource Formats
+
+While resources typically return JSON, they can return any string format:
+
+#### JSON (Most Common)
+
+```ruby
+class JsonResource < Tsikol::Resource
+  uri "data/users"
+  
+  def read
+    users = fetch_users
+    users.map { |u| { id: u.id, name: u.name } }.to_json
+  end
+end
+```
+
+#### Plain Text
+
+```ruby
+class TextResource < Tsikol::Resource
+  uri "docs/readme"
+  
+  def read
+    File.read("README.md")
+  end
+end
+```
+
+#### CSV
+
+```ruby
+class CsvResource < Tsikol::Resource
+  uri "data/export.csv"
+  
+  def read
+    require 'csv'
+    
+    CSV.generate do |csv|
+      csv << ["ID", "Name", "Email"]
+      users.each do |user|
+        csv << [user.id, user.name, user.email]
+      end
+    end
+  end
+end
+```
+
+#### XML
+
+```ruby
+class XmlResource < Tsikol::Resource
+  uri "data/config.xml"
+  
+  def read
+    builder = Nokogiri::XML::Builder.new do |xml|
+      xml.configuration {
+        xml.database {
+          xml.host ENV['DB_HOST']
+          xml.port ENV['DB_PORT']
+        }
+      }
+    end
+    builder.to_xml
+  end
+end
+```
+
+### Caching
+
+Implement caching for expensive operations:
+
+```ruby
+class CachedResource < Tsikol::Resource
+  uri "expensive/data"
+  description "Expensive computation (cached)"
+  
+  def initialize
+    super
+    @cache = nil
+    @cache_time = nil
+    @cache_ttl = 300  # 5 minutes
+  end
+  
+  def read
+    if cache_valid?
+      log :debug, "Cache hit"
+      @cache
+    else
+      log :debug, "Cache miss, computing..."
+      @cache = compute_expensive_data
+      @cache_time = Time.now
+      @cache
+    end
+  end
+  
+  private
+  
+  def cache_valid?
+    return false unless @cache && @cache_time
+    Time.now - @cache_time < @cache_ttl
+  end
+  
+  def compute_expensive_data
+    # Simulate expensive operation
+    sleep(0.5)
+    
+    {
+      computed_at: Time.now.iso8601,
+      result: perform_calculation,
+      valid_for: @cache_ttl
+    }.to_json
+  end
+end
+```
+
+### Error Handling
+
+Resources should handle errors gracefully:
+
+```ruby
+class SafeResource < Tsikol::Resource
+  uri "external/api"
+  description "Data from external API"
+  
+  def read
+    response = fetch_external_data
+    format_response(response)
+    
+  rescue Net::HTTPError => e
+    log :error, "HTTP error fetching data", error: e.message
+    error_response("External API unavailable")
+    
+  rescue JSON::ParserError => e
+    log :error, "Invalid JSON from API", error: e.message
+    error_response("Invalid data format")
+    
+  rescue => e
+    log :error, "Unexpected error", error: e.class.name
+    error_response("An error occurred")
+  end
+  
+  private
+  
+  def error_response(message)
+    {
+      error: message,
+      timestamp: Time.now.iso8601
+    }.to_json
+  end
+end
+```
+
+### Using Server Features
+
+Resources can access server capabilities:
+
+```ruby
+class ServerAwareResource < Tsikol::Resource
+  uri "server/info"
+  description "Information about this server"
+  
+  def read
+    info = {
+      name: @server.name,
+      version: @server.version,
+      uptime: calculate_uptime,
+      capabilities: list_capabilities
+    }
+    
+    # Add request count if metrics available
+    if @server.respond_to?(:metrics)
+      info[:total_requests] = @server.metrics[:request_count]
+    end
+    
+    info.to_json
+  end
+  
+  private
+  
+  def calculate_uptime
+    return 0 unless @start_time
+    Time.now - @start_time
+  end
+  
+  def list_capabilities
+    caps = []
+    caps << "logging" if @server.logging_enabled?
+    caps << "completion" if @server.completion_enabled?
+    caps << "sampling" if @server.sampling_enabled?
+    caps
+  end
+  
+  def set_server(server)
+    @server = server
+    @start_time = Time.now
+  end
+end
+```
+
+## Complete Example
+
+```ruby
+class SystemMetrics < Tsikol::Resource
+  uri "system/metrics"
+  description "Comprehensive system metrics and statistics"
+  
+  def initialize
+    super
+    @metrics_cache = {}
+    @last_cpu_check = Time.now
+    @last_cpu_value = 0
+  end
+  
+  def read
+    {
+      server: server_metrics,
+      system: system_metrics,
+      process: process_metrics,
+      custom: custom_metrics,
+      timestamp: Time.now.iso8601
+    }.to_json
+  rescue => e
+    log :error, "Error collecting metrics", error: e.message
+    minimal_metrics.to_json
+  end
+  
+  private
+  
+  def server_metrics
+    {
+      name: @server.name,
+      version: @server.version,
+      uptime_seconds: uptime,
+      total_requests: request_count,
+      active_tools: @server.tools.keys.count,
+      active_resources: @server.resources.keys.count
+    }
+  end
+  
+  def system_metrics
+    {
+      platform: RUBY_PLATFORM,
+      ruby_version: RUBY_VERSION,
+      cpu_count: cpu_count,
+      total_memory: total_memory,
+      load_average: load_average
+    }
+  end
+  
+  def process_metrics
+    {
+      pid: Process.pid,
+      memory_usage_mb: process_memory,
+      cpu_usage_percent: process_cpu,
+      thread_count: Thread.list.count,
+      gc_stats: GC.stat
+    }
+  end
+  
+  def custom_metrics
+    @server.respond_to?(:custom_metrics) ? @server.custom_metrics : {}
+  end
+  
+  def uptime
+    @start_time ? (Time.now - @start_time).to_i : 0
+  end
+  
+  def request_count
+    @server.respond_to?(:request_count) ? @server.request_count : 0
+  end
+  
+  def cpu_count
+    @metrics_cache[:cpu_count] ||= begin
+      if RUBY_PLATFORM =~ /linux/
+        `nproc`.to_i
+      elsif RUBY_PLATFORM =~ /darwin/
+        `sysctl -n hw.ncpu`.to_i
+      else
+        1
+      end
+    end
+  end
+  
+  def total_memory
+    @metrics_cache[:total_memory] ||= begin
+      if RUBY_PLATFORM =~ /linux/
+        `grep MemTotal /proc/meminfo`.match(/\d+/)[0].to_i / 1024
+      elsif RUBY_PLATFORM =~ /darwin/
+        `sysctl -n hw.memsize`.to_i / 1024 / 1024
+      else
+        0
+      end
+    end
+  end
+  
+  def load_average
+    if File.exist?("/proc/loadavg")
+      File.read("/proc/loadavg").split.first(3).map(&:to_f)
+    else
+      [0.0, 0.0, 0.0]
+    end
+  end
+  
+  def process_memory
+    rss = `ps -o rss= -p #{Process.pid}`.to_i
+    (rss / 1024.0).round(2)
+  end
+  
+  def process_cpu
+    # Simple CPU calculation
+    now = Time.now
+    if now - @last_cpu_check > 1
+      # Simplified CPU usage
+      @last_cpu_value = rand(0..20)
+      @last_cpu_check = now
+    end
+    @last_cpu_value
+  end
+  
+  def minimal_metrics
+    {
+      error: "Metrics collection failed",
+      server_name: @server.name,
+      timestamp: Time.now.iso8601
+    }
+  end
+  
+  def set_server(server)
+    @server = server
+    @start_time = Time.now
+    
+    if @server.logging_enabled?
+      define_singleton_method(:log) do |level, message, data: nil|
+        @server.log(level, message, data: data)
+      end
+    else
+      define_singleton_method(:log) do |*args|
+        # No-op
+      end
+    end
+  end
+end
+```
+
+## Testing Resources
+
+```ruby
+require 'minitest/autorun'
+require 'tsikol/test_helpers'
+
+class SystemMetricsTest < Minitest::Test
+  include Tsikol::TestHelpers::Assertions
+  
+  def setup
+    @server = Tsikol::Server.new(name: "test")
+    @server.logging true
+    @server.register_resource_instance(SystemMetrics.new)
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+    @client.initialize_connection
+  end
+  
+  def test_read_metrics
+    response = @client.read_resource("system/metrics")
+    
+    assert_successful_response(response)
+    
+    content = response.dig(:result, :contents, 0, :text)
+    data = JSON.parse(content)
+    
+    assert data["server"]
+    assert data["system"]
+    assert data["process"]
+    assert data["timestamp"]
+  end
+  
+  def test_metrics_structure
+    response = @client.read_resource("system/metrics")
+    content = response.dig(:result, :contents, 0, :text)
+    data = JSON.parse(content)
+    
+    # Verify server metrics
+    assert_equal "test", data["server"]["name"]
+    assert data["server"]["uptime_seconds"] >= 0
+    
+    # Verify system metrics
+    assert data["system"]["ruby_version"]
+    assert data["system"]["platform"]
+    
+    # Verify process metrics
+    assert_equal Process.pid, data["process"]["pid"]
+    assert data["process"]["memory_usage_mb"] > 0
+  end
+  
+  def test_error_handling
+    # Mock an error condition
+    resource = SystemMetrics.new
+    resource.define_singleton_method(:system_metrics) do
+      raise "Simulated error"
+    end
+    
+    @server.register_resource_instance(resource)
+    
+    response = @client.read_resource("system/metrics")
+    
+    # Should still return valid JSON
+    assert_successful_response(response)
+    content = response.dig(:result, :contents, 0, :text)
+    data = JSON.parse(content)
+    
+    # Should have minimal metrics on error
+    assert data["error"] || data["server"]
+  end
+end
+```
+
+## URI Patterns and Best Practices
+
+### Hierarchical Organization
+
+```ruby
+# Good: Clear hierarchy
+"config"                    # Top-level config
+"config/database"          # Database config
+"config/cache"             # Cache config
+"users/current"            # Current user
+"users/current/settings"   # User settings
+
+# Avoid: Flat structure
+"database-config"
+"cache-config"
+"current-user"
+"user-settings"
+```
+
+### Naming Conventions
+
+```ruby
+# Use lowercase with hyphens or underscores
+"system/health-check"      # Good
+"system/health_check"      # Good
+"system/HealthCheck"       # Avoid
+"SYSTEM/HEALTH"           # Avoid
+
+# Be descriptive but concise
+"api/endpoints"           # Good
+"api/available-endpoints-list"  # Too verbose
+```
+
+### Resource Types
+
+```ruby
+# Status/Info resources
+"system/status"
+"server/info"
+"health/check"
+
+# Configuration resources
+"config/app"
+"config/features"
+"settings/user"
+
+# Data resources
+"data/users"
+"reports/daily"
+"metrics/performance"
+
+# Documentation resources
+"docs/api"
+"help/commands"
+"schema/database"
+```
+
+## See Also
+
+- [Resources Guide](../guides/resources.md)
+- [Server API](server.md)
+- [Testing Guide](../guides/testing.md)
+- [Caching Patterns](../cookbook/caching.md)