cron

func NewChain ¶

func NewChain(c ...JobWrapper) Chain

NewChain returns a Chain consisting of the given JobWrappers.

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New()

	// Create a chain for specific jobs
	chain := cron.NewChain(
		cron.DelayIfStillRunning(cron.DefaultLogger),
	)

	// Wrap a job with the chain
	wrappedJob := chain.Then(cron.FuncJob(func() {
		fmt.Println("This job will queue if still running")
	}))

	c.Schedule(cron.Every(time.Minute), wrappedJob)
	c.Start()
	defer c.Stop()
}

func WithStateChangeCallback ¶ added in v0.12.0

func WithStateChangeCallback(fn func(CircuitBreakerEvent)) CircuitBreakerOption

WithStateChangeCallback sets a callback invoked on circuit breaker state transitions. This enables external monitoring and metrics collection.

State transitions that trigger the callback:

• Closed → Open (threshold failures reached)
• Open → HalfOpen (cooldown expired, probe attempted)
• HalfOpen → Closed (probe succeeded)
• HalfOpen → Open (probe failed)

The callback is invoked synchronously within the job execution goroutine. Keep callbacks fast to avoid delaying job execution.

Example with Prometheus:

CircuitBreaker(logger, 5, 5*time.Minute,
    cron.WithStateChangeCallback(func(e cron.CircuitBreakerEvent) {
        circuitState.WithLabelValues(e.NewState.String()).Set(1)
        if e.NewState == cron.CircuitOpen {
            circuitTrips.Inc()
        }
    }),
)

func Every ¶

func Every(duration time.Duration) ConstantDelaySchedule

Every returns a crontab Schedule that activates once every duration. Delays of less than a second are not supported (will round up to 1 second). Any fields less than a Second are truncated.

For custom minimum intervals, use EveryWithMin instead.

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New()

	// Run every 5 minutes
	c.Schedule(cron.Every(5*time.Minute), cron.FuncJob(func() {
		fmt.Println("Every 5 minutes")
	}))

	c.Start()
	defer c.Stop()
}

func EveryWithMin ¶ added in v0.6.0

func EveryWithMin(duration, minInterval time.Duration) ConstantDelaySchedule

EveryWithMin returns a crontab Schedule that activates once every duration, with a configurable minimum interval.

The minInterval parameter controls the minimum allowed duration:

• If minInterval > 0, durations below minInterval are rounded up to minInterval
• If minInterval <= 0, no minimum is enforced (allows sub-second intervals)

Any fields less than a Second are truncated unless minInterval allows sub-second.

Example:

// Standard usage (1 second minimum)
sched := EveryWithMin(500*time.Millisecond, time.Second) // rounds to 1s

// Sub-second intervals (for testing)
sched := EveryWithMin(100*time.Millisecond, 0) // allows 100ms

// Enforce minimum 1-minute intervals
sched := EveryWithMin(30*time.Second, time.Minute) // rounds to 1m

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New()

	// Allow sub-second intervals (useful for testing)
	// The second parameter (0) disables the minimum interval check
	schedule := cron.EveryWithMin(100*time.Millisecond, 0)
	c.Schedule(schedule, cron.FuncJob(func() {
		fmt.Println("Running every 100ms")
	}))

	// Enforce minimum 1-minute intervals (useful for rate limiting)
	// If duration < minInterval, it's rounded up to minInterval
	rateLimited := cron.EveryWithMin(30*time.Second, time.Minute)
	c.Schedule(rateLimited, cron.FuncJob(func() {
		fmt.Println("Running every minute (30s was rounded up)")
	}))

	c.Start()
	defer c.Stop()
}

func New ¶

func New(opts ...Option) *Cron

New returns a new Cron job runner, modified by the given options.

Available Settings

Time Zone
  Description: The time zone in which schedules are interpreted
  Default:     time.Local

Parser
  Description: Parser converts cron spec strings into cron.Schedules.
  Default:     Accepts this spec: https://en.wikipedia.org/wiki/Cron

Chain
  Description: Wrap submitted jobs to customize behavior.
  Default:     A chain that recovers panics and logs them to stderr.

See "cron.With*" to modify the default behavior.

package main

import (
	"fmt"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New()

	c.AddFunc("@hourly", func() {
		fmt.Println("Every hour")
	})

	c.Start()
	defer c.Stop()
}

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	nyc, _ := time.LoadLocation("America/New_York")
	c := cron.New(cron.WithLocation(nyc))

	// Run at 9 AM New York time
	c.AddFunc("0 9 * * *", func() {
		fmt.Println("Good morning, New York!")
	})

	c.Start()
	defer c.Stop()
}

package main

import (
	"fmt"

	cron "github.com/netresearch/go-cron"
)

func main() {
	// Enable seconds field (Quartz-style 6-field expressions)
	c := cron.New(cron.WithSeconds())

	// Run every 30 seconds
	c.AddFunc("*/30 * * * * *", func() {
		fmt.Println("Every 30 seconds")
	})

	c.Start()
	defer c.Stop()
}

func NewFakeClock ¶ added in v0.6.0

func NewFakeClock(t time.Time) *FakeClock

NewFakeClock creates a new FakeClock initialized to the given time.

func WithMissedGracePeriod ¶ added in v0.10.0

func WithMissedGracePeriod(d time.Duration) JobOption

WithMissedGracePeriod sets the maximum age of a missed execution that should be caught up. If zero (default), all missed executions are eligible for catch-up (subject to the safety limit of 100 executions for MissedRunAll).

This is useful to avoid running very old missed jobs that are no longer relevant. For example, if a daily report job was missed 3 days ago, you might not want to generate reports for all those days.

Example:

// Only catch up if missed within the last 2 hours
c.AddFunc("0 9 * * *", dailyReport,
    cron.WithPrev(lastRun),
    cron.WithMissedPolicy(cron.MissedRunOnce),
    cron.WithMissedGracePeriod(2*time.Hour),
)

func WithMissedPolicy ¶ added in v0.10.0

func WithMissedPolicy(policy MissedPolicy) JobOption

WithMissedPolicy configures how the scheduler handles missed job executions. A job is considered "missed" if it was scheduled to run while the scheduler was not running (e.g., during application restart).

This feature requires WithPrev() to provide the last run time. Without a known last run time, no catch-up will occur regardless of the policy.

Available policies:

• MissedSkip (default): Do not catch up; wait for next scheduled time
• MissedRunOnce: Run once immediately if any executions were missed
• MissedRunAll: Run for every missed execution (use with caution)

Example:

lastRun := loadFromDatabase("daily-report")
c.AddFunc("0 9 * * *", dailyReport,
    cron.WithPrev(lastRun),
    cron.WithMissedPolicy(cron.MissedRunOnce),
)

