Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

test(api): ratchet the statuses derived from error prose, ahead of milestone C

Juan Denisb2fd1198be52
diff --git a/backend/tests/STATUS_SNIFFING_CEILING b/backend/tests/STATUS_SNIFFING_CEILING
new file mode 100644
index 00000000..40994076
--- /dev/null
+++ b/backend/tests/STATUS_SNIFFING_CEILING
@@ -0,0 +1 @@
+23
diff --git a/backend/tests/status_sniffing_census.py b/backend/tests/status_sniffing_census.py
new file mode 100644
index 00000000..b943b89b
--- /dev/null
+++ b/backend/tests/status_sniffing_census.py
@@ -0,0 +1,138 @@
+"""Count HTTP statuses chosen by pattern-matching an error message (plan 76, C).
+
+ status = 403 if 'denied' in result.get('error', '').lower() else 400
+
+This is what a service returning ``{'success': False, 'error': '<prose>'}``
+forces on its callers: the service knows perfectly well that the failure was a
+denial, throws that away, and the route reconstructs it by searching the
+sentence. The status code is then coupled to the *wording*. Rephrasing "Access
+denied: path not in allowed directories" to "You do not have access to this
+path" silently turns a 403 into a 400, and nothing fails — not a test, not a
+type checker, not a lint rule.
+
+The fix is milestone C's: services raise typed errors from ``app.exceptions``
+and routes return data, so nobody re-derives what the service already knew.
+That is deliberately NOT done yet — ``file_service`` alone has eight callers,
+and converting one service to raise while its other callers still expect a dict
+leaves two contracts, which is the disease rather than the cure.
+
+So this is the ratchet that comes first (second-wave rule 1): the count may only
+go down. It exists to stop the pattern spreading while the envelope decision is
+made.
+
+A site is counted when a conditional expression chooses between two HTTP status
+codes, and its test inspects string content — ``in``, ``.lower()``,
+``.startswith()``, ``.endswith()``. Choosing a status from a real signal (a
+typed exception, an enum, a boolean field) is not counted, because that is the
+thing this is asking for.
+
+Usage (from ``backend/``)::
+
+ python tests/status_sniffing_census.py # print the count + report
+ python tests/status_sniffing_census.py --update # write the count as the ceiling
+"""
+
+import ast
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+BACKEND = os.path.dirname(HERE)
+APP_DIR = os.path.join(BACKEND, 'app')
+CEILING_FILE = os.path.join(HERE, 'STATUS_SNIFFING_CEILING')
+
+SKIP_DIRS = {'__pycache__', 'node_modules', '.venv', 'venv'}
+STRING_TESTS = {'lower', 'upper', 'startswith', 'endswith', 'strip', 'casefold'}
+
+
+def _rel(path):
+ return os.path.relpath(path, BACKEND).replace(os.sep, '/')
+
+
+def _is_status(node):
+ return (isinstance(node, ast.Constant) and isinstance(node.value, int)
+ and 100 <= node.value <= 599)
+
+
+def _test_inspects_a_string(test):
+ """True when the branch is decided by looking inside some text."""
+ for n in ast.walk(test):
+ if isinstance(n, ast.Compare):
+ for op in n.ops:
+ if isinstance(op, (ast.In, ast.NotIn)):
+ return True
+ if isinstance(n, ast.Call) and isinstance(n.func, ast.Attribute) \
+ and n.func.attr in STRING_TESTS:
+ return True
+ return False
+
+
+def count_file(path):
+ """Return [(lineno, snippet)] of sniffed statuses in one file."""
+ try:
+ with open(path, encoding='utf-8') as f:
+ source = f.read()
+ tree = ast.parse(source)
+ except (SyntaxError, UnicodeDecodeError):
+ return []
+
+ lines = source.split('\n')
+ found = []
+ for node in ast.walk(tree):
+ if not isinstance(node, ast.IfExp):
+ continue
+ if not (_is_status(node.body) and _is_status(node.orelse)):
+ continue
+ if not _test_inspects_a_string(node.test):
+ continue
+ snippet = lines[node.lineno - 1].strip() if node.lineno <= len(lines) else ''
+ found.append((node.lineno, snippet[:100]))
+ return sorted(found)
+
+
+def census():
+ found = {}
+ for dirpath, dirnames, filenames in os.walk(APP_DIR):
+ dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+ for name in sorted(filenames):
+ if not name.endswith('.py'):
+ continue
+ path = os.path.join(dirpath, name)
+ hits = count_file(path)
+ if hits:
+ found[_rel(path)] = hits
+ return found
+
+
+def total(found=None):
+ if found is None:
+ found = census()
+ return sum(len(v) for v in found.values())
+
+
+def read_ceiling():
+ with open(CEILING_FILE, encoding='utf-8') as f:
+ return int(f.read().strip())
+
+
+def _write_ceiling(value):
+ with open(CEILING_FILE, 'w', encoding='utf-8') as f:
+ f.write('%d\n' % value)
+
+
+if __name__ == '__main__':
+ found = census()
+ count = total(found)
+ for rel in sorted(found, key=lambda p: (-len(found[p]), p)):
+ print('%-40s %d' % (rel, len(found[rel])))
+ for lineno, snippet in found[rel][:3]:
+ print(' L%-5d %s' % (lineno, snippet))
+ print('\ntotal: %d' % count)
+ if '--update' in sys.argv:
+ _write_ceiling(count)
+ print('ceiling updated to %d' % count)
+ else:
+ try:
+ print('ceiling: %d' % read_ceiling())
+ except FileNotFoundError:
+ print('no ceiling file yet; run with --update')
diff --git a/backend/tests/test_status_sniffing_ratchet.py b/backend/tests/test_status_sniffing_ratchet.py
new file mode 100644
index 00000000..66f1307d
--- /dev/null
+++ b/backend/tests/test_status_sniffing_ratchet.py
@@ -0,0 +1,82 @@
+"""The status-sniffing ratchet (plan 76, milestone C).
+
+Second-wave rule 1: the ratchet comes before the migration, because a migration
+without one regrows — and here the ratchet comes *well* before, since converging
+these means deciding the service/route envelope (milestone C) rather than
+editing 23 lines.
+
+What it holds down is the population of HTTP statuses derived by searching an
+error message for a phrase. Those are the visible symptom of a service that
+returns ``{'success': False, 'error': '<prose>'}``: it knew the failure was a
+denial, discarded that, and the route reconstructs it from the sentence — which
+couples the status code to the wording, silently.
+"""
+
+from status_sniffing_census import census, count_file, read_ceiling, total
+
+
+def test_the_count_is_at_or_below_the_ceiling():
+ found = census()
+ count = total(found)
+ ceiling = read_ceiling()
+ worst = sorted(found, key=lambda p: -len(found[p]))[:5]
+ assert count <= ceiling, (
+ f'{count} HTTP statuses are chosen by matching an error message, '
+ f'ceiling is {ceiling}.\n'
+ f'Raise a typed error from app/exceptions.py in the service and let the '
+ f'global handler map it, instead of re-deriving the status from prose.\n'
+ f'Files: ' + ', '.join(f'{p} ({len(found[p])})' for p in worst)
+ )
+
+
+def test_the_ceiling_is_not_stale():
+ count, ceiling = total(), read_ceiling()
+ assert ceiling - count <= 5, (
+ f'ceiling {ceiling} is {ceiling - count} above the actual {count}; '
+ f'run `python tests/status_sniffing_census.py --update`'
+ )
+
+
+class TestTheCensusCountsTheRightThings:
+ """A miscounting ratchet is worse than none: it reads green either way."""
+
+ def _count(self, tmp_path, source):
+ path = tmp_path / 'sample.py'
+ path.write_text(source, encoding='utf-8')
+ return len(count_file(str(path)))
+
+ def test_counts_a_substring_test(self, tmp_path):
+ assert self._count(tmp_path, (
+ "status = 403 if 'denied' in result.get('error', '').lower() else 400\n"
+ )) == 1
+
+ def test_counts_a_startswith_test(self, tmp_path):
+ assert self._count(tmp_path, (
+ "code = 404 if err.startswith('not found') else 400\n"
+ )) == 1
+
+ def test_counts_a_key_presence_test(self, tmp_path):
+ """`'error' not in result` is the same coupling one step removed."""
+ assert self._count(tmp_path, (
+ "return jsonify(result), 200 if 'error' not in result else 400\n"
+ )) == 1
+
+ def test_does_not_count_a_status_chosen_from_a_real_signal(self, tmp_path):
+ assert self._count(tmp_path, (
+ 'status = 403 if denied else 400\n'
+ 'other = 404 if result.missing else 200\n'
+ )) == 0
+
+ def test_does_not_count_a_non_status_conditional(self, tmp_path):
+ """Only the pair-of-status-codes shape is the smell."""
+ assert self._count(tmp_path, (
+ "label = 'gone' if 'not found' in err else 'broken'\n"
+ "limit = 10 if 'small' in mode else 50\n"
+ )) == 0
+
+ def test_does_not_count_a_typed_exception_mapping(self, tmp_path):
+ """What the migration is supposed to produce must not read as debt."""
+ assert self._count(tmp_path, (
+ 'def handler(exc):\n'
+ ' return exc.status_code\n'
+ )) == 0