filed

Job queue using FUSE

git clone git://mccd.space/filed

commit ced0151bc5a7d6b78aa7e5f8dc3c74eb768b269f
parent d74b297abbb03a27868516e5f2fd5b54798261f1
Author: Marc Coquand <marc@coquand.email>
Date:   Mon, 15 Dec 2025 22:05:35 +0100

docs

Diffstat:

MREADME.md | 8++++----


Mqj.1.scd | 24++++++++++--------------


2 files changed, 14 insertions(+), 18 deletions(-)
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 `qj` is a simple job queue. It is intended for trusted, single-server workloads, and aims to work as a companion queue to another application, while also allowing admins to easily inspect and rerun jobs that have failed.
 
-`qj` uses files and directories for manipulation. Creating a job is as simple as adding it to `/pending`, viewing running jobs is as simple as running `ls /active`, and restarting a failed job is as simple as `mv /failed/1 /pending`.
+`qj` uses files and directories for manipulation. Creating a job is as simple as adding it to `/pending`, viewing running jobs is as simple as running `ls /active`, and restarting a failed job is as simple as `mv /failed/job /pending`.
 
 `qj` aims to be a good unix citizen, and works well with other tools in the ecosystem, for example:
 
@@ -70,11 +70,11 @@ Often these jobs can fail, whether that's due to network errors, memory issues o
 
 I wanted a tool that I could incorporate and use with whatever programming language I desired, and that makes it easy to understand when a job fail and rerun jobs if there is an error. `qj` is very intuitive to build an integration for: just write a file telling it what to execute.
 
-I also wanted a tool that made it simple to inspect, without needing to expose a web portal or have set up separate auth. `qj` allows you to inspect and operate the queue just by SSHing into the server, and reuses battle-proven identity system already built into Linux.
+I also wanted a tool that made it simple to inspect, without needing to expose a web portal or set up separate auth system. `qj` allows you to inspect and operate the queue just by SSHing into the server, and reuses the decades old proven identity system already built into Linux.
 
-The simple file-based API `qj`, inspired by plan9, allows me to slim down the amount of code needed considerably, while still exposing a very scriptable and easy-to-understand interface. 
+The simple file-based API `qj`, inspired by plan9, also allows me to slim down the amount of code needed considerably, while still exposing a very scriptable and easy-to-understand interface.
 
-I've tried a few other queue tools: sqs/sns, rabbitmq, bull, systemd-run. The first two felt heavyweight, and required setting up a lot of infrastructure, especially if you want to rerun and inspect jobs. It felt like far too much work for a simple app. Bull was more in line with what I wanted, but I think operating on files is simpler to build custom automation, and easier to secure. Systemd-run lacked the retry functionality and the interface was rather clunky.
+I've tried a few other queue tools: sqs/sns, rabbitmq, bull, systemd-run. The first two felt heavyweight, and required setting up a lot of infrastructure, especially if you want to rerun and inspect jobs. It felt like far too much work for a simple app. Bull was more in line with what I wanted, but I think operating on files is simpler for building custom automation, and easier to secure. Systemd-run lacked the retry functionality and the interface was rather clunky.
 
 ## TODO
 
diff --git a/qj.1.scd b/qj.1.scd
@@ -19,8 +19,8 @@ Job names must be unique across all four directories. The directories are:
 	*pending* - jobs to be run. To create a new job, create a file 
 	here with the command to run.
 
-	*active* - currently running jobs. You can change the max amount of
-	allowed concurrent jobs in settings. Directory is read-only.
+	*active* - currently running jobs. It is possible to access logs of
+	the running jobs by inspecting the files.
 
 	*failed* - jobs that exceeded retry count. You can retry a job by
 	moving them back to pending. You can also safely remove jobs here.
@@ -33,7 +33,8 @@ qj exposes 2 files:
 	*new-id* contains a short unique id that can be sampled for job
 	name entropy. The id is guaranteed to be unique at creation.
 
-	*config.json* provides various settings. See more in section *CONFIG*.
+	*config.json* provides various settings. Changes made to this file 
+	are applied immediately. See *CONFIGURATION* for full list of options.
 
 # SECURITY
 
@@ -57,19 +58,14 @@ Access rights can be modified using _CHOWN(1)_ and _CHMOD(1)_.
 # MAINTENANCE
 
 qj never removes logs of completed and failed jobs. It is therefore recommended
-that the admin adds a  cron job to clean up old jobs. Such a cron job could
+that the admin adds a cron job to clean up old jobs. The cron job could
 look like this, for example:
 
 	```
 	0 2 * * * find /path/to/qj/{complete,failed} -type f -mtime +7 -delete
 	```
 
-The above cronjob looks for jobs older than 1 week and removes them.
-
-# CONFIG
-
-Changes made to config.json are applied immediately. Below is a list of
-available options.
+# CONFIGURATION
 
 ## Max retries
 
@@ -98,13 +94,13 @@ Time before the job will be killed by a signal.
 Path to store sqlite state. File is created if it does not
 exist. Defaults to $XDG_DATA_HOME/qj.db, or exit(1) if XDG_DATA_HOME is unset.
 
-# EXAMPLES
+# EXAMPLE
 
-Create a new job  with a unique id, that echoes hello world:
+Create a new job with a unique id, that echoes hello world:
 
 	$ printf "echo helloworld" > "/var/qj/pending/$(< /var/qj/new-id)"
 
-Retry a job that filed:
+Retry a job that failed:
 
 	$ mv /var/qj/failed/myjob /var/qj/pending
 
@@ -117,7 +113,7 @@ Inspect a currently running job:
 
 Periodic jobs can be set up using _CRON(8)_.
 
-# AUTHOR
+# AUTHORS
 
 Maintained by Marc Coquand <marc@coquand.email>. Up-to-date sources can be
 found at https://git.sr.ht/~marcc/qj and bugs/patches can be submitted by