Chrono

go get oss.nandlabs.io/golly

package main

import (
    "context"
    "fmt"
    "time"

    "oss.nandlabs.io/golly/chrono"
)

func main() {
    // Create a new scheduler
    s := chrono.New()

    // Add a cron job — runs every 5 minutes
    s.AddCronJob("cleanup", "Temp Cleanup", func(ctx context.Context) error {
        fmt.Println("Cleaning up temporary files...")
        return nil
    }, "*/5 * * * *")

    // Add an interval job — runs every 30 seconds
    s.AddIntervalJob("heartbeat", "Heartbeat", func(ctx context.Context) error {
        fmt.Println("Sending heartbeat...")
        return nil
    }, 30*time.Second)

    // Add a one-shot job — runs once after 5 seconds
    s.AddOneShotJob("init", "Initialize Cache", func(ctx context.Context) error {
        fmt.Println("Initializing cache...")
        return nil
    }, 5*time.Second)

    // Start the scheduler
    s.Start()

    // ... application runs ...

    // Stop gracefully
    s.Stop()
}

// Set a timeout for job execution
chrono.WithTimeout(30 * time.Second)

// Set maximum retry attempts on failure
chrono.WithMaxRetries(3)

// Register a success callback
chrono.WithOnSuccess(func(jobID string) {
    log.Printf("Job %s completed successfully", jobID)
})

// Register an error callback
chrono.WithOnError(func(jobID string, err error) {
    log.Printf("Job %s failed: %v", jobID, err)
})

s.AddCronJob("report", "Daily Report", generateReport, "0 8 * * 1-5",
    chrono.WithTimeout(5*time.Minute),
    chrono.WithMaxRetries(2),
    chrono.WithOnSuccess(func(id string) {
        log.Println("Report generated successfully")
    }),
    chrono.WithOnError(func(id string, err error) {
        alert.Send("Report generation failed: " + err.Error())
    }),
)

// Pause a job — it will not be executed until resumed
s.PauseJob("cleanup")

// Resume a paused job — next run time is recomputed from now
s.ResumeJob("cleanup")

// Remove a job entirely
s.RemoveJob("cleanup")

// Get job information
info, err := s.GetJob("heartbeat")
if err == nil {
    fmt.Printf("Status: %s, Runs: %d, Errors: %d\n",
        info.Status, info.RunCount, info.ErrorCount)
}

// List all jobs
for _, job := range s.ListJobs() {
    fmt.Printf("%-15s %-12s Next: %s\n", job.ID, job.Status, job.NextRun)
}

s := chrono.New(
    chrono.WithStoragePollInterval(15 * time.Second),
    chrono.WithInstanceID("worker-1"),
    chrono.WithLockTTL(10 * time.Minute),
)

type Storage interface {
    // SaveJob persists a job record (upsert).
    SaveJob(ctx context.Context, record *JobRecord) error

    // GetJob retrieves a job record by ID.
    // Returns ErrJobNotFound if the job does not exist.
    GetJob(ctx context.Context, id string) (*JobRecord, error)

    // DeleteJob removes a job record by ID.
    // Returns ErrJobNotFound if the job does not exist.
    DeleteJob(ctx context.Context, id string) error

    // ListJobs returns all stored job records.
    ListJobs(ctx context.Context) ([]*JobRecord, error)

    // GetDueJobs returns jobs where NextRun <= now, not paused, and NextRun is non-zero.
    GetDueJobs(ctx context.Context, now time.Time) ([]*JobRecord, error)

    // AcquireLock attempts to acquire a distributed execution lock for a job.
    // Returns true if the lock was acquired, false if held by another owner.
    // The lock auto-expires after the TTL to handle crashed instances.
    AcquireLock(ctx context.Context, jobID string, ownerID string,
        ttl time.Duration) (bool, error)

    // ReleaseLock releases the execution lock. Only the lock owner can release it.
    ReleaseLock(ctx context.Context, jobID string, ownerID string) error

    // Close releases any resources held by the storage.
    Close() error
}

// Explicitly using in-memory storage (this is the default)
s := chrono.New(chrono.WithStorage(chrono.NewInMemoryStorage()))

// Equivalent — in-memory is used when no storage is specified
s := chrono.New()

// YAML format
store, err := chrono.NewFileStorage("/var/lib/myapp/chrono.yaml")
if err != nil {
    log.Fatal(err)
}
s := chrono.New(chrono.WithStorage(store))

// JSON format
store, err := chrono.NewFileStorage("/var/lib/myapp/chrono.json")

// XML format
store, err := chrono.NewFileStorage("/var/lib/myapp/chrono.xml")

package mystore

