Class: Html2rss::Config

Inherits:
Object
  • Object
show all
Defined in:
lib/html2rss/config.rb,
lib/html2rss/config/schema.rb,
lib/html2rss/config/validator.rb,
lib/html2rss/config/dynamic_params.rb,
lib/html2rss/config/request_headers.rb,
lib/html2rss/config/request_controls.rb,
lib/html2rss/config/selectors_validator.rb,
lib/html2rss/config/auto_source_contract.rb,
lib/html2rss/config/multiple_feeds_config.rb

Overview

The provided configuration is used to generate the RSS feed. This class provides methods to load and process configuration from a YAML file, supporting both single and multiple feed configurations.

Configuration is validated during initialization.

Defined Under Namespace

Modules: Schema Classes: DynamicParams, InvalidConfig, MultipleFeedsConfig, Preparer, RequestControls, RequestHeaders, SelectorsValidator, Validator

Constant Summary collapse

UNSET =

Sentinel to differentiate omitted params from explicit nil.

Object.new.freeze
AutoSourceContract =

Runtime source of truth for validating auto-source config values.

Dry::Schema.Params do # rubocop:disable Metrics/BlockLength
  optional(:limit).filled(:integer, gt?: 0)

  optional(:scraper).hash do # rubocop:disable Metrics/BlockLength
    optional(:wordpress_api).hash do
      optional(:enabled).filled(:bool)
    end
    optional(:sitemap).hash do
      optional(:enabled).filled(:bool)
      optional(:min_priority).filled(:float)
      optional(:max_age_days).filled(:integer, gt?: 0)
    end
    optional(:schema).hash do
      optional(:enabled).filled(:bool)
    end
    optional(:microdata).hash do
      optional(:enabled).filled(:bool)
    end
    optional(:microformats2).hash do
      optional(:enabled).filled(:bool)
    end
    optional(:json_state).hash do
      optional(:enabled).filled(:bool)
    end
    optional(:xhr_articles).hash do
      optional(:enabled).filled(:bool)
    end
    optional(:meta_oembed).hash do
      optional(:enabled).filled(:bool)
    end
    optional(:semantic_html).hash do
      optional(:enabled).filled(:bool)
      optional(:fallback_anchorless).filled(:bool)
    end
    optional(:html).hash do
      optional(:enabled).filled(:bool)
      optional(:minimum_selector_frequency).filled(:integer, gt?: 0)
      optional(:use_top_selectors).filled(:integer, gt?: 0)
      optional(:fallback_anchorless).filled(:bool)
    end
  end

  optional(:cleanup).hash do
    optional(:keep_different_domain).filled(:bool)
  end
end

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config) ⇒ Config

Initializes the configuration object.

Applies default values and validates the configuration.

Parameters:

  • config (Hash{Symbol => Object}) —

    the configuration hash.

Raises:



228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/html2rss/config.rb', line 228

def initialize(config)
  @request_controls = RequestControls.from_config(config)
  prepared_config = Preparer.new.call(config)
  validated_config = validated_config_for(prepared_config)

  @config = validated_config.freeze
  @request_controls = request_controls.with_effective_values(
    strategy: validated_config[:strategy],
    max_redirects: validated_config.dig(:request, :max_redirects),
    max_requests: validated_config.dig(:request, :max_requests),
    total_timeout_seconds: validated_config.dig(:request, :total_timeout_seconds)
  )
end

Instance Attribute Details

#request_controls ⇒ Html2rss::Config::RequestControls (readonly)

Returns request controls with provenance.

Returns:



261
262
263
 
# File 'lib/html2rss/config.rb', line 261

def request_controls
  @request_controls
end

Class Method Details

.auto_source_config(url:, items_selector: nil, request_controls: nil, limit: nil) ⇒ Hash{Symbol => Object}

Builds a top-level auto-source feed config for the public shortcut APIs.

Parameters:

  • url (String) —

    source page URL

  • items_selector (String, nil) (defaults to: nil) —

    optional selector hint for item extraction

  • request_controls (Html2rss::Config::RequestControls, nil) (defaults to: nil) —

    explicit request controls to write

  • limit (Integer, nil) (defaults to: nil) —

    max articles to keep in the auto-sourced feed

