idemcheck 0.1.0__py3-none-any.whl

idemcheck/__init__.py

@@ -0,0 +1,3 @@
+"""idemcheck: find HTTP handlers that will double-charge on a retry."""
+
+__version__ = "0.1.0"

idemcheck/analyze.py

@@ -0,0 +1,251 @@
+"""Find mutating routes whose writes have no protection against a second delivery.
+
+A client retries because the network lied. If the handler charges, inserts, or sends
+before it can answer, the retry charges twice. Libraries that solve this exist per
+framework; nothing tells you which of your routes is missing the guard.
+
+This is static analysis over the AST, so it can only see what is written down. A guard
+built by a decorator defined in another module, or an ORM method that commits for you,
+is invisible. The README says so instead of implying the tool proves safety.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+MUTATING = ("POST", "PUT", "PATCH", "DELETE")
+
+#: Methods that end in a write, anywhere in the codebase.
+WRITE_METHODS = frozenset({
+    "commit", "flush", "save", "insert", "insert_one", "insert_many", "update",
+    "update_one", "upsert", "delete", "delete_one", "execute", "create", "add",
+    "charge", "capture", "transfer", "refund", "enqueue", "delay", "send_message",
+})
+
+#: Outbound calls that move money or send something a retry would duplicate.
+OUTBOUND = ("requests.post", "requests.put", "httpx.post", "httpx.put", "aiohttp.",
+            "stripe.", "session.post", "client.post", "urlopen")
+
+#: Any of these in the handler means somebody thought about the retry.
+PROTECTION = ("idempotency", "idempotent", "idem_key", "idemkey", "request_id",
+              "requestid", "dedupe", "dedup_key", "nonce", "client_reference",
+              "get_or_create", "update_or_create", "on_conflict", "unique_together")
+
+ROUTE_DECORATORS = frozenset({"post", "put", "patch", "delete", "route", "api_route"})
+
+
+@dataclass(frozen=True)
+class Route:
+    """A handler and the mutating methods it answers."""
+
+    line: int
+    methods: Tuple[str, ...]
+    name: str
+
+
+@dataclass
+class Finding:
+    path: str
+    line: int
+    rule: str
+    severity: str
+    route: str
+    detail: str
+    writes: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {"path": self.path, "line": self.line, "rule": self.rule,
+                "severity": self.severity, "route": self.route,
+                "detail": self.detail, "writes": self.writes}
+
+
+@dataclass
+class Report:
+    files: int = 0
+    routes: int = 0
+    findings: List[Finding] = field(default_factory=list)
+
+
+def _dotted(node: ast.AST) -> str:
+    """The dotted name of a call target, or '' when it is not a plain name."""
+    parts = []
+    while isinstance(node, ast.Attribute):
+        parts.append(node.attr)
+        node = node.value
+    if isinstance(node, ast.Name):
+        parts.append(node.id)
+    return ".".join(reversed(parts))
+
+
+def _methods_from_decorator(node: ast.AST) -> Optional[Tuple[str, ...]]:
+    """Return the mutating methods a decorator registers, or None if it is not a route."""
+    if not isinstance(node, ast.Call):
+        return None
+    target = _dotted(node.func).rsplit(".", 1)[-1]
+    if target not in ROUTE_DECORATORS:
+        return None
+    if target in ("route", "api_route"):
+        for kw in node.keywords:
+            if kw.arg == "methods" and isinstance(kw.value, (ast.List, ast.Tuple)):
+                names = [e.value.upper() for e in kw.value.elts
+                         if isinstance(e, ast.Constant) and isinstance(e.value, str)]
+                picked = tuple(m for m in names if m in MUTATING)
+                return picked or None
+        return None
+    method = target.upper()
+    return (method,) if method in MUTATING else None
+
+
+def _strings_and_names(func: ast.AST) -> str:
+    """Every identifier and string literal in the handler, lowercased, for guard hunting."""
+    chunks: List[str] = []
+    for node in ast.walk(func):
+        if isinstance(node, ast.Name):
+            chunks.append(node.id)
+        elif isinstance(node, ast.Attribute):
+            chunks.append(node.attr)
+        elif isinstance(node, ast.Constant) and isinstance(node.value, str):
+            chunks.append(node.value)
+        elif isinstance(node, ast.keyword) and node.arg:
+            chunks.append(node.arg)
+    return " ".join(chunks).lower()
+
+
+def _writes(func: ast.AST) -> List[str]:
+    """Dotted names of calls that look like writes or outbound sends."""
+    found: List[str] = []
+    for node in ast.walk(func):
+        if not isinstance(node, ast.Call):
+            continue
+        name = _dotted(node.func)
+        short = name.rsplit(".", 1)[-1]
+        low = name.lower()
+        if short in WRITE_METHODS:
+            found.append(name or short)
+        elif any(marker in low for marker in OUTBOUND):
+            found.append(name or low)
+        elif short == "execute" and any(
+            kw in low for kw in ("insert", "update", "delete")
+        ):
+            found.append(name)
+    # dedupe, keep first-seen order
+    seen: List[str] = []
+    for name in found:
+        if name not in seen:
+            seen.append(name)
+    return seen
+
+
+def _docstring_node(func: ast.AST) -> Optional[ast.AST]:
+    body = getattr(func, "body", [])
+    if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant) \
+            and isinstance(body[0].value.value, str):
+        return body[0]
+    return None
+
+
+def _has_guard(func: ast.AST) -> bool:
+    """Is there any sign that a second delivery was considered?
+
+    The handler's own docstring is excluded: a docstring that says "TODO: idempotency"
+    is evidence of the bug, not of the fix.
+    """
+    doc = _docstring_node(func)
+    doc_text = doc.value if isinstance(doc, ast.Expr) else None
+    skip = {id(doc), id(doc_text)}
+    chunks: List[str] = []
+    for node in ast.walk(func):
+        if id(node) in skip:
+            continue
+        if isinstance(node, ast.Name):
+            chunks.append(node.id)
+        elif isinstance(node, ast.Attribute):
+            chunks.append(node.attr)
+        elif isinstance(node, ast.Constant) and isinstance(node.value, str):
+            chunks.append(node.value)
+        elif isinstance(node, ast.keyword) and node.arg:
+            chunks.append(node.arg)
+    text = " ".join(chunks).lower()
+    return any(token in text for token in PROTECTION)
+
+
+def _route_path(dec: ast.AST) -> str:
+    if isinstance(dec, ast.Call) and dec.args:
+        first = dec.args[0]
+        if isinstance(first, ast.Constant) and isinstance(first.value, str):
+            return first.value
+    return ""
+
+
+def analyze_source(source: str, path: str = "<src>") -> Tuple[int, List[Finding]]:
+    """Return (mutating routes seen, findings) for one source file."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return 0, []
+    routes = 0
+    findings: List[Finding] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        methods: List[str] = []
+        label = ""
+        for dec in node.decorator_list:
+            picked = _methods_from_decorator(dec)
+            if picked:
+                methods.extend(picked)
+                label = label or _route_path(dec)
+        if not methods:
+            continue
+        routes += 1
+        writes = _writes(node)
+        if not writes or _has_guard(node):
+            continue
+        outbound = any(any(m in w.lower() for m in OUTBOUND) for w in writes)
+        severity = "high" if (outbound or "POST" in methods) else "medium"
+        route = "%s %s" % ("|".join(sorted(set(methods))), label or node.name)
+        findings.append(Finding(
+            path=path, line=node.lineno, rule="missing-idempotency", severity=severity,
+            route=route,
+            detail="%s with no idempotency key, dedupe store or unique constraint"
+                   % node.name,
+            writes=writes,
+        ))
+    return routes, findings
+
+
+def _looks_like_tests(path: Path) -> bool:
+    parts = set(path.parts)
+    return "tests" in parts or path.name.startswith("test_") or path.name == "conftest.py"
+
+
+def analyze_files(paths: Iterable[Path], include_tests: bool = False) -> Report:
+    report = Report()
+    seen: set = set()
+    for base in paths:
+        files: Sequence[Path]
+        if base.is_dir():
+            files = sorted(p for p in base.rglob("*.py")
+                           if not any(skip in p.parts for skip in
+                                      (".git", "build", "dist", "node_modules", "__pycache__")))
+        else:
+            files = [base]
+        for path in files:
+            key = str(path.resolve())
+            if key in seen or (not include_tests and _looks_like_tests(path)):
+                continue
+            seen.add(key)
+            try:
+                source = path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            routes, findings = analyze_source(source, str(path))
+            report.files += 1
+            report.routes += routes
+            report.findings.extend(findings)
+    report.findings.sort(key=lambda f: ({"high": 0, "medium": 1, "low": 2}[f.severity],
+                                        f.path, f.line))
+    return report