import (
    "context"
    "time"

    "oss.nandlabs.io/golly/chrono"
)

// RedisStorage is an example custom Storage backed by Redis.
type RedisStorage struct {
    // your Redis client, connection pool, etc.
}

// NewRedisStorage creates a new Redis-backed storage.
func NewRedisStorage(addr string) (*RedisStorage, error) {
    // Initialize connection...
    return &RedisStorage{}, nil
}

// SaveJob persists a job record (upsert).
// Use a Redis hash or serialized JSON value keyed by job ID.
func (r *RedisStorage) SaveJob(ctx context.Context,
    record *chrono.JobRecord) error {
    // SET chrono:job:<id> <serialized record>
    return nil
}

// GetJob retrieves a job record by ID.
// Return chrono.ErrJobNotFound if the key does not exist.
func (r *RedisStorage) GetJob(ctx context.Context,
    id string) (*chrono.JobRecord, error) {
    // GET chrono:job:<id>
    // if not found: return nil, chrono.ErrJobNotFound
    return nil, nil
}

// DeleteJob removes a job record by ID.
// Return chrono.ErrJobNotFound if the key does not exist.
func (r *RedisStorage) DeleteJob(ctx context.Context, id string) error {
    // DEL chrono:job:<id>
    return nil
}

// ListJobs returns all stored job records.
// Use SCAN or maintain a separate set of job IDs for efficient listing.
func (r *RedisStorage) ListJobs(ctx context.Context) ([]*chrono.JobRecord,
    error) {
    // SCAN for chrono:job:* keys, deserialize each
    return nil, nil
}

// GetDueJobs returns job records that are due for execution.
// Use a sorted set with NextRun as the score for efficient range queries:
//   ZRANGEBYSCORE chrono:due 0 <now_unix>
// Filter out paused jobs and zero NextRun values.
func (r *RedisStorage) GetDueJobs(ctx context.Context,
    now time.Time) ([]*chrono.JobRecord, error) {
    return nil, nil
}

// AcquireLock attempts to acquire a distributed lock for the given job.
// Use SET NX EX (Redis single-key lock) or Redlock for stronger guarantees.
// Return true if the lock was acquired, false if held by another owner.
// Re-acquiring by the same owner should extend the TTL.
func (r *RedisStorage) AcquireLock(ctx context.Context,
    jobID, ownerID string, ttl time.Duration) (bool, error) {
    // SET chrono:lock:<jobID> <ownerID> NX EX <ttl_seconds>
    return false, nil
}

// ReleaseLock releases the execution lock for the given job.
// Only release if the current owner matches (use a Lua script for atomicity):
//   if redis.call("get", key) == ownerID then redis.call("del", key) end
func (r *RedisStorage) ReleaseLock(ctx context.Context,
    jobID, ownerID string) error {
    return nil
}

// Close releases any resources (close the Redis connection pool).
func (r *RedisStorage) Close() error {
    return nil
}

store, err := mystore.NewRedisStorage("localhost:6379")
if err != nil {
    log.Fatal(err)
}
defer store.Close()

s := chrono.New(
    chrono.WithStorage(store),
    chrono.WithInstanceID("worker-1"),
    chrono.WithLockTTL(10 * time.Minute),
    chrono.WithStoragePollInterval(10 * time.Second),
)

// Instance 1
s1 := chrono.New(
    chrono.WithStorage(sharedStore),
    chrono.WithInstanceID("instance-1"),
)
s1.AddCronJob("cleanup", "Cleanup", cleanupFunc, "*/5 * * * *")
s1.Start()

// Instance 2 (same jobs registered, storage coordinates execution)
s2 := chrono.New(
    chrono.WithStorage(sharedStore),
    chrono.WithInstanceID("instance-2"),
)
s2.AddCronJob("cleanup", "Cleanup", cleanupFunc, "*/5 * * * *")
s2.Start()

// Cron schedule
cron, _ := chrono.NewCronSchedule("*/10 * * * *")

// Interval schedule
interval, _ := chrono.NewIntervalSchedule(5 * time.Minute)

// One-shot schedule (by delay from now)
oneshot, _ := chrono.NewOneShotSchedule(10 * time.Second)

// One-shot schedule (at a specific time)
at := chrono.NewOneShotScheduleAt(
    time.Date(2026, 12, 31, 23, 59, 0, 0, time.UTC),
)

// Add with any schedule
s.AddJob("my-job", "My Job", myFunc, cron)

err := s.AddCronJob("job1", "Job", fn, "bad cron")
if errors.Is(err, chrono.ErrInvalidCronExpr) {
    log.Println("Invalid cron expression")
}