filed

Job queue using FUSE

commit 077146d189df58746afa0fbf54611b93ae37e843
parent 30b1a5a401c23532f294dd4cac77278283d8b66f
Author: Marc Coquand <marc@coquand.email>
Date:   Mon, 15 Dec 2025 15:48:33 +0100

README

Diffstat:
M
README.md
 | 
22
++++++++++------------

1 file changed, 10 insertions(+), 12 deletions(-)
diff --git a/README.md b/README.md
@@ -1,16 +1,13 @@
-# qj - queue jobs
+# qj - queue jobs and inspect
 
-`qj` is a simple job queue that is manipulated using files. It is intended for single-server workloads, for example as a companion to another app. `qj` makes it easy for admins to view and retry jobs. It features:
+`qj` is a simple job queue. It is intended for 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.
 
-- Retries
-- Output logs
-- Timeout
-- Job limits
+`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` aims to be a good unix citizen, and works well with other tools in the ecosystem, for example:
 
 - Periodic jobs using cron
-- Access rights specific for unix users
+- Authnz using built-in unix users
 
 ## Installation
 
@@ -32,11 +29,11 @@ scdoc < qj.1.scd > qj.1
 
 `qj` is a job queue that operates using files. Each job corresponds to one file, and the directories indicate the job state. It is recommended to read the [man pages] for more complete documentation and security considerations.
 
-`qj` requires a job directory and a location for a state file.
+`qj` requires a job directory and a state file location (defaulting to `XDG_DATA_HOME`).
 
 ```
 $ mkdir /tmp/qj-jobs
-$ qj /tmp/qj-jobs /tmp/qj-state.db
+$ qj /tmp/qj-jobs 
 ```
 
 Once run, `qj` will set up a directory in `qj-jobs` that contains a few files and directories.
@@ -53,13 +50,13 @@ If all went well, you can see the job output:
 $ cat /tmp/qj-jobs/complete/1
 ```
 
-By default, a job retries 3 times, and then moved to the `failed` directory. You can inspect the logs to see what went wrong:
+By default, a job retries 3 times, and if unsuccessful is moved to the `failed` directory. You can inspect the logs to see what went wrong:
 
 ```
-$ cat /tmp/qj-jobs/active/1
+$ cat /tmp/qj-jobs/failed/1
 ```
 
-To restart a job after that, move the job back to pending:
+And you can restart a job by moving the job back to pending:
 
 ```
 $ mv /tmp/qj-jobs/failed/1 /tmp/qj-jobs/pending
@@ -70,6 +67,7 @@ $ mv /tmp/qj-jobs/failed/1 /tmp/qj-jobs/pending
 - [x] Support chmod and chown
 - [x] State is configured via environment variable
 - [ ] Customizable backoff and timeout before retries
+- [ ] Last modified and created at are correctly rendered
 - [ ] "Landlock"-mode, or sandboxed jobs
 
 ## Alternatives