func WithName ¶ added in v0.6.0

func WithName(name string) JobOption

WithName sets a unique name for the job entry. Names must be unique within a Cron instance; adding a job with a duplicate name will return ErrDuplicateName.

Named jobs can be retrieved with EntryByName() or removed with RemoveByName().

Example:

c.AddFunc("@every 1h", cleanup, cron.WithName("hourly-cleanup"))

func WithPaused ¶ added in v0.12.0

func WithPaused() JobOption

WithPaused causes the entry to be added in a paused state. Paused entries remain registered with their schedule intact but are skipped during execution. Use ResumeEntry to activate the entry later.

This is useful for:

• Pre-registering jobs that should only run after explicit activation
• Maintenance windows: add jobs paused, resume when ready
• Feature flags: register jobs that are enabled externally

Example:

id, _ := c.AddFunc("@every 5m", syncData, cron.WithPaused(), cron.WithName("sync"))
// Later, when ready:
c.ResumeEntry(id)

func WithPrev ¶ added in v0.7.0

func WithPrev(prev time.Time) JobOption

WithPrev sets the previous execution time for an entry. This is useful for:

• Schedule migration: preserving execution history when moving jobs between schedulers
• Missed execution detection: combined with schedule analysis to detect missed runs
• Process restarts: preserving interval-based job continuity across restarts

Example:

// Migrate job with preserved history
lastRun := loadLastRunFromDB()
c.AddFunc("@every 1h", cleanup, cron.WithPrev(lastRun))

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New()
	defer c.Stop()

	// Simulate migrating a job from another scheduler
	// Set the previous execution time to preserve history
	lastRun := time.Date(2025, 1, 1, 9, 0, 0, 0, time.UTC)
	id, _ := c.AddFunc("@hourly", func() {
		fmt.Println("Running hourly job")
	}, cron.WithPrev(lastRun))

	entry := c.Entry(id)
	fmt.Printf("Previous run preserved: %v\n", entry.Prev.Equal(lastRun))
}

Output:

Previous run preserved: true

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New()

	lastRun := time.Date(2025, 1, 1, 9, 0, 0, 0, time.UTC)
	done := make(chan struct{})
	id, _ := c.AddFunc("@hourly", func() {
		fmt.Println("Job ran")
		close(done)
	}, cron.WithPrev(lastRun), cron.WithRunImmediately())

	entry := c.Entry(id)
	fmt.Printf("Prev preserved: %v\n", entry.Prev.Equal(lastRun))

	c.Start()
	<-done // Wait for job to complete
	c.Stop()

	fmt.Println("Both options work together")
}

Output:

Prev preserved: true
Job ran
Both options work together

func WithRunImmediately ¶ added in v0.7.0

func WithRunImmediately() JobOption

WithRunImmediately causes the job to run immediately upon registration, then follow the normal schedule thereafter. This is useful for:

• Initial sync: running a sync job once at startup before regular schedule
• Health checks: ensuring service connectivity is verified immediately
• Cache warming: populating caches before the first scheduled refresh

Example:

// Run immediately, then every hour
c.AddFunc("@every 1h", syncData, cron.WithRunImmediately())

package main

import (
	"fmt"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New()

	done := make(chan struct{})
	c.AddFunc("@hourly", func() {
		fmt.Println("Job executed immediately")
		close(done)
	}, cron.WithRunImmediately())

	c.Start()
	<-done // Wait for job to complete
	c.Stop()

	fmt.Println("Done")
}

Output:

Job executed immediately
Done

func WithRunOnce ¶ added in v0.7.0

func WithRunOnce() JobOption

WithRunOnce causes the job to be automatically removed after its first execution. This is useful for:

• One-time scheduled tasks: "send reminder in 24 hours"
• Deferred execution: schedule a task for later without manual cleanup
• Temporary events: schedule something for a specific time, then forget it

The job is removed from the scheduler after it is dispatched, regardless of whether the job succeeds or fails. The job's goroutine continues to run independently after the entry is removed.

WithRunOnce works correctly with job wrappers like Recover and RetryWithBackoff: the entry is removed after dispatch, but retries happen within the job's goroutine.

Can be combined with WithRunImmediately to run once immediately:

// Run once right now
c.AddFunc("@every 1h", task, cron.WithRunOnce(), cron.WithRunImmediately())

Example:

// Send reminder in 24 hours, then remove from scheduler
c.AddFunc("@in 24h", sendReminder, cron.WithRunOnce())

// Run at specific time, then remove
c.AddFunc("0 9 25 12 *", sendChristmasGreeting, cron.WithRunOnce())

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New()

	executed := make(chan struct{})

	// Add a job that will only run once, then auto-remove
	id, _ := c.AddFunc("@every 1s", func() {
		fmt.Println("Job executed")
		close(executed)
	}, cron.WithRunOnce())

	c.Start()
	<-executed // Wait for job to run

	// Give scheduler time to remove the entry
	time.Sleep(10 * time.Millisecond)

	// The entry no longer exists
	entry := c.Entry(id)
	fmt.Printf("Entry exists after execution: %v\n", entry.ID != 0)

	c.Stop()
}

Output:

Job executed
Entry exists after execution: false

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New(cron.WithChain(
		cron.Recover(cron.DefaultLogger),
	))

	done := make(chan struct{})

	id, _ := c.AddFunc("@every 1s", func() {
		close(done)
		panic("intentional panic")
	}, cron.WithRunOnce())

	c.Start()
	<-done
	time.Sleep(50 * time.Millisecond) // Wait for scheduler to process removal

	// Entry is still removed even though job panicked
	entry := c.Entry(id)
	fmt.Printf("Entry removed after panic: %v\n", entry.ID == 0)

	c.Stop()
}

Output:

Entry removed after panic: true

package main

import (
	"fmt"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New()

	done := make(chan struct{})

	// Run immediately AND only once - useful for deferred tasks
	c.AddFunc("@hourly", func() {
		fmt.Println("Immediate one-time execution")
		close(done)
	}, cron.WithRunOnce(), cron.WithRunImmediately())

	c.Start()
	<-done
	c.Stop()

	fmt.Println("Job ran immediately and was removed")
}

Output:

Immediate one-time execution
Job ran immediately and was removed

func WithTags ¶ added in v0.6.0

func WithTags(tags ...string) JobOption

WithTags sets tags for categorizing the job entry. Multiple entries can share the same tags, enabling group operations.

Tagged jobs can be filtered with EntriesByTag() or removed with RemoveByTag().

Example:

c.AddFunc("@every 1h", cleanup, cron.WithTags("maintenance", "hourly"))

