w3c_api 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c02121c87a6a5fc2c0f6c5c3f64a8c9fc559dd462819b38a4a5a08e18a2fec6
-  data.tar.gz: 722806176722df8e4d8ee75cf6af95ceb0f9fbb629d89fc7b70cd93366f03d97
+  metadata.gz: a4dbcfdf9468b2cea332e93d7302cce5238e3530b231bccfa848f77ef4ca106d
+  data.tar.gz: d481729a09d328bc716b34b577957f60bc16dd2a8ff303c0cff9109fced13bcf
 SHA512:
-  metadata.gz: b89d639121544a8212b3b13489cb537cf83b4ccb99c7b85cacacc38697f9d60a03d574bb6ece148f076840213ae5d07aac5b5e913daa9d0efc64b355d98c60f6
-  data.tar.gz: 3e180168c74b46b140328aae3736573e668f3653c4fa96196acf0a0b410aab8a0d8c66de784d479fe5c94b986d95bec5bec2b6297da5598d10e03e8028083fc0
+  metadata.gz: f7d6c35088901039ebfdf75f29e42c004ebe486e03fb9053e83e0599f33f8ae50c4b571097ce7cf63887b98d0fc7a4c4a1fbcacfb3a25d32b7a0b118a83b6fea
+  data.tar.gz: fbfcae8e668f7ccf48b8c355d7f6819f40acac18e0be02a706a926c6e6d74aaeef8b83f5a047fa3f02b7f70e6da831bc17ea05fb4cc4491db3095a9f813c54d9

data/.rubocop.yml

@@ -1 +1,16 @@
-inherit_from: .rubocop_todo.yml
+inherit_from:
+  - .rubocop_todo.yml
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
+
+Layout/LineLength:
+  Max: 180
+
+Metrics/MethodLength:
+  Exclude:
+    - 'demo/test_embed_functionality.rb'
+    - 'lib/w3c_api/commands/specification.rb'
+    - 'lib/w3c_api/hal.rb'
+
+Metrics/ParameterLists:
+  Exclude:
+    - 'lib/w3c_api/hal.rb'

data/.rubocop_todo.yml

@@ -1,56 +1,38 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-07-08 17:28:03 UTC using RuboCop version 1.78.0.
+# on 2025-07-09 06:57:51 UTC using RuboCop version 1.78.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Lint/ScriptPermission:
-  Exclude:
-    - 'demo/test_improved_embed_functionality.rb'
-
-# Offense count: 2
-# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+# Offense count: 4
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
-  Max: 121
-
-# Offense count: 51
-# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
-# AllowedMethods: refine
-Metrics/BlockLength:
-  Max: 370
+  Exclude:
+    - 'demo/test_embed_functionality.rb'
+    - 'lib/w3c_api/commands/group.rb'
+    - 'lib/w3c_api/commands/specification.rb'
+    - 'lib/w3c_api/hal.rb'
 
 # Offense count: 1
-# Configuration parameters: CountBlocks, CountModifierForms.
-Metrics/BlockNesting:
-  Max: 4
-
-# Offense count: 2
-# Configuration parameters: CountComments, CountAsOne.
-Metrics/ClassLength:
-  Max: 407
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'demo/test_embed_functionality.rb'
 
-# Offense count: 2
+# Offense count: 3
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 339
+  Max: 351
+  Exclude:
+    - 'demo/test_embed_functionality.rb'
+    - 'lib/w3c_api/commands/specification.rb'
+    - 'lib/w3c_api/hal.rb'
 
 # Offense count: 1
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 6
-
-# Offense count: 32
-# Configuration parameters: AllowedConstants.
-Style/Documentation:
-  Enabled: false
-
-# Offense count: 13
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
-# URISchemes: http, https
-Layout/LineLength:
-  Max: 457
+  Exclude:
+    - 'lib/w3c_api/hal.rb'

data/README.adoc