Returns:

  • (Hash{Symbol => Object}) —

    feed config hash ready for from_hash



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/html2rss/config.rb', line 153

def auto_source_config(url:, items_selector: nil, request_controls: nil, limit: nil)
  auto_source = AutoSource::DEFAULT_CONFIG
  auto_source = auto_source.merge(limit:) unless limit.nil?

  config = {
    channel: default_config[:channel].merge(url:),
    auto_source:
  }

  request_controls ||= RequestControls.new
  request_controls.apply_to(config)

  config[:selectors] = { items: { selector: items_selector, enhance: true } } if items_selector
  config
end

.default_config ⇒ Hash{Symbol => Object}

Provides a default configuration.

Returns:

  • (Hash{Symbol => Object}) —

    a hash with default configuration values.



173
174
175
176
177
178
179
180
181
 
# File 'lib/html2rss/config.rb', line 173

def default_config
  {
    strategy: default_strategy_name,
    request: default_request_config,
    channel: { time_zone: 'UTC' },
    headers: RequestHeaders.browser_defaults,
    stylesheets: Html2rss.defaults.stylesheets || []
  }
end

.default_strategy_name ⇒ Symbol

Returns the default feed-level strategy plan (+:auto+ or concrete).

Returns:

  • (Symbol) —

    the default feed-level strategy plan (+:auto+ or concrete)



184
185
186
 
# File 'lib/html2rss/config.rb', line 184

def default_strategy_name
  Html2rss.defaults.default_strategy || :auto
end

.from_hash(config, params: UNSET) ⇒ Html2rss::Config

Processes the provided configuration hash, applying dynamic parameters if given, and returns a new configuration object.

Parameters:

  • config (Hash{Symbol => Object}) —

    the configuration hash.

  • params (Hash{Symbol => Object, Hash{String => Object, nil}}) (defaults to: UNSET) —

    dynamic parameters for string formatting.

Returns:



141
142
143
 
# File 'lib/html2rss/config.rb', line 141

def from_hash(config, params: UNSET)
  new(resolve_effective_config(config, params:))
end

.from_yaml(string) ⇒ Hash{Symbol => Object}

Parses a YAML configuration string into a symbol-keyed hash.

Does not validate. Call validate or from_hash after this.

Parameters:

  • string (String) —

    YAML document

Returns:

  • (Hash{Symbol => Object}) —

    configuration hash

Raises:

  • (ArgumentError) —

    if string is not a String or does not deserialize to a Hash



93
94
95
96
97
98
99
100
 
# File 'lib/html2rss/config.rb', line 93

def from_yaml(string)
  raise ArgumentError, 'YAML must be a String' unless string.is_a?(String)

  parsed = YAML.safe_load(string)
  raise ArgumentError, 'YAML must deserialize to a Hash' unless parsed.is_a?(Hash)

  HashUtil.deep_symbolize_keys(parsed, context: 'config')
end

.json_schema ⇒ Hash{String => Object}

Returns the exported JSON Schema for html2rss configuration.

Returns:

  • (Hash{String => Object}) —

    JSON Schema represented as a Ruby hash



24
25
26
 
# File 'lib/html2rss/config.rb', line 24

def json_schema
  Schema.json_schema
end

.json_schema_json(pretty: true) ⇒ String

Returns the exported JSON Schema as JSON.

Parameters:

  • pretty (Boolean) (defaults to: true) —

    whether to pretty-print the JSON output

Returns:

  • (String) —

    serialized JSON Schema



33
34
35
 
# File 'lib/html2rss/config.rb', line 33

def json_schema_json(pretty: true)
  pretty ? JSON.pretty_generate(json_schema) : JSON.generate(json_schema)
end

.load_yaml(file, feed_name = nil, multiple_feeds_key: MultipleFeedsConfig::CONFIG_KEY_FEEDS) ⇒ Hash{Symbol => Object}

Loads the feed configuration from a YAML file.

Supports multiple feeds defined under the specified key (default :feeds).

