prodda

README

prodda

Prods tasks on schedule.

Overview

Tasks are scheduled using the extended cron syntax:

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

API reference

Root Endpoint

The root endpoint for the API is at /api/v0. All endpoints are nested below this path.

Authentication and authorization

All API requests must be made using basic authentication e.g:

curl https://username:password@127.0.0.1/api/v0/

Tasks endpoint

The endpoint for managing tasks is found at /tasks/.

Get all tasks

curl -XGET /tasks/

Create new task

The contents of the request body for creating a new task must contain a schedule field, the contents of which must be valid cron syntax, as well as sufficient information to create or update a task. This additional information varies by task type; see supported tasks for further information.

curl -XPOST /tasks/ -d '{<task-body-as-json>}'

Get specific task

curl -XGET /tasks/:id

Update existing task

The contents of the request body for updates must contain a schedule field, the contents of which must be valid cron syntax. Updating attributes of a task is not currently supported - instead the recommended approach is to delete the task and create a new one with the desired attributes.

curl -XPUT /tasks/:id -d '{<updated-task-body-as-json>}'

Delete existing task

curl -XDELETE /tasks/:id

<a name="supported-tasks" Supported tasks

Prodda supports multiple task types.

Travis builds

All travis tasks require a travis token. This can be obtained via the following:

gem install travis && travis login && travis token

More detailed information can be found on the official travis blog.

Re-running an existing travis build

Re-running a specific travis build can be accomplished by creating a new task with the following body:

{
  "schedule":"15 03 * * *",
  "type": "travis-re-run",
  "token":"my-travis-token",
  "buildID":123456789
}

URL Get

A URL Get task is one which will perform an get request to the specified URL, logging the response and any errors encountered. The URL should be fully-formed, including the protocol.

Running a url-get task can be achieved by creating a task with the following body:

{
  "schedule":"15 03 * * *",
  "type": "url-get",
  "url": "http://localhost/"
}

No-op

A no-op task is one which will log its start and finish points, sleeping for a configurable duration in between.

The duration is optional; it will default to zero if not present. If it is present then it must comply with the time.ParseDuration specification:

ParseDuration parses a duration string.

A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m".

Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

Running a no-op task can be achieved by creating a task with the following body:

{
  "schedule":"15 03 * * *",
  "type": "no-op",
  "sleepDuration": "1m"
}

Supported Golang versions

The code is tested against the latest version of golang 1.4.

Getting the code

The develop branch is where active development takes place; it is not guaranteed that any given commit will be stable.

The master branch points to a stable commit. All tests should pass.

Dependency management

Dependencies are managed via godep. To ensure the dependencies are correct, run godep restore. Adding a new dependency requires running godep save; the resultant changes in the Godeps/ directory must be committed.

Git hooks

To set up git hooks, run the following command:

./scripts/install-git-hooks

This will need to be re-run if any new git hooks are added, but not if existing ones change.

Running tests

Running the tests will require ginkgo and gomega:

go get github.com/onsi/ginkgo/ginkgo
go get github.com/onsi/ginkgo/gomega

In the cloned directory run the following command:

ginkgo -p -r -race -failOnPending -randomizeAllSpecs

Contributing

The upcoming work for prodda can be found on Pivotal Tracker.

Rull-requests are welcome; please make them against the develop branch. Please also include ginkgo tests. Multiple small commits are preferred over a single monolithic commit.