Class: W3cApi::Hal

Inherits:
Object
  • Object
show all
Includes:
Singleton
Defined in:
lib/w3c_api/hal.rb

Constant Summary collapse

API_URL = 
"https://api.w3.org/"

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Hal

Returns a new instance of Hal.



47
48
49
 
# File 'lib/w3c_api/hal.rb', line 47

def initialize
  # Don't call setup here - it will be called when register is first accessed
end

Instance Method Details

#client ⇒ Object 



51
52
53
54
55
56
57
 
# File 'lib/w3c_api/hal.rb', line 51

def client
  @client ||= Lutaml::Hal::Client.new(
    api_url: API_URL,
    connection: connection,
    rate_limiting: rate_limiting_options,
  )
end

#configure_rate_limiting(options = {}) ⇒ Object

Set rate limiting options



107
108
109
110
111
 
# File 'lib/w3c_api/hal.rb', line 107

def configure_rate_limiting(options = {})
  @rate_limiting_options = rate_limiting_options.merge(options)
  # Reset client to pick up new options
  @client = nil
end

#connection ⇒ Object

Faraday connection mirroring lutaml-hal’s default middleware stack, with a retry layer for the failures lutaml-hal’s RateLimiter does not cover: the W3C API signals rate-limiting with HTTP 403, plus transient connection and timeout errors. (lutaml-hal still retries 429 and 5xx.) Owning retries here means every consumer of the client is resilient without its own wrapper.



64
65
66
67
68
69
70
71
72
 
# File 'lib/w3c_api/hal.rb', line 64

def connection
  @connection ||= Faraday.new(url: API_URL.delete_suffix("/")) do |conn|
    conn.request :retry, retry_options
    conn.use Faraday::FollowRedirects::Middleware
    conn.request :json
    conn.response :json, content_type: /\bjson$/
    conn.adapter Faraday.default_adapter
  end
end

#disable_rate_limiting ⇒ Object

Disable rate limiting



114
115
116
 
# File 'lib/w3c_api/hal.rb', line 114

def disable_rate_limiting
  configure_rate_limiting(enabled: false)
end

#enable_rate_limiting ⇒ Object

Enable rate limiting



119
120
121
 
# File 'lib/w3c_api/hal.rb', line 119

def enable_rate_limiting
  configure_rate_limiting(enabled: true)
end

#rate_limiting_options ⇒ Object

Configure rate limiting options

lutaml-hal’s RateLimiter retries 429 and 5xx responses with exponential backoff (base_delay * backoff_factor**(attempt - 1), capped at max_delay). These defaults grow 1, 2, 4, 8, 16s so a rate-limited or briefly overloaded W3C API is given real room to recover during a bulk crawl.



96
97
98
99
100
101
102
103
104
 
# File 'lib/w3c_api/hal.rb', line 96

def rate_limiting_options
  @rate_limiting_options ||= {
    enabled: true,
    max_retries: 5,
    base_delay: 1.0,
    max_delay: 30.0,
    backoff_factor: 2.0,
  }
end

#register ⇒ Object 



123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/w3c_api/hal.rb', line 123

def register
  return @register if @register

  @register = Lutaml::Hal::ModelRegister.new(name: :w3c_api, client: client)
  Lutaml::Hal::GlobalRegister.instance.register(:w3c_api, @register)

  # Re-run setup to register all endpoints with the new register
  setup

  @register
end

#reset_register ⇒ Object 



135
136
137
 
# File 'lib/w3c_api/hal.rb', line 135

def reset_register
  @register = nil
end

#retry_options ⇒ Object

Retry policy for the W3C-specific transient failures (HTTP 403 and connection/timeout). Grows 1, 2, 4, 8, 16s, matching rate_limiting_options.



76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/w3c_api/hal.rb', line 76

def retry_options
  {
    max: 5,
    interval: 1.0,
    backoff_factor: 2,
    max_interval: 30.0,
    retry_statuses: [403],
    exceptions: [
      Errno::ETIMEDOUT, Timeout::Error,
      Faraday::TimeoutError, Faraday::ConnectionFailed
    ],
  }
end