@@ -17,6 +17,7 @@ https://github.com/lutaml/lutaml-model[lutaml-model]
 for all W3C API resources
 * HAL (Hypertext Application Language) implementation for recursive resource
 traversal
+* Built-in rate limiting with exponential backoff for reliable API access
 * A command-line interface using Thor following GitHub CLI patterns
 
 The endpoint supported is at https://api.w3.org.
@@ -72,6 +73,56 @@ from `lutaml-hal`, showing multiple levels of automatic link resolution.
 
 == Ruby API
 
+=== Rate limiting
+
+The W3C API client includes built-in rate limiting with exponential backoff to handle API rate limits gracefully. Rate limiting is enabled by default and works transparently with all API operations.
+
+==== Quick start
+
+[source,ruby]
+----
+require 'w3c_api'
+
+# Rate limiting is enabled by default
+client = W3cApi::Client.new
+
+# Configure rate limiting if needed
+W3cApi::Hal.instance.configure_rate_limiting(
+  max_retries: 5,        # Maximum retry attempts
+  base_delay: 1.0,       # Initial delay in seconds
+  max_delay: 60.0,       # Maximum delay cap
+  backoff_factor: 2.0    # Exponential backoff multiplier
+)
+
+# Make requests - rate limiting works automatically
+specifications = client.specifications
+----
+
+==== Demo and examples
+
+To see rate limiting in action, run the included demonstration scripts:
+
+[source,shell]
+----
+# Basic rate limiting demo
+$ ruby demo/rate_limiting_demo.rb
+
+# Advanced stress testing and performance analysis
+$ ruby examples/rate_limiting_stress_test.rb
+----
+
+The demo script shows:
+* Default rate limiting configuration
+* Custom configuration examples
+* Enabling/disabling rate limiting
+* Status checking
+
+The stress test example demonstrates:
+* Rapid sequential requests
+* Cross-endpoint performance analysis
+* Dynamic configuration changes
+* Bulk operation patterns
+
 === Embed support with auto-realize
 
 ==== General

data/Rakefile

@@ -1,11 +1,11 @@
 # 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
 

data/demo/rate_limiting_demo.rb

