sm-configure: Engine Configuration DSL

Comprehensive reference for configuring SourceMonitor via SourceMonitor.configure.

When to Use

• Adding or modifying settings in config/initializers/source_monitor.rb
• Understanding what configuration options are available
• Debugging configuration-related issues
• Setting up environment-specific overrides

Configuration Entry Point

All configuration lives inside the configure block in the host app's initializer:

SourceMonitor.configure do |config|
  # settings here
end

After the block executes, ModelExtensions.reload! runs automatically to apply any model changes. Restart web and worker processes after changes.

Configuration Sections

The config object (SourceMonitor::Configuration) has 13 sub-sections plus top-level queue/job settings:

See reference/configuration-reference.md for every setting with types, defaults, and examples.

Quick Examples

Queue Configuration

config.queue_namespace = "source_monitor"
config.fetch_queue_name = "source_monitor_fetch"
config.fetch_queue_concurrency = 4

HTTP Client

config.http.timeout = 30
config.http.proxy = ENV["HTTP_PROXY"]
config.http.retry_max = 3

Authentication (Devise)

SourceMonitor is fail-closed by default: with no authenticatewith/authorizewith handler configured, every engine route returns 403 Forbidden. Configure a handler to protect the dashboard (the handler decides access and bypasses the fail-closed guard):

config.authentication.authenticate_with :authenticate_user!
config.authentication.authorize_with ->(c) { c.current_user&.admin? }

For local demos/sandboxes only, opt out of the fail-closed guard (non-production):

config.authentication.open_access = true # default: false -- demo/non-production only

Image Downloads (Active Storage)

config.images.download_to_active_storage = true
config.images.max_download_size = 5 * 1024 * 1024  # 5 MB
config.images.download_timeout = 15
config.images.allowed_content_types = %w[image/jpeg image/png image/webp]

Events

config.events.after_item_created { |e| Notifier.new_item(e.item) }
config.events.register_item_processor ->(ctx) { Indexer.index(ctx.item) }

Model Extensions

config.models.table_name_prefix = "sm_"
config.models.source.include_concern "MyApp::SourceExtension"
config.models.item.validate :custom_check

Favicons (Active Storage)

config.favicons.enabled = true
config.favicons.fetch_timeout = 10
config.favicons.max_download_size = 512 * 1024  # 512 KB
config.favicons.retry_cooldown_days = 14

Realtime

config.realtime.adapter = :redis
config.realtime.redis_url = ENV["REDIS_URL"]

Helper APIs

SourceMonitor.config                         # Current configuration
SourceMonitor.configure { |c| ... }          # Set configuration
SourceMonitor.reset_configuration!           # Revert to defaults (for tests)
SourceMonitor.events                         # Shortcut to config.events
SourceMonitor.queue_name(:fetch)             # Resolved queue name
SourceMonitor.queue_concurrency(:scrape)     # Resolved concurrency
SourceMonitor.mission_control_dashboard_path # Resolved MC path or nil

Key Source Files

References

• reference/configuration-reference.md -- Complete settings reference
• docs/configuration.md -- Official configuration documentation
• lib/generators/sourcemonitor/install/templates/sourcemonitor.rb.tt -- Initializer template

Testing

Reset configuration between tests:

setup do
  SourceMonitor.reset_configuration!
end

Test custom configuration:

test "custom queue name" do
  SourceMonitor.configure do |config|
    config.fetch_queue_name = "custom_fetch"
  end
  assert_equal "custom_fetch", SourceMonitor.queue_name(:fetch)
end

Checklist

• Initializer exists at config/initializers/source_monitor.rb
• Queue names match config/queue.yml (or config/solid_queue.yml) entries
• Dispatcher config includes recurring_schedule: config/recurring.yml (handled by install generator)
• Authentication decision made: configure authenticatewith/authorizewith (fail-closed default) OR set config.authentication.open_access = true for demos only
• HTTP timeouts appropriate for target feeds
• Retention policy set for production
• Workers restarted after configuration changes