odd-jobs-0.2.1: A full-featured PostgreSQL-backed job queue (with an admin UI)

Safe HaskellNone
LanguageHaskell2010

OddJobs.Cli

Contents

Synopsis

Introduction

This module has a bunch of functions (that use the 'optparse-applicative' library) to help you rapidly build a standalone job-runner deamon based on odd-jobs. You should probably start-off by using the pre-packaged default behaviour, notably the defaultMain function. If the default behaviour of the resultant CLI doesn't suit your needs, consider reusing/extending the individual argument parsers. If you find you cannot reuse those, then it would be best to write your CLI from scratch instead of force-fitting whatever has been provided here.

It is highly recommended that you read the following links before putting odd-jobs into production.

Default behaviour

defaultMain Source #

Arguments

:: ((Config -> IO ()) -> IO ())

A callback function that will be executed once the dameon has forked into the background.

-> IO () 

Please do not get scared by the type-signature of the first argument. Conceptually, it's a callback, within another callback.

The callback function that you pass to defaultMain will be executed once the job-runner has forked as a background dameon. Your callback function will be given another callback function, i.e. the Config -> IO () part that you need to call once you've setup Config and whatever environment is required to run your application code.

This complication is necessary because immediately after forking a new daemon process, a bunch of resources will need to be allocated for the job-runner to start functioning. At the minimum, a DB connection pool and logger. However, realistically, a bunch of additional resources will also be required for setting up the environment needed for running jobs in your application's monad.

All of these resource allocations need to be bracketed so that when the job-runner exits, they may be cleaned-up gracefully.

Please take a look at the getting started guide for an example of how to use this function.

defaultStartCommand Source #

Arguments

:: StartArgs 
-> ((Config -> IO ()) -> IO ())

the same callback-within-callback function described in defaultMain

-> IO () 

Used by defaultMain if the Start command is issued via the CLI. If --daemonize switch is also passed, it checks for startPidFile:

  • If it doesn't exist, it forks a background daemon, writes the PID file, and exits.
  • If it exists, it refuses to start, to prevent multiple invocations of the same background daemon.

defaultStopCommand :: StopArgs -> IO () Source #

Used by defaultMain if Stop command is issued via the CLI. Sends a SIGINT signal to the process indicated by shutPidFile. Waits for a maximum of shutTimeout seconds (controller by --timeout) for the daemon to shutdown gracefully, after which a SIGKILL is issued

Default CLI parsers

If the default behaviour doesn't suit your needs, you can write a main function yourself, and consider using/extending the CLI parsers documented in this section.

data Args Source #

The command-line is parsed into this data-structure using argParser

Constructors

Args 

Fields

Instances
Eq Args Source # 
Instance details

Defined in OddJobs.Cli

Methods

(==) :: Args -> Args -> Bool #

(/=) :: Args -> Args -> Bool #

Show Args Source # 
Instance details

Defined in OddJobs.Cli

Methods

showsPrec :: Int -> Args -> ShowS #

show :: Args -> String #

showList :: [Args] -> ShowS #

argParser :: Parser Args Source #

The top-level command-line parser

Top-level command parser

data Command Source #

CLI commands are parsed into this data-structure by commandParser

Instances
Eq Command Source # 
Instance details

Defined in OddJobs.Cli

Methods

(==) :: Command -> Command -> Bool #

(/=) :: Command -> Command -> Bool #

Show Command Source # 
Instance details

Defined in OddJobs.Cli

Start command

data StartArgs Source #

start command is parsed into this data-structure by startParser

Constructors

StartArgs 

Fields

  • startWebUiAuth :: !(Maybe WebUiAuth)

    Switch to pick the authentication mechanism for web UI. Note: We don't have a separate switch to enable/disable the web UI. Picking an authentication mechanism by specifying the relevant options, automatically enables the web UI. Ref: webUiAuthParser

  • startWebUiPort :: !Int

    Port on which the web UI will run.

  • startDaemonize :: !Bool

    You'll need to pass the --daemonize switch to fork the job-runner as a background daemon, else it will keep running as a foreground process.

  • startPidFile :: !FilePath

    PID file for the background dameon. Ref: pidFileParser

Instances
Eq StartArgs Source # 
Instance details

Defined in OddJobs.Cli

Show StartArgs Source # 
Instance details

Defined in OddJobs.Cli

data WebUiAuth Source #

Constructors

AuthNone 
AuthBasic !Text !Text 
Instances
Eq WebUiAuth Source # 
Instance details

Defined in OddJobs.Cli

Show WebUiAuth Source # 
Instance details

Defined in OddJobs.Cli

webUiAuthParser :: Parser (Maybe WebUiAuth) Source #

Pick one of the following auth mechanisms for the web UI:

  • No auth - --web-ui-no-auth NOT RECOMMENDED
  • Basic auth - --web-ui-basic-auth-user USER and --web-ui-basic-auth-password PASS

Stop command

data StopArgs Source #

stop command is parsed into this data-structure by stopParser. Please note, that this command first sends a SIGINT to the daemon and waits for shutTimeout seconds. If the daemon doesn't shut down cleanly within that time, it sends a SIGKILL to kill immediately.

Constructors

StopArgs 

Fields

Instances
Eq StopArgs Source # 
Instance details

Defined in OddJobs.Cli

Show StopArgs Source # 
Instance details

Defined in OddJobs.Cli

Status command

statusParser :: Parser Command Source #

The status command has not been implemented yet. PRs welcome :-)

Other parsing utilities

pidFileParser :: Parser FilePath Source #

If --pid-file is not given as a command-line argument, this defaults to ./odd-jobs.pid

Auth implementations for the default Web UI

Basic Auth

data OddJobsUser Source #

Constructors

OddJobsUser !Text !Text 
Instances
Eq OddJobsUser Source # 
Instance details

Defined in OddJobs.Cli

Show OddJobsUser Source # 
Instance details

Defined in OddJobs.Cli