@@ -0,0 +1,135 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/w3c_api"
+
+# Demo script to demonstrate rate limiting functionality
+puts "W3C API Rate Limiting Demo"
+puts "=" * 40
+
+puts "\nThis demo shows how to use the built-in rate limiting features"
+puts "of the W3C API client to handle API rate limits gracefully."
+
+# Create a client instance
+client = W3cApi::Client.new
+
+# Demo 1: Default rate limiting (enabled by default)
+puts "\n1. Default Rate Limiting Configuration:"
+puts "   - Max retries: 3"
+puts "   - Base delay: 1.0s"
+puts "   - Max delay: 60.0s"
+puts "   - Backoff factor: 2.0"
+
+begin
+  start_time = Time.now
+
+  puts "\n   Making API requests with default rate limiting..."
+
+  # Fetch specifications
+  specs = client.specifications(items: 3)
+  puts "   ✓ Retrieved #{specs.links.specifications.length} specifications"
+
+  # Fetch a specific specification
+  spec_detail = client.specification("html5")
+  puts "   ✓ Retrieved specification: #{spec_detail.title}"
+
+  end_time = Time.now
+  puts "   ⏱️  Total time: #{(end_time - start_time).round(2)}s"
+rescue StandardError => e
+  puts "   ✗ Error: #{e.message}"
+end
+
+# Demo 2: Custom rate limiting configuration
+puts "\n2. Custom Rate Limiting Configuration:"
+puts "   Configuring more aggressive rate limiting for APIs with strict limits"
+
+begin
+  # Configure custom rate limiting
+  W3cApi::Hal.instance.configure_rate_limiting(
+    max_retries: 5,        # More retry attempts
+    base_delay: 0.5,       # Shorter initial delay
+    max_delay: 30.0,       # Lower maximum delay
+    backoff_factor: 1.5, # Gentler backoff
+  )
+
+  puts "   ✓ Rate limiting reconfigured"
+
+  start_time = Time.now
+
+  # Make requests with custom configuration
+  groups = client.groups(items: 3)
+  puts "   ✓ Retrieved #{groups.links.groups.length} groups"
+
+  end_time = Time.now
+  puts "   ⏱️  Total time: #{(end_time - start_time).round(2)}s"
+rescue StandardError => e
+  puts "   ✗ Error: #{e.message}"
+end
+
+# Demo 3: Temporarily disable rate limiting
+puts "\n3. Temporarily Disabling Rate Limiting:"
+puts "   Useful for bulk operations where you control the rate manually"
+
+begin
+  # Disable rate limiting
+  W3cApi::Hal.instance.disable_rate_limiting
+  puts "   ✓ Rate limiting disabled"
+
+  start_time = Time.now
+
+  # Make requests without rate limiting
+  series = client.series(items: 3)
+  puts "   ✓ Retrieved #{series.links.series.length} series"
+
+  end_time = Time.now
+  puts "   ⏱️  Total time: #{(end_time - start_time).round(2)}s"
+rescue StandardError => e
+  puts "   ✗ Error: #{e.message}"
+end
+
+# Demo 4: Re-enable rate limiting
+puts "\n4. Re-enabling Rate Limiting:"
+
+begin
+  # Re-enable rate limiting with default settings
+  W3cApi::Hal.instance.enable_rate_limiting
+  puts "   ✓ Rate limiting re-enabled with default settings"
+
+  start_time = Time.now
+
+  ecosystems = client.ecosystems
+  puts "   ✓ Retrieved #{ecosystems.links.ecosystems.length} ecosystems"
+
+  end_time = Time.now
+  puts "   ⏱️  Total time: #{(end_time - start_time).round(2)}s"
+rescue StandardError => e
+  puts "   ✗ Error: #{e.message}"
+end
+
+# Demo 5: Check rate limiting status
+puts "\n5. Checking Rate Limiting Status:"
+
+if W3cApi::Hal.instance.rate_limiting_enabled?
+  puts "   ✓ Rate limiting is currently ENABLED"
+else
+  puts "   ⚠️  Rate limiting is currently DISABLED"
+end
+
+puts "\n#{'=' * 40}"
+puts "Rate Limiting Demo Completed! 🎉"
+
+puts "\n📚 Key Takeaways:"
+puts "• Rate limiting is enabled by default for reliable API access"
+puts "• You can customize retry behavior for different API requirements"
+puts "• Rate limiting can be temporarily disabled for bulk operations"
+puts "• The system automatically handles 429 and 5xx errors with exponential backoff"
+puts "• Retry-After headers from the server are automatically respected"
+
+puts "\n🔧 Common Use Cases:"
+puts "• Default settings work well for most applications"
+puts "• Increase max_retries for critical operations"
+puts "• Decrease delays for APIs with generous rate limits"
+puts "• Disable temporarily for bulk data processing"
+
+puts "\n📖 For more information, see the rate limiting documentation"
+puts "   in the lutaml-hal library or the W3C API documentation."

data/demo/test_embed_functionality.rb

@@ -1,11 +1,29 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require_relative 'lib/w3c_api'
+require "bundler/setup"
+require_relative "lib/w3c_api"
 
-puts 'Testing W3C API Embed Functionality'
-puts '=' * 40
+def test_link_realization(groups_with_embed)
+  return unless groups_with_embed.respond_to?(:links) && groups_with_embed.links.respond_to?(:groups)
+
+  first_group_link = groups_with_embed.links.groups.first
+  return unless first_group_link
+
+  puts "   First group link: #{first_group_link.href}"
+  return unless first_group_link.respond_to?(:realize)
+
+  begin
+    realized_group = first_group_link.realize(parent_resource: groups_with_embed)
+    puts "   ✓ Link realization with embedded data successful"
+    puts "   Realized group name: #{realized_group.name if realized_group.respond_to?(:name)}"
+  rescue StandardError => e
+    puts "   ⚠ Link realization failed: #{e.message}"
+  end
+end
+
+puts "Testing W3C API Embed Functionality"
+puts "=" * 40
 
 # Initialize the client
 client = W3cApi::Client.new