idemcheck/cli.py

@@ -0,0 +1,88 @@
+"""The command line: read paths, print findings, and answer with an exit code."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+from . import __version__
+from .analyze import analyze_files
+
+EXIT_OK = 0
+EXIT_FINDINGS = 1
+EXIT_USAGE = 2
+
+SEVERITIES = ("high", "medium", "low")
+SEVERITY_RANK = {name: index for index, name in enumerate(SEVERITIES)}
+
+FIX_HINT = (
+    "read an Idempotency-Key and store it before the first write, or make the write\n"
+    "         itself unique so a second delivery cannot land twice"
+)
+
+
+def render(findings: List[dict], files: int, routes: int) -> str:
+    if not findings:
+        return ("No issues found by idemcheck v%s across %d mutating route(s) in %d file(s).\n"
+                "That means no unguarded write was recognised, not that every handler is safe."
+                % (__version__, routes, files))
+
+    worst = min((f["severity"] for f in findings), key=lambda s: SEVERITY_RANK[s])
+    lines = ["idemcheck: %d finding(s) across %d mutating route(s) in %d file(s), worst %s"
+             % (len(findings), routes, files, worst), ""]
+    for f in findings:
+        lines.append("[%s] %s:%d (%s)" % (f["severity"].upper(), f["path"], f["line"], f["rule"]))
+        lines.append("  route: %s" % f["route"])
+        lines.append("  why:   %s" % f["detail"])
+        if f["writes"]:
+            lines.append("  calls: %s" % ", ".join(f["writes"]))
+        lines.append("  fix:   %s" % FIX_HINT)
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="idemcheck",
+        description="Find the HTTP handlers that will double-charge when a client retries.",
+    )
+    parser.add_argument("paths", nargs="*", default=["."],
+                        help="files or directories to scan (default: .)")
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    parser.add_argument("--fail-on", choices=("high", "medium", "low", "none"), default="high",
+                        help="lowest severity that fails the run (default: high)")
+    parser.add_argument("--include-tests", action="store_true",
+                        help="also scan tests/ and test_*.py")
+    parser.add_argument("--version", action="version", version="idemcheck %s" % __version__)
+    args = parser.parse_args(argv)
+
+    targets = [Path(p) for p in args.paths]
+    missing = [str(p) for p in targets if not p.exists()]
+    if missing:
+        print("no such path: %s" % ", ".join(missing), file=sys.stderr)
+        return EXIT_USAGE
+
+    report = analyze_files(targets, include_tests=args.include_tests)
+    findings = [f.to_dict() for f in report.findings]
+
+    if args.json:
+        print(json.dumps({
+            "findings": findings,
+            "summary": {"files": report.files, "routes": report.routes,
+                        "findings": len(findings), "fail_on": args.fail_on},
+        }, indent=2))
+    else:
+        print(render(findings, report.files, report.routes))
+
+    if args.fail_on == "none" or not findings:
+        return EXIT_OK
+    limit = SEVERITY_RANK[args.fail_on]
+    return EXIT_FINDINGS if any(SEVERITY_RANK[f["severity"]] <= limit for f in findings) \
+        else EXIT_OK
+
+
+if __name__ == "__main__":        # so `python -m idemcheck.cli` works too
+    raise SystemExit(main())

idemcheck-0.1.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: idemcheck
+Version: 0.1.0
+Summary: Find the HTTP handlers that will double-charge when a client retries.
+Author: mgkvibez
+License: MIT
+Keywords: idempotency,api,retries,payments,fastapi,flask,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# idemcheck
+
+Find the HTTP handlers that will double-charge when a client retries.
+
+A client retries because the network lied. If your handler writes before it can answer,
+the retry writes again. Idempotency libraries exist for every framework, and nothing tells
+you which of your routes is missing the guard.
+
+```
+$ idemcheck examples/
+idemcheck: 1 finding(s) across 2 mutating route(s) in 1 file(s), worst high
+
+[HIGH] examples/app.py:12 (missing-idempotency)
+  route: POST /charge
+  why:   charge with no idempotency key, dedupe store or unique constraint
+  calls: db.orders.insert_one, db.session.commit
+  fix:   read an Idempotency-Key and store it before the first write, or make the write
+         itself unique so a second delivery cannot land twice
+```
+
+The example file contains two POST handlers: `/charge` writes and is flagged, `/charge-safe`
+reads an `Idempotency-Key` first and is not.
+
+## Install
+
+```bash
+pipx install idemcheck     # once it is on PyPI
+# or straight from the repo:
+pipx install git+https://github.com/mgkvibez/idemcheck
+```
+
+Python 3.9 or newer. No runtime dependencies.
+
+## Usage
+
+```bash
+idemcheck                      # scan the current directory
+idemcheck src/ app.py          # scan specific paths
+idemcheck --json | jq .        # machine-readable
+idemcheck --fail-on medium     # stricter gate, for a payments service
+idemcheck --include-tests      # include tests/ (skipped by default)
+```
+
+Exit codes: `0` nothing at or above the threshold, `1` findings, `2` usage error.
+
+`--fail-on` defaults to `high`, so a `PUT` that writes without a guard reports and exits 0
+until you ask otherwise.
+
+## What it looks for
+
+A handler is a finding when it answers a mutating method **and** calls something that
+writes **and** nothing in it mentions a guard.
+
+| Severity | When |
+|---|---|
+| high | `POST`, or any outbound money/HTTP send, with unguarded writes |
+| medium | `PUT`/`PATCH`/`DELETE` with unguarded writes (they should already be idempotent) |
+
+Writes are recognised by method name: `commit`, `flush`, `insert*`, `update*`, `delete*`,
+`save`, `upsert`, `execute`, `add`, plus money movement like `charge`, `capture`,
+`transfer`, `refund`, and queue sends like `delay` and `enqueue`.
+
+A guard is recognised by any of: `idempotency`, `idempotent`, `idem_key`, `request_id`,
+`dedupe`, `dedup_key`, `nonce`, `client_reference`, `get_or_create`, `update_or_create`,
+`on_conflict`, `unique_together`.
+
+Routes are read from the decorator: `@app.post`, `@router.put`, and the
+`methods=[...]` keyword on `@app.route` and `@app.api_route` (Flask and FastAPI).
+
+## What this deliberately does not do
+
+Static analysis cannot prove a handler is safe, and this tool does not claim to.
+
+- A guard installed by a decorator defined in another module is invisible here.
+- An ORM that commits on your behalf, or a write hidden inside a helper function, is
+  invisible here.
+- Django class-based views, generic routers and dynamically constructed handlers are not
+  detected at all.
+- A handler that mentions `request_id` incidentally is treated as guarded, even when it is
+  not. That is a false negative, and it is the direction this tool errs on purpose: a
+  checker that cries wolf gets uninstalled after one afternoon.
+
+The clean line is exactly what it says: no unguarded write was **recognised**.
+
+## Tests
+
+```bash
+python -m pytest -q      # 19 tests
+bash scripts/verify.sh   # the release gate
+```
+
+## Contributing
+
+Adding a framework means teaching the decorator reader one more name in `analyze.py`, and
+adding a fixture that proves both the flagged and the guarded case. A rule that cannot show
+both is not ready.
+
+## License
+
+MIT.

idemcheck-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+idemcheck/__init__.py,sha256=GbStGxrquBtIDKnWCwLiF9a06cYSx60eRWbBew2qDzs,95
+idemcheck/analyze.py,sha256=JI_JVUxiTampFpMmGkAauSYz879crZmavyMDLlaK-q8,9201
+idemcheck/cli.py,sha256=YzKrq9DWwQ6LDYvqqdNw3eYCoXEIaJ0IoeW2cQUdgSY,3466
+idemcheck-0.1.0.dist-info/licenses/LICENSE,sha256=e-0Bks6hOWW2m30Xgh8w6CENzPJoV246vIq2lz_9Ing,1065
+idemcheck-0.1.0.dist-info/METADATA,sha256=SMpSxxoIQlu6ccNGl4l3DSMTDTjwt5A4uaSj8vGHCIA,4355
+idemcheck-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+idemcheck-0.1.0.dist-info/entry_points.txt,sha256=ABmFiCHP31Yq003bmI1c-vGHKGK9Hb9xlLeA-1QtI2A,49
+idemcheck-0.1.0.dist-info/top_level.txt,sha256=wtTQujSCAF4LpjXC361rBbCxou0DfPp5BOex_4wWbsk,10
+idemcheck-0.1.0.dist-info/RECORD,,

idemcheck-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

idemcheck-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+idemcheck = idemcheck.cli:main

idemcheck-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mgkvibez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

idemcheck-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+idemcheck