feat: separate config file polling from container detection

[CybotTM]

Summary

This PR redesigns the configuration model to clearly separate INI config file polling from Docker container detection, addressing confusion where these concerns were mixed under poll-interval.

Key Changes

• config-poll-interval (default: 10s): Polls for INI configuration file changes only
• events (default: true): Uses Docker events API for real-time container detection
• docker-poll-interval (default: 0/disabled): Explicit container polling (fallback method)
• polling-fallback (default: 10s): Auto-enables container polling if events fail

Features

• ✅ Events enabled by default with exponential backoff reconnection (1s-5min)
• ✅ Auto-fallback to polling when event stream fails (if configured)
• ✅ Warning logged if both events and explicit polling are enabled (wasteful)
• ✅ Users can now disable container polling while keeping INI file watching
• ✅ Backwards compatibility with deprecated poll-interval and no-poll options

Breaking Changes

• poll-interval → config-poll-interval (with deprecation warning)
• no-poll → Use docker-poll-interval=0 (with deprecation warning)

Configuration Examples

[docker]
; Default: events for containers, polling for INI file
events = true
config-poll-interval = 10s

; Explicit polling only (e.g., when events are unreliable)
events = false
docker-poll-interval = 30s

; Events with auto-fallback
events = true
polling-fallback = 30s

Test Plan

• All existing tests pass
• Linting passes
• CI workflow validates changes
• Manual testing with Docker events and polling scenarios

Closes discussion from previous PR about confusing configuration.

---

Addresses:

• Hot reload of the config mcuadros/ofelia#5
• Live jobs discovery from docker labels mcuadros/ofelia#57
• [Feature] detect new and stopped containers during runtime mcuadros/ofelia#89
• Reload config.ini mcuadros/ofelia#108

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[github-actions]

⚠️ Mutation Testing Results

Mutation Score: 0% (threshold: 60%)

⚠️ Score is below threshold. Consider improving test coverage or test quality.

What is mutation testing?

Mutation testing measures test quality by introducing small changes (mutations) to the code and checking if tests detect them. A higher score means better test effectiveness.

• Killed mutants: Tests caught the mutation (good!)
• Survived mutants: Tests missed the mutation (needs improvement)

[Copilot]

Pull request overview

This PR redesigns Ofelia's configuration model to cleanly separate INI configuration file polling from Docker container detection mechanisms. Previously, both concerns were conflated under a single poll-interval setting, leading to confusion about what was being polled. The refactoring introduces explicit, well-named configuration options and implements Docker events as the default container detection method with automatic fallback to polling when events fail.

Key Changes:

• Replaced monolithic poll-interval with separate config-poll-interval (INI file watching) and docker-poll-interval (container polling) options
• Changed default container detection from polling to Docker events API (events=true by default)
• Implemented exponential backoff reconnection logic (1s-5min) for Docker event stream failures
• Added automatic fallback to container polling when event subscription fails (polling-fallback option)

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
cli/config.go	Adds new configuration fields (ConfigPollInterval, DockerPollInterval, PollingFallback) with comprehensive documentation; changes UseEvents default from false to true; retains deprecated fields for backward compatibility
cli/docker_config_handler.go	Core implementation: adds resolveConfig() for deprecation handling; splits original watch() into watchConfig(), watchEvents(), and watchContainerPolling(); implements event stream reconnection with exponential backoff and automatic fallback mechanism
cli/docker_handler_test.go	Updates test to reflect renamed field configPollInterval and renamed method watchConfig()
cli/daemon_lifecycle_test.go	Updates all mock DockerHandler initializations to use new field names (configPollInterval, dockerPollInterval, pollingFallback)
cli/config_initialize_test.go	Updates mock DockerHandler factory functions to use new configuration field names
README.md	Comprehensive documentation update explaining the separation of concerns, new configuration options, CLI flags, and backward compatibility with deprecated options

[CybotTM]

🚀 Released in v0.15.0

Thank you for your contribution! 🙏

This is now available in the latest release. Please test and verify everything works as expected in your environment.

If you encounter any issues, please open a new issue.