@@ -17,10 +35,10 @@ begin
   puts "   Response type: #{groups_with_embed.class}"
   puts "   Has embedded content: #{groups_with_embed.respond_to?(:has_embedded?) && groups_with_embed.has_embedded?('groups')}"
 
-  if groups_with_embed.respond_to?(:has_embedded?) && groups_with_embed.has_embedded?('groups')
+  if groups_with_embed.respond_to?(:has_embedded?) && groups_with_embed.has_embedded?("groups")
     puts "   Available methods: #{groups_with_embed.methods.grep(/embed/).join(', ')}"
 
-    embedded_groups = groups_with_embed.get_embedded('groups')
+    embedded_groups = groups_with_embed.get_embedded("groups")
     puts "   Number of embedded groups: #{embedded_groups.length}"
     puts "   First embedded group: #{embedded_groups.first['name'] if embedded_groups.first}"
   end
@@ -31,10 +49,10 @@ begin
   puts "   Response type: #{specs_with_embed.class}"
   puts "   Has embedded content: #{specs_with_embed.respond_to?(:has_embedded?) && specs_with_embed.has_embedded?('specifications')}"
 
-  if specs_with_embed.respond_to?(:has_embedded?) && specs_with_embed.has_embedded?('specifications')
+  if specs_with_embed.respond_to?(:has_embedded?) && specs_with_embed.has_embedded?("specifications")
     puts "   Available methods: #{specs_with_embed.methods.grep(/embed/).join(', ')}"
 
-    embedded_specs = specs_with_embed.get_embedded('specifications')
+    embedded_specs = specs_with_embed.get_embedded("specifications")
     puts "   Number of embedded specifications: #{embedded_specs.length}"
     puts "   First embedded spec: #{embedded_specs.first['title'] if embedded_specs.first}"
   end
@@ -53,35 +71,18 @@ begin
   with_embed_time = Time.now - start_time
   puts "   With embed: #{with_embed_time.round(3)}s"
 
-  if groups_with_embed.respond_to?(:has_embedded?) && groups_with_embed.has_embedded?('groups')
-    puts '   ✓ Embed functionality working correctly!'
+  if groups_with_embed.respond_to?(:has_embedded?) && groups_with_embed.has_embedded?("groups")
+    puts "   ✓ Embed functionality working correctly!"
   else
-    puts '   ⚠ Embed parameter accepted but no embedded content returned'
+    puts "   ⚠ Embed parameter accepted but no embedded content returned"
   end
 
   puts "\n4. Testing link realization with embedded content..."
-
-  if groups_with_embed.respond_to?(:links) && groups_with_embed.links.respond_to?(:groups)
-    first_group_link = groups_with_embed.links.groups.first
-    if first_group_link
-      puts "   First group link: #{first_group_link.href}"
-
-      # Test realization with parent_resource (should use embedded data)
-      if first_group_link.respond_to?(:realize)
-        begin
-          realized_group = first_group_link.realize(parent_resource: groups_with_embed)
-          puts '   ✓ Link realization with embedded data successful'
-          puts "   Realized group name: #{realized_group.name if realized_group.respond_to?(:name)}"
-        rescue StandardError => e
-          puts "   ⚠ Link realization failed: #{e.message}"
-        end
-      end
-    end
-  end
+  test_link_realization(groups_with_embed)
 
   puts "\n✅ Embed functionality test completed successfully!"
 rescue StandardError => e
   puts "\n❌ Error during testing: #{e.message}"
-  puts 'Backtrace:'
+  puts "Backtrace:"
   puts e.backtrace.first(5).join("\n")
 end