func CircuitBreaker ¶ added in v0.6.0

func CircuitBreaker(logger Logger, threshold int, cooldown time.Duration, opts ...CircuitBreakerOption) JobWrapper

CircuitBreaker wraps jobs with a circuit breaker that opens after threshold consecutive panics, skipping execution for the cooldown duration. After cooldown, a single probe attempt is allowed (half-open state); if it succeeds the circuit closes, otherwise it re-opens. State is shared across all jobs wrapped by the same wrapper instance. Use CircuitBreakerWithHandle for monitoring access.

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	logger := cron.DefaultLogger

	c := cron.New(cron.WithChain(
		// Outermost: catches re-panic from circuit breaker
		cron.Recover(logger),
		// Open circuit after 3 consecutive failures, cooldown for 5 minutes
		cron.CircuitBreaker(logger, 3, 5*time.Minute),
	))

	c.AddFunc("@every 1m", func() {
		// Simulate a job calling an external service
		if err := callExternalAPI(); err != nil {
			panic(err) // After 3 failures, circuit opens for 5 minutes
		}
		fmt.Println("API call succeeded")
	})

	c.Start()
	defer c.Stop()
}

// callExternalAPI is a mock function for the CircuitBreaker example
func callExternalAPI() error {

	return nil
}

func DelayIfStillRunning ¶

func DelayIfStillRunning(logger Logger) JobWrapper

DelayIfStillRunning serializes jobs, delaying subsequent runs until the previous one is complete. Jobs running after a delay of more than a minute have the delay logged at Info.

The returned wrapper implements JobWithContext, propagating the incoming context to the inner job if it also implements JobWithContext.

func Jitter ¶ added in v0.7.0

func Jitter(maxJitter time.Duration) JobWrapper

Jitter adds a random delay before job execution to prevent thundering herd. When many jobs are scheduled at the same time (e.g., @hourly), they would all execute simultaneously, causing database connection spikes, API rate limiting, and resource contention. Jitter spreads out the execution times.

The delay is uniformly distributed in the range [0, maxJitter). A maxJitter of 0 or negative disables jitter (no delay).

The returned wrapper implements JobWithContext, propagating the incoming context to the inner job if it also implements JobWithContext.

Example:

// Add 0-30s random delay before each execution
cron.NewChain(cron.Jitter(30 * time.Second)).Then(myJob)

// Compose with other wrappers
cron.NewChain(
    cron.Recover(logger),
    cron.Jitter(30 * time.Second),
    cron.SkipIfStillRunning(logger),
).Then(myJob)

// Use via WithChain option
c.AddFunc("@hourly", syncData, cron.WithChain(cron.Jitter(30*time.Second)))

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New(cron.WithChain(
		cron.Recover(cron.DefaultLogger),
		// Add 0-30s random delay before each job execution
		cron.Jitter(30*time.Second),
	))

	c.AddFunc("@hourly", func() {
		// This job will start between 0-30 seconds after the hour
		// Each execution gets a new random delay
		fmt.Println("Processing hourly task")
	})

	c.Start()
	defer c.Stop()
}

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New(cron.WithChain(
		cron.Recover(cron.DefaultLogger),
	))

	// High-priority job: minimal jitter (0-5s)
	highPriorityJob := cron.NewChain(cron.Jitter(5 * time.Second)).Then(cron.FuncJob(func() {
		fmt.Println("High priority task")
	}))
	c.Schedule(cron.Every(time.Hour), highPriorityJob)

	// Low-priority job: larger jitter (0-60s)
	lowPriorityJob := cron.NewChain(cron.Jitter(60 * time.Second)).Then(cron.FuncJob(func() {
		fmt.Println("Low priority task")
	}))
	c.Schedule(cron.Every(time.Hour), lowPriorityJob)

	c.Start()
	defer c.Stop()
}

func JitterWithLogger ¶ added in v0.7.0

func JitterWithLogger(logger Logger, maxJitter time.Duration) JobWrapper

JitterWithLogger is like Jitter but logs the applied delay. This is useful for debugging and observability to verify jitter is working.

The returned wrapper implements JobWithContext, propagating the incoming context to the inner job if it also implements JobWithContext.

Example:

cron.NewChain(cron.JitterWithLogger(logger, 30 * time.Second)).Then(myJob)

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	logger := cron.DefaultLogger

	c := cron.New(cron.WithChain(
		cron.Recover(logger),
		// Log the jitter delay for each execution
		cron.JitterWithLogger(logger, 30*time.Second),
	))

	c.AddFunc("@hourly", func() {
		fmt.Println("Task with logged jitter")
	})

	c.Start()
	defer c.Stop()
}

func MaxConcurrent ¶ added in v0.12.0

func MaxConcurrent(n int) JobWrapper

MaxConcurrent limits the total number of jobs that can run concurrently across all entries wrapped by this chain. When all slots are occupied, new job executions wait until a slot becomes available or the context is canceled (e.g., during scheduler shutdown).

This is useful when many jobs are scheduled at the same time (e.g., many @hourly jobs at minute 0) to limit concurrent resource usage (database connections, API rate limits, CPU).

Goroutine Accumulation ¶

The scheduler spawns a goroutine for each due job. MaxConcurrent blocks those goroutines while waiting for a slot, so goroutines still accumulate if jobs are triggered faster than they complete. If this is a concern, use MaxConcurrentSkip instead, which drops excess executions immediately.

Unlike SkipIfStillRunning (which limits per-job), MaxConcurrent limits across all jobs sharing the same wrapper instance.

A limit of 0 or negative panics — use no wrapper if you want no limit.

The returned wrapper implements JobWithContext, propagating the incoming context to the inner job if it also implements JobWithContext. If the context is canceled while waiting for a slot, the job is abandoned.

Example:

// Limit all jobs to 10 concurrent executions
c := cron.New(cron.WithChain(
    cron.Recover(logger),
    cron.MaxConcurrent(10),
))

// Compose with jitter to prevent thundering herd AND limit concurrency
c := cron.New(cron.WithChain(
    cron.Recover(logger),
    cron.Jitter(30 * time.Second),
    cron.MaxConcurrent(10),
))

func MaxConcurrentSkip ¶ added in v0.12.0

func MaxConcurrentSkip(logger Logger, n int) JobWrapper

MaxConcurrentSkip is like MaxConcurrent but skips execution instead of waiting when the concurrency limit is reached. This is useful when you prefer to drop executions rather than queue them up.

Unlike SkipIfStillRunning (which limits per-job), MaxConcurrentSkip limits across all jobs sharing the same wrapper instance.

The returned wrapper implements JobWithContext, propagating the incoming context to the inner job if it also implements JobWithContext.

Example:

c := cron.New(cron.WithChain(
    cron.Recover(logger),
    cron.MaxConcurrentSkip(logger, 5),
))

func Recover ¶

func Recover(logger Logger, opts ...RecoverOption) JobWrapper

Recover panics in wrapped jobs and log them with the provided logger.

By default, panics are logged at Error level. Use WithLogLevel to change this behavior, for example when combined with retry wrappers.

The returned wrapper implements JobWithContext, propagating the incoming context to the inner job if it also implements JobWithContext.

Workflow-aware: when running inside a workflow execution, Recover logs the panic and then re-panics so the workflow engine correctly detects the failure. The scheduler catches the re-panic without crashing.

Example:

// Default behavior - logs at Error level
cron.NewChain(cron.Recover(logger)).Then(job)

// Log at Info level (useful with retries)
cron.NewChain(cron.Recover(logger, cron.WithLogLevel(cron.LogLevelInfo))).Then(job)

func RetryOnError ¶ added in v0.10.0

func RetryOnError(logger Logger, maxRetries int, initialDelay, maxDelay time.Duration, multiplier float64, opts ...RetryOption) JobWrapper

RetryOnError wraps an ErrorJob to retry on returned errors with exponential backoff. Unlike RetryWithBackoff which catches panics, this wrapper uses Go-idiomatic error returns for retry decisions. Jobs must implement the ErrorJob interface to benefit from this wrapper; regular Jobs that only implement Run() are passed through unchanged.

Parameters:

• logger: For logging retry attempts
• maxRetries: Maximum retry attempts:
• 0 = no retries (execute once, log error if it fails) - SAFE DEFAULT
• >0 = retry up to N times (N+1 total attempts)
• -1 = unlimited retries (use with caution - can cause resource exhaustion)
• initialDelay: First retry delay
• maxDelay: Maximum delay cap (prevents exponential explosion)
• multiplier: Delay multiplier per retry (typically 2.0)

When all retries are exhausted, the final error is logged and then panicked, propagating the failure through the middleware chain (e.g., CircuitBreaker, Recover). This is consistent with RetryWithBackoff and ensures downstream wrappers see the failure.

Example usage:

c := cron.New(
    cron.WithChain(
        cron.Recover(logger),   // Outermost: catches panics from non-ErrorJob jobs
        cron.RetryOnError(logger, 3, time.Second, time.Minute, 2.0),
    ),
)
c.AddJob("@every 5m", cron.FuncErrorJob(func() error {
    return callAPI() // Returned errors trigger retry
}))

Retry behavior for maxRetries=3, initialDelay=1s, multiplier=2.0:

| Attempt | Delay | Action             |
|---------|-------|--------------------|
| 1       | 0     | Execute            |
| 2       | 1s    | Retry after delay  |
| 3       | 2s    | Retry after delay  |
| 4       | 4s    | Final retry        |
| -       | -     | Log + panic (done) |

func RetryWithBackoff ¶ added in v0.6.0

func RetryWithBackoff(logger Logger, maxRetries int, initialDelay, maxDelay time.Duration, multiplier float64, opts ...RetryOption) JobWrapper

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	logger := cron.DefaultLogger

	c := cron.New(cron.WithChain(
		// Outermost: catches final re-panic after retries exhausted
		cron.Recover(logger),
		// Retry up to 3 times with exponential backoff
		// Initial delay: 1s, max delay: 30s, multiplier: 2.0
		cron.RetryWithBackoff(logger, 3, time.Second, 30*time.Second, 2.0),
	))

	attempts := 0
	c.AddFunc("@hourly", func() {
		attempts++
		// Simulate transient failure that succeeds on 3rd attempt
		if attempts < 3 {
			panic(fmt.Sprintf("attempt %d failed", attempts))
		}
		fmt.Printf("Succeeded on attempt %d\n", attempts)
	})

	c.Start()
	defer c.Stop()
}

package main

import (
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	logger := cron.DefaultLogger

	c := cron.New(cron.WithChain(
		cron.Recover(logger),
		// maxRetries=0 means no retries - execute once, fail immediately
		cron.RetryWithBackoff(logger, 0, time.Second, 30*time.Second, 2.0),
	))

	c.AddFunc("@hourly", func() {
		// This will execute once, panic, and not retry
		panic("immediate failure")
	})

	c.Start()
	defer c.Stop()
}

func SkipIfStillRunning ¶

func SkipIfStillRunning(logger Logger) JobWrapper

SkipIfStillRunning skips an invocation of the Job if a previous invocation is still running. It logs skips to the given logger at Info level.

The returned wrapper implements JobWithContext, propagating the incoming context to the inner job if it also implements JobWithContext.

func Timeout ¶ added in v0.6.0

func Timeout(logger Logger, timeout time.Duration, opts ...TimeoutOption) JobWrapper

Timeout wraps a job with a timeout. If the job takes longer than the given duration, the wrapper returns and logs an error, but the underlying job goroutine continues running until completion.

⚠️ IMPORTANT: Abandonment Model ¶

This wrapper implements an "abandonment model" - when a timeout occurs, the wrapper returns but the job's goroutine is NOT canceled. The job will continue executing in the background until it naturally completes. This means:

• Resources held by the job will not be released until completion
• Side effects will still occur even after timeout
• Multiple abandoned goroutines can accumulate if jobs consistently timeout

Goroutine Accumulation Risk ¶

If a job consistently takes longer than its schedule interval, abandoned goroutines will accumulate:

// DANGER: This pattern causes goroutine accumulation!
c.AddFunc("@every 1s", func() {
    time.Sleep(5 * time.Second) // Takes 5x longer than schedule
})
// With Timeout(2s), a new abandoned goroutine is created every second

Tracking Abandoned Goroutines ¶

Use WithTimeoutCallback to track timeout events for metrics and alerting:

cron.Timeout(logger, 5*time.Minute,
    cron.WithTimeoutCallback(func(timeout time.Duration) {
        abandonedGoroutines.Inc() // Prometheus counter
    }),
)

Recommended Alternatives ¶

For jobs that need true cancellation support, use TimeoutWithContext with jobs that implement JobWithContext:

c := cron.New(cron.WithChain(
    cron.TimeoutWithContext(logger, 5*time.Minute),
))
c.AddJob("@every 1h", cron.FuncJobWithContext(func(ctx context.Context) {
    select {
    case <-ctx.Done():
        return // Timeout - clean up and exit
    case <-doWork():
        // Work completed
    }
}))

To prevent accumulation without context support, combine with SkipIfStillRunning:

c := cron.New(cron.WithChain(
    cron.Recover(logger),
    cron.Timeout(logger, 5*time.Minute),
    cron.SkipIfStillRunning(logger), // Prevents overlapping executions
))

