sm-configure

name	sm-configure
description	Use when configuring SourceMonitor engine settings via the DSL, including queue settings, HTTP client, fetching, health, scrapers, retention, scraping controls, events, model extensions, realtime, and authentication.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep

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:

Section	Accessor	Class
Top-level	config.*	Configuration
HTTP	config.http	HTTPSettings
Fetching	config.fetching	FetchingSettings
Health	config.health	HealthSettings
Scrapers	config.scrapers	ScraperRegistry
Retention	config.retention	RetentionSettings
Scraping	config.scraping	ScrapingSettings
Events	config.events	Events
Models	config.models	Models
Realtime	config.realtime	RealtimeSettings
Authentication	config.authentication	AuthenticationSettings
Images	config.images	ImagesSettings
Favicons	config.favicons	FaviconsSettings

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 authenticate_with/authorize_with 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

File	Purpose
lib/source_monitor/configuration.rb	Main Configuration class
lib/source_monitor/configuration/http_settings.rb	HTTP client settings
lib/source_monitor/configuration/fetching_settings.rb	Adaptive scheduling
lib/source_monitor/configuration/health_settings.rb	Health monitoring
lib/source_monitor/configuration/scraper_registry.rb	Scraper adapter registry
lib/source_monitor/configuration/retention_settings.rb	Item retention
lib/source_monitor/configuration/scraping_settings.rb	Scraping controls
lib/source_monitor/configuration/events.rb	Event callbacks
lib/source_monitor/configuration/models.rb	Model extensions config
lib/source_monitor/configuration/model_definition.rb	Per-model definition
lib/source_monitor/configuration/realtime_settings.rb	Action Cable settings
lib/source_monitor/configuration/authentication_settings.rb	Auth settings
lib/source_monitor/configuration/images_settings.rb	Image download settings
lib/source_monitor/configuration/validation_definition.rb	Validation wrapper

References

• reference/configuration-reference.md -- Complete settings reference
• docs/configuration.md -- Official configuration documentation
• lib/generators/source_monitor/install/templates/source_monitor.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 authenticate_with/authorize_with (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