feat: add PrevN/NextN schedule introspection to web API

[CybotTM]

Summary

• Add NextRuns and PrevRuns arrays (5 entries each) to the /api/jobs response using go-cron v0.12.0's NextN/PrevN introspection APIs
• Add EntryByName method to Scheduler for looking up cron entries by job name with nil-safe guard
• Disabled, removed, and triggered jobs correctly return empty run arrays

Test Plan

• TestJobsEndpointNextPrevRuns - verifies next/prev runs populated
• TestJobsEndpointTriggeredJobEmptyRuns - triggered jobs have empty runs
• TestDisabledJobsEndpointEmptyRuns - disabled jobs have empty runs
• TestRemovedJobsEndpointEmptyRuns - removed jobs have empty runs
• TestJobsEndpointNextPrevRunsJSONFormat - JSON format validation
• All existing tests pass
• golangci-lint clean (0 issues)

Closes #493

[gemini-code-assist]

Summary of Changes

Hello @CybotTM, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the /api/jobs web API by exposing detailed scheduling information for cron jobs. It allows users to view the next five upcoming and previous five past execution times directly through the API, providing better visibility into job schedules. This feature is implemented with careful consideration for different job states, ensuring that non-scheduled jobs (triggered, disabled, removed) correctly report no upcoming or past runs.

Highlights

• API Enhancement: Introduced NextRuns and PrevRuns arrays, each containing 5 entries, to the /api/jobs API response, leveraging go-cron v0.12.0's introspection capabilities.
• Scheduler Functionality: Added an EntryByName method to the Scheduler for safe lookup of cron entries by their job name.
• Job State Handling: Ensured that disabled, removed, and triggered jobs correctly return empty arrays for NextRuns and PrevRuns.

Changelog

• core/scheduler.go
  • Added EntryByName method to Scheduler for retrieving cron entries by name.
• web/server.go
  • Imported go-cron package.
  • Added NextRuns and PrevRuns fields to the apiJob struct.
  • Implemented logic to calculate and populate NextN and PrevN schedule times for jobs.
  • Ensured NextRuns and PrevRuns are empty for triggered, disabled, and removed jobs.
• web/server_test.go
  • Added NextRuns and PrevRuns fields to the apiJob test struct.
  • Introduced TestJobsEndpointNextPrevRuns to verify correct population and order of next/previous runs.
  • Added TestJobsEndpointTriggeredJobEmptyRuns to confirm empty runs for triggered jobs.
  • Added TestDisabledJobsEndpointEmptyRuns to confirm empty runs for disabled jobs.
  • Added TestRemovedJobsEndpointEmptyRuns to confirm empty runs for removed jobs.
  • Added TestJobsEndpointNextPrevRunsJSONFormat to validate JSON output format for run times.

Activity

• Verified NextRuns and PrevRuns population with TestJobsEndpointNextPrevRuns.
• Confirmed triggered jobs have empty runs using TestJobsEndpointTriggeredJobEmptyRuns.
• Ensured disabled jobs have empty runs via TestDisabledJobsEndpointEmptyRuns.
• Validated removed jobs have empty runs with TestRemovedJobsEndpointEmptyRuns.
• Checked JSON format validation for NextRuns and PrevRuns using TestJobsEndpointNextPrevRunsJSONFormat.
• Confirmed all existing tests passed.
• Ensured golangci-lint reported 0 issues.
• Closed issue feat: add PrevN/NextN schedule introspection to web dashboard #493.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Automated approval for solo maintainer project

All CI checks passed. See SECURITY.md for compensating controls.

[github-actions]

✅ Mutation Testing Results

Mutation Score: 100.00% (threshold: 60%)

✨ Good job! Mutation score meets the threshold.

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)

[github-actions]

Dependency Review

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

Scanned Files

None

[Copilot]

Pull request overview

This pull request adds schedule introspection capabilities to the web API by exposing the next 5 and previous 5 scheduled execution times for each job. It leverages go-cron v0.12.0's NextN and PrevN APIs to provide better visibility into job scheduling patterns.

Changes:

• Added NextRuns and PrevRuns array fields to the /api/jobs response containing 5 upcoming and 5 previous schedule times
• Implemented EntryByName method in the Scheduler for safe cron entry lookups
• Properly handle edge cases where triggered, disabled, and removed jobs return empty run arrays

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
core/scheduler.go	Added EntryByName method with nil-safe guard for looking up cron entries by job name
web/server.go	Enhanced apiJob struct and buildAPIJobs to compute and populate next/prev runs using go-cron's introspection APIs
web/server_test.go	Added comprehensive test coverage for next/prev runs functionality including edge cases for triggered, disabled, and removed jobs

[github-actions]

Automated approval for solo maintainer project

All CI checks passed. See SECURITY.md for compensating controls.

[gemini-code-assist]

Code Review

This pull request introduces a valuable feature for job introspection by adding next and previous run times to the API response. The implementation is well-executed and accompanied by a comprehensive set of tests. I have one suggestion regarding code consistency in the disabledJobsHandler to prevent duplication and ensure all apiJob fields are populated uniformly. Additionally, it would be beneficial to update the API documentation in docs/API.md to reflect these new fields (nextRuns and prevRuns) in the /api/jobs endpoint response, ensuring users are aware of this new capability.

[codspeed-hq]

Merging this PR will degrade performance by 91.24%

⚡ 1 improved benchmark
❌ 3 regressed benchmarks
✅ 22 untouched benchmarks

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	lookup_100_jobs	505 ns	952 ns	-46.95%
❌	add	26.4 µs	29.9 µs	-11.73%
❌	lookup_1000_jobs	576 ns	6,576 ns	-91.24%
⚡	disable	71.9 µs	37.2 µs	+93.44%

---

_{Comparing feat/493-prevn-nextn-introspection (a0174bf) with main (537c4f2)¹}

Footnotes

1. No successful run was found on main (a0174bf) during the generation of this report, so 537c4f2 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[github-actions]

🚀 Released in v0.21.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.