didntrun-sdk 1.0.0__py3-none-any.whl

didntrun/__init__.py

@@ -0,0 +1,25 @@
+"""First-party Python client for the didnt.run ping API.
+
+    from didntrun import Watchdog
+
+    wd = Watchdog.from_dsn(os.environ["DIDNT_RUN_DSN"])
+    wd.ping("app.daily-report")
+
+The contract: after construction, nothing in this package may slow the instrumented job beyond its
+time budget or fail it. Every transport problem is swallowed and logged.
+"""
+
+from didntrun.ping_kind import PingKind
+from didntrun.transport.base import TimeBudget, Transport, TransportResult
+from didntrun.transport.http_client import HttpClientTransport
+from didntrun.watchdog import Watchdog
+
+__all__ = [
+    "HttpClientTransport",
+    "PingKind",
+    "TimeBudget",
+    "Transport",
+    "TransportResult",
+    "Watchdog",
+]
+__version__ = "1.0.0"

didntrun/cli.py

@@ -0,0 +1,351 @@
+"""`didnt-run` — instrument a shell crontab without writing any Python.
+
+No logging is configured here on purpose. The library attaches no handler, so logging.lastResort
+writes WARNING and above to stderr — which is where a cron runner already looks, and which triggers
+cron mail regardless of the exit code.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import os
+import subprocess
+import sys
+import threading
+import time
+from collections.abc import Callable, Sequence
+from typing import IO
+
+from didntrun.log_text import one_line
+from didntrun.watchdog import Watchdog, _elapsed_ms
+
+_EXIT_USAGE = 2
+_REPORT_PREFIX = "didnt-run: "
+
+#: Which subcommands take a `-- <command>` tail. Declared once and checked once, because the rule
+#: "argv after `--` belongs to a subcommand that takes a command" was being spelled twice with
+#: opposite polarity — `_ping` rejecting a non-empty tail, `_run` rejecting an empty one — so a
+#: third subcommand would have started life with the hole open again.
+_TAKES_COMMAND = frozenset({"run"})
+
+
+def _check_arity(subcommand: str, external_id: str, command: list[str]) -> None:
+    if command and subcommand not in _TAKES_COMMAND:
+        # The worst failure a watchdog has. `ping` and `run` are adjacent subcommands whose argument
+        # lists look identical, so typing one for the other used to send a cheerful "the job ran"
+        # for a job that never executed — on schedule, forever, with nothing contradicting it. A
+        # missed alert is recoverable; a false all-clear is not.
+        raise _UsageError(
+            f"{subcommand} takes no command — did you mean "
+            f"`didnt-run run {external_id} -- {' '.join(command)}`?"
+        )
+    if not command and subcommand in _TAKES_COMMAND:
+        raise _UsageError(f"{subcommand} needs a command: didnt-run {subcommand} <id> -- <cmd> [args...]")
+
+
+def _stderr_writer() -> Callable[[bytes], None]:
+    """Resolve where the child's stderr goes ONCE, and never let it hurt the caller.
+
+    Three shapes of `sys.stderr` reach this in the wild. A real file object (cron) has `.buffer`.
+    A programmatic caller — which the `argv` parameter invites — may have replaced it with a
+    text-only object that has none. And when fd 2 is closed (`2>&-` in a crontab line is ordinary)
+    CPython sets `sys.stderr` to **None** outright, which the previous version of this function
+    did not survive: it crashed AFTER the wrapped command had already run.
+
+    Every writer swallows its own failures. A broken pipe on OUR stderr — `didnt-run run … 2>&1 |
+    head` is a normal idiom, and `head` closing early is the normal case — must not become the
+    wrapped command's problem.
+    """
+    stream = sys.stderr
+    if stream is None:
+        return lambda _chunk: None
+
+    sink = getattr(stream, "buffer", None)
+    if sink is not None:
+
+        def write_bytes(chunk: bytes) -> None:
+            with contextlib.suppress(Exception):
+                sink.write(chunk)
+                sink.flush()
+
+        return write_bytes
+
+    def write_text(chunk: bytes) -> None:
+        with contextlib.suppress(Exception):
+            stream.write(chunk.decode("utf-8", errors="replace"))
+            stream.flush()
+
+    return write_text
+
+
+def _quiet_broken_stderr() -> None:
+    """Stop a broken stderr pipe from becoming exit 120 at interpreter shutdown.
+
+    CPython exits **120** when it cannot flush sys.stderr on the way out, and that happens after
+    main() has returned the wrapped command's exit code — so `didnt-run run job -- cmd 2>&1 | head`
+    silently replaced a successful 0 with 120. Suppressing the write is not enough: the data is
+    still sitting in the buffer at shutdown. Pointing fd 2 at /dev/null once the pipe is known
+    broken gives the interpreter something it can flush.
+
+    `head`, `grep -m1` and `logger` all close early as a matter of course, so this is the ordinary
+    case for a crontab line, not an edge case.
+    """
+    if sys.stderr is None:
+        return
+    try:
+        sys.stderr.flush()
+    except Exception:
+        with contextlib.suppress(Exception):
+            os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stderr.fileno())
+
+
+def _report(message: str) -> None:
+    """The one place a CLI diagnostic reaches stderr.
+
+    docs/sdk-conformance.md C-9 — one call, one line — is a property of the package, not of
+    Watchdog. These messages interpolate raw argv (an external_id, a command line), so a CR/LF in
+    one would forge a second line indistinguishable from a genuine one.
+
+    It writes through _stderr_writer rather than `print(file=sys.stderr)`, because when fd 2 is
+    closed `sys.stderr` is None and `print(file=None)` falls back to **stdout** — which injects
+    `didnt-run:` chatter into the wrapped command's own output, breaking `didnt-run run j -- emit
+    -json | jq` in the one direction nothing tests for: not swallowing output, adding it.
+    """
+    _stderr_writer()(f"{one_line(_REPORT_PREFIX + message)}\n".encode())
+
+
+#: Shell convention: 126 = found but not executable, 127 = not found. The wrapper claims the
+#: crontab's semantics are unchanged, so it has to make the same distinction the shell does.
+_EXIT_NOT_FOUND = 127
+_EXIT_NOT_EXECUTABLE = 126
+_STDERR_TAIL_BYTES = 512
+_STDERR_TAIL_CHARS = 512
+#: How long to let the drain finish after the child exits. Bounded so a backgrounded grandchild
+#: holding the pipe open cannot keep the wrapper alive.
+_DRAIN_GRACE_S = 0.25
+
+
+class _UsageError(Exception):
+    """A usage problem: exit 2, and never run anything."""
+
+
+def _split_command(argv: list[str]) -> tuple[list[str], list[str]]:
+    """Split on the first `--`, before argparse sees anything.
+
+    argparse.REMAINDER is quirky and semi-deprecated, and the wrapped command's own flags (`-v`,
+    `--force`) must never be parsed as ours.
+    """
+    if "--" in argv:
+        index = argv.index("--")
+        return argv[:index], argv[index + 1 :]
+    return argv, []
+
+
+def _parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--dsn", default=None, help="Overrides $DIDNT_RUN_DSN.")
+    common.add_argument(
+        "--meta",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="Extra context for the ping; repeatable. Values are always strings.",
+    )
+
+    parser = argparse.ArgumentParser(prog="didnt-run", description="didnt.run watchdog client.")
+    subparsers = parser.add_subparsers(dest="subcommand", required=True)
+
+    ping = subparsers.add_parser("ping", parents=[common], help="Send one 'the job ran' ping.")
+    ping.add_argument("external_id")
+    ping.add_argument("--duration-ms", type=int, default=None)
+
+    run = subparsers.add_parser(
+        "run",
+        parents=[common],
+        help="Run a command, then report how it went.",
+        epilog="Example: didnt-run run backups.nightly -- /usr/bin/backup.sh --full",
+    )
+    run.add_argument("external_id")
+    run.add_argument("--lifecycle", action="store_true", help="Also send a start ping first.")
+    run.add_argument(
+        "--capture-stderr",
+        action="store_true",
+        help="Tee stderr and put its last 512 bytes in meta. OFF by default: a failing command's "
+        "stderr routinely contains connection strings, and unlike an exception message you did "
+        "not write it and cannot predict it.",
+    )
+    return parser
+
+
+def _meta(pairs: Sequence[str]) -> dict[str, str]:
+    meta: dict[str, str] = {}
+    for pair in pairs:
+        key, separator, value = pair.partition("=")
+        if not separator or not key:
+            raise _UsageError(f"--meta expects KEY=VALUE, got {pair!r}")
+        meta[key] = value
+    return meta
+
+
+def _run_meta(pairs: Sequence[str]) -> dict[str, str]:
+    """`--meta` for `run`, where a typo must not stop the backup.
+
+    It was the ONLY watchdog-side input on this path that could: a missing DSN, a malformed DSN, an
+    empty external_id and an oversize one all run the command anyway, on the stated reasoning that
+    this executes at cron time rather than wiring time. A metadata typo is strictly less important
+    than any of those, and it was the one that silently stopped the job — forever, since a crontab
+    line does not get retyped.
+    """
+    try:
+        return _meta(pairs)
+    except _UsageError as error:
+        _report(f"{error} — continuing without it")
+        return {}
+
+
+def _watchdog(args: argparse.Namespace) -> Watchdog:
+    dsn = args.dsn or os.environ.get("DIDNT_RUN_DSN", "")
+    if not dsn:
+        raise ValueError("no DSN: set $DIDNT_RUN_DSN or pass --dsn")
+    return Watchdog.from_dsn(dsn)
+
+
+def _ping(args: argparse.Namespace, meta: dict[str, str]) -> int:
+
+    try:
+        watchdog = _watchdog(args)
+    except ValueError as error:
+        _report(f"{error}")
+        return _EXIT_USAGE
+
+    # The return value is deliberately discarded. An undeliverable ping is already a log line on
+    # stderr, which is what cron mails on; failing the command as well would make a brief watchdog
+    # outage look like a failed backup.
+    watchdog.ping(args.external_id, duration_ms=args.duration_ms, meta=meta or None)
+    return 0
+
+
+def _drain(stream: IO[bytes], write: Callable[[bytes], None], tail: bytearray) -> None:
+    """Tee the child's stderr as it arrives, keeping the last _STDERR_TAIL_BYTES.
+
+    `os.read` rather than `stream.read(4096)`: BufferedReader.read(n) blocks until it has n bytes or
+    EOF, so a job that logs a line then works for three minutes had its line withheld for three
+    minutes — and if the wrapper died in between, that output was lost where it would have reached
+    cron mail unwrapped. os.read returns whatever is available.
+
+    Swallows everything. This runs on a thread alongside a command that is already executing, and
+    the one job it must never do is turn a problem with OUR stderr into a problem for the child.
+    """
+    with contextlib.suppress(Exception):
+        while True:
+            chunk = os.read(stream.fileno(), 4096)
+            if not chunk:
+                return
+            write(chunk)
+            tail.extend(chunk)
+            del tail[:-_STDERR_TAIL_BYTES]
+
+
+def _execute(command: list[str], *, capture_stderr: bool) -> tuple[int, str | None]:
+    """Run the command. Returns (returncode, stderr tail or None).
+
+    Without capture this is a plain passthrough — the child inherits our stdio, so cron sees exactly
+    what it would have seen without the wrapper.
+
+    With capture the drain runs on a THREAD while this one waits on the child, which is not a
+    refinement but a correctness fix. Reading to EOF in the foreground waits for the last writer to
+    close the pipe, and a child that backgrounds anything (`sleep 5 & exit 0`) keeps it open — so
+    the wrapper returned five seconds after the command did, reported an inflated duration into the
+    p99 that feeds hung detection, and with a real daemon never returned at all. Turning on a
+    metadata flag must not change when the wrapper returns.
+    """
+    if not capture_stderr:
+        return subprocess.run(command, check=False).returncode, None
+
+    tail = bytearray()
+    process = subprocess.Popen(command, stderr=subprocess.PIPE)
+    stream = process.stderr
+    if stream is None:  # pragma: no cover - PIPE always provides one
+        return process.wait(), None
+
+    drain = threading.Thread(target=_drain, args=(stream, _stderr_writer(), tail), daemon=True)
+    drain.start()
+    returncode = process.wait()
+    drain.join(timeout=_DRAIN_GRACE_S)
+    with contextlib.suppress(Exception):
+        stream.close()
+
+    # Truncate AFTER decoding: errors="replace" expands each orphaned byte into a 3-byte U+FFFD, so
+    # capping the bytearray alone let the tail exceed the 512 bytes --help promises.
+    return returncode, tail.decode("utf-8", errors="replace")[-_STDERR_TAIL_CHARS:]
+
+
+def _run(args: argparse.Namespace, meta: dict[str, str], command: list[str]) -> int:
+    watchdog: Watchdog | None
+    try:
+        watchdog = _watchdog(args)
+    except ValueError as error:
+        # Deliberately NOT fatal, unlike `ping`: there is a command to protect, and this runs at
+        # cron time rather than at wiring time.
+        _report(f"{error} — running the command uninstrumented")
+        watchdog = None
+
+    if watchdog is not None and (args.lifecycle or watchdog.lifecycle):
+        watchdog.start(args.external_id, meta=meta or None)
+
+    started = time.monotonic()
+    try:
+        returncode, stderr_tail = _execute(command, capture_stderr=args.capture_stderr)
+    except OSError as error:
+        not_runnable = _EXIT_NOT_EXECUTABLE if isinstance(error, PermissionError) else _EXIT_NOT_FOUND
+        elapsed_ms = _elapsed_ms(started)
+        if watchdog is not None:
+            watchdog.fail(
+                args.external_id,
+                duration_ms=elapsed_ms,
+                meta={**meta, "exit_code": not_runnable, "error": str(error)},
+            )
+        _report(f"{error}")
+        return not_runnable
+
+    elapsed_ms = _elapsed_ms(started)
+    # subprocess reports a signal death as a NEGATIVE returncode; shells report 128 + signal.
+    exit_code = returncode if returncode >= 0 else 128 - returncode
+    outcome: dict[str, object] = {**meta, "exit_code": exit_code}
+    if returncode < 0:
+        outcome["signal"] = -returncode
+    if stderr_tail is not None:
+        outcome["stderr_tail"] = stderr_tail
+
+    if watchdog is not None:
+        report = watchdog.success if exit_code == 0 else watchdog.fail
+        report(args.external_id, duration_ms=elapsed_ms, meta=outcome)
+
+    return exit_code
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    try:
+        return _main(argv)
+    finally:
+        _quiet_broken_stderr()
+
+
+def _main(argv: Sequence[str] | None = None) -> int:
+    raw = list(sys.argv[1:] if argv is None else argv)
+    before, command = _split_command(raw)
+    try:
+        args = _parser().parse_args(before)
+        _check_arity(args.subcommand, args.external_id, command)
+        if args.subcommand == "ping":
+            # `ping` has nothing to protect, so a bad --meta is fatal here.
+            return _ping(args, _meta(args.meta))
+        return _run(args, _run_meta(args.meta), command)
+    except _UsageError as error:
+        _report(f"{error}")
+        return _EXIT_USAGE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

didntrun/external_id.py

@@ -0,0 +1,33 @@
+"""The FQCN-friendly external_id normalizer.
+
+IDENTITY-DEFINING: renaming a class, or moving a function between modules, renames the job. Dots
+instead of backslashes so ids survive proxies (%5C mangling) and read cleanly in the SPA.
+"""
+
+#: Mirrors ping-api's RecordPing::MAX_EXTERNAL_ID_LENGTH. Counted in BYTES, because the server
+#: checks strlen() — see truncate().
+MAX_LENGTH = 255
+
+
+def normalize(raw: str) -> str | None:
+    """Return the canonical id, or None when it normalizes to nothing."""
+    identifier = raw.lstrip("\\").replace("\\", ".")
+    return identifier or None
+
+
+def byte_length(identifier: str) -> int:
+    """The length the server will measure."""
+    return len(identifier.encode("utf-8"))
+
+
+def truncate(identifier: str) -> str:
+    """Cut to MAX_LENGTH *bytes*, dropping a trailing partial character rather than splitting one.
+
+    `len()` counts characters and the server counts bytes, so a non-ASCII id can be under the cap by
+    one measure and over it by the other. Slicing bytes can land mid-sequence, which is what
+    errors="ignore" cleans up.
+    """
+    encoded = identifier.encode("utf-8")
+    if len(encoded) <= MAX_LENGTH:
+        return identifier
+    return encoded[:MAX_LENGTH].decode("utf-8", errors="ignore")

didntrun/log_text.py

@@ -0,0 +1,15 @@
+"""One log() call must produce exactly ONE log line, whatever the sink.
+
+Context values arrive verbatim from the caller: `external_id` is whatever the consumer passed, and
+normalize() maps backslashes to dots without stripping control characters. A CR/LF in one forges a
+second line indistinguishable from a genuine SDK line; an ESC writes raw ANSI into whatever terminal
+an operator is tailing.
+"""
+
+import re
+
+_CONTROL = re.compile(r"[\x00-\x1f\x7f]")
+
+
+def one_line(value: str) -> str:
+    return _CONTROL.sub("?", value)

didntrun/ping_kind.py

@@ -0,0 +1,12 @@
+"""The lifecycle vocabulary. Values mirror the domain's PingKind — pinned by the contract suite."""
+
+from enum import StrEnum
+
+
+class PingKind(StrEnum):
+    """`RUN` is the one-ping "the job ran" signal; the other three bracket a run."""
+
+    RUN = "run"
+    START = "start"
+    SUCCESS = "success"
+    FAIL = "fail"

didntrun/transport/__init__.py

@@ -0,0 +1,4 @@
+from didntrun.transport.base import TimeBudget, Transport, TransportResult
+from didntrun.transport.http_client import HttpClientTransport
+
+__all__ = ["HttpClientTransport", "TimeBudget", "Transport", "TransportResult"]

didntrun/transport/base.py

@@ -0,0 +1,84 @@
+"""The transport seam: the interface that lets the SDK promise it never hurts the job."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class TimeBudget:
+    """A wall-clock ceiling for one ping, plus the share of it the connect phase may use."""
+
+    total_ms: int
+    connect_ms: int
+
+    def __post_init__(self) -> None:
+        if self.total_ms < 1 or self.connect_ms < 1:
+            raise ValueError("Timeout budget must be positive milliseconds.")
+
+    def remaining_from(self, started: float, *, floor_ms: int) -> TimeBudget | None:
+        """What is left of this budget since `started`, or None if less than `floor_ms` remains.
+
+        The guard lives with the invariant rather than in a docstring telling callers to check
+        first. In a package whose top-line contract is that nothing raises after construction, a
+        value object whose safe use is guaranteed by a comment is one rung too low — and it held
+        only by accident, because the retry floor that happened to call it is also >= 1.
+        """
+        remaining_ms = self.total_ms - int((time.monotonic() - started) * 1000)
+        if remaining_ms < floor_ms or remaining_ms < 1:
+            return None
+        return self.with_total(remaining_ms)
+
+    def with_total(self, total_ms: int) -> TimeBudget:
+        """The retry's shrunken budget: whatever wall-clock remains, connect capped to fit.
+
+        The caller must ensure total_ms >= 1 — __post_init__ raises otherwise, so guard the
+        remainder before shrinking.
+        """
+        return TimeBudget(total_ms, min(self.connect_ms, total_ms))
+
+
+@dataclass(frozen=True, slots=True)
+class TransportResult:
+    """What a transport reports back. Either a status was received, or it was not."""
+
+    status: int | None
+    error: str | None
+
+    @classmethod
+    def response(cls, status: int) -> TransportResult:
+        return cls(status, None)
+
+    @classmethod
+    def failure(cls, error: str) -> TransportResult:
+        return cls(None, error)
+
+    @property
+    def is_connection_failure(self) -> bool:
+        """No HTTP response at all — refused, DNS, or a timeout before the status line.
+
+        NOT the retry predicate: retry policy is the client's concern and lives in
+        Watchdog._is_retryable(), which also retries 408 and 5xx. This stays a dumb value object.
+        """
+        return self.status is None
+
+
+class Transport(Protocol):
+    """A Protocol, not a base class: a requests/httpx adapter satisfies it without importing us.
+
+    Implementations MUST NOT raise, MUST NOT exceed the budget, and MUST NOT follow redirects — a
+    redirect-following transport silently changes ping semantics. Report every problem as
+    TransportResult.failure(). Return TransportResult.response() only when an actual HTTP status was
+    received; anything earlier is a failure.
+    """
+
+    def post(
+        self,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes,
+        budget: TimeBudget,
+    ) -> TransportResult: ...