fix: semantic bugs found in the LLM audit backlog

Closes the four findings tracked in #120 that ruff/bandit/vulture could
not catch because they are about intent, not pattern.

- cache.py: flip the expiry comparison from `<=` to `<`. Before, a cache
  entry set with `expire=now+5` was marked expired at exactly second 5.
  Now it is valid up to and including second 5 and first becomes
  expired at second 6, matching HTTP Cache-Control max-age and Redis
  EXPIRE semantics.
- human.py: `_to_human()` now compares `abs(n)` against the thresholds
  and preserves the sign in the scaled output. `bytes2human(-1048576)`
  used to fall through to the fallback unit and return `-1048576.0B`;
  it now returns `-1.0MiB`. Affects bits2human, bytes2human, bps2human.
  Matters for counter deltas that can legitimately go negative (counter
  resets, reclaimed memory, bandwidth drops).
- shell.py: in the non-shell pipeline path, close the previous stage's
  `stdout` after the new Popen has inherited it. Without this, the
  upstream child never saw EOF/SIGPIPE when the downstream stage exited
  early, and each stage leaked a file descriptor in the parent.
- url.py: drop the `timeout=timeout if digest_auth_user else timeout`
  dead ternary in `fetch()` (both branches evaluated to `timeout`).
  No behavior change.

Version bumps: cache.py, human.py, shell.py. url.py is unchanged
behaviorally so its version stays.

Author: markuslf

CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 * Fix `--require-hashes` pip installs in CI workflows by using pinned versions instead
+* cache.py: treat a cache entry as valid up to and including its `expire` timestamp instead of expiring it one second early (`<` instead of `<=`). A key set with `expire=now+5` is now still served at `now+5` and first becomes unavailable at `now+6`, matching HTTP Cache-Control max-age and Redis EXPIRE semantics. Callers that relied on the old one-second-early expiry see their cached value live one second longer ([#120](https://github.com/Linuxfabrik/lib/issues/120))
+* human.py: `bits2human()`, `bytes2human()` and `bps2human()` now scale negative values to a unit that matches their magnitude. Before, `bytes2human(-1048576)` returned `-1048576.0B`, now it returns `-1.0MiB`. This matters for counter deltas that can legitimately be negative (counter resets, reclaimed memory, bandwidth drops) ([#120](https://github.com/Linuxfabrik/lib/issues/120))
+* shell.py: close the upstream process's `stdout` after connecting it to the next pipeline stage. Without this, the upstream process never received EOF/SIGPIPE when the downstream stage exited early, and each pipeline stage leaked a file descriptor until garbage collection caught up ([#120](https://github.com/Linuxfabrik/lib/issues/120))
+* url.py: drop the dead `timeout=timeout if digest_auth_user else timeout` ternary in `fetch()`; both branches evaluated to `timeout`, so behavior is unchanged ([#120](https://github.com/Linuxfabrik/lib/issues/120))
 * db_sqlite.py: pass `usedforsecurity=False` to `hashlib.sha1()` so bandit no longer flags a non-security SHA1 use as a weak hash (the hash is only used to derive sanitized SQL identifiers)
 * db_sqlite.py: rename unused loop variable in `rm_db()` to silence ruff B007
 * grassfish.py: remove unused `match()` helper that referenced undefined names (`re` and `compiled_custom_id_regex`); the function was never called and would have raised `NameError` at runtime

cache.py

@@ -25,7 +25,7 @@
 """
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2025042001'
+__version__ = '2026041201'
 
 from . import db_sqlite, time
 
@@ -86,13 +86,17 @@ def get(
         if not success or not result:
             return False
 
-        # Check if the key has expired
+        # Check if the key has expired. `timestamp` is the "expires at" Unix
+        # epoch set via `set(expire=...)`. We treat the entry as valid up to
+        # and including that timestamp (strict-less-than), so a key with
+        # expire=now+5 is still served at now+5 and first becomes expired at
+        # now+6. This matches HTTP Cache-Control max-age and Redis EXPIRE.
         now = time.now()
-        if result['timestamp'] != 0 and result['timestamp'] <= now:
+        if result['timestamp'] != 0 and result['timestamp'] < now:
             # Clean up all expired entries
             db_sqlite.delete(
                 conn,
-                sql='DELETE FROM cache WHERE timestamp <= :now;',
+                sql='DELETE FROM cache WHERE timestamp < :now;',
                 data={'now': now},
             )
             db_sqlite.commit(conn)

human.py

@@ -13,7 +13,7 @@
 """
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026030301'
+__version__ = '2026041201'
 
 import math
 
@@ -155,9 +155,13 @@
 
 
 def _to_human(n, thresholds, fallback_unit, decimals=1, space=False):
+    # compare against the absolute value so negative deltas (counter resets,
+    # memory reclaimed, bandwidth swings) still get scaled to a unit that
+    # matches their magnitude. e.g. -1048576 bytes reads as '-1.0MiB'.
     sep = ' ' if space else ''
+    abs_n = abs(n)
     for symbol, threshold in thresholds:
-        if n >= threshold:
+        if abs_n >= threshold:
             return f'{float(n) / threshold:.{decimals}f}{sep}{symbol}'
     return f'{n:.{decimals}f}{sep}{fallback_unit}'
 

shell.py

@@ -11,7 +11,7 @@
 """Communicates with the Shell on Linux and Windows."""
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026032101'
+__version__ = '2026041201'
 
 
 import os
@@ -178,21 +178,28 @@ def shell_exec(
         return True, (stdout, stderr, retc)
 
     # non-shell pipeline: cmd string is split on '|' and each segment runs with
-    # shell=False; args come from the caller's cmd string via shlex.split
+    # shell=False; args come from the caller's cmd string via shlex.split.
+    # after connecting a stage's stdout to the next stage's stdin, we close it
+    # in the parent so only the downstream child holds the read end. Without
+    # this, the upstream child never sees EOF / SIGPIPE when the downstream
+    # exits early, and we leak a file descriptor per pipeline stage.
     cmds = cmd.split('|')
     p = None
     for part in cmds:
         try:
             args = shlex.split(part.strip())
+            prev = p
             p = subprocess.Popen(  # nosec B603
                 args,
-                stdin=p.stdout if p else subprocess.PIPE,
+                stdin=prev.stdout if prev else subprocess.PIPE,
                 stdout=subprocess.PIPE,
                 stderr=subprocess.PIPE,
                 env=env,
                 shell=False,
                 cwd=cwd,
             )
+            if prev is not None:
+                prev.stdout.close()
         except (OSError, ValueError, Exception) as e:
             return False, f'Error "{e}" while calling command "{part}"'
 

url.py

@@ -159,9 +159,11 @@ def fetch(
             )
             response = opener.open(request)  # nosec B310
         else:
+            # when digest auth is active the opener installed further up
+            # already carries its own context, so we must not pass one here
             response = urllib.request.urlopen(  # nosec B310
                 request,
-                timeout=timeout if digest_auth_user else timeout,
+                timeout=timeout,
                 context=None if digest_auth_user else ctx,
             )