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

#cache_options ⇒ Object

Cache options for the model register

lutaml-hal caches realized objects keyed by their (canonical) URL, so a document linked from many places is fetched once. In-memory by default; pass an adapter config such as ‘{ adapter: { type: :filesystem, options: { path: “…” } } }` for cross-run persistence. Returns nil when caching is disabled.



130
131
132
133
134
 
# File 'lib/w3c_api/hal.rb', line 130

def cache_options
  return @cache_options if defined?(@cache_options)

  @cache_options = { adapter: :memory }
end

#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_cache(options = {}) ⇒ Object

Set cache options (merged into the current ones)



137
138
139
140
 
# File 'lib/w3c_api/hal.rb', line 137

def configure_cache(options = {})
  @cache_options = (cache_options || {}).merge(options)
  reset_register
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_cache ⇒ Object

Disable caching of realized objects



143
144
145
146
 
# File 'lib/w3c_api/hal.rb', line 143

def disable_cache
  @cache_options = nil
  reset_register
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_cache(options = nil) ⇒ Object

Enable caching of realized objects



149
150
151
152
 
# File 'lib/w3c_api/hal.rb', line 149

def enable_cache(options = nil)
  @cache_options = options || { adapter: :memory }
  reset_register
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 



154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/w3c_api/hal.rb', line 154

def register
  return @register if @register

  @register = Lutaml::Hal::ModelRegister.new(
    name: :w3c_api,
    client: client,
    cache: cache_options,
  )
  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 



170
171
172
173
174
175
 
# File 'lib/w3c_api/hal.rb', line 170

def reset_register
  # Drop the global registration too, otherwise rebuilding the register
  # raises "replacing another one" when it re-registers the same name.
  Lutaml::Hal::GlobalRegister.instance.unregister(:w3c_api)
  @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