A timeout of zero or negative disables the timeout and returns the job unchanged.

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	logger := cron.DefaultLogger

	c := cron.New(cron.WithChain(
		// Jobs that exceed 30 seconds will be "abandoned" (wrapper returns,
		// but the goroutine keeps running until the job completes naturally)
		cron.Timeout(logger, 30*time.Second),
		// Recover panics from timed-out jobs
		cron.Recover(logger),
	))

	c.AddFunc("@hourly", func() {
		// This job may run longer than 30 seconds.
		// If it does, the timeout wrapper will return early and log an error,
		// but this goroutine continues until completion.
		fmt.Println("Starting long job")
		time.Sleep(45 * time.Second) // Exceeds timeout
		fmt.Println("Job completed (even after timeout)")
	})

	c.Start()
	defer c.Stop()
}

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	// CancellableWorker demonstrates a job that can be cleanly canceled
	type CancellableWorker struct {
		cancel chan struct{}
		done   chan struct{}
	}

	worker := &CancellableWorker{
		cancel: make(chan struct{}),
		done:   make(chan struct{}),
	}

	c := cron.New()

	// Wrap the worker in a FuncJob
	c.Schedule(cron.Every(time.Minute), cron.FuncJob(func() {
		defer close(worker.done)
		for i := 0; i < 100; i++ {
			select {
			case <-worker.cancel:
				fmt.Println("Job canceled cleanly")
				return
			default:
				// Do a small chunk of work
				time.Sleep(100 * time.Millisecond)
			}
		}
		fmt.Println("Job completed normally")
	}))

	c.Start()

	// Later, to cancel the job:
	// close(worker.cancel)
	// <-worker.done  // Wait for clean shutdown

	defer c.Stop()
}

package main

import (
	"context"
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	// ContextAwareJob wraps job execution with context-based cancellation.
	// This pattern is recommended when jobs make external calls (HTTP, DB, etc.)
	// that accept context for cancellation.
	type ContextAwareJob struct {
		ctx    context.Context
		cancel context.CancelFunc
	}

	// Create a job with its own cancellation context
	ctx, cancel := context.WithCancel(context.Background())
	job := &ContextAwareJob{ctx: ctx, cancel: cancel}

	c := cron.New()

	c.Schedule(cron.Every(time.Minute), cron.FuncJob(func() {
		// Create a timeout context for this execution
		execCtx, execCancel := context.WithTimeout(job.ctx, 30*time.Second)
		defer execCancel()

		// Use NewTimer instead of time.After to avoid timer leak on early return
		workTimer := time.NewTimer(10 * time.Second)
		defer workTimer.Stop()

		// Simulate work that respects context cancellation
		select {
		case <-execCtx.Done():
			if execCtx.Err() == context.DeadlineExceeded {
				fmt.Println("Job timed out")
			} else {
				fmt.Println("Job canceled")
			}
			return
		case <-workTimer.C:
			// Simulated work completed
			fmt.Println("Job completed successfully")
		}
	}))

	c.Start()

	// To gracefully shutdown:
	// job.cancel()  // Signal cancellation to all running jobs
	// c.Stop()      // Stop scheduling new jobs

	defer c.Stop()
}

func TimeoutWithContext ¶ added in v0.6.0

func TimeoutWithContext(logger Logger, timeout time.Duration, opts ...TimeoutOption) JobWrapper

TimeoutWithContext wraps a job with a timeout that supports true cancellation. Unlike Timeout, this wrapper passes a context with deadline to jobs that implement JobWithContext, allowing them to check for cancellation and clean up gracefully.

When the timeout expires:

• Jobs implementing JobWithContext receive a canceled context and can stop gracefully
• Jobs implementing only Job continue running (same as Timeout wrapper)

Use WithTimeoutCallback to track timeout/abandonment events:

cron.TimeoutWithContext(logger, 5*time.Minute,
    cron.WithTimeoutCallback(func(timeout time.Duration) {
        timeoutCounter.Inc()
    }),
)

A timeout of zero or negative disables the timeout and returns the job unchanged.

Example:

c := cron.New(cron.WithChain(
    cron.TimeoutWithContext(cron.DefaultLogger, 5*time.Minute),
))

c.AddJob("@every 1h", cron.FuncJobWithContext(func(ctx context.Context) {
    // This job will receive the timeout context
    select {
    case <-ctx.Done():
        // Timeout or shutdown - clean up and return
        return
    case <-doWork():
        // Work completed
    }
}))

package main

import (
	"context"
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	logger := cron.DefaultLogger

	c := cron.New(cron.WithChain(
		// Outermost: catches any panics
		cron.Recover(logger),
		// Jobs have 5 minutes to complete; context is canceled on timeout
		cron.TimeoutWithContext(logger, 5*time.Minute),
	))

	// Use FuncJobWithContext for jobs that need context support
	c.AddJob("@hourly", cron.FuncJobWithContext(func(ctx context.Context) {
		// Create a timer for simulated work
		workTimer := time.NewTimer(10 * time.Minute)
		defer workTimer.Stop()

		select {
		case <-ctx.Done():
			// Context canceled - clean up and exit gracefully
			fmt.Println("Job canceled:", ctx.Err())
			return
		case <-workTimer.C:
			// Work completed normally
			fmt.Println("Job completed")
		}
	}))

	c.Start()
	defer c.Stop()
}

func PrintfLogger ¶

func PrintfLogger(l interface{ Printf(string, ...any) }) Logger

PrintfLogger wraps a Printf-based logger (such as the standard library "log") into an implementation of the Logger interface which logs errors only.

func VerbosePrintfLogger ¶

func VerbosePrintfLogger(l interface{ Printf(string, ...any) }) Logger

VerbosePrintfLogger wraps a Printf-based logger (such as the standard library "log") into an implementation of the Logger interface which logs everything.

package main

import (
	"fmt"
	"log"

	cron "github.com/netresearch/go-cron"
)

func main() {
	logger := cron.VerbosePrintfLogger(log.Default())

	c := cron.New(cron.WithLogger(logger))

	c.AddFunc("@hourly", func() {
		fmt.Println("hourly job")
	})

	c.Start()
	defer c.Stop()
}

func WithCapacity ¶ added in v0.10.0

func WithCapacity(n int) Option

WithCapacity pre-allocates internal data structures for the expected number of entries. This reduces map rehashing and slice growth during bulk additions, improving performance when adding many jobs at startup.

Pre-allocates:

• entryIndex map with capacity n (O(1) lookup by ID)
• nameIndex map with capacity n (O(1) lookup by name)
• entries heap slice with capacity n

