timdaub / at-bindings

A bindings library for datetime-based task scheduling on Linux and Mac OS.

at-bindings

A bindings library for datetime-based task scheduling on POSIX operating systems.

Requirements

• Run on POSIX/UNIX operating system

Installation

Mac OS X Prerequisites

Unfortunately, Mac OS X's date utility exposes a different API than its GNU counterpart. For this tool, I went with supporting the GNU version. On a Mac, this means you'll have to do the following

1. Enable at on Mac OS X
2. Install GNU date through coreutils

For verification:

$ gdate --version
date (GNU coreutils) 8.31
Copyright (C) 2019 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by David MacKenzie.

Installing the package

$ npm install --save at-bindings

Usage

schedule(command, dateVal)

const { schedule } = require("at-bindings");

// Prints "hello world" in 1 minutes from now
const job = schedule("echo hello", "+ 1 minutes")
console.log(job);

{
  id: 141,
  date: { plain: '2020-06-24T13:25:00.000Z', obj: 2020-06-11T09:31:00.000Z }
}

NOTE: schedule's second argument (dateVal) accepts the following date format syntax:

• output of date -d
• ISO 8601 e.g. from new Date().toISOString()

schedule throws...

• ScheduleError when the input date is in the past.

list()

const { list } = require("at-bindings");

// Lists all jobs currently scheduled on the system
const jobs = list();
console.log(jobs);

[{
  id: 141,
  date: { plain: '2020-06-24T13:25:00.000Z', obj: 2020-06-11T09:31:00.000Z }
}]

remove(jobId)

const { remove } = require("at-bindings");

// Removes a job for a given id
remove(1234);

NOTE: Function throws IndexError if jobId wasn't found.

getContent(jobId)

const { getContent } = require("at-bindings");

const content = getContent(1);
console.log(content);

> #!/bin/sh
> # atrun uid=501 gid=20
> ...

In cases where no job could be found or where the job content equals the empty string, an IndexError is thrown.

exists(jobId)

const { exists, schedule } = require("at-bindings");

const res = exists(schedule("echo hello", "+ 1 minutes").id);
console.log(res);

> true

console.log(exists(1337));

> false

Custom Error Types

at-binding extends JavaScript with two custom errors. To match them e.g. with instanceof, they can be imported using:

const { ScheduleError, IndexError } = require("at-bindings");

FAQ

Why use this library over other solutions?

at-bindings uses the unix system's atd service to schedule tasks, which I imagine to be a fairly failure-safe system.

Is this library safe?

at-bindings doesn't sanitize any inputs (e.g. in the schedule function). Hence, if you pass user input to it, injections may be possible. Please take care of sanitizing your inputs! Help/feedback is appreciated.

Changelog

0.3.0

• getContent(jobId) now throws when no job is found or content of job is falsy (breaking change).
• Using schedule with ISO 8601 dates is now officially supported.

0.2.3

• Previously:

require("at-bindings").schedule("echo hello", new Date())

would work on Ubuntu, but gdate (Mac OS) would throw an error: at: trying to travel back in time. By checking for minutal differences, both operating systems should now throw on the above statement.

0.2.2

• For outputs of at -l that include a user name e.g. "... a root", at-binding's job parser can now read these too.

0.2.1

• Export IndexError

0.2.0

• remove(jobId) now throws an IndexError on non-existent jobs

0.1.2

• Add exists(jobId) function
• Add getContent(jobId) function
• Added more tests
• Documented all functions in README.md

0.1.1

• Add remove(jobId) function

0.1.0

• job object of list and schedule now returns a job.date.plain as a ISO8601 string.

0.0.4

• Add ScheduleError to interrupt on dates schedules in the past.

0.0.3

• Fix problem with schedule. Command argument was executed twice.

0.0.2

• Implement list function

0.0.1

• Implement schedule and shift functions

License

MIT

References

• Enable at on Mac OS X
• Overview of command posibilities with at
• Install GNU date through coreutils on Mac OS
• Online man page of date

at-bindings's Issues

TODOs for MVP

Implementation:

• List all jobs
• Remove/cancel a job
• Get/Inspect a job. See #3
• On startup, check if atd is running on the machine
• Setup test runner (e.g. Travis, GitHub Actions, ...)

Research:

• Are atd jobs persisted regularly. In case a machine crashes or reboots, are the jobs still available and will the reliably be executed?

Fix tests to that GH Actions run smoothly

schedule drops quotes in commands

> const { schedule } = require("at-bindings");
undefined
> schedule(`"bla"`, "now + 5 minutes")
{
  id: 265,
  date: { plain: 'Thu Jun 18 14:05:00 2020', obj: 2020-06-18T12:05:00.000Z }
}
>

$ at -c 265
bla

(quotes are gone)

Get content of specific job

Useful:

$ at -c <jobid>

https://serverfault.com/a/174680

linux returns "Cannot find jobid 3" when job cannot be found, mac os doesn't

tag releases in git

In schedule, command is executed twice

• Execution happens when scheduling happens and at the datetime when the command is intended to run.

When no job is found, Ubuntu is throwing an error whereas mac os isn't

Unix and Mac os react differently to scheduling a date "now"

# ubuntu
root@box:~/box# node
Welcome to Node.js v14.5.0.
Type ".help" for more information.
> require("at-bindings").schedule("echo hello", new Date())
{
  id: 86,
  date: { plain: '2020-10-26T15:50:00.000Z', obj: 2020-10-26T15:50:00.000Z }
}
> 
root@box:~/box# logout
Connection to bla.de closed.

# Mac OS
~/Projects/box   master ●  node
Welcome to Node.js v13.9.0.
Type ".help" for more information.
> require("at-bindings").schedule("echo hello", new Date())
Uncaught ScheduleError: schedule expectes a datetime in the future
    at Object.schedule (/Users/timdaub/Projects/box/node_modules/at-bindings/src/schedule.js:90:11) {
  name: 'ScheduleError'
}
> 

Date in job object isn't ISO compatible