linkorb/commando

Commando: Execute Commands from Queues

Commando

Commando is a generic job-runner., _(*1)

You can define your own commands in Json or Yaml files, and process jobs from different stores such as a directory of files, or a database., _(*2)

It's goal is to make it easy to implement background jobs into your application., _(*3)

An example workflow:, _(*4)

1. You define a command "hello" in commando.yml:

commands:
  hello:
    template: echo "Hello {{ greeted }}"
    inputs:
      greeted:
        default: world

1. Your app writes a job into /your/commando-path/new called 1.json:

{
  "command": "hello",
  "inputs": {
    "greeted": "universe"
  }
}

1. You (or cron) runs commando run.
2. Commando will check for new job files in the configured store (in this case a directory), execute the command, replacing arguments in the template with the passed job arguments, finally executing echo "Hello universe"
3. Commando reports the job status back to the store, including exit codes, start/end times, total duration, and stdout and stderr
4. Your app reports back to the user if needed, based on the status report.

Stores:

• JsonDirJobStore: Manages jobs through json files with a simple directory structure
• PdoJobStore: Manages jobs through a database table
• CamundaJobStore: Camunda External Task client

Use-cases

You can replace the template with much more complex command-lines or shell-scripts., _(*5)

Your app should treat these jobs as "fire-and-forget", meaning the app should not block, waiting for response. It's most ideal in scenarios where your triggers commands and doesn't need to know about the response right away:, _(*6)

Examples:, _(*7)

• Update PDFs or reports in the background
• Send emails and notifications
• Create a database backup
• Process uploaded image files
• ...etc

Conventional Commits

This repository is using Conventional Commits, _(*8)

Please run npm install at least once, in order to install the appropriate tooling and git hooks (this helps you to follow the conventions by linting them before actually committing)., _(*9)

In short: you should prefix your commit titles with the correct type (i.e. feat: my new cool feature). This helps to create clear commit histories, automatically handles semver, tagging and CHANGELOG.md generation., _(*10)

If you'd like to reference a card in our planning system, simply add a #123 to the end of your commit title. The card will be correctly linked from the changelogs etc., _(*11)

To publish a new release, simply run npm run publish. This will update the changelog, and manifests like composer.json, package.json, etc to a new tag. The tag follows Semver, and is selected based on your commit types since the last release., _(*12)

License

Please refer to the included LICENSE.md file, _(*13)

Brought to you by the LinkORB Engineering team

Check out our other projects at engineering.linkorb.com., _(*14)

Btw, we're hiring!, _(*15)