feat(odin): Build candidate log file list in Extractor

[vikramlc-cognite]

Summary

Builds the candidate log file list for the fetch_logs built-in action. After validating the date range, the action now resolves the extractor's log file path from config, enumerates the [start_date, end_date] date range, and partitions files into candidates (exist, non-empty) and skipped (missing or empty). This is the second step of the bulk log upload feature - it sets up the file set that Tasks 3–4 will stream to CDF Files.

---

Type of change

• New feature (non-breaking change that adds functionality)

---

What changed

• _log_upload_action.py:
  • LogFileCandidate frozen dataclass - carries date, path, is_current. is_current=True marks the live file.log (unrotated), which Task 3 (BoundedReader) uses to know a size snapshot is required before reading.
  • _resolve_log_file_path(config: ExtractorConfig) -> Path | None - returns the base log path from the first LogFileHandlerConfig in config.log_handlers, or None if no file handler is configured.
  • _build_candidate_files(base_path, start_date, end_date, today) - enumerates the date range. Historical dates resolve to .YYYY-MM-DD, today resolves to the live base_path. Uses try/except FileNotFoundError on stat() (not exists() + stat()) to eliminate the TOCTOU race during log rotation. Files that don't exist or are 0 bytes go to skipped.
  • fetch_logs_action extended: after date validation, resolves the log path (raises ActionError(error_type="no_file_handler_configured") if absent), then calls _build_candidate_files to produce candidates and skipped lists for Tasks 3–5.

---

Why it changed

Part of the bulk log upload design (refer section: Related docs). Before uploading anything, the action needs to know which files exist and are non-empty for the requested date range. Separating file discovery from upload also makes each stage independently testable.

---

Related docs / discussion:

Design Doc - Bulk Log Upload Action

---

What to focus on during review

• _build_candidate_files uses try/except FileNotFoundError around path.stat() rather than path.exists() + path.stat(). This is intentional - eliminates the TOCTOU window where the file is deleted between the two calls (which can happen during log rotation rename).
• The rotation race scenario: if the action is dispatched immediately after midnight before TimedRotatingFileHandler renames file.log → file.log.YYYY-MM-DD, the rotated file won't exist yet and that date goes to skipped. This is documented in _build_candidate_files's docstring. The operator retries after rotation completes (within seconds).
• _resolve_log_file_path returns the first LogFileHandlerConfig found. Extractors with multiple file handlers will have the first one used. This is consistent with how base.py sets up log handlers.
• fetch_logs_action accesses ctx._extractor.application_config - acceptable since both are in the private framework implementation. Resolving at call time (not at registration time) ensures config changes are reflected immediately.

---

Test evidence

• tests/test_unstable/test_log_upload_action.py (17 test functions, 26 parametrized cases total):
  • _resolve_log_file_path: console-only → None; single file handler; multiple file handlers → first
  • _build_candidate_files: all files present; missing/empty files → skipped; today uses live file; mixed range; boundary (single day, exact max)
  • fetch_logs_action integration: no file handler → no_file_handler_configured; file handler + files present → succeeded; file handler + all files missing → succeeded (empty upload set)
• All 55 tests pass; ruff clean.

---

Risks and unknowns

• _candidates and _skipped are computed but not yet consumed - Tasks 3–5 will use them. The action currently succeeds after building the list regardless of whether any files were found.
• Log file path detection assumes LogFileHandlerConfig.path is the actual path on disk. If the extractor is run in a container with volume mounts that differ from the configured path, files won't be found and all dates will be skipped.
• The rotation race window (sub-second) is handled gracefully by skipping the missing date, but there is no automatic retry - the operator must re-invoke the action.

---

Rollout and rollback

No config changes or API changes required. fetch_logs_action now raises no_file_handler_configured for extractors without a file log handler (previously it would have silently succeeded with no uploads - which is the same observable behaviour since uploads aren't implemented yet).
Rolling back means reverting this commit, no CDF state is written at this stage.

---

Checklist

• Self-reviewed the diff
• Tests added or updated
• Docs updated - N/A (design doc is pre-existing)
• No secrets, credentials, or PII committed
• Breaking changes called out - none

[gemini-code-assist]

Code Review

This pull request introduces a built-in fetch_logs action to stream rotated log files to CDF Files, along with a structured ActionError exception for reporting failures. The framework now automatically registers this action and handles structured errors during dispatching. The feedback suggests improving robustness by catching OSError instead of only FileNotFoundError when checking log files, and adding validation to reject future date ranges to prevent silent failures.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.08%. Comparing base (4e5fc1a) to head (ec96aad).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #542      +/-   ##
==========================================
+ Coverage   82.90%   83.08%   +0.17%     
==========================================
  Files          45       45              
  Lines        4475     4522      +47     
==========================================
+ Hits         3710     3757      +47     
  Misses        765      765              

Files with missing lines	Coverage Δ
...extractorutils/unstable/core/_log_upload_action.py	100.00% <100.00%> (ø)
cognite/extractorutils/unstable/core/actions.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nithinb]

Thanks for resolving the rest of the issues.

Can you take another look at the conversation related to private variables?

[vikramlc-cognite]

@nithinb Agree, my concern was misplaced. I have gone ahead and added the application_config in the action context.

[nithinb]

risk review ok