Add cron.NextOccurrence to compute a job's next fire time

Nobody has started this yet — be first.

Business impact

Anyone managing jobs through the API today has no way to answer "when will this job next run?" without doing cron-expression math in their head or in a separate tool. That's a small but constant friction for every operator-facing surface that could show it: a dashboard listing jobs alongside their next fire time, a "this job hasn't run recently, is that expected?" sanity check, or simply GET /v1/jobs being genuinely useful for a human glancing at it instead of just machine-consumable.

Problem

pkg/cron/materializer.go's internal cron-parsing logic (parser, used by materializeCron) already knows how to compute a schedule's next occurrence, but that capability isn't exposed as a reusable, exported function -- it's inlined into the materializer's own catch-up loop. NextOccurrence is a placeholder that panics with "TODO(ticket-E4): NextOccurrence not implemented".

Current behavior

Calling cron.NextOccurrence panics instead of returning a computed next-fire time.

Expected behavior

cron.NextOccurrence(cronExpr, from) returns the next time the given cron expression fires at or after from, so the API layer can eventually expose it (e.g. a next_scheduled_for field on GET /v1/jobs) without duplicating cron-parsing logic.

Steps to reproduce

Call cron.NextOccurrence("* * * * *", time.Now()).
Observe: a panic, "TODO(ticket-E4): NextOccurrence not implemented", instead of a computed time.

Why this matters

This is the same underlying capability materializeCron already uses (parser.Parse + schedule.Next), just extracted into a small, independently testable, reusable function instead of being locked inside the materializer's private loop.

Suggested approach

Look at materializeCron's use of parser.Parse(*job.CronExpr) followed by schedule.Next(from) for the exact pattern to reuse.

Acceptance criteria

cron.NextOccurrence(cronExpr, from) returns the correct next fire time for a valid cron expression
It returns a non-nil error for an invalid cron expression (don't panic on bad input either)
go build ./..., go vet ./..., gofmt -l . stay clean

Verification

go test ./tickets/tests/... -run TestTicket11 -v

Hints (0/2)

Try it without hints first — the reading is the exercise.

Working on this ticket

Work on a branch named for the ticket — that's what you'll submit.

Branch off your fork

$git checkout -b feat/next-occurrence

Fix it and commit

Meet every acceptance criterion, and add a test that would have caught this.

Push the branch

$git push -u origin feat/next-occurrence

Submit it below

Paste your fork URL and the branch name, with a short write-up of the root cause.

Submit your fix

Questions

Stuck on something?

Ask about anything unclear in the ticket — the maintainer and anyone who has solved it can answer. Please don't post full solutions.

No questions yet. If something in this ticket reads ambiguously, you are probably not the only one — ask.

The project

Chronos — Distributed Cron Scheduler

A "cron-as-a-service" job scheduler backed entirely by Postgres -- SKIP LOCKED leasing and advisory-lock leader election, no etcd/ZooKeeper/Consul -- twenty ways the coordination quietly breaks.

Fork on GitHub

Download

Setup

Chronos — Distributed Cron Scheduler

git clone <your-fork>
cd GolangDevTraining/chronos
docker compose up --build   # postgres + two app replicas + adminer, hot-reloading on save

Two replicas run on () and (), both against the same database; Adminer is at . Verify with and .