Simple Cron library for go that can execute closures or functions at varying intervals, from once a second to once a year on a specific date and time. Primarily for web applications and long running daemons

Cron.go
=======

This is a simple library to handle scheduled tasks. Tasks can be run in a
minimum delay of once a second--for which Cron isn't actually designed.
Comparisons are fast and efficient and take place in a goroutine; matched
jobs are also executed in goroutines.

For instance, you can use the following in your web application that uses
MySQL:

    func init() {
      cron.NewWeeklyJob(1, 23, 59, 59, func (time.Time) {
        _, err := conn.Query("OPTIMIZE TABLE mytable;")
        if(err != nil) { println(err) }
      })
    }

License
-------

Copyright 2011 Robert Kosek <thewickedflea@gmail.com>. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are
permitted provided that the following conditions are met:

   1. Redistributions of source code must retain the above copyright notice, this list of
      conditions and the following disclaimer.

   2. Redistributions in binary form must reproduce the above copyright notice, this list
      of conditions and the following disclaimer in the documentation and/or other materials
      provided with the distribution.

THIS SOFTWARE IS PROVIDED BY ROBERT KOSEK ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ROBERT KOSEK OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those of the
authors and should not be interpreted as representing official policies, either expressed
or implied, of Robert Kosek.


go-cron

Smart and featureful cron job scheduler with job queuing and live monitoring built in

# ![](https://raw.githubusercontent.com/bamzi/jobrunner/master/views/runclock.jpg) JobRunner

JobRunner is framework for performing work asynchronously, outside of the request flow. It comes with cron to schedule and queue job functions for processing at specified time. 

It includes a live monitoring of current schedule and state of active jobs that can be outputed as JSON or Html template. 

## Install

`go get github.com/bamzi/jobrunner`

### Setup

```go
package main

import "github.com/bamzi/jobrunner"

func main() {
    jobrunner.Start() // optional: jobrunner.Start(pool int, concurrent int) (10, 1)
    jobrunner.Schedule("@every 5s", ReminderEmails{})
}

// Job Specific Functions
type ReminderEmails struct {
    // filtered
}

// ReminderEmails.Run() will get triggered automatically.
func (e ReminderEmails) Run() {
    // Queries the DB
    // Sends some email
    fmt.Printf("Every 5 sec send reminder emails \n")
}
```