data/demo/test_improved_embed_functionality.rb

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "../lib/w3c_api"
+
+puts "=== W3C API Improved Embed Functionality Demo ==="
+puts
+
+# Test 1: List embed-supported endpoints
+puts "1. Testing embed-supported endpoints discovery:"
+supported_endpoints = W3cApi::Client.embed_supported_endpoints
+puts "   Embed-supported endpoints: #{supported_endpoints.join(', ')}"
+puts
+
+# Test 2: Check specific endpoint support
+puts "2. Testing specific endpoint embed support:"
+client = W3cApi::Client.new
+puts "   specifications supports embed: #{client.embed_supported?(:specification_index)}"
+puts "   groups supports embed: #{client.embed_supported?(:group_index)}"
+puts "   series supports embed: #{client.embed_supported?(:serie_index)}"
+puts "   specification_resource supports embed: #{client.embed_supported?(:specification_resource)}"
+puts
+
+# Test 3: Get embed information
+puts "3. Testing embed information:"
+embed_info = W3cApi::Embed.embed_info
+puts "   Supported endpoints: #{embed_info[:supported_endpoints].join(', ')}"
+puts "   Discovery: #{embed_info[:usage_example][:discovery]}"
+puts "   Usage: #{embed_info[:usage_example][:usage]}"
+puts "   Automatic realization: #{embed_info[:usage_example][:automatic_realization]}"
+puts
+
+# Test 4: Use Client methods with embed
+puts "4. Testing Client methods with embed parameter:"
+begin
+  puts "   Fetching specifications with embed=true..."
+  specs = client.specifications(embed: true, items: 2)
+  puts "   ✓ Successfully fetched #{specs.class}"
+
+  if specs.respond_to?(:embedded_data) && specs.embedded_data
+    puts "   ✓ Has embedded data: #{specs.embedded_data.keys.join(', ')}"
+  else
+    puts "   ⚠ No embedded data found"
+  end
+
+  # Test automatic embedded content detection
+  if specs.links.respond_to?(:specifications) && specs.links.specifications.any?
+    puts "   Testing automatic embedded content detection..."
+    first_spec_link = specs.links.specifications.first
+
+    begin
+      # This should automatically use embedded content without parent_resource parameter
+      spec = first_spec_link.realize
+      puts "   ✓ Successfully realized specification automatically"
+      puts "   ✓ Specification class: #{spec.class}"
+      puts "   ✓ Specification title: #{spec.title}" if spec.respond_to?(:title)
+    rescue StandardError => e
+      puts "   ✗ Error realizing specification: #{e.message}"
+    end
+  end
+rescue StandardError => e
+  puts "   ✗ Error: #{e.message}"
+end
+puts
+
+# Test 5: Test Embed module information methods
+puts "5. Testing Embed module information methods:"
+begin
+  puts "   Testing supported_endpoints method..."
+  supported = W3cApi::Embed.supported_endpoints
+  puts "   ✓ Supported endpoints: #{supported.join(', ')}"
+
+  puts "   Testing supports_embed? method..."
+  puts "   ✓ specifications supports embed: #{W3cApi::Embed.supports_embed?(:specification_index)}"
+  puts "   ✓ groups supports embed: #{W3cApi::Embed.supports_embed?(:group_index)}"
+
+  puts "   Testing endpoint_descriptions method..."
+  descriptions = W3cApi::Embed.endpoint_descriptions
+  puts "   ✓ Available descriptions: #{descriptions.keys.join(', ')}"
+rescue StandardError => e
+  puts "   ✗ Error: #{e.message}"
+end
+puts
+
+puts "=== Demo completed ==="
+puts "Summary of improvements:"
+puts "• ✓ Added embed-supported endpoints discovery methods"
+puts "• ✓ Client methods now support embed parameter directly"
+puts "• ✓ Automatic embedded content detection (no parent_resource needed)"
+puts "• ✓ Enhanced Embed module with information methods"
+puts "• ✓ Removed deprecated code for cleaner API"