| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
OddJobs.Cli
Contents
Synopsis
- defaultMain :: ((Config -> IO ()) -> IO ()) -> IO ()
- defaultStartCommand :: StartArgs -> ((Config -> IO ()) -> IO ()) -> IO ()
- defaultWebUi :: StartArgs -> Config -> IO ()
- defaultStopCommand :: StopArgs -> IO ()
- data Args = Args {
- argsCommand :: !Command
- argParser :: Parser Args
- data Command
- commandParser :: Parser Command
- data StartArgs = StartArgs {
- startWebUiAuth :: !(Maybe WebUiAuth)
- startWebUiPort :: !Int
- startDaemonize :: !Bool
- startPidFile :: !FilePath
- startParser :: Parser Command
- data WebUiAuth
- webUiAuthParser :: Parser (Maybe WebUiAuth)
- data StopArgs = StopArgs {
- shutTimeout :: !Seconds
- shutPidFile :: !FilePath
- stopParser :: Parser Command
- statusParser :: Parser Command
- pidFileParser :: Parser FilePath
- defaultCliParserPrefs :: ParserPrefs
- defaultCliInfo :: ParserInfo Args
- defaultDaemonOptions :: DaemonOptions
- data OddJobsUser = OddJobsUser !Text !Text
- defaultBasicAuth :: (Text, Text) -> BasicAuthCheck OddJobsUser
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.
- The getting started
guide
which will walk you through a bare-bones example of using the
defaultMainfunction. It should make the callback-within-callback clearer. - The section on deployment in the guide.
Default behaviour
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.
Arguments
| :: StartArgs | |
| -> ((Config -> IO ()) -> IO ()) | the same callback-within-callback function described in
|
| -> 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.
The command-line is parsed into this data-structure using argParser
Constructors
| Args | |
Fields
| |
Top-level command parser
CLI commands are parsed into this data-structure by commandParser
Start command
start command is parsed into this data-structure by startParser
Constructors
| StartArgs | |
Fields
| |
Stop command
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
| |
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 # | |
Defined in OddJobs.Cli | |
| Show OddJobsUser Source # | |
Defined in OddJobs.Cli Methods showsPrec :: Int -> OddJobsUser -> ShowS # show :: OddJobsUser -> String # showList :: [OddJobsUser] -> ShowS # | |
defaultBasicAuth :: (Text, Text) -> BasicAuthCheck OddJobsUser Source #