gearcmd
wraps command line programs and turns them into Gearman workers.
Instead of writing programs as Gearman workers that speak the Gearman protocol, you can write programs as regular Unix command line programs. gearcmd
will speak Gearman on behalf of your program and translate it into the standard command line protocol.
This allows programs to be easily run locally in a Unix dev environment or in other contexts besides Gearman.
In addition, this decouples your program's process from the Gearman worker's process, ensuring that if your process crashes, the Gearman worker won't, so it will be able to report the crash as a job failure. By default, if a worker crashes, Gearman will silently retry jobs with a new worker without reporting the crash. gearcmd
ensures that crashes result in loud failures that you can address.
While the gearman command line tool offers similar functionality, gearcmd
differs in a few key ways:
gearcmd
lets clients submit different command line flags for each job, whilegearman
passes the job payload through the command's stdin.- While both forward the command's stderr to the worker's stderr,
gearcmd
also emits stderr output as worker warnings, allowing clients to receive error information from workers.
gearcmd -name <function name> -cmd <command> -host <host> -port <port>
Params:
name
: The name of the Gearman function to listen for.cmd
: The command to run when the wrapper receives a Gearman job.host
(optional): The Gearman host to connect to. Defaults to$SERVICE_GEARMAND_TCP_HOST
which is often generated by discovery-go.port
(optional): The Gearman port to connect to. Defaults to$SERVICE_GEARMAND_TCP_PORT
which is often generated by discovery-go.parseargs
(optional): If false, send the job payload directly to the cmd as its first argument without parsing it. Requires flag syntax-parseargs=[true/false]
. It will not work properly without the equal sign.cmdtimeout
(optional): Maximum time for the command to run before it will be killed, as parsed by time.ParseDuration (e.g.2h
,30m
,2h30m
). Defaults to never.retry
(optional): Number of times to retry the job if it fails. Defaults to 0.
Injected env var:
JOB_ID
: this is whatever is found after the last:
in the job handle. This is intended for integration with gearman-admin which adds a random job ID on job creation.WORK_DIR
: this is the path to a directory that is created before thecmd
is called and deleted after the job exits.
The command will be given as its arguments the exact arguments passed as the Gearman payload. These arguments will be parsed as if the command were being called in Bash. For example, running gearcmd --name grep --cmd grep
and then submitting a Gearman job with function grep
and payload -i 'some regex' some-file.txt
would result in grep
being run as if it were called on the command line like so: grep -i 'some regex' some-file.txt
.
The environment variable JOB_ID
is injected while the job command is run. It is set to the job number of the gearman job being handled.
- The command's stdout will be emitted as the Gearman worker's
WORK_DATA
events. - The last 5 lines of the command's stderr will be emitted as the Gearman worker's
WORK_WARNING
events. - If the command has exit code 0, the Gearman worker will emit
WORK_COMPLETE
, otherwise it will emitWORK_FAIL
. - The command's stdout and stderr will be outputted to
gearcmd
's stdout and stderr respectively.
This will walk you through running a simple task through gearcmd
. First, install gearcmd
as described below.
Then create a bash script, my-echo.sh
. This will be the command gearcmd
runs:
#!/bin/bash
echo $1
echo $2
Run a local Gearman server:
gearmand -d
Start gearcmd
and tell it to register itself as a Gearman worker for jobs with function echo
, and run my-echo.sh
to process these jobs:
gearcmd -name echo -cmd my-echo.sh
At this point you should be able to submit Gearman jobs. For example, this command:
gearman -f echo -h localhost -v -s "firstLine secondLine"
should output:
firstLine
secondLine
Install from source via go get github.com/Clever/gearcmd/cmd/gearcmd
, or download a release on the releases page.
Set this repository up in the standard location in your GOPATH
, i.e. $GOPATH/src/github.com/Clever/gearcmd
.
Once this is done, make test
runs the tests.
The release process requires a cross-compilation toolchain.
gox
can install the toolchain with one command: gox -build-toolchain
.
From there you can build release tarballs for different OS and architecture combinations with make release
.
Official releases are listed on the releases page. To create an official release:
-
On
master
, bump the version in theVERSION
file in accordance with semver. You can do this withgitsem
, but make sure not to create the tag, e.g.gitsem -tag=false patch
. -
Push the change to Github. Drone will automatically create a release for you.
Please view the dev-handbook for instructions.