For applications adding fewer than 100 jobs, the default allocation is sufficient. Use this option when bulk-loading hundreds or thousands of jobs.

A capacity of 0 or negative has no effect (uses default allocation).

Example:

// Expect ~1000 jobs at startup
c := cron.New(cron.WithCapacity(1000))
for _, job := range jobs {
    c.AddFunc(job.Schedule, job.Func)
}

func WithChain ¶

func WithChain(wrappers ...JobWrapper) Option

WithChain specifies Job wrappers to apply to all jobs added to this cron. Refer to the Chain* functions in this package for provided wrappers.

package main

import (
	"fmt"

	cron "github.com/netresearch/go-cron"
)

func main() {
	// Create cron with job wrappers applied to all jobs
	c := cron.New(
		cron.WithChain(
			// Recover from panics and log them
			cron.Recover(cron.DefaultLogger),
			// Skip job execution if the previous run hasn't completed
			cron.SkipIfStillRunning(cron.DefaultLogger),
		),
	)

	c.AddFunc("* * * * *", func() {
		fmt.Println("This job is protected by Recover and SkipIfStillRunning")
	})

	c.Start()
	defer c.Stop()
}

func WithClock ¶ added in v0.6.0

func WithClock(clock Clock) Option

WithClock uses the provided Clock implementation instead of the default RealClock. This is useful for testing time-dependent behavior without waiting.

The Clock interface provides both Now() for current time and NewTimer() for creating timers, enabling fully deterministic testing of scheduled jobs.

Example usage:

fakeClock := cron.NewFakeClock(time.Date(2024, 1, 1, 12, 0, 0, 0, time.UTC))
c := cron.New(cron.WithClock(fakeClock))
// ... add jobs ...
c.Start()
fakeClock.Advance(time.Hour) // Advance time and trigger jobs deterministically

func WithContext ¶ added in v0.6.0

func WithContext(ctx context.Context) Option

WithContext sets the base context for all job executions. When Stop() is called, this context is canceled, signaling all running jobs that implement JobWithContext to shut down gracefully.

If not specified, context.Background() is used as the base context.

Use cases:

• Propagate application-wide cancellation to cron jobs
• Attach tracing context or correlation IDs to all jobs
• Integrate with application lifecycle management

Example:

// Create cron with application context
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
c := cron.New(cron.WithContext(ctx))

// Jobs implementing JobWithContext will receive this context
c.AddJob("@every 1m", cron.FuncJobWithContext(func(ctx context.Context) {
    select {
    case <-ctx.Done():
        return // Application shutting down
    default:
        // Do work
    }
}))

func WithLocation ¶

func WithLocation(loc *time.Location) Option

WithLocation overrides the timezone of the cron instance.

func WithLogger ¶

func WithLogger(logger Logger) Option

WithLogger uses the provided logger.

func WithMaxEntries ¶ added in v0.6.0

func WithMaxEntries(maxEntries int) Option

WithMaxEntries limits the maximum number of entries that can be added to the Cron. When the limit is reached:

• AddFunc and AddJob return ErrMaxEntriesReached
• Schedule returns 0 (invalid EntryID) and logs an error

A limit of 0 (the default) means unlimited entries.

This option provides protection against memory exhaustion from excessive entry additions, which could occur from buggy code or untrusted input.

Note: When the cron is running, the limit enforcement is approximate due to concurrent entry additions. The actual count may briefly exceed the limit.

Example usage:

c := cron.New(cron.WithMaxEntries(1000))
for i := 0; i < 2000; i++ {
    _, err := c.AddFunc("* * * * *", func() {})
    if errors.Is(err, cron.ErrMaxEntriesReached) {
        log.Println("Entry limit reached")
        break
    }
}

package main

import (
	"fmt"

	cron "github.com/netresearch/go-cron"
)

func main() {
	c := cron.New(cron.WithMaxEntries(2))

	// Add first job - succeeds
	_, err := c.AddFunc("@hourly", func() { fmt.Println("Job 1") })
	if err != nil {
		fmt.Println("Job 1 failed:", err)
	}

	// Add second job - succeeds
	_, err = c.AddFunc("@hourly", func() { fmt.Println("Job 2") })
	if err != nil {
		fmt.Println("Job 2 failed:", err)
	}

	// Add third job - fails (limit reached)
	_, err = c.AddFunc("@hourly", func() { fmt.Println("Job 3") })
	if err != nil {
		fmt.Println("Job 3 failed:", err)
	}

	fmt.Printf("Total jobs: %d\n", len(c.Entries()))
}

Output:

Job 3 failed: cron: max entries limit reached
Total jobs: 2

func WithMaxSearchYears ¶ added in v0.6.0

func WithMaxSearchYears(years int) Option

WithMaxSearchYears configures the maximum years into the future that schedule matching will search before giving up. This prevents infinite loops for unsatisfiable schedules (e.g., Feb 30).

The default is 5 years. Values <= 0 will use the default.

Use cases:

• Shorter limits for faster failure detection: WithMaxSearchYears(1)
• Longer limits for rare schedules: WithMaxSearchYears(10)

Note: This option replaces the current parser. If you need custom parser options along with a custom max search years, use WithParser with a manually configured parser:

p := cron.NewParser(cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow | cron.Descriptor).
    WithMaxSearchYears(10)
c := cron.New(cron.WithParser(p))

Example:

// Allow searching up to 10 years for rare schedules
c := cron.New(cron.WithMaxSearchYears(10))
c.AddFunc("0 0 13 * 5", func() { ... }) // Friday the 13th

func WithMinEveryInterval ¶ added in v0.6.0

func WithMinEveryInterval(d time.Duration) Option

WithMinEveryInterval configures the minimum interval allowed for @every expressions. This allows overriding the default 1-second minimum.

Use cases:

• Sub-second intervals for testing: WithMinEveryInterval(0) or WithMinEveryInterval(100*time.Millisecond)
• Enforce longer minimums for rate limiting: WithMinEveryInterval(time.Minute)

The interval affects:

• Parsing of "@every <duration>" expressions
• The EveryWithMin function when called via the parser

Note: This option replaces the current parser. If you need custom parser options along with a custom minimum interval, use WithParser with a manually configured parser:

p := cron.NewParser(cron.Second | cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow | cron.Descriptor).
    WithMinEveryInterval(100 * time.Millisecond)
c := cron.New(cron.WithParser(p))

Example:

// Allow sub-second intervals (useful for testing)
c := cron.New(cron.WithMinEveryInterval(0))
c.AddFunc("@every 100ms", func() { ... })

// Enforce minimum 1-minute intervals
c := cron.New(cron.WithMinEveryInterval(time.Minute))
c.AddFunc("@every 30s", func() { ... }) // Error: must be at least 1 minute

