[gmpassos]

Summary

Adds a built-in scheduler that calls API routes on cron schedules, so apps don't need an external cron hitting a secret-protected route.

Jobs (APICronJob)

• 5-field cron expression (CronExpression: lists, ranges, steps, names, @daily/@hourly/...) evaluated in an IANA time zone, DST aware (a nonexistent time runs at the next valid instant; a repeated time runs once).
• Declared by @APICron on reflected route methods, APIRoot.loadCronJobs(), or the cron.jobs config (which can also override or disable code jobs by name).
• Called through APIRoot.call with APIAuthentication.system (passes APIRouteAuthenticatedRule), requester source internal, and X-Cron-Job / X-Cron-Scheduled-At / X-Cron-Run / X-Cron-Attempt headers.
• Continuation: while the response has X-Continuation (APIResponse.continuation), the route is called again with continuation=<token>, up to maxCalls.
• Retries (APICronRetry): exponential backoff (default 3 attempts: 30s, 2m), honors Retry-After; UNAUTHORIZED/BAD_REQUEST/NOT_FOUND aren't retried; per-call timeout.

Scheduler (APICronScheduler)

• Started by APIRoot.initialize when cron.enabled: true (not in auxiliary worker isolates: one per process), stopped by APIRoot.close.
• Exactly once per occurrence: the run row is claimed with a unique (job, scheduled time) insert, so it also works across instances.
• Never in parallel: a per-job lock with a lease, renewed while running. If an instance stops mid-run, another instance resumes the run from its last continuation token once the lease expires.
• Missed occurrences: the latest runs once within maxLateness (default 1 day); older ones are recorded as skipped.
• runNow(job), selectRuns(job), history pruning (history_days), logger APICron.

Store (APICronStore)

• APICronStoreMemory (single instance, tests) and APICronStoreDB (api_cron_job_run, api_cron_job_lock). It uses only inserts with unique constraints and deletes by ID or by expired lease, so it works on PostgreSQL, MySQL and the memory adapters with no adapter-specific locking.
• APIRoot.loadCronStore() picks the DB store when APICronStoreDB.buildRepositories(adapter) is registered.

Notes

• New dependency: timezone.
• APIModule gains cronJobs/addCronJob. Apps with generated module reflection need to regenerate it (build_runner) for the new field.
• Version 1.27.0 + CHANGELOG + README section "Cron: scheduled routes".

Review fixes (31a1aa8)

• Start after init: the scheduler starts once APIRoot and its modules are fully initialized, outside the init hook (cronSchedulerReady). Before, the first check could call a route before a module's initialize() finished.
• Owner-only writes: updateRun only writes a run that is still running and owned by the writer (previousOwner on take-over). An instance that lost its lock, or is stopping, writes nothing more; this is checked after every call. A finished run is never put back to running.
• Lease loss: if renewals fail until the lease runs out, the lock is considered lost.
• No overlap on timeout: a slow call is logged and waited for, never overlapped by a retry.
• No poison runs: a continuation token over 4096 chars, or an error while running, fails the run instead of leaving it running to be resumed forever.
• Store hardening: lock renew/release verify the row after writing, so no auto-inserted garbage lock is left. Pruning never deletes a running run. lastRun/selectRuns read only the latest rows.
• Smaller fixes: runNow never takes a scheduled slot; Retry-After is capped at maxDelay; graceful stop() + waitRunning(); a warning when the in-memory store is used.

Review fixes (2) (890cbb3)

• Lenient cron config: a cron value that isn't a map no longer breaks APIRoot.initialize. A bool (or bool string) means enabled; any other value disables cron. Scheduling the start never fails initialization.
• Stop: after stop(), tick()/runNow() do nothing until start() again.
• No ghost locks: an in-flight lock renewal is awaited before the lock is released.
• Config entries: a bad or stale cron.jobs entry is skipped and logged; an override of an unknown job is ignored. A top-level attempts key is supported.
• Validation: positive timeout/maxLateness/leaseDuration, retry.attempts >= 1; the time zone is resolved lazily (a job with an invalid zone is skipped).
• Module jobs: a duplicate job name in a module is an error, and an @APICron job is only added with its route.
• Start: only after a successful init. cronSchedulerReady works before initialize and is reset on close; startCronScheduler restarts a stopped scheduler; a rejected final save is reported as interrupted.
• Docs: fixed retry/timeout, config overrides, resume timing and the skipped-record cap.

Also added since the first description

• @APICron.at(minute:, hour:, dayOfMonth:, month:, dayOfWeek:, ...); both constructors take timeout, maxLateness, leaseDuration, retry.
• Fix: history pruning keeps runs still inside their job's maxLateness window (otherwise the occurrence could run again).
• Tests: CronExpression property tests against a minute-by-minute scan; DB integration through the real APIRoot lifecycle (two instances on one DB run an occurrence once; a closed instance is resumed by another); APIServer integration (forged X-Cron-* headers are refused).

Tests

• test/bones_api_cron_test.dart: cron parsing and next/previous times (UTC, Europe/Paris DST gap/overlap, America/Sao_Paulo), config/merging, retry/backoff/Retry-After, timeout, continuation and maxCalls, system auth and headers, locks, two schedulers on one store, no-parallel, resume, missed/skipped, history pruning, @APICron on reflected routes, APIRoot integration.
• test/bones_api_cron_db_*_test.dart: APICronStoreDB on memory, PostgreSQL and MySQL (docker): unique claims, locks (renew/take-over/release), parallel claims and locks with one winner, and two schedulers on the same DB including resume.
• Local on 890cbb3: unit (-x docker -x concurrency) 2150 pass, -t docker 329 pass, concurrency 86 pass; dart analyze --fatal-infos clean; pub publish --dry-run 0 warnings.
• CI on 890cbb3: all checks green (unit, docker, postgres, mysql, concurrency, chrome ×3, codecov).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 98.33507% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.53%. Comparing base (01c4a84) to head (890cbb3).

Files with missing lines	Patch %	Lines
lib/src/bones_api_cron_store.dart	97.69%	6 Missing ⚠️
lib/src/bones_api_cron_scheduler.dart	98.44%	5 Missing ⚠️
lib/src/bones_api_base.dart	95.94%	3 Missing ⚠️
lib/src/bones_api_authentication.dart	83.33%	1 Missing ⚠️
lib/src/bones_api_cron_expression.dart	99.35%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #189      +/-   ##
==========================================
+ Coverage   95.44%   95.53%   +0.09%     
==========================================
  Files          69       73       +4     
  Lines       24215    25174     +959     
==========================================
+ Hits        23111    24049     +938     
- Misses       1104     1125      +21     

Flag	Coverage Δ
unittests	95.53% <98.33%> (+0.09%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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