### Live Monitoring
![](https://raw.githubusercontent.com/bamzi/jobrunner/master/views/jobrunner-html.png)
```go

// Example of GIN micro framework
func main() {
    routes := gin.Default()

    // Resource to return the JSON data
    routes.GET("/jobrunner/json", JobJson)

    // Load template file location relative to the current working directory
    routes.LoadHTMLGlob("../github.com/bamzi/jobrunner/views/Status.html")

    // Returns html page at given endpoint based on the loaded
    // template from above
    routes.GET("/jobrunner/html", JobHtml)

    routes.Run(":8080")
}

func JobJson(c *gin.Context) {
    // returns a map[string]interface{} that can be marshalled as JSON
    c.JSON(200, jobrunner.StatusJson())
}

func JobHtml(c *gin.Context) {
    // Returns the template data pre-parsed
    c.HTML(200, "", jobrunner.StatusPage())

}

```
## WHY?
To reduce our http response latency by 200+%

JobRunner was created to help us process functions unrelated to response without any delays to the http response. GoRoutines would timeout because response has already been processed, closing the instance window all together. 

Instead of creating a separate independent app, we wanted to save time and manageability of our current app by coupling-in the job processing. We did not want to have micro services. It's premature optimization.

If you have a web app or api service backend and want a job processing framework built into your app then JobRunner is for you. Once you hit mass growth and need to scale, you can simply decouple you JobRunners into a dedicated app.

## Use cases
Here are some examples of what we use JobRunner for:

* Send emails to new users after signup
* Sending push notification or emails based on specifics
* ReMarketing Engine - send invites, reminder emails, etc ...
* Clean DB, data or AMZ S3
* Sending Server stats to monitoring apps
* Send data stats at daily or weekly intervals

### Supported Featured
*All jobs are processed outside of the request flow*

* Now: process a job immediately
* In: processing a job one time, after a given time
* Every: process a recurring job after every given time gap
* Schedule: process a job (recurring or otherwise) at a given time


## Compatibility

JobRunner is designed to be framework agnostic. So it will work with pure Go apps as well as any framework written in Go Language. 

*Verified Supported Frameworks*

* Gin
* Echo
* Martini
* Beego
* Revel (JobRunner is modified version of revel's Jobs module)
* ...

**Examples & recipes are coming soon**

## Basics

```go
    jobrunner.Schedule("* */5 * * * *", DoSomething{}) // every 5min do something
    jobrunner.Schedule("@every 1h30m10s", ReminderEmails{})
    jobrunner.Schedule("@midnight", DataStats{}) // every midnight do this..
    jobrunner.Every(16*time.Minute, CleanS3{}) // evey 16 min clean...
    jobrunner.In(10*time.Second, WelcomeEmail{}) // one time job. starts after 10sec
    jobrunner.Now(NowDo{}) // do the job as soon as it's triggered
```
[**More Detailed CRON Specs**](https://github.com/robfig/cron/blob/v2/doc.go)

## Contribute

**Use issues for everything**

- Report problems
- Discuss before sending pull request
- Suggest new features
- Improve/fix documentation

## Credits
- [revel jobs module](https://github.com/revel/modules/tree/master/jobs) - Origin of JobRunner
- [robfig cron v3](https://github.com/robfig/cron/tree/v3) - github.com/robfig/cron/v3
- [contributors](https://github.com/bamzi/jobrunner/graphs/contributors)

### Author 
**Bam Azizi**
Github: [@bamzi](https://github.com/bamzi)
Twitter: [@bamazizi](https://twitter/bamazizi)

#### License
MIT

JobRunner

Job scheduler that supports webhooks, crons and classic scheduling

# Leprechaun

[![Codacy Badge](https://app.codacy.com/project/badge/Grade/b5252a28362743fa8bd94f56e5637c1c)](https://www.codacy.com/gh/kilgaloon/leprechaun/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=kilgaloon/leprechaun&amp;utm_campaign=Badge_Grade)
[![Go Report Card](https://goreportcard.com/badge/github.com/Kilgaloon/Leprechaun)](https://goreportcard.com/report/github.com/Kilgaloon/Leprechaun) [![codecov](https://codecov.io/gh/Kilgaloon/Leprechaun/branch/master/graph/badge.svg)](https://codecov.io/gh/Kilgaloon/Leprechaun)

**Leprechaun** is tool where you can schedule your recurring tasks to be performed over and over.

In **Leprechaun** tasks are **recipes**, lets observe simple recipe file which is written using **YAML** syntax.
  
File is located in recipes directory which can be specified in `configs.ini` configurational file. For all possible settings take a look [here](https://github.com/Kilgaloon/Leprechaun/blob/master/dist/configs/config.ini)

By definition there are 3 types of recipes, the ones that can be scheduled, the others that can be hooked and last ones that use cron pattern for scheduling jobs, they are similiar regarding steps but have some difference in definition

First we will talk about scheduled recipes and they are defined like this:

	name: job1 // name of recipe
	definition: schedule // definition of which type is recipe
	schedule:
		min: 0 // every min
		hour: 0 // every hour
		day: 0 // every day
	steps: // steps are done from first to last
		- touch ./test.txt
		- echo "Is this working?" > ./test.txt
		- mv ./test.txt ./imwondering.txt

If we set something like this

	schedule:
		min: 10 // every min
		hour: 2 // every hour
		day: 2 // every day

Task will run every 2 days 2 hours and 10 mins, if we put just days to 0 then it will run every 2 hours and 10 mins

	name: job2 // name of recipe
	definition: hook // definition of which type is recipe
	id: 45DE2239F // id which we use to find recipe
	steps:
		- echo "Hooked!" > ./hook.txt

Hooked recipe can be run by sending request to `{host}:{port}/hook?id={id_of_recipe}` on which Leprechaun server is listening, for example `localhost:11400/hook?id=45DE2239F`.

Recipes that use cron pattern to schedule tasks are used like this:

	name: job3 // name of recipe
	definition: cron // definition of which type is recipe
	pattern: * * * * *
	steps: // steps are done from first to last
		- touch ./test.txt
		- echo "Is this working?" > ./test.txt
		- mv ./test.txt ./imwondering.txt

Steps also support variables which syntax is `$variable`, and those are environment variables ex: `$LOGNAME` and in our steps it will be available as `$LOGNAME`. We can now rewrite our job file and it will look like something like this:

	name: job1 // name of recipe
	definition: schedule
	schedule:
		min: 0 // every min
		hour: 0 // every hour
		day: 0 // every day
	steps: // steps are done from first to last
		- echo "Is this working?" > $LOGNAME

Usage is very straightforward, you just need to start client and it will run recipes you defined previously.

Steps also can be defined as `sync/async` tasks which is defined by `->`, but keep in mind that steps in recipes are performed by linear path because one that is not async can block other from performing, lets take this one as example

	steps:
	- -> ping google.com
	- echo "I will not wait above task to perform, he is async so i will start immidiatelly"

but in this case for example first task will block performing on any task and all others will hang waiting it to finish
  
	steps:
	- ping google.com
	- -> echo "I need to wait above step to finish, then i can do my stuff"

## Step Pipe

Output from one step can be passed to input of next step:

	name: job1 // name of recipe
	definition: schedule
	schedule:
		min: 0 // every min
		hour: 0 // every hour
		day: 0 // every day
	steps: // steps are done from first to last
		- echo "Pipe this to next step" }>
		- cat > piped.txt

As you see, first step is using syntax `}>` at the end, which tells that this command output will be passed to next command input, you can chain like this how much you want.

## Step Failure

Since steps are executed linear workers doesn't care if some of the commands fail, they continue with execution, but you get notifications if you did setup those configurations. If you want that workers stop execution of next steps if some command failes you can specifify it with `!` like in example:

	name: job1 // name of recipe
	definition: schedule
	schedule:
		min: 0 // every min
		hour: 0 // every hour
		day: 0 // every day
	steps: // steps are done from first to last
		- ! echo "Pipe this to next step" }>
		- cat > piped.txt
		
If first step fails, recipe will fail and all other steps wont be executed

## Remote step execution

Steps can be handled by your local machine using regular syntax, if there is any need that you want specific step to be
executed by some remote machine you can spoecify that in step provided in example under, syntax is `rmt:some_host`, leprechaun will try to communicate with remote service that is configured on provided host and will run this command at that host.

	name: job1 // name of recipe
	definition: schedule
	schedule:
		min: 0 // every min
		hour: 0 // every hour
		day: 0 // every day
	steps: // steps are done from first to last
		- rmt:some_host echo "Pipe this to next step"

 Note that also as regular step this step also can pipe output to next step, so something like this is possible also:

	steps: // steps are done from first to last
		- rmt:some_host echo "Pipe this to next step" }>
		- rmt:some_other_host grep -a "Pipe" }>
		- cat > stored.txt

## Installation

Go to `leprechaun` directory and run `make install`, you will need sudo privileges for this. This will install scheduler, cron, and webhook services.

To install remote service run `make install-remote-service`, this will create `leprechaunrmt` binary.

## Build

Go to `leprechaun` directory and run `make build`. This will build scheduler, cron, and webhook services.

To build remote service run `make build-remote-service`, this will create `leprechaunrmt` binary.


## Starting/Stopping services

To start leprechaun just simply run it in background like this : `leprechaun &`

For more available commands run `leprechaun --help`

# Lepretools

For cli tools take a look [here](https://github.com/Kilgaloon/Leprechaun/blob/master/cmd/lepretools/README.md)

# Testing

To run tests with covarage `make test`, to run tests and generate reports run `make test-with-report` files will be generated in `coverprofile` dir. To test specific package run `make test-package package=[name]`


leprechaun

Persistent and flexible background jobs library.

Jobs
====

Development Status
------------------

Jobs is ***no longer*** being actively developed. I will still try my best to
respond to issues and pull requests, but in general you should not expect much
support. No new features will be added. Still, Jobs is reasonably
well-tested, and it is probably fine to use it for low-traffic hobby sites. If
you are looking for something for more serious, production use-cases, consider
alternatives such as [RabbitMQ](https://github.com/streadway/amqp).

Jobs follows semantic versioning but offers no guarantees of backwards compatibility until version
1.0.

About
-----

Jobs is a persistent and flexible background jobs library for go.

[![Version](https://img.shields.io/badge/version-0.4.2-5272B4.svg)](https://github.com/albrow/jobs/releases)
[![Circle CI](https://img.shields.io/circleci/project/albrow/jobs.svg)](https://circleci.com/gh/albrow/jobs)
[![GoDoc](https://godoc.org/github.com/albrow/jobs?status.svg)](https://godoc.org/github.com/albrow/jobs)

Jobs is powered by Redis and supports the following features:

 - A job can encapsulate any arbitrary functionality. A job can do anything
   which can be done in a go function.
 - A job can be one-off (only executed once) or recurring (scheduled to
   execute at a specific interval).
 - A job can be retried a specified number of times if it fails.
 - A job is persistent, with protections against power loss and other worst
   case scenarios. (See the [Guarantees](#guarantees) section below)
 - Work on jobs can be spread amongst any number of concurrent workers across any
   number of machines.
 - Provided it is persisted to disk, every job will be executed *at least* once,
 	and in ideal network conditions will be executed *exactly* once. (See the
 	[Guarantees](#guarantees) section below)
 - You can query the database to find out e.g. the number of jobs that are
   currently executing or how long a particular job took to execute.
 - Any job that permanently fails will have its error captured and stored.


Why is it Useful?
-----------------

Jobs is intended to be used in web applications. It is useful for cases where you need
to execute some long-running code, but you don't want your users to wait for the code to
execute before rendering a response. A good example is sending a welcome email to your users
after they sign up. You can use Jobs to schedule the email to be sent asynchronously, and
render a response to your user without waiting for the email to be sent. You could use a
goroutine to accomplish the same thing, but in the event of a server restart or power loss,
the email might never be sent. Jobs guarantees that the email will be sent at some time
and allows you to spread the work between different machines.


Installation
------------

Jobs requires Go version >= 1.2. If you do not already have it, follow these instructions:

- [Install Go](http://golang.org/doc/install)
- Follow the instructions for [setting up your go workspace](https://golang.org/doc/code.html)

Jobs requires access to a Redis database. If you plan to have multiple worker pools spread
out across different machines, they should all connect to the same Redis database. If you
only want to run one worker pool, it is safe to install Redis locally and run it on the same
machine. In either case, if you need to install Redis, follow these instructions:

- [Install Redis](http://redis.io/download).
- Follow the instructions in the section called
  [Installing Redis more properly](http://redis.io/topics/quickstart#installing-redis-more-properly).
- Make sure you understand how [Redis Persistence](http://redis.io/topics/persistence) works and have
  edited your config file to get your desired persistence. We recommend using both RDB and AOF and setting
  fsync to either "always" or "everysec".

After that, you can install Jobs like you would any other go package: `go get github.com/albrow/jobs`.
If you want to update the package later, use `go get -u github.com/albrow/jobs`. Then you can import
Jobs like you would any other go package by adding `import github.com/albrow/jobs` to your go source
file.


Quickstart Guide
----------------

### Connecting to Redis

You can configure the connection to Redis by editing Config.Db. Here are the options:

- Address is the address of the redis database to connect to. Default is
  "localhost:6379".
- Network is the type of network to use to connect to the redis database
Default is "tcp".
- Database is the redis database number to use for storing all data. Default
  is 0.
- Password is a password to use for connecting to a redis database via the
  AUTH command. If empty, Jobs will not attempt to authenticate. Default is
  "" (an empty string).

You should edit Config.Db during program initialization, before running Pool.Start
or scheduling any jobs. Here's an example of how to configure Jobs to use databse #10
and authenticate with the password "foobar":

``` go
func main() {
	// Configure database options at the start of your application
	jobs.Config.Db.Database = 10
	jobs.Config.Db.Password = "foobar"
}
```

### Registering Job Types

Jobs must be organized into discrete types. Here's an example of how to register a job
which sends a welcome email to users:

``` go
// We'll specify that we want the job to be retried 3 times before finally failing
welcomeEmailJobs, err := jobs.RegisterType("welcomeEmail", 3, func(user *User) error {
	msg := fmt.Sprintf("Hello, %s! Thanks for signing up for foo.com.", user.Name)
	if err := emails.Send(user.EmailAddress, msg); err != nil {
		// The returned error will be captured by a worker, which will then log the error
		// in the database and trigger up to 3 retries.
		return err
	}
})
```

The final argument to the RegisterType function is a [HandlerFunc](http://godoc.org/github.com/albrow/jobs#HandlerFunc)
which will be executed when the job runs. HandlerFunc must be a function which accepts either
zero or one arguments and returns an error.

### Scheduling a Job

After registering a job type, you can schedule a job using the Schedule or ScheduleRecurring
methods like so:

``` go
// The priority argument lets you choose how important the job is. Higher
// priority jobs will be executed first.
job, err := welcomeEmailJobs.Schedule(100, time.Now(), &User{EmailAddress: "foo@example.com"})
if err != nil {
	// Handle err
}
```

You can use the [Job object](http://godoc.org/github.com/albrow/jobs#Job) returned by Schedule
or ScheduleRecurring to check on the status of the job or cancel it manually.

### Starting and Configuring Worker Pools

You can schedule any number of worker pools across any number of machines, provided every machine
agrees on the definition of the job types. If you want, you can start a worker pool on the same
machines that are scheduling jobs, or you can have each worker pool running on a designated machine.
Since each pool is assigned an id based on a unique hardware identifier, you must only run one
worker pool per machine.

To create a new pool with the [default configuration](http://godoc.org/github.com/albrow/jobs#pkg-variables),
just pass in nil:

``` go
pool, err := jobs.NewPool(nil)
if err != nil {
	// Handle err
}
```

You can also specify a different configuration by passing in
[*PoolConfig](http://godoc.org/github.com/albrow/jobs#PoolConfig). Any zero values in the config you pass
in will fallback to the default values. So here's how you could start a pool with 10 workers and a batch
size of 10, while letting the other options remain the default.

``` go
pool, err := jobs.NewPool(&jobs.PoolConfig{
	NumWorkers: 10,
	BatchSize: 10,
})
if err != nil {
	// Handle err
}
```

After you have created a pool, you can start it with the Start method. Once started, the pool will
continuously query the database for new jobs and delegate those jobs to workers. Any program that calls
Pool.Start() should also wait for the workers to finish before exiting. You can do so by wrapping Close and
Wait in a defer statement. Typical usage looks something like this:

``` go
func main() {
	pool, err := jobs.NewPool(nil)
	if err != nil {
		// Handle err
	}
	defer func() {
		pool.Close()
		if err := pool.Wait(); err != nil {
			// Handle err
		}
	}()
	if err := pool.Start(); err != nil {
		// Handle err
	}
}
```

You can also call Close and Wait at any time to manually stop the pool from executing new jobs. In this
case, any jobs that are currently being executed will still finish.


Testing
-------

To run the tests, make sure you have Redis running and accepting unix socket connections on the address
/tmp/redis.sock. The tests will use database #14. **WARNING:** After each test is run, database #14 will be completely
erased, so make sure you do not have any important data stored there.

To run the tests just run `go test .` If anything fails, please report an issue and describe what happened.


Contributing
------------

See [Contributing.md](https://github.com/albrow/jobs/blob/master/CONTRIBUTING.md)


Guarantees
-----------

### Persistence

Since jobs is powered by Redis, there is a chance that you can lose data with the default Redis configuration.
To get the best persistence guarantees, you should set Redis to use both AOF and RDB persistence modes and set
fsync to "always". With these settings, Redis is more or less
[as persistent as a database like postgres](http://redis.io/topics/persistence#ok-so-what-should-i-use). If want
better performance and are okay with a slightly greater chance of losing data (i.e. jobs not executing), you can
set fsync to "everysec".

[Read more about Redis persistence](http://redis.io/topics/persistence).

### Atomicity

Jobs is carefully written using Redis transactions and lua scripting so that all database changes are atomic.
If Redis crashes in the middle of a transaction or script execution, it is possible that your AOF file can become
corrupted. If this happens, Redis will refuse to start until the AOF file is fixed. It is relatively easy to fix
the problem with the redis-check-aof tool, which will remove the partial transaction from the AOF file. In effect,
this guarantees that modifications of the database are atomic, even in the event of a power loss or hard reset,
with the caveat that you may need to use the redis-check-aof tool in the worst case scenario.

Read more about [Redis transactions](http://redis.io/topics/transactions) and
[scripts](http://redis.io/commands#scripting).

### Job Execution

Jobs guarantees that a job will be executed *at least* once, provided it has been persisted on disk. (See the section
on [Persistence](#persistence) directly above). A job can only picked up by one pool at a time because a pool
atomically pops (gets and immediately moves) the next available jobs from the database. A job can only be executed
by one worker at a time because the jobs are delegated to workers via a shared channel. Each worker pool checks on
the health of all the other pools when it starts. If a pool crashes or is otherwise disconnected, any jobs it had
grabbed from the database that did not yet finish will be re-queued and picked up by a different pool.

This is in no way an exhaustive list, but here are some known examples of scenarios that may cause a job to be
executed more than once:

1. If there is a power failure or hard reset while a worker is in the middle of executing a job, the job may be
   stuck in a half-executed state. Since there is no way to know how much of the job was successfully completed,
   the job will be re-queued and picked up by a different pool, where it may be partially or fully executed
   more than once.
2. If a pool becomes disconnected, it will be considered stale and its jobs will be re-queued and reclaimed
   by a different pool. However, if the stale pool is able to partly or fully execute jobs without a reliable
   internet connection, any jobs belonging to the stale pool might be executed more than once. You can increase
   the [StaleTimeout](https://godoc.org/github.com/albrow/jobs#PoolConfig) parameter for a pool to make this
   scenario less likely.


License
-------

Jobs is licensed under the MIT License. See the LICENSE file for more information.


jobs

A job scheduler with the ability to fast-forward time

![logo](https://user-images.githubusercontent.com/9574743/123485083-bbdffb00-d609-11eb-92eb-28d907180b5b.png)

<a href="https://github.com/romshark/sched/actions?query=workflow%3ACI">
  <img src="https://github.com/romshark/sched/workflows/CI/badge.svg" alt="GitHub Actions: CI">
</a>
<a href="https://goreportcard.com/report/github.com/romshark/sched">
  <img src="https://goreportcard.com/badge/github.com/romshark/sched" alt="GoReportCard">
</a>
<a href="https://coveralls.io/github/romshark/sched?branch=main">
  <img src="https://coveralls.io/repos/github/romshark/sched/badge.svg?branch=main" alt="Coverage Status">
</a>
<a href="https://pkg.go.dev/github.com/romshark/sched">
  <img src="https://pkg.go.dev/badge/github.com/romshark/sched.svg" alt="Go Reference">
</a>

# sched

A job scheduler for Go with the ability to fast-forward time.

Example: https://play.golang.org/p/BQDi8MKraIe


sched

Job scheduler library with database support

cdule

A simple crontab like scheduler that aims to offer a KISS approach to job scheduling.

<img src="https://storage.googleapis.com/cheek-scheduler/cheek-64.png" alt="cheek" />

# cheek

![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/datarootsio/cheek?label=version)
[![dataroots](https://dataroots.io/maintained.svg)](https://dataroots.io/) [![codecov](https://codecov.io/gh/datarootsio/cheek/branch/main/graph/badge.svg?token=011KCCGPE6)](https://codecov.io/gh/datarootsio/cheek)
![workflow](https://github.com/datarootsio/cheek/actions/workflows/ci.yml/badge.svg)
[![Go Report Card](https://goreportcard.com/badge/github.com/datarootsio/cheek)](https://goreportcard.com/report/github.com/datarootsio/cheek)
[![Go Reference](https://pkg.go.dev/badge/github.com/datarootsio/cheek.svg)](https://pkg.go.dev/github.com/datarootsio/cheek)
[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/avelino/awesome-go)
![love](https://img.shields.io/badge/made_with-%E2%9D%A4%EF%B8%8F-blue)

`cheek` is a pico-sized declarative job scheduler designed to excel in a single-node environment. `cheek` aims to be lightweight, stand-alone and simple. It does not compete for robustness.

> 📄 This bump to v1 introduces a storage backend switch, moving from jsonline logs to sqlite. This might introduce the need to adjust your long-term log storage approach.

## Getting started

Fetch the latest version for your system below.

[darwin-arm64](https://storage.googleapis.com/cheek-scheduler/darwin/arm64/cheek) |
[darwin-amd64](https://storage.googleapis.com/cheek-scheduler/darwin/amd64/cheek) |
[linux-386](https://storage.googleapis.com/cheek-scheduler/linux/386/cheek) |
[linux-arm64](https://storage.googleapis.com/cheek-scheduler/linux/arm64/cheek) |
[linux-amd64](https://storage.googleapis.com/cheek-scheduler/linux/amd64/cheek)

You can (for example) fetch it like below, make it executable and run it. Optionally put `cheek` on your `PATH`.

```sh
curl https://storage.googleapis.com/cheek-scheduler/darwin/amd64/cheek -o cheek
chmod +x cheek
./cheek
```

Everything about how you want the scheduler to function is defined in a schedule specification written in YAML. Start by creating this specification using the below example. Note, this structure should be more or less self-explanatory, if it is not, create an [issue](https://github.com/datarootsio/cheek/issues).

```yaml
tz_location: Europe/Brussels # optionally set timezone to adhere to
jobs:
  foo:
    command: date
    cron: "* * * * *" # a cron string to specify when to run
    on_success:
      trigger_job: # trigger something on run
        - bar
  bar:
    command: # command to run, use a list if you want to pass args
      - echo
      - $foo
    env: # you can pass env variables
      foo: bar
  other_workingdir:
    command: pwd
    working_directory: ../testdata # specify the working directory of the job
  coffee:
    command: this fails
    cron: "* * * * *"
    retries: 3
    on_error:
      notify_webhook: # notify something on error
        - https://webhook.site/4b732eb4-ba10-4a84-8f6b-30167b2f2762
      notify_slack_webhook: # notify slack via a slack compatible webhook
        - https://webhook.site/048ff47f-9ef5-43fb-9375-a795a8c5cbf5
```

If your `command` requires arguments, please make sure to pass them as an array like in `foo_job`.

Note that you can set `tz_location` if the system time of where you run your service is not to your liking.

## Scheduler

The core of `cheek` consists of a scheduler that uses the schedule specs defined in your `yaml` file to trigger jobs when they are due.

You can launch the scheduler via:

```sh
cheek run ./path/to/my-schedule.yaml
```

Check out `cheek run --help` for configuration options.

## Web UI

`cheek` ships with a web UI that by default gets launched on port `8081`. You can define the port on which it is accessible via the `--port` flag.

![main-screen](/readme_assets/main.png)
 main overview

![main-screen](/readme_assets/joboverview.png)
job detail

You can access the UI by navigating to `http://localhost:8081`. When `cheek` is deployed you are recommended to NOT make this port publicly accessible, instead navigate to the UI via an SSH tunnel.

The UI allows to get a quick overview on jobs that have run, that error'd and their logs. It basically does this by fetching the state of the scheduler and by reading the logs that (per job) get written to `$HOME/.cheek/`. Note that you can ignore these logs, output of jobs will always go to stdout as well.

Note, `cheek` prior to version `0.3.0` originally used to boast a TUI, which has since been removed.

## Configuration

All configuration options are available by checking out `cheek --help` or the help of its subcommands (e.g. `cheek run --help`).

Configuration can be passed as flags to the `cheek` CLI directly. All configuration flags are also possible to set via environment variables. The following environment variables are available, they will override the default and/or set value of their similarly named CLI flags (without the prefix): `CHEEK_PORT`, `CHEEK_SUPPRESSLOGS`, `CHEEK_LOGLEVEL`, `CHEEK_PRETTY`, `CHEEK_HOMEDIR`.

## Events & Notifications

There are two types of event you can hook into: `on_success` and `on_error`. Both events materialize after an (attempted) job run. Three types of actions can be taken as a response: `notify_webhook`, `notify_slack_webhook` and `trigger_job`. See the example below. Definition of these event actions can be done on job level or at schedule level, in the latter case it will apply to all jobs.

```yaml
on_success:
  notify_webhook:
    - https://webhook.site/e33464a3-1a4f-4f1a-99d3-743364c6b10f
jobs:
  coffee:
    command: this fails # this will create on_error event
    cron: "* * * * *"
    on_error:
      notify_webhook:
        - https://webhook.site/e33464a3-1a4f-4f1a-99d3-743364c6b10f
  beans:
    command: echo grind # this will create on_success event
    cron: "* * * * *"
```

Webhooks are a generic way to push notifications to a plethora of tools. There is a generic way to do this via the `notify_webhook` option or a Slack-compatible one via `notify_slack_webhook`.

The `notify_webhook` sends a JSON payload to your webhook url with the following structure:

```json
{
	"status": 0,
	"log": "I'm a teapot, not a coffee machine!",
	"name": "TeapotTask",
	"triggered_at": "2023-04-01T12:00:00Z",
	"triggered_by": "CoffeeRequestButton",
	"triggered": ["CoffeeMachine"] // this job triggered another one
}
```

The `notify_slack_webhook` sends a JSON payload to your Slack webhook url with the following structure (which is Slack app compatible):

```json
{
	"text": "TeapotTask (exitcode 0):\nI'm a teapot, not a coffee machine!"
}
```


## Docker

Check out the `Dockerfile.example` for an example on how to use `cheek` within the context of a Docker container. Note that this builds upon a published Ubuntu-based image build that you can find in the base [Dockerfile](https://github.com/datarootsio/cheek/blob/main/Dockerfile).

Prebuilt images are available at `ghcr.io/datarootsio/cheek:latest` where `latest` can be replaced by a version tag. Check out the [available images](https://github.com/datarootsio/cheek/pkgs/container/cheek) for an overview on available tags.

## Available versions

If you want to pin your setup to a specific version of `cheek` you can use the following template to fetch your `cheek` binary:

- latest version: https://storage.googleapis.com/cheek-scheduler/{os}/{arch}/cheek
- tagged version: https://storage.googleapis.com/cheek-scheduler/{os}/{arch}/cheek-{tag}
- `main` branch builds: https://storage.googleapis.com/cheek-scheduler/{os}/{arch}/cheek-{shortsha}

Where:

- `os` is one of `linux`, `darwin`
- `arch` is one of `amd64`, `arm64`, `386`
- `tag` is one the [available tags](https://github.com/datarootsio/cheek/tags)
- `shortsha` is a 7-char SHA and most commits on `main` will be available

## Acknowledgements

`cheek` is building on top of many great OSS assets. Noteable thanks goes to:

- [chota](https://jenil.github.io/chota/): for a pico sized css framework
- [gronx](https://github.com/adhocore/gronx): for allowing me not to worry about CRON strings.

<br/>
 
![GitHub Contributors](https://contrib.rocks/image?repo=datarootsio/cheek)


cheek

Define time-based tasks using a simple Go API and Gron’s scheduler will run them accordingly

# gron
[![Build Status](https://semaphoreci.com/api/v1/roylee0704/gron/branches/master/badge.svg)](https://semaphoreci.com/roylee0704/gron)
[![Go Report Card](https://goreportcard.com/badge/github.com/roylee0704/gron)](https://goreportcard.com/report/github.com/roylee0704/gron)
[![GoDoc](https://godoc.org/github.com/roylee0704/gron?status.svg)](https://godoc.org/github.com/roylee0704/gron)

Gron provides a clear syntax for writing and deploying cron jobs.

## Goals

- Minimalist APIs for scheduling jobs.
- Thread safety.
- Customizable Job Type.
- Customizable Schedule.

## Installation

```sh
$ go get github.com/roylee0704/gron
```

## Usage
Create `schedule.go`

```go
package main

import (
	"fmt"
	"time"
	"github.com/roylee0704/gron"
)

func main() {
	c := gron.New()
	c.AddFunc(gron.Every(1*time.Hour), func() {
		fmt.Println("runs every hour.")
	})
	c.Start()
}
```

#### Schedule Parameters

All scheduling is done in the machine's local time zone (as provided by the Go [time package](http://www.golang.org/pkg/time)).


Setup basic periodic schedule with `gron.Every()`.

```go
gron.Every(1*time.Second)
gron.Every(1*time.Minute)
gron.Every(1*time.Hour)
```

Also support `Day`, `Week` by importing `gron/xtime`:
```go
import "github.com/roylee0704/gron/xtime"

gron.Every(1 * xtime.Day)
gron.Every(1 * xtime.Week)
```

Schedule to run at specific time with `.At(hh:mm)`
```go
gron.Every(30 * xtime.Day).At("00:00")
gron.Every(1 * xtime.Week).At("23:59")
```

#### Custom Job Type
You may define custom job types by implementing `gron.Job` interface: `Run()`.

For example:

```go
type Reminder struct {
	Msg string
}

func (r Reminder) Run() {
  fmt.Println(r.Msg)
}
```

After job has defined, instantiate it and schedule to run in Gron.
```go
c := gron.New()
r := Reminder{ "Feed the baby!" }
c.Add(gron.Every(8*time.Hour), r)
c.Start()
```

#### Custom Job Func
You may register `Funcs` to be executed on a given schedule. Gron will run them in their own goroutines, asynchronously.

```go
c := gron.New()
c.AddFunc(gron.Every(1*time.Second), func() {
	fmt.Println("runs every second")
})
c.Start()
```


#### Custom Schedule
Schedule is the interface that wraps the basic `Next` method: `Next(p time.Duration) time.Time`

In `gron`, the interface value `Schedule` has the following concrete types:

- **periodicSchedule**. adds time instant t to underlying period p.
- **atSchedule**. reoccurs every period p, at time components(hh:mm).

For more info, checkout `schedule.go`.

### Full Example

```go
package main

import (
	"fmt"
	"github.com/roylee0704/gron"
	"github.com/roylee0704/gron/xtime"
)

type PrintJob struct{ Msg string }

func (p PrintJob) Run() {
	fmt.Println(p.Msg)
}

func main() {

	var (
		// schedules
		daily     = gron.Every(1 * xtime.Day)
		weekly    = gron.Every(1 * xtime.Week)
		monthly   = gron.Every(30 * xtime.Day)
		yearly    = gron.Every(365 * xtime.Day)

		// contrived jobs
		purgeTask = func() { fmt.Println("purge aged records") }
		printFoo  = printJob{"Foo"}
		printBar  = printJob{"Bar"}
	)

	c := gron.New()

	c.Add(daily.At("12:30"), printFoo)
	c.AddFunc(weekly, func() { fmt.Println("Every week") })
	c.Start()

	// Jobs may also be added to a running Gron
	c.Add(monthly, printBar)
	c.AddFunc(yearly, purgeTask)

	// Stop Gron (running jobs are not halted).
	c.Stop()
}
```


gron

Cron expression parser, task runner and daemon consuming crontab like task list

# adhocore/gronx

[![Latest Version](https://img.shields.io/github/release/adhocore/gronx.svg?style=flat-square)](https://github.com/adhocore/gronx/releases)
[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)
[![Go Report](https://goreportcard.com/badge/github.com/adhocore/gronx)](https://goreportcard.com/report/github.com/adhocore/gronx)
[![Test](https://github.com/adhocore/gronx/actions/workflows/test-action.yml/badge.svg)](https://github.com/adhocore/gronx/actions/workflows/test-action.yml)
[![Lint](https://github.com/adhocore/gronx/actions/workflows/lint-action.yml/badge.svg)](https://github.com/adhocore/gronx/actions/workflows/lint-action.yml)
[![Codecov](https://img.shields.io/codecov/c/github/adhocore/gronx/main.svg?style=flat-square)](https://codecov.io/gh/adhocore/gronx)
[![Support](https://img.shields.io/static/v1?label=Support&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/adhocore)
[![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Lightweight+fast+and+deps+free+cron+expression+parser+for+Golang&url=https://github.com/adhocore/gronx&hashtags=go,golang,parser,cron,cronexpr,cronparser)

`gronx` is Golang [cron expression](#cron-expression) parser ported from [adhocore/cron-expr](https://github.com/adhocore/php-cron-expr) with task runner
and daemon that supports crontab like task list file. Use it programatically in Golang or as standalone binary instead of crond. If that's not enough, you can use gronx to find the next (`NextTick()`) or previous (`PrevTick()`) run time of an expression from any arbitrary point of time.

- Zero dependency.
- Very **fast** because it bails early in case a segment doesn't match.
- Built in crontab like daemon.
- Supports time granularity of Seconds.

Find gronx in [pkg.go.dev](https://pkg.go.dev/github.com/adhocore/gronx).

## Installation

```sh
go get -u github.com/adhocore/gronx
```

## Usage

```go
import (
	"time"

	"github.com/adhocore/gronx"
)

gron := gronx.New()
expr := "* * * * *"

// check if expr is even valid, returns bool
gron.IsValid(expr) // true

// check if expr is due for current time, returns bool and error
gron.IsDue(expr) // true|false, nil

// check if expr is due for given time
gron.IsDue(expr, time.Date(2021, time.April, 1, 1, 1, 0, 0, time.UTC)) // true|false, nil
```

> Validity can be checked without instantiation:

```go
import "github.com/adhocore/gronx"

gronx.IsValid("* * * * *") // true
```

### Batch Due Check

If you have multiple cron expressions to check due on same reference time use `BatchDue()`:
```go
gron := gronx.New()
exprs := []string{"* * * * *", "0 */5 * * * *"}

// gives []gronx.Expr{} array, each item has Due flag and Err enountered.
dues := gron.BatchDue(exprs)

for _, expr := range dues {
    if expr.Err != nil {
        // Handle err
    } else if expr.Due {
        // Handle due
    }
}

// Or with given time
ref := time.Now()
gron.BatchDue(exprs, ref)
```

### Next Tick

To find out when is the cron due next (in near future):
```go
allowCurrent = true // includes current time as well
nextTime, err := gronx.NextTick(expr, allowCurrent) // gives time.Time, error

// OR, next tick after certain reference time
refTime = time.Date(2022, time.November, 1, 1, 1, 0, 0, time.UTC)
allowCurrent = false // excludes the ref time
nextTime, err := gronx.NextTickAfter(expr, refTime, allowCurrent) // gives time.Time, error
```

### Prev Tick

To find out when was the cron due previously (in near past):
```go
allowCurrent = true // includes current time as well
prevTime, err := gronx.PrevTick(expr, allowCurrent) // gives time.Time, error

// OR, prev tick before certain reference time
refTime = time.Date(2022, time.November, 1, 1, 1, 0, 0, time.UTC)
allowCurrent = false // excludes the ref time
nextTime, err := gronx.PrevTickBefore(expr, refTime, allowCurrent) // gives time.Time, error
```

> The working of `PrevTick*()` and `NextTick*()` are mostly the same except the direction.
> They differ in lookback or lookahead.

### Standalone Daemon

In a more practical level, you would use this tool to manage and invoke jobs in app itself and not
mess around with `crontab` for each and every new tasks/jobs.

In crontab just put one entry with `* * * * *` which points to your Go entry point that uses this tool.
Then in that entry point you would invoke different tasks if the corresponding Cron expr is due.
Simple map structure would work for this.

Check the section below for more sophisticated way of managing tasks automatically using `gronx` daemon called `tasker`.

---
### Go Tasker

Tasker is a task manager that can be programatically used in Golang applications. It runs as a daemon and invokes tasks scheduled with cron expression:
```go
package main

import (
	"context"
	"time"

	"github.com/adhocore/gronx/pkg/tasker"
)

func main() {
	taskr := tasker.New(tasker.Option{
		Verbose: true,
		// optional: defaults to local
		Tz:      "Asia/Bangkok",
		// optional: defaults to stderr log stream
		Out:     "/full/path/to/output-file",
	})

	// add task to run every minute
	taskr.Task("* * * * *", func(ctx context.Context) (int, error) {
		// do something ...

		// then return exit code and error, for eg: if everything okay
		return 0, nil
	}).Task("*/5 * * * *", func(ctx context.Context) (int, error) { // every 5 minutes
		// you can also log the output to Out file as configured in Option above:
		taskr.Log.Printf("done something in %d s", 2)

		return 0, nil
	})

	// run task without overlap, set concurrent flag to false:
	concurrent := false
	taskr.Task("* * * * * *", , tasker.Taskify("sleep 2", tasker.Option{}), concurrent)

	// every 10 minute with arbitrary command
	taskr.Task("@10minutes", taskr.Taskify("command --option val -- args", tasker.Option{Shell: "/bin/sh -c"}))

	// ... add more tasks

	// optionally if you want tasker to stop after 2 hour, pass the duration with Until():
	taskr.Until(2 * time.Hour)

	// finally run the tasker, it ticks sharply on every minute and runs all the tasks due on that time!
	// it exits gracefully when ctrl+c is received making sure pending tasks are completed.
	taskr.Run()
}
```

#### Concurrency

By default the tasks can run concurrently i.e if previous run is still not finished
but it is now due again, it will run again.
If you want to run only one instance of a task at a time, set concurrent flag to false:

```go
taskr := tasker.New(tasker.Option{})

concurrent := false
expr, task := "* * * * * *", tasker.Taskify("php -r 'sleep(2);'")
taskr.Task(expr, task, concurrent)
```

### Task Daemon

It can also be used as standalone task daemon instead of programmatic usage for Golang application.

First, just install tasker command:
```sh
go install github.com/adhocore/gronx/cmd/tasker@latest
```

Or you can also download latest prebuilt binary from [release](https://github.com/adhocore/gronx/releases/latest) for platform of your choice.

Then prepare a taskfile ([example](./tests/../test/taskfile.txt)) in crontab format
(or can even point to existing crontab).
> `user` is not supported: it is just cron expr followed by the command.

Finally run the task daemon like so
```
tasker -file path/to/taskfile
```
> You can pass more options to control the behavior of task daemon, see below.

####  Tasker command options:

```txt
-file string <required>
    The task file in crontab format
-out string
    The fullpath to file where output from tasks are sent to
-shell string
    The shell to use for running tasks (default "/usr/bin/bash")
-tz string
    The timezone to use for tasks (default "Local")
-until int
    The timeout for task daemon in minutes
-verbose
    The verbose mode outputs as much as possible
```

Examples:
```sh
tasker -verbose -file path/to/taskfile -until 120 # run until next 120min (i.e 2hour) with all feedbacks echoed back
tasker -verbose -file path/to/taskfile -out path/to/output # with all feedbacks echoed to the output file
tasker -tz America/New_York -file path/to/taskfile -shell zsh # run all tasks using zsh shell based on NY timezone
```

> File extension of taskfile for (`-file` option) does not matter: can be any or none.
> The directory for outfile (`-out` option) must exist, file is created by task daemon.

> Same timezone applies for all tasks currently and it might support overriding timezone per task in future release.

#### Notes on Windows

In Windows if it doesn't find `bash.exe` or `git-bash.exe` it will use `powershell`.
`powershell` may not be compatible with Unix flavored commands. Also to note:
you can't do chaining with `cmd1 && cmd2` but rather `cmd1 ; cmd2`.

---
### Cron Expression

A complete cron expression consists of 7 segments viz:
```
<second> <minute> <hour> <day> <month> <weekday> <year>
```

However only 5 will do and this is most commonly used. 5 segments are interpreted as:
```
<minute> <hour> <day> <month> <weekday>
```
in which case a default value of 0 is prepended for `<second>` position.

In a 6 segments expression, if 6th segment matches `<year>` (i.e 4 digits at least) it will be interpreted as:
```
<minute> <hour> <day> <month> <weekday> <year>
```
and a default value of 0 is prepended for `<second>` position.

For each segments you can have **multiple choices** separated by comma:
> Eg: `0 0,30 * * * *` means either 0th or 30th minute.

To specify **range of values** you can use dash:
> Eg: `0 10-15 * * * *` means 10th, 11th, 12th, 13th, 14th and 15th minute.

To specify **range of step** you can combine a dash and slash:
> Eg: `0 10-15/2 * * * *` means every 2 minutes between 10 and 15 i.e 10th, 12th and 14th minute.

For the `<day>` and `<weekday>` segment, there are additional [**modifiers**](#modifiers) (optional).

And if you want, you can mix the multiple choices, ranges and steps in a single expression:
> `0 5,12-20/4,55 * * * *` matches if any one of `5` or `12-20/4` or `55` matches the minute.

### Real Abbreviations

You can use real abbreviations (3 chars) for month and week days. eg: `JAN`, `dec`, `fri`, `SUN`

### Tags

Following tags are available and they are converted to real cron expressions before parsing:

- *@yearly* or *@annually* - every year
- *@monthly* - every month
- *@daily* - every day
- *@weekly* - every week
- *@hourly* - every hour
- *@5minutes* - every 5 minutes
- *@10minutes* - every 10 minutes
- *@15minutes* - every 15 minutes
- *@30minutes* - every 30 minutes
- *@always* - every minute
- *@everysecond* - every second

> For BC reasons, `@always` still means every minute for now, in future release it may mean every seconds instead.

```go
// Use tags like so:
gron.IsDue("@hourly")
gron.IsDue("@5minutes")
```

### Modifiers

Following modifiers supported

- *Day of Month / 3rd of 5 segments / 4th of 6+ segments:*
    - `L` stands for last day of month (eg: `L` could mean 29th for February in leap year)
    - `W` stands for closest week day (eg: `10W` is closest week days (MON-FRI) to 10th date)
- *Day of Week / 5th of 5 segments / 6th of 6+ segments:*
    - `L` stands for last weekday of month (eg: `2L` is last tuesday)
    - `#` stands for nth day of week in the month (eg: `1#2` is second monday)

---
## License

> &copy; [MIT](./LICENSE) | 2021-2099, Jitendra Adhikari

## Credits

This project is ported from [adhocore/cron-expr](https://github.com/adhocore/php-cron-expr) and
release managed by [please](https://github.com/adhocore/please).

---
### Other projects

My other golang projects you might find interesting and useful:

- [**urlsh**](https://github.com/adhocore/urlsh) - URL shortener and bookmarker service with UI, API, Cache, Hits Counter and forwarder using postgres and redis in backend, bulma in frontend; has [web](https://urlssh.xyz) and cli client
- [**fast**](https://github.com/adhocore/fast) - Check your internet speed with ease and comfort right from the terminal
- [**goic**](https://github.com/adhocore/goic) - Go Open ID Connect, is OpenID connect client library for Golang, supports the Authorization Code Flow of OpenID Connect specification.
- [**chin**](https://github.com/adhocore/chin) - A Go lang command line tool to show a spinner as user waits for some long running jobs to finish.


gronx

Go package to schedule periodic jobs using a simple, fluent syntax

# clockwerk

[![Coverage Status](https://coveralls.io/repos/github/onatm/clockwerk/badge.svg?branch=main)](https://coveralls.io/github/onatm/clockwerk?branch=main)
[![Go Report Card](https://goreportcard.com/badge/github.com/onatm/clockwerk)](https://goreportcard.com/report/github.com/onatm/clockwerk)
[![Go Reference](https://pkg.go.dev/badge/github.com/onatm/clockwerk.svg)](https://pkg.go.dev/github.com/onatm/clockwerk)

Job Scheduling Library

clockwerk allows you to schedule periodic jobs using a simple, fluent syntax.

## Installing

Using clockwerk is easy. First, use `go get` to install the latest version of the library.

``` sh
go get -u github.com/onatm/clockwerk@latest
```

## Usage

Include clockwerk in your application:

```go
import "github.com/onatm/clockwerk"
```

## Example

``` go
package main

import (
  "fmt"
  "time"
  "github.com/onatm/clockwerk"
)

type DummyJob struct{}

func (d DummyJob) Run() {
  fmt.Println("Every 30 seconds")
}

func main() {
  var job DummyJob
  c := clockwerk.New()
  c.Every(30 * time.Second).Do(job)
  c.Start()
}
```


clockwerk

A ticker implementation to support cron schedules

# cronticker
Golang ticker that works with Cron scheduling.

[![CircleCI](https://circleci.com/gh/circleci/circleci-docs.svg?style=shield)](https://circleci.com/gh/circleci/circleci-docs)
![Codecov](https://img.shields.io/codecov/c/github/krayzpipes/cronticker)
[![Go Report Card](https://goreportcard.com/badge/github.com/krayzpipes/cronticker)](https://goreportcard.com/report/github.com/krayzpipes/cronticker)
## Import it

```bash
go get github.com/krayzpipes/cronticker/cronticker
```

```go
import "github.com/krayzpipes/cronticker/cronticker"
```

## Usage

Create a new ticker:

```go
ticker, err := NewTicker("TZ=America/New_York 0 0 0 ? * SUN")
```

Check the ticker's channel for the next tick:

```go
tickerTime := <-ticker.C
```

Reset the ticker to a new cron schedule

```go
err := ticker.Reset("0 0 0 ? * MON,TUE,WED")
```

Stop the ticker
```go
ticker.Stop()
```

Use `defer ticker.Stop()` whenever you can to ensure the cleanup of goroutines.

```go
ticker, _ := NewTicker("@daily")
defer ticker.Stop()
```

### Cron Schedule Format
The Cron schedule can be in **Unix** or **Quartz** format. Directives like
'@weekly' or '@daily' can also be parsed as defined in the
package github.com/robfig/cron/v3.

You may add the TimeZone/location to the beginning of the cron schedule
to change the time zone. Default is UTC if `TZ=Whatever` is not prepended
to the cron schedule.

#### Examples
| Cron Schedule | Type/Format | Description |
|---------------|------|-------------|
|"TZ=America/Los_Angeles 0 0 * * *"|Unix|Daily at 12 AM in Los Angeles|
|"TZ=America/Los_Angeles 0 0 0 ? * MON"|Quartz|Mondays at 12 AM in Los Angeles|
|"TZ=America/Los_Angeles @daily"|Directive|Daily at 12 AM in Los Angeles|
|"@daily"|Directive|Daily at 12 AM UTC|

You may also use the following characters:

| Character | Description | Example |
|-----------|-------------|---------|
|-|Range|4-5|
|/|Step|0/5|
|*|Any|*/5|
|,|List|1,4,5|

cronticker

An easy to use in-process scheduler for recurring tasks in Go

# Tasks

[![tests](https://github.com/madflojo/tasks/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/madflojo/tasks/actions/workflows/tests.yml)
[![codecov](https://codecov.io/gh/madflojo/tasks/graph/badge.svg?token=882QTXA7PX)](https://codecov.io/gh/madflojo/tasks)
[![Go Report Card](https://goreportcard.com/badge/github.com/madflojo/tasks)](https://goreportcard.com/report/github.com/madflojo/tasks) 
[![PkgGoDev](https://pkg.go.dev/badge/github.com/madflojo/tasks)](https://pkg.go.dev/github.com/madflojo/tasks)

Package tasks is an easy to use in-process scheduler for recurring tasks in Go. Tasks is focused on high frequency
tasks that run quick, and often. The goal of Tasks is to support concurrent running tasks at scale without scheduler
induced jitter.

Tasks is focused on accuracy of task execution. To do this each task is called within it's own goroutine. This ensures 
that long execution of a single invocation does not throw the schedule as a whole off track.

For simplicity this task scheduler uses the time.Duration type to specify intervals. This allows for a simple interface 
and flexible control over when tasks are executed.

## Key Features

- **Concurrent Execution**: Tasks are executed in their own goroutines, ensuring accurate scheduling even when individual tasks take longer to complete.
- **Optimized Goroutine Scheduling**: Tasks leverages Go's `time.AfterFunc()` function to reduce sleeping goroutines and optimize CPU scheduling.
- **Flexible Task Intervals**: Tasks uses the `time.Duration` type to specify intervals, offering a simple interface and flexible control over task execution timing.
- **Delayed Task Start**: Schedule tasks to start at a later time by specifying a start time, allowing for greater control over task execution.
- **One-Time Tasks**: Schedule tasks to run only once by setting the `RunOnce` flag, ideal for single-use tasks or one-time actions.
- **Custom Error Handling**: Define a custom error handling function to handle errors returned by tasks, enabling tailored error handling logic.

## Usage

Here are some examples to help you get started with Tasks:

### Basic Usage

```go
// Start the Scheduler
scheduler := tasks.New()
defer scheduler.Stop()

// Add a task
id, err := scheduler.Add(&tasks.Task{
  Interval: 30 * time.Second,
  TaskFunc: func() error {
    // Put your logic here
  },
})
if err != nil {
  // Do Stuff
}
```

### Delayed Scheduling

Sometimes schedules need to started at a later time. This package provides the ability to start a task only after a 
certain time. The below example shows this in practice.

```go
// Add a recurring task for every 30 days, starting 30 days from now
id, err := scheduler.Add(&tasks.Task{
  Interval: 30 * (24 * time.Hour),
  StartAfter: time.Now().Add(30 * (24 * time.Hour)),
  TaskFunc: func() error {
    // Put your logic here
  },
})
if err != nil {
  // Do Stuff
}
```

### One-Time Tasks

It is also common for applications to run a task only once. The below example shows scheduling a task to run only once 
after waiting for 60 seconds.

```go
// Add a one time only task for 60 seconds from now
id, err := scheduler.Add(&tasks.Task{
  Interval: 60 * time.Second,
  RunOnce:  true,
  TaskFunc: func() error {
    // Put your logic here
  },
})
if err != nil {
  // Do Stuff
}
```

### Custom Error Handling

One powerful feature of Tasks is that it allows users to specify custom error handling. This is done by allowing users 
to define a function that is called when a task returns an error. The below example shows scheduling a task that logs 
when an error occurs.

```go
// Add a task with custom error handling
id, err := scheduler.Add(&tasks.Task{
  Interval: 30 * time.Second,
  TaskFunc: func() error {
    // Put your logic here
  },
  ErrFunc: func(e error) {
    log.Printf("An error occurred when executing task %s - %s", id, e)
  },
})
if err != nil {
  // Do Stuff
}
```

For more details on usage, see the [GoDoc](https://pkg.go.dev/github.com/madflojo/tasks).

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for more details.


tasks

# scheduler
[![GoDoc](https://godoc.org/github.com/carlescere/scheduler?status.svg)](https://godoc.org/github.com/carlescere/scheduler)
[![Build Status](https://travis-ci.org/carlescere/scheduler.svg?branch=master)](https://travis-ci.org/carlescere/scheduler)
[![Coverage Status](https://coveralls.io/repos/carlescere/scheduler/badge.svg?branch=master)](https://coveralls.io/r/carlescere/scheduler?branch=master)

Job scheduling made easy.

Scheduler allows you to schedule recurrent jobs with an easy-to-read syntax.

Inspired by the article **[Rethinking Cron](http://adam.heroku.com/past/2010/4/13/rethinking_cron/)** and the **[schedule](https://github.com/dbader/schedule)** python module.

## How to use?
```go
package main

import (
	"fmt"
	"runtime"
	"time"

	"github.com/carlescere/scheduler"
)

func main() {
	job := func() {
		t := time.Now()
		fmt.Println("Time's up! @", t.UTC())
	}
      // Run every 2 seconds but not now.
	scheduler.Every(2).Seconds().NotImmediately().Run(job)
      
      // Run now and every X.
	scheduler.Every(5).Minutes().Run(job)
	scheduler.Every().Day().Run(job)
	scheduler.Every().Monday().At("08:30").Run(job)
      
      // Keep the program from not exiting.
	runtime.Goexit()
}
```

## How it works?
By specifying the chain of calls, a `Job` struct is instantiated and a goroutine is starts observing the `Job`.

The goroutine will be on pause until:
* The next run scheduled is due. This will cause to execute the job.
* The `SkipWait` channel is activated. This will cause to execute the job.
* The `Quit` channel is activated. This will cause to finish the job.

## Not immediate recurrent jobs
By default the behaviour of the recurrent jobs (Every(N) seconds, minutes, hours) is to start executing the job right away and then wait the required amount of time. By calling specifically `.NotImmediately()` you can override that behaviour and not execute it directly when the function `Run()` is called.

```go
scheduler.Every(5).Minutes().NotImmediately().Run(job)
```

## License
Distributed under MIT license. See `LICENSE` for more information.


scheduler

A flexible and extensible job scheduling and execution library for Go

# go-job

![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/cybergarage/go-job)
[![test](https://github.com/cybergarage/go-job/actions/workflows/make.yml/badge.svg)](https://github.com/cybergarage/go-job/actions/workflows/make.yml)
[![Go Reference](https://pkg.go.dev/badge/github.com/cybergarage/go-job.svg)](https://pkg.go.dev/github.com/cybergarage/go-job)
 [![Go Report Card](https://img.shields.io/badge/go%20report-A%2B-brightgreen)](https://goreportcard.com/report/github.com/cybergarage/go-job) 
[![codecov](https://codecov.io/gh/cybergarage/go-job/graph/badge.svg?token=NVG8DWJX3Y)](https://codecov.io/gh/cybergarage/go-job)

`go-job` is a flexible and extensible job scheduling and execution library for Go. It enables you to register, schedule, and manage jobs with arbitrary function signatures, supporting custom executors, priorities, and advanced scheduling options such as cron expressions and delayed execution.

![](doc/img/job-framework.png)

 The library provides robust job observation features, including state and log history tracking, as well as customizable response and error handlers. With support for distributed storage backends, `go-job` is suitable for both local and distributed environments, making it ideal for building scalable, reliable job processing systems in Go applications.

## Features

`go-job` offers a powerful and flexible foundation for job scheduling, execution, and monitoring in Go. It supports arbitrary function execution, dynamic scheduling, prioritization, distributed processing, and detailed job observation.

Key features include:

* **Arbitrary Function Execution** – Register and run any function with custom input/output types using Go's `any` type. This allows you to create jobs from functions with any signature, enabling integration of diverse tasks.
* **Flexible Scheduling** – Schedule jobs to run immediately, after a delay, at a specific time, or on a recurring cron schedule. Supports both one-time and repeated executions (cron), providing versatility for time-based job triggers.
* **Queue Priority & Worker Management** – Prioritize jobs in the queue and dynamically adjust worker pools for concurrency control. Higher-priority jobs run before lower-priority ones, and the number of worker goroutines can be scaled to meet throughput needs.
* **Job Observation** – Monitor the full lifecycle of jobs, including state changes and logs. You can attach custom handlers to job completion or failure events and track each job’s state history and log history for auditing and debugging.
* **Pluggable Storage for Distributed Support** – Abstracted storage via a `Store` interface allows integration of various backends (in-memory, file, database, etc.). This makes it possible to coordinate jobs across multiple nodes, enabling distributed job processing with persistent state.

For detailed feature descriptions and usage examples, see the [Feature Overview and Usage Guide](doc/overview.md).

## Getting Started

### Installation

```sh
go get github.com/cybergarage/go-job
```

### Basic Usage

```go
package main

import (
    "fmt"
    "github.com/cybergarage/go-job/job"
)

func main() {
	// Create a job manager
	mgr, _ := job.NewManager()

	// Register a job with a custom executor
	sumJob, _ := job.NewJob(
		job.WithKind("sum"),
		job.WithExecutor(func(ji job.Instance, a, b int) int {
			ji.Infof("%s (%s): attempts %d", ji.UUID(), ji.Kind(), ji.Attempts())
			return a + b
		}),
		job.WithStateChangeProcessor(func(ji job.Instance, state job.JobState) {
			ji.Infof("State changed to: %v", state)
		}),
		job.WithCompleteProcessor(func(ji job.Instance, res []any) {
			ji.Infof("Result: %v", res)
		}),
		job.WithTerminateProcessor(func(ji job.Instance, err error) error {
			ji.Errorf("Error executing job: %v", err)
			return err
		}),
	)
	mgr.RegisterJob(sumJob)

	// Schedule the registered job
	ji, _ := mgr.ScheduleRegisteredJob("sum",
		job.WithArguments("?", 1, 2),   // "?" is a dummy placeholder for job.Instance
		job.WithScheduleAt(time.Now()), // immediate scheduling is the default, so this option is redundant
	)

	// Start the job manager
	mgr.Start()

	// Wait waits for all jobs to complete or terminate.
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	mgr.Wait(ctx)

	// Retrieve all queued and executed job instances
	query := job.NewQuery() // queries all job instances (any state)
	jis, _ := mgr.LookupInstances(query)
	for _, ji := range jis {
		fmt.Printf("Job Instance: %s, UUID: %s, State: %s\n", ji.Kind(), ji.UUID(), ji.State())
	}

	// Retrieve and print the job instance state history
	query = job.NewQuery(
		job.WithQueryInstance(ji), // filter by specific job instance
	)
	history, _ := mgr.LookupInstanceHistory(query)
	for _, record := range history {
		fmt.Println(record.State())
	}

	// Retrieve and print the job instance logs
	query = job.NewQuery(
		job.WithQueryInstance(ji), // filter by specific job instance
	)
	logs, _ := mgr.LookupInstanceLogs(query)
	for _, log := range logs {
		fmt.Println(log.Message())
	}

	// Stop the job manager
	mgr.Stop()
}
```

# User Guides

- Getting Started
  - [Quick Start](doc/quick-start.md)
- Usage & Features
  - [Feature Overview and Usage Guide](doc/overview.md)
- Operation
  - [Command-Line Interface (jobctl)](doc/cmd/cli/jobctl.md)
  - [gRPC API](doc/grpc-api.md)
  - [Metrics (Prometheus)](doc/metrics.md)
- Design & Comparison
  - [go-job Comparison (OpenAI Research)](doc/design-comparison.md)

# References

- [![Go Reference](https://pkg.go.dev/badge/github.com/cybergarage/go-job.svg)](https://pkg.go.dev/github.com/cybergarage/go-job)

# Developer Guides

- Architecture & Development
  - [Design and Architecture](doc/design.md)
- Extending go-job
  - [Extension Guide](doc/extension-guide.md)

# Related Projects

`go-job` is developed in collaboration with the following Cybergarage projects:

- [go-logger](https://github.com/cybergarage/go-logger) ![go logger](https://img.shields.io/github/v/tag/cybergarage/go-logger)
- [go-safecast](https://github.com/cybergarage/go-safecast) ![go safecast](https://img.shields.io/github/v/tag/cybergarage/go-safecast)

go-job

Simple, zero-dependency scheduling library for Go

# go-quartz

[![Build](https://github.com/reugn/go-quartz/actions/workflows/build.yml/badge.svg)](https://github.com/reugn/go-quartz/actions/workflows/build.yml)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/reugn/go-quartz)](https://pkg.go.dev/github.com/reugn/go-quartz)
[![Go Report Card](https://goreportcard.com/badge/github.com/reugn/go-quartz)](https://goreportcard.com/report/github.com/reugn/go-quartz)
[![codecov](https://codecov.io/gh/reugn/go-quartz/branch/master/graph/badge.svg)](https://codecov.io/gh/reugn/go-quartz)

A minimalistic and zero-dependency scheduling library for Go.

## About

The implementation is inspired by the design of the [Quartz](https://github.com/quartz-scheduler/quartz)
Java scheduler.

The core [scheduler](#scheduler-interface) component can be used to manage scheduled [jobs](#job-interface) (tasks)
using [triggers](#trigger-interface).
The implementation of the cron trigger fully supports the Quartz [cron expression format](#cron-expression-format)
and can be used independently to calculate a future time given the previous execution time.

If you need to run multiple instances of the scheduler, see the [distributed mode](#distributed-mode) section for
guidance.

### Library building blocks

#### Scheduler interface

```go
type Scheduler interface {
	// Start starts the scheduler. The scheduler will run until
	// the Stop method is called or the context is canceled. Use
	// the Wait method to block until all running jobs have completed.
	Start(context.Context)

	// IsStarted determines whether the scheduler has been started.
	IsStarted() bool

	// ScheduleJob schedules a job using the provided Trigger.
	ScheduleJob(jobDetail *JobDetail, trigger Trigger) error

	// GetJobKeys returns the keys of scheduled jobs.
	// For a job key to be returned, the job must satisfy all of the
	// matchers specified.
	// Given no matchers, it returns the keys of all scheduled jobs.
	GetJobKeys(...Matcher[ScheduledJob]) ([]*JobKey, error)

	// GetScheduledJob returns the scheduled job with the specified key.
	GetScheduledJob(jobKey *JobKey) (ScheduledJob, error)

	// DeleteJob removes the job with the specified key from the
	// scheduler's execution queue.
	DeleteJob(jobKey *JobKey) error

	// PauseJob suspends the job with the specified key from being
	// executed by the scheduler.
	PauseJob(jobKey *JobKey) error

	// ResumeJob restarts the suspended job with the specified key.
	ResumeJob(jobKey *JobKey) error

	// Clear removes all of the scheduled jobs.
	Clear() error

	// Wait blocks until the scheduler stops running and all jobs
	// have returned. Wait will return when the context passed to
	// it has expired. Until the context passed to start is
	// cancelled or Stop is called directly.
	Wait(context.Context)

	// Stop shutdowns the scheduler.
	Stop()
}
```

Implemented Schedulers

- StdScheduler

#### Trigger interface

```go
type Trigger interface {
	// NextFireTime returns the next time at which the Trigger is scheduled to fire.
	NextFireTime(prev int64) (int64, error)

	// Description returns the description of the Trigger.
	Description() string
}
```

Implemented Triggers

- CronTrigger
- SimpleTrigger
- RunOnceTrigger

#### Job interface

Any type that implements it can be scheduled.

```go
type Job interface {
	// Execute is called by a Scheduler when the Trigger associated with this job fires.
	Execute(context.Context) error

	// Description returns the description of the Job.
	Description() string
}
```

Several common Job implementations can be found in the [job](./job) package.

## Cron expression format

| Field Name   | Mandatory | Allowed Values  | Allowed Special Characters |
|--------------|-----------|-----------------|----------------------------|
| Seconds      | YES       | 0-59            | , - * /                    |
| Minutes      | YES       | 0-59            | , - * /                    |
| Hours        | YES       | 0-23            | , - * /                    |
| Day of month | YES       | 1-31            | , - * ? / L W              |
| Month        | YES       | 1-12 or JAN-DEC | , - * /                    |
| Day of week  | YES       | 1-7 or SUN-SAT  | , - * ? / L #              |
| Year         | NO        | empty, 1970-    | , - * /                    |

### Special characters

- `*`: All values in a field (e.g., `*` in minutes = "every minute").
- `?`: No specific value; use when specifying one of two related fields (e.g., "10" in day-of- month, `?` in
  day-of-week).
- `-`: Range of values (e.g., `10-12` in hour = "hours 10, 11, and 12").
- `,`: List of values (e.g., `MON,WED,FRI` in day-of-week = "Monday, Wednesday, Friday").
- `/`: Increments (e.g., `0/15` in seconds = "0, 15, 30, 45"; `1/3` in day-of-month = "every 3 days from the 1st").
- `L`: Last day; meaning varies by field. Ranges or lists are not allowed with `L`.
  - Day-of-month: Last day of the month (e.g, `L-3` is the third to last day of the month).
  - Day-of-week: Last day of the week (7 or SAT) when alone; "last xxx day" when used after
    another value (e.g., `6L` = "last Friday").
- `W`: Nearest weekday in the month to the given day (e.g., `15W` = "nearest weekday to the 15th"). If `1W` on
  Saturday, it fires Monday the 3rd. `W` only applies to a single day, not ranges or lists.
- `#`: Nth weekday of the month (e.g., `6#3` = "third Friday"; `2#1` = "first Monday"). Firing does not occur if
  that nth weekday does not exist in the month.

<sup>1</sup> The `L` and `W` characters can also be combined in the day-of-month field to yield `LW`, which
translates to "last weekday of the month".

<sup>2</sup> The names of months and days of the week are not case-sensitive. MON is the same as mon.

## Distributed mode

The scheduler can use its own implementation of `quartz.JobQueue` to allow state sharing.  
An example implementation of the job queue using the file system as a persistence layer
can be found [here](./examples/queue/file_system.go).

## Usage example

```go
package main

import (
	"context"
	"log/slog"
	"net/http"
	"os"
	"time"

	"github.com/reugn/go-quartz/job"
	"github.com/reugn/go-quartz/logger"
	"github.com/reugn/go-quartz/quartz"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	// create a scheduler using the logger configuration option
	slogLogger := slog.New(slog.NewTextHandler(os.Stdout, nil))
	scheduler, _ := quartz.NewStdScheduler(quartz.WithLogger(logger.NewSlogLogger(ctx, slogLogger)))

	// start the scheduler
	scheduler.Start(ctx)

	// create jobs
	cronTrigger, _ := quartz.NewCronTrigger("1/5 * * * * *")
	shellJob := job.NewShellJob("ls -la")

	request, _ := http.NewRequest(http.MethodGet, "https://worldtimeapi.org/api/timezone/utc", nil)
	curlJob := job.NewCurlJob(request)

	functionJob := job.NewFunctionJob(func(_ context.Context) (int, error) { return 1, nil })

	// register the jobs with the scheduler
	_ = scheduler.ScheduleJob(quartz.NewJobDetail(shellJob, quartz.NewJobKey("shellJob")),
		cronTrigger)
	_ = scheduler.ScheduleJob(quartz.NewJobDetail(curlJob, quartz.NewJobKey("curlJob")),
		quartz.NewSimpleTrigger(7*time.Second))
	_ = scheduler.ScheduleJob(quartz.NewJobDetail(functionJob, quartz.NewJobKey("functionJob")),
		quartz.NewSimpleTrigger(5*time.Second))

	// stop the scheduler
	scheduler.Stop()

	// wait for all workers to exit
	scheduler.Wait(ctx)
}
```

See the examples directory for additional code samples.

## License

Licensed under the MIT License.


go-quartz

Job scheduler supporting standard cron expressions, custom descriptors, intervals, and task dependencies

> [!NOTE]
> This README was generated by [SKILL](https://github.com/pardnchiu/skill-readme-generate), get the ZH version from [here](./README.zh.md).

# go-scheduler

[![pkg](https://pkg.go.dev/badge/github.com/pardnchiu/go-scheduler.svg)](https://pkg.go.dev/github.com/pardnchiu/go-scheduler)
[![card](https://goreportcard.com/badge/github.com/pardnchiu/go-scheduler)](https://goreportcard.com/report/github.com/pardnchiu/go-scheduler)
[![codecov](https://img.shields.io/codecov/c/github/pardnchiu/go-scheduler)](https://app.codecov.io/github/pardnchiu/go-scheduler)
[![license](https://img.shields.io/github/license/pardnchiu/go-scheduler)](LICENSE)
[![version](https://img.shields.io/github/v/tag/pardnchiu/go-scheduler?label=release)](https://github.com/pardnchiu/go-scheduler/releases)

> Lightweight Go task scheduler with cron syntax, task dependency chains, and failure strategy control.

## Table of Contents

- [Features](#features)
- [Architecture](#architecture)
- [File Structure](#file-structure)
- [License](#license)
- [Author](#author)
- [Stars](#stars)

## Features

> `go get github.com/pardnchiu/go-scheduler` · [Documentation](./doc.md)

### Cron Scheduling with Live Dispatch

Supports standard five-field cron expressions and preset descriptors like `@every` and `@daily`. A min-heap sorts trigger times so the next due task is woken with minimal overhead. Tasks can be added or removed dynamically while the scheduler is running, with no restart required.

### Task Dependency Chains with Failure Strategies

Tasks can declare dependencies on other tasks, and the scheduler automatically blocks execution until prerequisites complete. Two failure strategies are provided: Skip ignores the failure and proceeds, while Stop aborts the entire dependency chain. Each dependency accepts an independent timeout to prevent a single stalled task from blocking the whole schedule.

### Concurrency-Safe Execution with Panic Recovery

Each task runs in its own goroutine, with mutex and channel coordination ensuring consistent state. Panics are automatically recovered so one failing task never crashes the scheduler. Context-based timeouts trigger an onDelay callback, giving callers a hook for cleanup logic.

## Architecture

```mermaid
graph TB
    subgraph Scheduler
        C[Cron Engine]
        H[Min-Heap]
    end

    subgraph Dependencies
        DM[Depend Manager]
        W[Worker Pool]
    end

    C -->|schedule trigger| H
    H -->|due task| C
    C -->|has deps| DM
    C -->|no deps| G[Goroutine Exec]
    DM -->|check complete| W
    W -->|deps satisfied| G
    G -->|report result| DM
```

## File Structure

```
go-scheduler/
├── instance.go          # Scheduler creation, start, stop, and task execution
├── add.go               # Task addition and argument parsing
├── remove.go            # Task removal
├── task.go              # Task listing and heap implementation
├── schedule.go          # Cron expression and descriptor parsing
├── type.go              # Type definitions and constants
├── depend.go            # Dependency worker pool and task execution
├── dependManager.go     # Dependency checking, waiting, and state updates
├── cron_test.go         # Unit tests and benchmarks
├── go.mod
└── LICENSE
```

## License

This project is licensed under the [MIT LICENSE](LICENSE).

## Author

<img src="https://avatars.githubusercontent.com/u/25631760" align="left" width="96" height="96" style="margin-right: 0.5rem;">

<h4 style="padding-top: 0">邱敬幃 Pardn Chiu</h4>

<a href="mailto:dev@pardn.io" target="_blank">
<img src="https://pardn.io/image/email.svg" width="48" height="48">
</a> <a href="https://linkedin.com/in/pardnchiu" target="_blank">
<img src="https://pardn.io/image/linkedin.svg" width="48" height="48">
</a>

## Stars

[![Star](https://api.star-history.com/svg?repos=pardnchiu/go-scheduler&type=Date)](https://www.star-history.com/#pardnchiu/go-scheduler&Date)

***

©️ 2025 [邱敬幃 Pardn Chiu](https://linkedin.com/in/pardnchiu)


go-scheduler

Easy and fluent Go job scheduling. This is an actively maintained fork of [jasonlvhit/gocron](https://github.com/jasonlvhit/gocron)

# gocron: A Golang Job Scheduling Package

[![CI State](https://github.com/go-co-op/gocron/actions/workflows/go_test.yml/badge.svg?branch=v2&event=push)](https://github.com/go-co-op/gocron/actions)
![Go Report Card](https://goreportcard.com/badge/github.com/go-co-op/gocron) [![Go Doc](https://godoc.org/github.com/go-co-op/gocron/v2?status.svg)](https://pkg.go.dev/github.com/go-co-op/gocron/v2)

gocron is a job scheduling package which lets you run Go functions at pre-determined intervals.

> Looking for a visual interface?  
> Check out [**gocron-ui**](https://github.com/go-co-op/gocron-ui) — a lightweight web dashboard to monitor, trigger, and manage your `gocron` jobs in real time.

If you want to chat, you can find us on Slack at
[<img src="https://img.shields.io/badge/gophers-gocron-brightgreen?logo=slack">](https://gophers.slack.com/archives/CQ7T0T1FW)

## Quick Start

```
go get github.com/go-co-op/gocron/v2
```

```golang
package main

import (
	"fmt"
	"time"

	"github.com/go-co-op/gocron/v2"
)

func main() {
	// create a scheduler
	s, err := gocron.NewScheduler()
	if err != nil {
		// handle error
	}

	// add a job to the scheduler
	j, err := s.NewJob(
		gocron.DurationJob(
			10*time.Second,
		),
		gocron.NewTask(
			func(a string, b int) {
				// do things
			},
			"hello",
			1,
		),
	)
	if err != nil {
		// handle error
	}
	// each job has a unique id
	fmt.Println(j.ID())

	// start the scheduler
	s.Start()

	// block until you are ready to shut down
	select {
	case <-time.After(time.Minute):
	}

	// when you're done, shut it down
	err = s.Shutdown()
	// or for context-aware teardown: 
	// err = s.ShutdownWithContext(ctx)
	if err != nil {
		// handle error
	}
}
```

## Examples

- [Go doc examples](https://pkg.go.dev/github.com/go-co-op/gocron/v2#pkg-examples)
- [Examples directory](examples)

## Articles & Blog Posts

Community articles and tutorials about using gocron:

- [Building a dynamic, highly available scheduler in Go](https://tech.efg.gg/posts/2025/highly-available-scheduler-in-go/) - A deep dive into building a highly available scheduler using gocron, MongoDB change streams, and leader election patterns for the FACEIT Watch platform.

## Concepts

- **Job**: The job encapsulates a "task", which is made up of a go function and any function parameters. The Job then
  provides the scheduler with the time the job should next be scheduled to run.
- **Scheduler**: The scheduler keeps track of all the jobs and sends each job to the executor when
  it is ready to be run.
- **Executor**: The executor calls the job's task and manages the complexities of different job
  execution timing requirements (e.g. singletons that shouldn't overrun each other, limiting the max number of jobs running)


## Features

### Job types
Jobs can be run at various intervals.
- [**Duration**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#DurationJob):
Jobs can be run at a fixed `time.Duration`.
- [**Random duration**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#DurationRandomJob):
Jobs can be run at a random `time.Duration` between a min and max.
- [**Cron**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#CronJob):
Jobs can be run using a crontab.
- [**Daily**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#DailyJob):
Jobs can be run every x days at specific times.
- [**Weekly**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WeeklyJob):
Jobs can be run every x weeks on specific days of the week and at specific times.
- [**Monthly**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#MonthlyJob):
Jobs can be run every x months on specific days of the month and at specific times.
- [**One time**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#OneTimeJob):
Jobs can be run at specific time(s) (either once or many times).

### Interval Timing
Jobs can be scheduled with different interval timing modes.
- [**Interval from scheduled time (default)**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#DurationJob):
By default, jobs calculate their next run time from when they were scheduled to start, resulting in fixed intervals 
regardless of execution time. Good for cron-like scheduling at predictable times.
- [**Interval from completion time**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithIntervalFromCompletion):
Jobs can calculate their next run time from when they complete, ensuring consistent rest periods between executions.
Ideal for rate-limited APIs, resource-intensive jobs, and scenarios where execution time varies.

### Concurrency Limits
Jobs can be limited individually or across the entire scheduler.
- [**Per job limiting with singleton mode**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithSingletonMode):
Jobs can be limited to a single concurrent execution that either reschedules (skips overlapping executions)
or queues (waits for the previous execution to finish).
- [**Per scheduler limiting with limit mode**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithLimitConcurrentJobs):
Jobs can be limited to a certain number of concurrent executions across the entire scheduler
using either reschedule (skip when the limit is met) or queue (jobs are added to a queue to
wait for the limit to be available).
- **Note:** A scheduler limit and a job limit can both be enabled.

### Distributed instances of gocron
Multiple instances of gocron can be run.
- [**Elector**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithDistributedElector):
An elector can be used to elect a single instance of gocron to run as the primary with the
other instances checking to see if a new leader needs to be elected.
  - Implementations: [go-co-op electors](https://github.com/go-co-op?q=-elector&type=all&language=&sort=)
    (don't see what you need? request on slack to get a repo created to contribute it!)
- [**Locker**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithDistributedLocker):
A locker can be used to lock each run of a job to a single instance of gocron.
Locker can be at job or scheduler, if it is defined both at job and scheduler then locker of job will take precedence.
  - See Notes in the doc for [Locker](https://pkg.go.dev/github.com/go-co-op/gocron/v2#Locker) for
    details and limitations of the locker design.
  - Implementations: [go-co-op lockers](https://github.com/go-co-op?q=-lock&type=all&language=&sort=)
    (don't see what you need? request on slack to get a repo created to contribute it!)

### Events
Job events can trigger actions.
- [**Listeners**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithEventListeners):
Can be added to a job, with [event listeners](https://pkg.go.dev/github.com/go-co-op/gocron/v2#EventListener),
or all jobs across the
[scheduler](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithGlobalJobOptions)
to listen for job events and trigger actions.

### Options
Many job and scheduler options are available.
- [**Job options**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#JobOption):
Job options can be set when creating a job using `NewJob`.
- [**Global job options**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithGlobalJobOptions):
Global job options can be set when creating a scheduler using `NewScheduler`
and the `WithGlobalJobOptions` option.
- [**Scheduler options**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#SchedulerOption):
Scheduler options can be set when creating a scheduler using `NewScheduler`.

### Logging
Logs can be enabled.
- [Logger](https://pkg.go.dev/github.com/go-co-op/gocron/v2#Logger):
The Logger interface can be implemented with your desired logging library.
The provided NewLogger uses the standard library's log package.

### Metrics
Metrics may be collected from the execution of each job and scheduler lifecycle events.
- [**Monitor**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#Monitor):
A monitor can be used to collect metrics for each job from a scheduler.
  - Implementations: There are currently no open source implementations of the Monitor interface available.
    We'd love for you to be the first to contribute one! Check out the [Monitor interface documentation](https://pkg.go.dev/github.com/go-co-op/gocron/v2#Monitor)
    to get started, or reach out on [Slack](https://gophers.slack.com/archives/CQ7T0T1FW) if you'd like to discuss your implementation.
- [**MonitorStatus**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#MonitorStatus):
Extends Monitor with status and error tracking for each job.
  - Implementations: There are currently no open source implementations of the MonitorStatus interface available.
    We'd love for you to be the first to contribute one! Check out the [MonitorStatus interface documentation](https://pkg.go.dev/github.com/go-co-op/gocron/v2#MonitorStatus)
    to get started, or reach out on [Slack](https://gophers.slack.com/archives/CQ7T0T1FW) if you'd like to discuss your implementation.
- [**SchedulerMonitor**](https://pkg.go.dev/github.com/go-co-op/gocron/v2#SchedulerMonitor):
A scheduler monitor provides comprehensive observability into scheduler and job lifecycle events.

  **Available Metrics:**
  - **Scheduler Lifecycle**: `SchedulerStarted`, `SchedulerStopped`, `SchedulerShutdown`
  - **Job Management**: `JobRegistered`, `JobUnregistered` - track jobs added/removed from scheduler
  - **Job Execution**: `JobStarted`, `JobRunning`, `JobCompleted`, `JobFailed` - monitor job execution flow
  - **Performance**: `JobExecutionTime`, `JobSchedulingDelay` - measure job duration and scheduling lag
  - **Concurrency**: `ConcurrencyLimitReached` - detect when singleton or limit mode constraints are hit

  **Derived Metrics** (calculable from events):
  - Error rate: `JobFailed / (JobCompleted + JobFailed)`
  - Average execution time: from `JobExecutionTime` events
  - Active jobs: `JobRegistered - JobUnregistered`
  - Current queue depth: `JobStarted - (JobCompleted + JobFailed)`

  **Example - Prometheus Integration:**
  ```go
  type PrometheusMonitor struct {
      jobsCompleted   prometheus.Counter
      jobsFailed      prometheus.Counter
      executionTime   prometheus.Histogram
      schedulingDelay prometheus.Histogram
  }

  func (p *PrometheusMonitor) JobExecutionTime(job gocron.Job, duration time.Duration) {
      p.executionTime.Observe(duration.Seconds())
  }

  func (p *PrometheusMonitor) JobSchedulingDelay(job gocron.Job, scheduled, actual time.Time) {
      if delay := actual.Sub(scheduled); delay > 0 {
          p.schedulingDelay.Observe(delay.Seconds())
      }
  }

  // Initialize scheduler with monitor
  s, _ := gocron.NewScheduler(gocron.WithSchedulerMonitor(monitor))
  ```

  **Use Cases:** Prometheus metrics, custom dashboards, alerting systems, performance monitoring

  - Implementations: There are currently no open source implementations of the SchedulerMonitor interface available.
    We'd love for you to be the first to contribute one! Check out the [SchedulerMonitor interface documentation](https://pkg.go.dev/github.com/go-co-op/gocron/v2#SchedulerMonitor)
    to get started, or reach out on [Slack](https://gophers.slack.com/archives/CQ7T0T1FW) if you'd like to discuss your implementation.

### Testing
The gocron library is set up to enable testing.
- Mocks are provided in [the mock package](mocks) using [gomock](https://github.com/uber-go/mock).
- Time can be mocked by passing in a [FakeClock](https://pkg.go.dev/github.com/jonboulle/clockwork#FakeClock)
to [WithClock](https://pkg.go.dev/github.com/go-co-op/gocron/v2#WithClock) -
see the [example on WithClock](https://pkg.go.dev/github.com/go-co-op/gocron/v2#example-WithClock).

## Supporters

We appreciate the support for free and open source software!

This project is supported by:

[JetBrains](https://www.jetbrains.com/?from=gocron)

<a href="https://www.jetbrains.com/?from=gocron">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="assets/jetbrains-mono-white.png" />
   <source media="(prefers-color-scheme: light)" srcset="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.png" />
   <img alt="JetBrains logo" src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.png" />
 </picture>
</a>

[Sentry](https://sentry.io/welcome/)

<a href="https://sentry.io/?utm_source=github&utm_medium=logo">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="assets/sentry-wordmark-light-280x84.png" />
   <source media="(prefers-color-scheme: light)" srcset="https://sentry-brand.storage.googleapis.com/sentry-wordmark-dark-280x84.png" />
   <img alt="Sentry logo" src="https://sentry-brand.storage.googleapis.com/sentry-wordmark-dark-280x84.png" />
 </picture>
</a>

## Star History

<a href="https://www.star-history.com/#go-co-op/gocron&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=go-co-op/gocron&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=go-co-op/gocron&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=go-co-op/gocron&type=Date" />
 </picture>
</a>


gocron

A simple but powerful DAG scheduler and dashboard

![Build Status](https://github.com/fieldryand/goflow/actions/workflows/go.yml/badge.svg)
[![codecov](https://codecov.io/gh/fieldryand/goflow/branch/master/graph/badge.svg)](https://codecov.io/gh/fieldryand/goflow)
[![Go Report Card](https://goreportcard.com/badge/github.com/fieldryand/goflow)](https://goreportcard.com/report/github.com/fieldryand/goflow)
[![GoDoc](https://pkg.go.dev/badge/github.com/fieldryand/goflow/v2?status.svg)](https://pkg.go.dev/github.com/fieldryand/goflow/v2?tab=doc)
[![Release](https://img.shields.io/github/v/release/fieldryand/goflow)](https://github.com/fieldryand/goflow/releases)

# Goflow

A simple but powerful DAG scheduler and dashboard, written in Go.

![goflow-demo](https://user-images.githubusercontent.com/3333324/147818084-ade84547-4404-4d58-a697-c18ecb06fd30.gif)

------

**Use it if:**
- you need a directed acyclic graph (DAG) scheduler like Apache Airflow, but without the complexity.
- you have a variety of clusters or services performing heavy computations and you want something small and light to orchestrate them.
- you want a monitoring dashboard.
- you want the easiest possible deployment with a single binary or container, saving you time. Volume mounts etc are too much headache.
- you want it to run on a single tiny VM, saving on cloud costs.
- you want to choose your storage technology--embedded, Postgres, Redis, S3, DynamoDB or something else.
- you prefer to define your DAGs with code rather than configuration files. This approach can make it easier to manage complex DAGs.

**Don't use it if:**
- you need to queue a huge number of tasks. Goflow is not tested at massive scale and does not support horizontal scaling.

## Contents

- [Quick start](#quick-start)
   - [With Docker](#with-docker)
   - [Without Docker](#without-docker)
- [Development overview](#development-overview)
   - [Jobs and tasks](#jobs-and-tasks)
   - [Custom Operators](#custom-operators)
   - [Retries](#retries)
   - [Task dependencies](#task-dependencies)
   - [Trigger rules](#trigger-rules)
   - [The Goflow engine](#the-goflow-engine)
   - [Available operators](#available-operators)
- [Storage](#storage)
- [API and integration](#api-and-integration)

## Quick start

### With Docker

```shell
docker run -p 8181:8181 ghcr.io/fieldryand/goflow-example:latest
```

Check out the dashboard at `localhost:8181`.

### Without Docker

In a fresh project directory:

```shell
go mod init # create a new module
go get github.com/fieldryand/goflow/v2 # install dependencies
```

Create a file `main.go` with contents:
```go
package main

import "github.com/fieldryand/goflow/v2"

func main() {
        options := goflow.Options{
                UIPath: "ui/",
                ShowExamples:  true,
                WithSeconds:  true,
        }
        gf := goflow.New(options)
        gf.Use(goflow.DefaultLogger())
        gf.Run(":8181")
}
```

Download and untar the dashboard:

```shell
wget https://github.com/fieldryand/goflow/releases/latest/download/goflow-ui.tar.gz
tar -xvzf goflow-ui.tar.gz
rm goflow-ui.tar.gz
```

Now run the application with `go run main.go` and see it in the browser at localhost:8181.

## Development overview

First a few definitions.

- `Job`: A Goflow workflow is called a `Job`. Jobs can be scheduled using cron syntax.
- `Task`: Each job consists of one or more tasks organized into a dependency graph. A task can be run under certain conditions; by default, a task runs when all of its dependencies finish successfully.
- Concurrency: Jobs and tasks execute concurrently.
- `Operator`: An `Operator` defines the work done by a `Task`. Goflow comes with a handful of basic operators, and implementing your own `Operator` is straightforward.
- Retries: You can allow a `Task` a given number of retry attempts. Goflow comes with two retry strategies, `ConstantDelay` and `ExponentialBackoff`.
- Streaming: Goflow uses server-sent events to stream the status of jobs and tasks to the dashboard in real time.

### Jobs and tasks

Let's start by creating a function that returns a job called `my-job`. There is a single task in this job that sleeps for one second.

```go
package main

import (
	"errors"

	"github.com/fieldryand/goflow/v2"
)

func myJob() *goflow.Job {
	j := &goflow.Job{Name: "my-job", Schedule: "* * * * *", Active: true}
	j.Add(&goflow.Task{
		Name:     "sleep-for-one-second",
		Operator: goflow.Command{Cmd: "sleep", Args: []string{"1"}},
	})
	return j
}
```

By setting `Active: true`, we are telling Goflow to apply the provided cron schedule for this job when the application starts.
Job scheduling can be activated and deactivated from the dashboard.

### Custom operators

A custom `Operator` needs to implement the `Run` method. Here's an example of an operator that adds two positive numbers.

```go
type PositiveAddition struct{ a, b int }

func (o PositiveAddition) Run() (interface{}, error) {
	if o.a < 0 || o.b < 0 {
		return 0, errors.New("Can't add negative numbers")
	}
	result := o.a + o.b
	return result, nil
}
```

### Retries

Let's add a retry strategy to the `sleep-for-one-second` task:

```go
func myJob() *goflow.Job {
	j := &goflow.Job{Name: "my-job", Schedule: "* * * * *"}
	j.Add(&goflow.Task{
		Name:       "sleep-for-one-second",
		Operator:   goflow.Command{Cmd: "sleep", Args: []string{"1"}},
		Retries:    5,
		RetryDelay: goflow.ConstantDelay{Period: 1},
	})
	return j
}
```

Instead of `ConstantDelay`, we could also use `ExponentialBackoff` (see https://en.wikipedia.org/wiki/Exponential_backoff).

### Task dependencies

A job can define a directed acyclic graph (DAG) of independent and dependent tasks. Let's use the `SetDownstream` method to
define two tasks that are dependent on `sleep-for-one-second`. The tasks will use the `PositiveAddition` operator we defined earlier,
as well as a new operator provided by Goflow, `Get`.

```go
func myJob() *goflow.Job {
	j := &goflow.Job{Name: "my-job", Schedule: "* * * * *"}
	j.Add(&goflow.Task{
		Name:       "sleep-for-one-second",
		Operator:   goflow.Command{Cmd: "sleep", Args: []string{"1"}},
		Retries:    5,
		RetryDelay: goflow.ConstantDelay{Period: 1},
	})
	j.Add(&goflow.Task{
		Name:       "get-google",
		Operator:   goflow.Get{Client: &http.Client{}, URL: "https://www.google.com"},
	})
	j.Add(&goflow.Task{
		Name:       "add-two-plus-three",
		Operator:   PositiveAddition{a: 2, b: 3},
	})
	j.SetDownstream(j.Task("sleep-for-one-second"), j.Task("get-google"))
	j.SetDownstream(j.Task("sleep-for-one-second"), j.Task("add-two-plus-three"))
	return j
}
```

### Trigger rules

By default, a task has the trigger rule `allSuccessful`, meaning the task starts executing when all the tasks directly
upstream exit successfully. If any dependency exits with an error, all downstream tasks are skipped, and the job exits with an error.

Sometimes you want a downstream task to execute even if there are upstream failures. Often these are situations where you want
to perform some cleanup task, such as shutting down a server. In such cases, you can give a task the trigger rule `allDone`.

Let's modify `sleep-for-one-second` to have the trigger rule `allDone`.


```go
func myJob() *goflow.Job {
	// other stuff
	j.Add(&goflow.Task{
		Name:        "sleep-for-one-second",
		Operator:    goflow.Command{Cmd: "sleep", Args: []string{"1"}},
		Retries:     5,
		RetryDelay:  goflow.ConstantDelay{Period: 1},
		TriggerRule: "allDone",
	})
	// other stuff
}
```

### The Goflow Engine

Finally, let's create a Goflow engine, register our job, attach a logger, and run the application.

```go
func main() {
	gf := goflow.New(goflow.Options{Streaming: true})
	gf.AddJob(myJob)
	gf.Use(goflow.DefaultLogger())
	gf.Run(":8181")
}
```

You can pass different options to the engine. Options currently supported:
- `Store`: This is [described in more detail below.](#storage)
- `UIPath`: The path to the dashboard code. The default value is an empty string, meaning Goflow serves only the API and not the dashboard. Suggested value if you want the dashboard: `ui/`
- `ShowExamples`: Whether to show the example jobs. Default value: `false`
- `WithSeconds`: Whether to include the seconds field in the cron spec. See the [cron package documentation](https://github.com/robfig/cron) for details. Default value: `false`

Goflow is built on the [Gin framework](https://github.com/gin-gonic/gin), so you can pass any Gin handler to `Use`.

### Available operators

Goflow provides several operators for common tasks. [See the package documentation](https://pkg.go.dev/github.com/fieldryand/goflow) for details on each.

- `Command` executes a shell command.
- `Get` makes a GET request.
- `Post` makes a POST request.

## Storage

For persisting your job execution history, Goflow allows you to plug in many different key-value stores thanks to the [excellent gokv package](https://github.com/philippgille/gokv/). This way you can recover from a crash or deploy a new version of your app without losing your data.

> Note: the gokv API is not yet stable. Goflow has been tested against v0.6.0.

By default, Goflow uses an in-memory database, but you can easily replace it with Postgres, Redis, S3 or any other `gokv.Store`. Here is an example:

```go
package main

import "github.com/fieldryand/goflow/v2"
import "github.com/philippgille/gokv/redis"

func main() {
        // create a storage client
        client, err := redis.NewClient(redis.DefaultOptions)
        if err != nil {
                panic(err)
        }
        defer client.Close()

        // pass the client as a Goflow option
        options := goflow.Options{
                Store: client,
                UIPath: "ui/",
                Streaming: true,
                ShowExamples:  true,
        }
        gf := goflow.New(options)
        gf.Use(goflow.DefaultLogger())
        gf.Run(":8181")
}
```


## API and integration

You can use the API to integrate Goflow with other applications, such as an existing dashboard. Here is an overview of available endpoints:
- `GET /api/health`: Check health of the service
- `GET /api/jobs`: List registered jobs
- `GET /api/jobs/{jobname}`: Get the details for a given job
- `GET /api/executions`: Query and list job executions
- `POST /api/jobs/{jobname}/submit`: Submit a job for execution
- `POST /api/jobs/{jobname}/toggle`: Toggle a job schedule on or off
- `/stream`: This endpoint returns Server-Sent Events with a `data` payload matching the one returned by `/api/executions`. The dashboard that ships with Goflow uses this endpoint.

Check out the OpenAPI spec for more details. Easiest way is to clone the repo, then within the repo use Swagger as in the following:

```shell
docker run -p 8080:8080 -e SWAGGER_JSON=/app/swagger.json -v $(pwd):/app swaggerapi/swagger-ui
```


goflow

ID-based debounced task scheduler for deferred tasks with cancellation, graceful shutdown, and optional concurrency limits

# pending

[![Go Reference](https://pkg.go.dev/badge/github.com/kahoon/pending.svg)](https://pkg.go.dev/github.com/kahoon/pending)
[![Go Report Card](https://goreportcard.com/badge/github.com/kahoon/pending)](https://goreportcard.com/report/github.com/kahoon/pending)
[![codecov](https://codecov.io/gh/kahoon/pending/branch/main/graph/badge.svg)](https://codecov.io/gh/kahoon/pending)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**pending** is a minimalist, context-aware deferred task scheduler for Go.

`pending` is designed for in-memory, ID-based deferred actions. It fits use cases like debouncing user input, handling hardware delays, or managing state-dependent timeouts.

![pending overview](assets/pending.png)

## Why pending?

- **Pure Go**: Built entirely on the standard library.
- **Simple API**: Core lifecycle methods plus optional introspection helpers.
- **Debouncing by ID**: Scheduling the same ID replaces the previous task.
- **Concurrency Limits**: Choose blocking or dropping behavior when at capacity.
- **Graceful Shutdown**: Cancel timers and wait for active tasks to finish.
- **Runtime Stats**: Read pending/running/status state via `Stats()`.
- **Task Introspection**: Check `IsPending()` and `TimeRemaining()` per task ID.
- **Pluggable Telemetry**: Attach your own metrics/logging hooks.

## Installation

```bash
go get github.com/kahoon/pending
```

## Quick Start

```go
mgr := pending.NewManager(
    pending.WithLimit(5, pending.StrategyDrop),
)

defer mgr.Shutdown(context.Background())

mgr.Schedule("user:42:email", 2*time.Second, func(ctx context.Context) {
    // send email reminder
})

// reschedule with same ID (debounce)
mgr.Schedule("user:42:email", 2*time.Second, func(ctx context.Context) {
    // send latest reminder payload
})
```

## Scheduling APIs

### Simple path: `Schedule`

Use `Schedule` for straightforward delayed execution with ID-based debouncing:

```go
mgr.Schedule("invoice:42:reminder", 10*time.Minute, func(ctx context.Context) {
    if ctx.Err() != nil {
        return
    }
    sendReminder("42")
})
```

### Advanced path: `ScheduleWith`

Use `ScheduleWith` when you need option-driven behavior such as absolute-time
scheduling and `IfAbsent` semantics:

```go
at := time.Now().Add(30 * time.Second)

scheduled, err := mgr.ScheduleWith(
    "report:nightly",
    func(ctx context.Context) error {
        return generateReport(ctx)
    },
    pending.ScheduleOptions{
        At:       at,
        IfAbsent: true,
    },
)
if err != nil {
    if errors.Is(err, pending.ErrInvalidScheduleOptions) {
        log.Printf("invalid scheduling options: %v", err)
    }
    if errors.Is(err, pending.ErrManagerNotAccepting) {
        log.Printf("manager is shutting down, task rejected")
    }
}
if !scheduled {
    log.Printf("task already exists and IfAbsent prevented replacement")
}
```

## Cookbook

### Debouncing User Events

```go
mgr := pending.NewManager()

func onSearchInput(userID, query string) {
    key := "search:" + userID
    mgr.Schedule(key, 300*time.Millisecond, func(ctx context.Context) {
        if ctx.Err() != nil {
            return
        }
        runSearch(query)
    })
}
```

### Resettable State Timeout

```go
mgr := pending.NewManager()

func onSessionActivity(sessionID string) {
    key := "session-timeout:" + sessionID
    mgr.Schedule(key, 15*time.Minute, func(ctx context.Context) {
        if ctx.Err() != nil {
            return
        }
        expireSession(sessionID)
    })
}
```

### Concurrency Limits (Drop)

```go
mgr := pending.NewManager(
    pending.WithLimit(5, pending.StrategyDrop),
)

for i := 0; i < 100; i++ {
    id := fmt.Sprintf("task_%d", i)
    mgr.Schedule(id, 1*time.Second, heavyDatabaseQuery)
}
```

When a task is dropped under `StrategyDrop`, your telemetry handler receives
`pending.ErrTaskDropped` via `OnFailed`, so you can match it with `errors.Is`.

### Delayed Retry with Cancellation

```go
mgr := pending.NewManager()

func scheduleRetry(jobID string, attempt int) {
    key := "retry:" + jobID
    delay := time.Duration(attempt) * time.Second

    mgr.Schedule(key, delay, func(ctx context.Context) {
        if ctx.Err() != nil {
            return
        }
        if err := sendWebhook(jobID); err != nil {
            scheduleRetry(jobID, attempt+1)
        }
    })
}

// Stop any pending retry if the job succeeds elsewhere.
func onJobSucceeded(jobID string) {
    mgr.Cancel("retry:" + jobID)
}
```

### Safe Service Shutdown Wiring in `main()`

```go
func main() {
    mgr := pending.NewManager()
    defer func() {
        ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        _ = mgr.Shutdown(ctx)
    }()

    sig := make(chan os.Signal, 1)
    signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)
    defer signal.Stop(sig)

    go runHTTPServer(mgr)

    <-sig
    log.Println("signal received, draining pending tasks")
}
```

### Manual Cancellation

```go
mgr := pending.NewManager()

mgr.Schedule("user_123_unlock", 30*time.Minute, unlockTask)

// User was unlocked manually, no need to run delayed task.
mgr.Cancel("user_123_unlock")
```

### Runtime Stats

```go
s := mgr.Stats()
log.Printf("pending=%d running=%d status=%s", s.Pending, s.Running, s.Status)
```

### Task Introspection

```go
if mgr.IsPending("retry:order-42") {
    remaining := mgr.TimeRemaining("retry:order-42")
    log.Printf("retry is still pending, timer fires in %s", remaining)
}
```

`TimeRemaining` reports time until the task's timer fires. It returns `0` if
the task is missing or already started.

## Benchmarks

Run benchmarks:

```bash
go test -run ^$ -bench BenchmarkManager_ -benchmem ./...
```

Sample output (darwin/arm64, Apple M4):

```text
BenchmarkManager_Schedule-10                     	  969188	       293.8 ns/op	     473 B/op	       6 allocs/op
BenchmarkManager_RescheduleSameID-10             	 1502884	       158.6 ns/op	     304 B/op	       5 allocs/op
BenchmarkManager_Cancel-10                       	 1280494	       188.9 ns/op	     311 B/op	       5 allocs/op
BenchmarkManager_Shutdown_NoRunningTasks-10      	   75316	      3226 ns/op	      16 B/op	       1 allocs/op
BenchmarkManager_Shutdown_WithRunningTasks-10    	   44101	      5451 ns/op	      16 B/op	       1 allocs/op
```

Results will vary by hardware, OS, and Go version.

## Scope

`pending` is not a cron replacement. It is intentionally focused on in-process deferred work with ID-based replacement and cancellation.

## Community

- Contributing guide: [CONTRIBUTING](CONTRIBUTING.md)
- Security policy: [SECURITY](SECURITY.md)
- Code of Conduct: [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md)
- Changelog: [CHANGELOG](CHANGELOG.md)

## License

MIT. See [LICENSE](LICENSE).


pending

Go-native distributed job scheduler with delayed tasks, batched Redis coordination, retries, lease-based recovery, and versioned queue partitioning

A simple crontab like scheduler that aims to offer a KISS approach to job scheduling

<img src="docs/static/cheek-v2.svg" alt="cheek" />

# cheek

![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/bart6114/cheek?label=version)
![workflow](https://github.com/bart6114/cheek/actions/workflows/ci.yml/badge.svg)
[![Go Report Card](https://goreportcard.com/badge/github.com/bart6114/cheek)](https://goreportcard.com/report/github.com/bart6114/cheek)
[![Go Reference](https://pkg.go.dev/badge/github.com/bart6114/cheek.svg)](https://pkg.go.dev/github.com/bart6114/cheek)
[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/avelino/awesome-go)
![love](https://img.shields.io/badge/made_with-%E2%9D%A4%EF%B8%8F-blue)

`cheek` is a pico-sized declarative job scheduler designed to excel in a single-node environment. `cheek` aims to be lightweight, stand-alone and simple. It does not compete for robustness.

## Quick Start

Fetch the latest version for your system:

[darwin-arm64](https://github.com/bart6114/cheek/releases/latest/download/cheek-darwin-arm64) |
[darwin-amd64](https://github.com/bart6114/cheek/releases/latest/download/cheek-darwin-amd64) |
[linux-386](https://github.com/bart6114/cheek/releases/latest/download/cheek-linux-386) |
[linux-arm64](https://github.com/bart6114/cheek/releases/latest/download/cheek-linux-arm64) |
[linux-amd64](https://github.com/bart6114/cheek/releases/latest/download/cheek-linux-amd64)

```sh
curl -L https://github.com/bart6114/cheek/releases/latest/download/cheek-darwin-amd64 -o cheek
chmod +x cheek
./cheek run schedule.yaml
```

## Documentation

For comprehensive documentation, configuration options, examples, and advanced features, visit:

**📚 [cheek.barts.space](https://cheek.barts.space)**

## Acknowledgements

`cheek` is building on top of many great OSS assets. Notable thanks goes to:

- [gronx](https://github.com/adhocore/gronx): for allowing me not to worry about CRON strings.

<br/>
 
![GitHub Contributors](https://contrib.rocks/image?repo=bart6114/cheek)


The Best Go Libraries For Job Scheduler (21)

go-cron

JobRunner

leprechaun

jobs

sched

cdule

cheek

gron

gronx

clockwerk

cronticker

tasks

scheduler

go-job

go-quartz

go-scheduler

gocron

goflow

pending

scheduler

cheek