package main

import (
	"fmt"
	"log"

	cron "github.com/netresearch/go-cron"
)

func main() {
	// Allow sub-second @every intervals (useful for testing)
	c := cron.New(cron.WithMinEveryInterval(0))

	_, err := c.AddFunc("@every 100ms", func() {
		fmt.Println("Running every 100ms")
	})
	if err != nil {
		log.Fatal(err)
	}

	// With default settings, sub-second would fail:
	// c := cron.New() // default minimum is 1 second
	// _, err := c.AddFunc("@every 100ms", ...) // returns error

	c.Start()
	defer c.Stop()
}

package main

import (
	"fmt"
	"log"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	// Enforce minimum 1-minute intervals
	c := cron.New(cron.WithMinEveryInterval(time.Minute))

	// This will fail because 30s < 1m minimum
	_, err := c.AddFunc("@every 30s", func() {
		fmt.Println("This won't be added")
	})
	if err != nil {
		fmt.Println("Error:", err)
	}

	// This will succeed because 2m >= 1m minimum
	_, err = c.AddFunc("@every 2m", func() {
		fmt.Println("Running every 2 minutes")
	})
	if err != nil {
		log.Fatal(err)
	}

	c.Start()
	defer c.Stop()
}

Output:

Error: @every duration must be at least 1m0s: "@every 30s"

func WithObservability ¶ added in v0.6.0

func WithObservability(hooks ObservabilityHooks) Option

WithObservability configures observability hooks for monitoring cron operations. Hooks are called asynchronously in separate goroutines to prevent slow callbacks from blocking the scheduler. This means callback execution order is not guaranteed.

All hook callbacks are optional; nil callbacks are safely ignored.

Example with Prometheus metrics:

hooks := cron.ObservabilityHooks{
    OnJobStart: func(id cron.EntryID, name string, scheduled time.Time) {
        jobsStarted.WithLabelValues(name).Inc()
    },
    OnJobComplete: func(id cron.EntryID, name string, dur time.Duration, recovered any) {
        jobDuration.WithLabelValues(name).Observe(dur.Seconds())
        if recovered != nil {
            jobPanics.WithLabelValues(name).Inc()
        }
    },
}
c := cron.New(cron.WithObservability(hooks))

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	var jobsStarted, jobsCompleted int

	hooks := cron.ObservabilityHooks{
		OnJobStart: func(id cron.EntryID, name string, scheduled time.Time) {
			// In production: prometheus.Counter.Inc()
			jobsStarted++
		},
		OnJobComplete: func(id cron.EntryID, name string, duration time.Duration, recovered any) {
			// In production: prometheus.Histogram.Observe(duration.Seconds())
			jobsCompleted++
		},
		OnSchedule: func(id cron.EntryID, name string, nextRun time.Time) {
			// In production: prometheus.Gauge.Set(nextRun.Unix())
		},
	}

	c := cron.New(cron.WithObservability(hooks))

	c.AddFunc("@hourly", func() {
		// Job logic here
	})

	c.Start()
	c.Stop()

	fmt.Println("Hooks configured successfully")
}

Output:

Hooks configured successfully

func WithParser ¶

func WithParser(p ScheduleParser) Option

WithParser overrides the parser used for interpreting job schedules.

func WithSecondOptional ¶ added in v0.7.0

func WithSecondOptional() Option

WithSecondOptional overrides the parser used for interpreting job schedules to accept an optional seconds field as the first one. When provided, expressions can have either 5 fields (standard) or 6 fields (with seconds). If 5 fields are given, the seconds field defaults to 0.

This is useful when you want to support both standard 5-field cron expressions and extended 6-field expressions with seconds precision in the same cron instance.

Examples:

c := cron.New(cron.WithSecondOptional())
c.AddFunc("* * * * *", job)        // 5 fields: runs every minute at :00 seconds
c.AddFunc("30 * * * * *", job)     // 6 fields: runs every minute at :30 seconds
c.AddFunc("*/10 * * * * *", job)   // 6 fields: runs every 10 seconds

func WithSeconds ¶

func WithSeconds() Option

WithSeconds overrides the parser used for interpreting job schedules to include a seconds field as the first one.

func WithWorkflowRetention ¶ added in v0.12.0

func WithWorkflowRetention(n int) Option

WithWorkflowRetention sets the maximum number of completed workflow executions to retain for query via WorkflowStatus/ActiveWorkflows. Default is 100. Set to 0 for unlimited retention (not recommended for long-running services).

func FullParser ¶ added in v0.8.0

func FullParser() Parser

FullParser returns a parser that accepts all cron syntax variants including optional seconds, year field, descriptors, hash expressions, and extended day-of-month/day-of-week syntax.

This parser supports:

• Standard 5-field cron: minute, hour, day-of-month, month, day-of-week
• Optional seconds prefix (6 fields): second, minute, hour, dom, month, dow
• Optional year suffix (7 fields with seconds, 6 without)
• Descriptors: @yearly, @monthly, @weekly, @daily, @hourly, @every <duration>
• Hash expressions: H for load-distributed scheduling
• Extended syntax: FRI#3 (3rd Friday), MON#L (last Monday), L (last day), 15W (nearest weekday)

Example:

c := cron.New(cron.WithParser(cron.FullParser()))
c.AddFunc("0 30 14 25 12 2025", myFunc) // Run at 14:30 on Dec 25, 2025
c.AddFunc("0 0 0 1 1 * 2030", myFunc)   // Run at midnight on Jan 1, 2030

func MustNewParser ¶ added in v0.6.0

func MustNewParser(options ParseOption) Parser

MustNewParser is like TryNewParser but panics if the options are invalid. This follows the Go convention of Must* functions for cases where failure indicates a programming error rather than a runtime condition.

Use MustNewParser when:

• Parser options are hardcoded constants
• Invalid configuration is a bug that should fail fast

Use TryNewParser when:

• Parser options come from config files, environment, or user input
• You want to handle configuration errors gracefully

Note: In v2.0, NewParser will return (Parser, error) and MustNewParser will be the only panicking variant. Using MustNewParser now ensures forward compatibility with v2.0.

Example:

// Panics if options are invalid (hardcoded, so invalid = bug)
var parser = cron.MustNewParser(cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow)

func StandardParser ¶ added in v0.6.0

func StandardParser() Parser

StandardParser returns a copy of the standard parser used by ParseStandard. This can be used as a base for creating custom parsers with modified settings.

Example:

// Create parser allowing sub-second @every intervals
p := StandardParser().WithMinEveryInterval(0)
c := cron.New(cron.WithParser(p))

func TryNewParser ¶ added in v0.6.0