rubocop:disable Metrics/MethodLength

Parameters:

  • file (String) —

    the YAML file to load.

  • feed_name (String, nil) (defaults to: nil) —

    the feed name when using multiple feeds.

  • multiple_feeds_key (Symbol) (defaults to: MultipleFeedsConfig::CONFIG_KEY_FEEDS) —

    the key under which multiple feeds are defined.

Returns:

  • (Hash{Symbol => Object}) —

    the configuration hash.

Raises:

  • (ArgumentError) —

    if the file doesn't exist or feed is not found.



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/html2rss/config.rb', line 113

def load_yaml(file, feed_name = nil, multiple_feeds_key: MultipleFeedsConfig::CONFIG_KEY_FEEDS)
  raise ArgumentError, "File '#{file}' does not exist" unless File.exist?(file)
  raise ArgumentError, "`#{multiple_feeds_key}` is a reserved feed name" if feed_name == multiple_feeds_key

  yaml = YAML.safe_load_file(file, symbolize_names: true)

  return yaml unless yaml.key?(multiple_feeds_key)

  unless feed_name
    available_feeds = yaml.fetch(multiple_feeds_key).keys.join(', ')
    raise ArgumentError,
          "Feed name is required under `#{multiple_feeds_key}`. Available feeds: #{available_feeds}"
  end

  config = yaml.dig(multiple_feeds_key, feed_name.to_sym)
  raise ArgumentError, "Feed '#{feed_name}' not found under `#{multiple_feeds_key}` key." unless config

  MultipleFeedsConfig.to_single_feed(config, yaml, multiple_feeds_key:)
end

.schema_path ⇒ String

Returns the packaged JSON Schema file path.

Returns:

  • (String) —

    absolute path to the packaged JSON Schema file



58
59
60
 
# File 'lib/html2rss/config.rb', line 58

def schema_path
  Schema.path
end

.to_yaml(hash) ⇒ String

Serializes a configuration hash to string-key YAML.

This is the single serializer for CLI capture and MCP capture_config.

Parameters:

  • hash (Hash) —

    configuration hash (symbol or string keys)

Returns:

  • (String) —

    YAML document without Ruby symbol-key prefixes



81
82
83
 
# File 'lib/html2rss/config.rb', line 81

def to_yaml(hash)
  YAML.dump(HashUtil.deep_stringify_keys(hash))
end

.validate(config, params: UNSET) ⇒ Dry::Validation::Result

Validates a configuration hash with the runtime validator.

Parameters:

  • config (Hash{Symbol => Object}) —

    the configuration hash

  • params (Hash{Symbol => Object, Hash{String => Object, nil}}) (defaults to: UNSET) —

    dynamic parameters for string formatting

Returns:

  • (Dry::Validation::Result) —

    validation result after defaults are applied



43
44
45
46
47
48
49
50
51
52
 
# File 'lib/html2rss/config.rb', line 43

def validate(config, params: UNSET)
  prepared_config = prepare_for_validation(resolve_effective_config(config, params:))

  Validator.new.call(prepared_config)
rescue DynamicParams::ParamsMissing => error
  prepared_config = prepare_for_validation(HashUtil.deep_symbolize_keys(config, context: 'config'))
  prepared_config[:dynamic_params_error] = error.message

  Validator.new.call(prepared_config)
end

.validate_yaml(file, feed_name = nil, multiple_feeds_key: MultipleFeedsConfig::CONFIG_KEY_FEEDS, params: UNSET) ⇒ Dry::Validation::Result

Loads and validates a YAML configuration file.

Parameters:

  • file (String) —

    the YAML file to load

  • feed_name (String, nil) (defaults to: nil) —

    optional feed name for multi-feed files

  • multiple_feeds_key (Symbol) (defaults to: MultipleFeedsConfig::CONFIG_KEY_FEEDS) —

    key under which multiple feeds are defined

  • params (Hash{Symbol => Object, Hash{String => Object, nil}}) (defaults to: UNSET) —

    dynamic parameters for string formatting

Returns:

  • (Dry::Validation::Result) —

    validation result after defaults are applied



