Jobba

Jobba the Hub, a job scheduler and runner.

Description

Jobba is a wrapper around Bull, which makes it a lot easier to work with (at least for our uses). It is written in TypeScript and used internally by Whitebox. It has an exposed HTTP API built upon Yawk, a great HTTP router and server. It also serves a simple management interface, (our fork of) Arena.

Terminology

• Jobba: The job hub itself, which is what you register and schedule Tasks with.
  • Jobba#register returns a Task.
• Task: Handlers that you register, which can be scheduled to run (creating a Job).
  • Task#schedule schedules the run of a Task.
  • Upon run, a Job is created and passed to the Task's handler.
• Job: A scheduled Task, which can be a one-off run of its handler or a recurring run.

Usage

Setup

import Jobba, { Job, JobbaConfig } from 'jobba';

const config: JobbaConfig = {
    yawk: {
        port: 5000
    }
};

function registrar(jobba: Jobba) {
    jobba.register({
        id: 'some-task',
        handler: async (job: Job) => {
            await job.log('The params passed to this job:', job.params);
            return 'some response';
        }
    });
}

const jobba = new Jobba(config, registrar);
jobba.start();

NOTE: The Job and JobbaConfig type annotations are not needed, but are shown for clarity.

There are three ways to interact with Jobba:

1. the Node.js module
2. the HTTP API
3. the front-end

Module

// one-off run
jobba.schedule('some-task', { some: 'params' });

// recurring run
jobba.schedule('some-task', { some: 'params' }, {
    repeat: { cron: '0 * * * *' }
});

HTTP API

The API is served at /api. GET /api/routes returns a list of endpoints and in some cases their descriptions or expected input and output schemas.

The most important endpoint is POST /api/tasks/${taskId}/schedule, which supports passing optional params and options like in this example:

{
    "options": {
        "repeat": {
            "cron": "0 * * * *"
        }
    },
    "params": {
        "some": "params"
    }
}

Front-end

The front-end is served at /. In its current state it is quite simplistic, and is mostly read-only for now. You cannot yet schedule tasks, though you can see details about completed/failed tasks as well as cancel scheduled ones.

Features

Returns

Tasks do not need to return anything. Their return values are indeed reflected in the front-end, but in practice most of our tasks don't return anything.

Errors

Any errors thrown are captured and reflected in the front-end as well, with their error message and stack trace.

jobba.register({
    id: 'some-task',
    handler: (job: Job) => {
        throw new Error('uh oh...');
    }
});

Logging

Logs are recorded with their log level, a timestamp, and their contents.

jobba.register({
    id: 'some-task',
    handler: async (job: Job) => {
        await job.log('Logging can be convenient.');
        await job.info('Logging can be informative.');
        await job.debug('Logging can be introspective.');
        await job.warn('Logging can be dangerous.');
        await job.error('Logging can be unfortunate.');

        await job.log('logs', 'support', 'infinite', 'arguments');
        await job.log('logs', 'support', [ 'various' ], { types: true });
    }
});

Creating a Job subclass

export class MyCustomJob extends Job {

    public async init(): Promise<any> {
        // Code here executed before the job's `process` function is invoked. 
    }

    public async process(): Promise<any> {
        // Do some processing work...
    }

    public async onProcessCompleted(): Promise<any> {
        // The `process` function has completed.
        // Can use this function for cleanup, logging, etc.
    }

}

Misc

jobba.register({
    id: 'some-task',
    handler: async (job: Job) => {
        // you can set progress
        await job.progress(40)
    }
});