A cron-run Ruby log-rotation script logs its failures, but cron always sees status 0; what in the script decides the exit status?

## The contract with cron A scheduler cannot read your log; it reads the **exit status**. By convention 0 means success and anything else means failure, and alerting (a mail from cron, a failed job in a scheduler, a red check) keys off that number. A Ruby script therefore has to make sure that every failure path ends with a non-zero status. ## How Ruby decides the status | How the program ends | Status | |---|---| | main script finishes normally | 0 | | `exit` / `exit(true)` | 0 | | `exit(false)`, `abort(msg)` | 1 | | `exit(n)` | `n`, truncated to 8 bits by the OS | | uncaught exception other than `SystemExit` | 1 | | `raise SystemExit` with no status | 0 | | an `at_exit` handler calls `exit(m)` | `m`, replacing the earlier status | ## Trap 1: rescue, log, fall off the end ```ruby def rotate!(dir) Dir.glob(File.join(dir, "*.log")).each { |p| File.rename(p, "#{p}.1") } rescue SystemCallError => e warn "rotate_logs: #{e.message}" end rotate!("/var/log/app") # status 0 even when the rename failed ``` Once the exception is rescued it no longer exists as far as the exit status is concerned. Writing to `$stderr` with `warn` does not change the status, and neither does the error's class: an `Errno::EACCES` does not become status 13. The main script finishes normally and returns 0. ## Trap 2: something cancels the `SystemExit` `exit 1` and `abort` work by raising **`SystemExit`**. Any code between the call and the top level that rescues it, whether a `rescue SystemExit` or a very broad rescue clause, cancels the exit: execution continues after that `begin` block and, unless something else fails, ends with 0. Search the call path for rescues broad enough to catch it. ## Trap 3: an `at_exit` handler overrides the status A handler that calls `exit` or `exit 0`, perhaps written to guarantee a tidy shutdown message, replaces whatever status the program had, because its own `SystemExit` becomes the final one. Check handlers registered by the script and by the libraries it loads. ## Trap 4: statuses that look like failure but are not - `raise SystemExit` without arguments defaults to status `true`, which is 0; pass a status (`raise SystemExit.new(1, "rotation failed")`) or call `abort`. - On POSIX systems only the low 8 bits reach the parent: `exit 256` is seen as 0 and `exit 257` as 1. Keep your own failure codes small; shells reserve values from 126 up for their own meanings. ## The fixed shape 1. Keep the work in a method that returns `true`/`false` or a list of failures. 2. Rescue `SystemCallError` or other specific classes inside it, log with context, and record the failure. 3. End the script with exactly one statement that maps the result: `exit(ok)` or `abort "reason"`. 4. Verify by hand: run the script, check `$?` in the shell with `echo $?`, then force a failure (a read-only directory) and check again. ## Testing the contract Unit tests should call the method and assert on its return value rather than letting the script's `exit` run inside the test process. For an end-to-end check, run the script as a child process from the test and assert on the child's exit status. ## A review checklist for scheduled scripts - Is there exactly one place where the script decides its status, and does every failure path reach it? - Does any rescue between an `exit` call and the top level catch `SystemExit`? - Do any `at_exit` handlers call `exit`, and if so, do they preserve a failing status by checking `$!.success?` first? - Are custom status codes documented and kept below 126? - Does the job's alerting read the status rather than search the log text? A script that passes this checklist fails loudly: the scheduler sees a non-zero status, and the log explains why.