70
71
72
 
# File 'lib/html2rss/config.rb', line 70

def validate_yaml(file, feed_name = nil, multiple_feeds_key: MultipleFeedsConfig::CONFIG_KEY_FEEDS, params: UNSET)
  validate(load_yaml(file, feed_name, multiple_feeds_key:), params:)
end

Instance Method Details

#auto_source ⇒ Hash{Symbol => Object, nil}

Returns auto-source configuration.

Returns:

  • (Hash{Symbol => Object, nil}) —

    auto-source configuration



278
 
# File 'lib/html2rss/config.rb', line 278

def auto_source = config[:auto_source]

#channel ⇒ Hash{Symbol => Object}

Returns channel configuration.

Returns:

  • (Hash{Symbol => Object}) —

    channel configuration



266
267
 
# File 'lib/html2rss/config.rb', line 266

def channel = config[:channel]
# @return [String] source channel URL

#explicit_max_requests? ⇒ Boolean

Returns whether max_requests was explicitly configured by the caller.

Returns:

  • (Boolean) —

    whether max_requests was explicitly configured by the caller



255
256
257
 
# File 'lib/html2rss/config.rb', line 255

def explicit_max_requests?
  request_controls.explicit?(:max_requests)
end

#headers ⇒ Hash{String => String}

Returns normalized HTTP headers.

Returns:

  • (Hash{String => String}) —

    normalized HTTP headers



264
265
 
# File 'lib/html2rss/config.rb', line 264

def headers = config[:headers]
# @return [Hash{Symbol => Object}] channel configuration

#max_redirects ⇒ Integer?

Returns configured redirect budget.

Returns:

  • (Integer, nil) —

    configured redirect budget



245
246
 
# File 'lib/html2rss/config.rb', line 245

def max_redirects = request_controls.max_redirects
# @return [Integer, nil] configured request budget

#max_requests ⇒ Integer?

Returns configured request budget.

Returns:

  • (Integer, nil) —

    configured request budget



247
248
 
# File 'lib/html2rss/config.rb', line 247

def max_requests = request_controls.max_requests
# @return [Integer, nil] configured request timeout

#request ⇒ Hash{Symbol => Object}

Returns request envelope configuration.

Returns:

  • (Hash{Symbol => Object}) —

    request envelope configuration



273
 
# File 'lib/html2rss/config.rb', line 273

def request = config[:request]

#selectors ⇒ Hash{Symbol => Object, nil}

Returns selectors configuration.

Returns:

  • (Hash{Symbol => Object, nil}) —

    selectors configuration



276
277
 
# File 'lib/html2rss/config.rb', line 276

def selectors = config[:selectors]
# @return [Hash{Symbol => Object, nil}] auto-source configuration

#strategy ⇒ Symbol?

Returns selected request strategy.

Returns:

  • (Symbol, nil) —

    selected request strategy



243
244
 
# File 'lib/html2rss/config.rb', line 243

def strategy = request_controls.strategy
# @return [Integer, nil] configured redirect budget

#stylesheets ⇒ Array<Hash>

Returns stylesheet definitions.

Returns:

  • (Array<Hash>) —

    stylesheet definitions



251
 
# File 'lib/html2rss/config.rb', line 251

def stylesheets = config[:stylesheets]

#time_zone ⇒ String?

Returns configured channel time zone.

Returns:

  • (String, nil) —

    configured channel time zone



270
 
# File 'lib/html2rss/config.rb', line 270

def time_zone = config.dig(:channel, :time_zone)

#total_timeout_seconds ⇒ Integer?

Returns configured request timeout.

Returns:

  • (Integer, nil) —

    configured request timeout



249
250
 
# File 'lib/html2rss/config.rb', line 249

def total_timeout_seconds = request_controls.total_timeout_seconds
# @return [Array<Hash>] stylesheet definitions

#url ⇒ String

Returns source channel URL.

Returns:

  • (String) —

    source channel URL



268
269
 
# File 'lib/html2rss/config.rb', line 268

def url = config.dig(:channel, :url)
# @return [String, nil] configured channel time zone