func TryNewParser(options ParseOption) (Parser, error)

TryNewParser creates a Parser with custom options, returning an error if the configuration is invalid. This is the safe alternative to NewParser for cases where parser options come from runtime configuration rather than hardcoded values.

Use TryNewParser when:

• Parser options come from config files, environment variables, or user input
• You want to handle configuration errors gracefully

Use NewParser when:

• Parser options are hardcoded constants (invalid config = bug)
• You want to fail fast during initialization

Returns ErrNoFields if no fields or Descriptor are configured. Returns ErrMultipleOptionals if more than one optional field is configured.

Example:

// Safe parsing from config
opts := loadParserOptionsFromConfig()
parser, err := TryNewParser(opts)
if err != nil {
    return fmt.Errorf("invalid parser config: %w", err)
}

func WithLogLevel ¶ added in v0.6.0

func WithLogLevel(level LogLevel) RecoverOption

WithLogLevel sets the log level for recovered panics. Default is LogLevelError. Use LogLevelInfo to reduce noise when combined with retry wrappers like RetryWithBackoff.

Example:

cron.Recover(logger, cron.WithLogLevel(cron.LogLevelInfo))

func WithRetryCallback ¶ added in v0.12.0

func WithRetryCallback(fn func(RetryAttempt)) RetryOption

WithRetryCallback sets a callback invoked after each attempt (including the initial execution). This enables external monitoring and metrics collection for retry behavior.

Example with Prometheus:

RetryWithBackoff(logger, 3, time.Second, time.Minute, 2.0,
    cron.WithRetryCallback(func(a cron.RetryAttempt) {
        retryCounter.WithLabelValues(fmt.Sprint(a.Attempt)).Inc()
        if !a.WillRetry && a.Err != nil {
            retryExhausted.Inc()
        }
    }),
)

func ParseStandard ¶

func ParseStandard(standardSpec string) (Schedule, error)

ParseStandard returns a new crontab schedule representing the given standardSpec (https://en.wikipedia.org/wiki/Cron). It requires 5 entries representing: minute, hour, day of month, month and day of week, in that order. It returns a descriptive error if the spec is not valid.

It accepts

• Standard crontab specs, e.g. "* * * * ?"
• Descriptors, e.g. "@midnight", "@every 1h30m"

package main

import (
	"fmt"
	"log"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	schedule, err := cron.ParseStandard("0 9 * * MON-FRI")
	if err != nil {
		log.Fatal(err)
	}

	// Get the next scheduled time
	now := time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC) // Wednesday
	next := schedule.Next(now)
	fmt.Printf("Next run: %s\n", next.Format("Mon 15:04"))
}

Output:

Next run: Wed 09:00

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	// Both "0" and "7" represent Sunday
	schedSun0, _ := cron.ParseStandard("0 9 * * 0") // Sunday as 0
	schedSun7, _ := cron.ParseStandard("0 9 * * 7") // Sunday as 7

	// Start from Saturday
	saturday := time.Date(2025, 1, 4, 0, 0, 0, 0, time.UTC) // Saturday

	// Both find the same Sunday
	next0 := schedSun0.Next(saturday)
	next7 := schedSun7.Next(saturday)

	fmt.Printf("Using 0: %s\n", next0.Format("Mon Jan 2"))
	fmt.Printf("Using 7: %s\n", next7.Format("Mon Jan 2"))
	fmt.Printf("Same day: %v\n", next0.Equal(next7))
}

Output:

Using 0: Sun Jan 5
Using 7: Sun Jan 5
Same day: true

package main

import (
	"fmt"
	"time"

	cron "github.com/netresearch/go-cron"
)

func main() {
	// "5-7" covers Friday(5), Saturday(6), Sunday(7->0)
	schedule, _ := cron.ParseStandard("0 10 * * 5-7")

	// Start from Wednesday
	wednesday := time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)

	next := schedule.Next(wednesday)
	fmt.Printf("Next after Wed: %s\n", next.Format("Mon"))

	next = schedule.Next(next)
	fmt.Printf("Then: %s\n", next.Format("Mon"))

	next = schedule.Next(next)
	fmt.Printf("Then: %s\n", next.Format("Mon"))
}

Output:

Next after Wed: Fri
Then: Sat
Then: Sun

func NewSlogLogger ¶ added in v0.6.0

func NewSlogLogger(l *slog.Logger) *SlogLogger

NewSlogLogger creates a Logger that writes to the given slog.Logger. If l is nil, slog.Default() is used.

func AnalyzeSpec ¶ added in v0.7.0

func AnalyzeSpec(spec string, options ...ParseOption) SpecAnalysis

AnalyzeSpec provides detailed analysis of a cron expression. It returns a SpecAnalysis struct containing validation status, next run time, parsed fields, and other metadata.

This is useful for:

• Configuration validation with detailed feedback
• UI previews showing when a job will run
• Debugging cron expressions
• Import/migration validation

Example:

result := cron.AnalyzeSpec("0 9 * * MON-FRI")
if !result.Valid {
    log.Printf("Invalid: %v", result.Error)
} else {
    log.Printf("Next run: %v", result.NextRun)
    log.Printf("Fields: %v", result.Fields)
}

func AnalyzeSpecWithHash ¶ added in v0.7.0

func AnalyzeSpecWithHash(spec string, options ParseOption, hashSeed string) SpecAnalysis

AnalyzeSpecWithHash analyzes a cron expression containing H hash expressions. This is like AnalyzeSpec but takes a hash seed for resolving H expressions. The seed should be a unique identifier (like a job name) that produces deterministic, distributed scheduling times.

Example:

result := AnalyzeSpecWithHash("H H * * *", Minute|Hour|Dom|Month|Dow|Hash, "my-job")
if result.Valid {
    log.Printf("Next run: %v", result.NextRun)
}

func WithTimeoutCallback ¶ added in v0.6.0

func WithTimeoutCallback(fn func(timeout time.Duration)) TimeoutOption

WithTimeoutCallback sets a callback invoked when a job times out and is abandoned. This is useful for metrics collection and alerting on goroutine accumulation.

Example with Prometheus:

abandonedGoroutines := prometheus.NewCounter(prometheus.CounterOpts{
    Name: "cron_abandoned_goroutines_total",
    Help: "Number of job goroutines abandoned due to timeout",
})

c := cron.New(cron.WithChain(
    cron.Timeout(logger, 5*time.Minute,
        cron.WithTimeoutCallback(func(timeout time.Duration) {
            abandonedGoroutines.Inc()
        }),
    ),
))

func NewWorkflow ¶ added in v0.12.0

func NewWorkflow(name string) *Workflow

NewWorkflow creates a new Workflow with the given name.