httptap 0.6.2__tar.gz → 0.7.0__tar.gz

{httptap-0.6.2 → httptap-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httptap
-Version: 0.6.2
+Version: 0.7.0
 Summary: HTTP request visualizer with detailed timing breakdown (DNS → TCP → TLS → HTTP)
 Keywords: http,https,performance,timing,dns,tls,ssl,networking,monitoring,diagnostics,waterfall,curl,httpx
 Author: Sergei Ozeranskii
@@ -14,13 +14,13 @@ Classifier: Topic :: System :: Networking :: Monitoring
 Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: Utilities
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
 Classifier: Environment :: Console
 Classifier: Operating System :: OS Independent
 Classifier: Operating System :: POSIX
@@ -28,17 +28,22 @@ Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Typing :: Typed
 Requires-Dist: httpx[http2,socks]>=0.28.1
+Requires-Dist: httpcore>=1.0.0
 Requires-Dist: rich>=14.3.2
-Requires-Dist: dnspython>=2.8.0
+Requires-Dist: cryptography>=50.0.2
 Requires-Dist: argcomplete>=3.7.2 ; extra == 'completion'
+Requires-Dist: opentelemetry-api>=1.30.0 ; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.30.0 ; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30.0 ; extra == 'otel'
 Maintainer: Sergei Ozeranskii
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/ozeranskii/httptap
 Project-URL: Documentation, https://docs.httptap.dev
 Project-URL: Repository, https://github.com/ozeranskii/httptap.git
 Project-URL: Issues, https://github.com/ozeranskii/httptap/issues
 Project-URL: Changelog, https://github.com/ozeranskii/httptap/blob/main/CHANGELOG.md
 Provides-Extra: completion
+Provides-Extra: otel
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -160,13 +165,21 @@ performance baselines.
   data is unavailable).
 - **All HTTP methods** – GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS with request body support.
 - **Request body support** – send JSON, XML, or any data inline or from file with automatic Content-Type detection.
-- **IPv4/IPv6 aware** – the resolver and TLS inspector report both the address and its family.
+- **IPv4/IPv6 aware** – the resolver and TLS inspector report both the address and its family; `-4`/`-6` restrict
+  resolution to one family, and `--resolve HOST:PORT:ADDR` pins a host to an address while keeping the original `Host`
+  header and TLS SNI.
 - **TLS insights** – certificate CN, SANs, issuer, serial, validity window and expiry countdown, plus cipher suite and
   protocol version, are captured automatically from the live connection (no extra handshake).
 - **Multiple output modes** – rich waterfall view, compact single-line summaries, or `--metrics-only` for scripting.
-- **JSON export** – persist full step data (including redirect chains) for later processing.
-- **SLO threshold checking** – `--slo total=500,ttfb=200` gates CI jobs, cron probes, and readiness checks on per-phase
-  latency budgets; non-zero exit on violation while still rendering the full report.
+- **JSON export** – persist full step data (including redirect chains) for later processing, or stream it to stdout with
+  `--json -`.
+- **Prometheus and OpenTelemetry export** – `--prometheus PATH` writes a node_exporter textfile; `--otlp ENDPOINT` sends
+  per-phase spans to an OTLP/HTTP collector (requires `httptap[otel]`).
+- **SLO threshold checking** – `--slo total=500,ttfb=200` (or thresholds read from a file with `--slo-file`) gates CI
+  jobs, cron probes, and readiness checks on per-phase latency budgets; non-zero exit on violation while still rendering
+  the full report.
+- **Scriptable exit codes** – `-f/--fail` exits `22` on HTTP 4xx/5xx responses, and SLO violations, network errors, and
+  the redirect limit each have their own [exit code](#exit-codes).
 - **Extensible** – clean Protocol interfaces for DNS, TLS, timing, visualization, and export so you can plug in custom
   behavior.
 
@@ -203,7 +216,7 @@ performance baselines.
 
 ## Requirements
 
-- Python 3.10-3.15 (CPython)
+- Python 3.11-3.15 (CPython)
 - macOS, Linux, or Windows (tested on CPython)
 - No system dependencies beyond standard networking
 - Code must follow the Google Python Style Guide (docstrings, formatting). See
@@ -299,6 +312,20 @@ If you installed httptap via `pip` or `uv`, you need to install the optional com
 
 **Note:** The global activation script provides argument completions for bash and zsh only. Other shells are not covered by the script and must be configured separately.
 
+#### Isolated installs (`uv tool`, `pipx`)
+
+`uv tool install` and `pipx install` put only the `httptap` command on your `PATH`, not argcomplete's helper scripts. Expose them at install time, then register completion for `httptap` in your shell startup file (e.g. `~/.bashrc` or `~/.zshrc`):
+
+```shell
+uv tool install --with-executables-from argcomplete "httptap[completion]"
+# or
+pipx install --include-resources-from argcomplete "httptap[completion]"
+
+eval "$(register-python-argcomplete httptap)"
+```
+
+Older pipx releases without `--include-resources-from` can use `--include-deps` instead.
+
 #### Usage Examples
 
 Once completions are installed, you can use `Tab` to autocomplete commands and options:
@@ -306,7 +333,7 @@ Once completions are installed, you can use `Tab` to autocomplete commands and o
 ```shell
 # Complete command options
 httptap --<TAB>
-# Shows: --method, --data, --follow, --timeout, --no-http2, --ignore-ssl, --cacert, --proxy, --header, --compact, --metrics-only, --json, --version, --help
+# Shows: --help --version --request --method --data --location --follow --max-time --timeout --no-http2 --http1.1 --fail --ipv4 --ipv6 --resolve --insecure --ignore-ssl --cacert --ca-bundle --proxy --header --compact --metrics-only --json --prometheus --otlp --slo --slo-file
 
 # Complete after typing partial option
 httptap --fol<TAB>
@@ -339,7 +366,7 @@ httptap https://httpbin.io/post --data '{"name": "John", "email": "john@example.
 
 **Note:** When `--data` is provided without `--method`, httptap automatically switches to POST (similar to curl).
 
-**Curl-compatible flags:** httptap accepts the most common curl syntax, so you can often replace `curl` with `httptap` directly. Aliases include `-X/--request` for `--method`, `-L/--location` for `--follow`, `-m/--max-time` for `--timeout`, `-k/--insecure` for `--ignore-ssl`, `-x` for `--proxy`, and `--http1.1` for `--no-http2`. (Not every curl option is supported—stick to these shared flags when swapping commands.)
+**Curl-compatible flags:** httptap accepts the most common curl syntax, so you can often replace `curl` with `httptap` directly. Aliases include `-X/--request` for `--method`, `-L/--location` for `--follow`, `-m/--max-time` for `--timeout`, `-k/--insecure` for `--ignore-ssl`, `-x` for `--proxy`, and `--http1.1` for `--no-http2`. `-f/--fail`, `-4/--ipv4`, `-6/--ipv6`, and `--resolve HOST:PORT:ADDR` use the same names as in curl. (Not every curl option is supported—stick to these shared flags when swapping commands.)
 
 Load data from file:
 
@@ -384,6 +411,9 @@ httptap \
   https://httpbin.io/bearer
 ```
 
+Header names must be HTTP tokens and values printable ASCII (spaces and tabs allowed). Anything else, such as CR/LF or
+non-ASCII text, is rejected with exit code `64` before any request is made.
+
 ### Redirects and JSON Export
 
 Follow redirect chains and dump metrics to JSON:
@@ -392,6 +422,10 @@ Follow redirect chains and dump metrics to JSON:
 httptap --follow --json out/report.json https://httpbin.io/redirect/2
 ```
 
+A redirect to a URL that cannot be requested (invalid port, missing host, non-HTTP scheme) ends the chain with a failed
+step, `Invalid redirect target: …`, and exit code `75`. Credentials in `Location` URLs are masked in the output and JSON
+export.
+
 ### Output Modes
 
 Collect compact (single-line) timings suitable for logs:
@@ -450,7 +484,9 @@ httptap --proxy "" https://httpbin.io/get
 
 The output and JSON export include the proxy URI and its source so you
 can confirm what path was used (e.g., `(from arg --proxy)`,
-`(from env HTTPS_PROXY)`, `(bypassed by env no_proxy)`).
+`(from env HTTPS_PROXY)`, `(bypassed by env no_proxy)`). Proxy credentials
+are masked (`http://user:****@proxy:3128`). A malformed `--proxy` value is
+rejected with exit code `64`.
 
 ---
 
@@ -499,23 +535,28 @@ Full specification, evaluation rules, and recipes:
 
 ## Environment Variables
 
-httptap reads the following environment variables at runtime. All of them are
-overridable via CLI flags, and the actual source used for each request is
-recorded in the output and JSON export.
+httptap reads the following environment variables at runtime. The proxy
+variables can be overridden with `-x/--proxy` or ignored with `--proxy ""`, and
+the proxy source used for each request is recorded in the output and JSON
+export. The color variables have no CLI equivalent.
 
 | Variable                              | Purpose                                                                                                      | Overridden by         |
 |---------------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------|
 | `HTTP_PROXY` / `http_proxy`           | Proxy URL used for `http://` targets.                                                                        | `-x/--proxy`          |
 | `HTTPS_PROXY` / `https_proxy`         | Proxy URL used for `https://` targets.                                                                       | `-x/--proxy`          |
 | `ALL_PROXY` / `all_proxy`             | Fallback proxy URL when scheme-specific variables are unset.                                                 | `-x/--proxy`          |
-| `NO_PROXY` / `no_proxy`               | Comma-separated exclusion list (supports `*`, leading `.`, exact matches). Bypassed entries connect direct.  | `--proxy ""`          |
+| `NO_PROXY` / `no_proxy`               | Comma-separated exclusion list: `*` matches every host, `example.com` the host and its subdomains, `.example.com` subdomains only. No CIDR ranges. Bypassed hosts connect direct. | `-x/--proxy`, `--proxy ""` |
 | `NO_COLOR`                            | Disables ANSI colors in all Rich output (honors the [NO_COLOR](https://no-color.org) convention).            | —                     |
 | `FORCE_COLOR`                         | Forces colored output even when stdout is not a TTY (Rich convention).                                       | —                     |
 | `TERM=dumb`                           | Rich downgrades to plain-text rendering.                                                                     | —                     |
 
-> Precedence for proxy configuration: explicit `-x/--proxy` → `--proxy ""`
-> (disables env) → `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY` (scheme-matching) →
-> `NO_PROXY` exclusion → direct connection.
+> Precedence for proxy configuration: explicit `-x/--proxy` or `--proxy ""`
+> (disables env) → `NO_PROXY` exclusion (direct connection) → the variable
+> matching the URL scheme (`HTTPS_PROXY` or `HTTP_PROXY`) → `ALL_PROXY` →
+> direct connection. Lowercase variables take priority over uppercase ones.
+> A proxy variable without a scheme (`proxy.local:3128`) is treated as
+> `http://`; one that is not a valid proxy URL fails the request with a
+> network error (exit code `75`).
 
 ---
 
@@ -528,11 +569,20 @@ shell pipelines, CI jobs, and systemd services.
 |:-----:|-------------------------|------------------------------------------------------------|
 | `0`   | `EX_OK`                 | Success.                                                   |
 | `4`   | —                       | SLO threshold violation (request succeeded but too slow).  |
+| `22`  | —                       | HTTP 4xx/5xx response when `-f` / `--fail` is used.        |
+| `47`  | —                       | Maximum redirects followed.                                |
 | `64`  | `EX_USAGE`              | Invalid command-line arguments.                            |
 | `70`  | `EX_SOFTWARE`           | Internal error (unexpected exception, bug).                |
+| `73`  | `EX_CANTCREAT`          | `--json` output file could not be written.                 |
 | `75`  | `EX_TEMPFAIL`           | Network / TLS error (partial output may still be rendered). |
 | `128 + N` | Signal offset       | Killed by signal `N` (e.g., `130` for `SIGINT` / Ctrl-C).  |
 
+When several conditions apply, the highest-priority code wins:
+`70` > `47` > `75` > `73` > `22` > `4` > `0`. Invalid arguments (`64`) are
+reported before any request is made. See
+[SLO exit codes](https://docs.httptap.dev/usage/slo/#exit-codes) for the full
+precedence table.
+
 Example — fail a CI job only on usage errors, tolerating transient network
 issues:
 
@@ -549,26 +599,20 @@ fi
 
 ## Releasing
 
-### Prerequisites
+Releases are cut by the manually triggered **Release** workflow (GitHub Actions → **Release** → **Run workflow**) with
+either an exact version (e.g., `0.3.0`) or a `patch`/`minor`/`major` bump:
 
-- GitHub Environment `pypi` must be configured in repository settings
-- PyPI Trusted Publishing configured for `ozeranskii/httptap`
+1. **Prepare** – bumps the version with `uv version`, refreshes `uv.lock`, prepends the `git-cliff` changelog entry to
+   `CHANGELOG.md`, and creates a gitsign-signed release commit and tag locally. Nothing is pushed yet.
+2. **Build** – runs the full test suite on the unpushed tag, builds the wheel and sdist, generates the SBOMs (CycloneDX,
+   SPDX), OpenVEX document, and man page, and attests build provenance.
+3. **Push** – only after the build and attestation succeed, fast-forwards `main` to the release commit and pushes the
+   tag. If `main` moved during the release, the push fails and nothing is published.
+4. **Publish** – uploads to TestPyPI and then PyPI via Trusted Publishing (OIDC), pushes the signed multi-arch container
+   image to GHCR, and creates the GitHub Release with the wheel, sdist, SBOM, VEX, and man page.
 
-### Steps
-
-1. Trigger the **Release** workflow from GitHub Actions:
-   - Provide exact version (e.g., `0.3.0`), OR
-   - Select bump type: `patch`, `minor`, or `major`
-2. The workflow will:
-   - Update version in `pyproject.toml` using `uv version`
-   - Generate changelog with `git-cliff` and update `CHANGELOG.md`
-   - Commit changes and create a git tag
-   - Run full test suite on the tagged version
-   - Build wheel and source distribution
-   - Generate SBOM in CycloneDX and SPDX formats via Syft
-   - Attach the current OpenVEX document (`.vex/httptap.openvex.json`)
-   - Publish to PyPI via Trusted Publishing (OIDC)
-   - Create GitHub Release with wheel, sdist, SBOM, and VEX assets
+Prerequisites (GitHub environments, Trusted Publishing, deploy key) and job details are in the
+[release process documentation](https://docs.httptap.dev/development/release/).
 
 ---
 
@@ -585,6 +629,9 @@ The redirect summary includes a total row:
 
 ```json
 {
+  "schema_version": 1,
+  "httptap_version": "0.6.3",
+  "timestamp": "2026-09-18T08:00:00Z",
   "initial_url": "https://httpbin.io/redirect/2",
   "total_steps": 3,
   "steps": [
@@ -613,14 +660,14 @@ The redirect summary includes a total row:
         "tls_version": "TLSv1.2",
         "tls_cipher": "ECDHE-RSA-AES128-GCM-SHA256",
         "cert_cn": "httpbin.io",
-        "cert_days_left": 143,
+        "cert_days_left": 41,
         "cert_sans": ["httpbin.io", "*.httpbin.io"],
         "cert_issuer": "WE1",
         "cert_serial": "05BB0F0AA84C8FECE0E72D805BA7A5D2B",
-        "cert_not_before": "2025-04-01T00:00:00+00:00",
-        "cert_not_after": "2025-09-01T00:00:00+00:00",
+        "cert_not_before": "2026-08-01T00:00:00+00:00",
+        "cert_not_after": "2026-10-30T00:00:00+00:00",
         "tls_verified": true,
-        "tls_custom_ca": null,
+        "tls_custom_ca": false,
         "proxy_url": null,
         "proxy_source": null
       },
@@ -629,18 +676,19 @@ The redirect summary includes a total row:
         "bytes": 0,
         "content_type": null,
         "server": null,
-        "date": "2025-10-23T19:20:36+00:00",
+        "date": "2026-09-18T07:59:59+00:00",
         "location": "/relative-redirect/1",
         "headers": {
           "access-control-allow-credentials": "true",
           "access-control-allow-origin": "*",
           "location": "/relative-redirect/1",
-          "date": "Thu, 23 Oct 2025 19:20:36 GMT",
+          "date": "Fri, 18 Sep 2026 07:59:59 GMT",
           "content-length": "0"
         }
       },
       "error": null,
       "note": null,
+      "redirect_limit_reached": false,
       "proxy": null
     },
     {
@@ -668,14 +716,14 @@ The redirect summary includes a total row:
         "tls_version": "TLSv1.2",
         "tls_cipher": "ECDHE-RSA-AES128-GCM-SHA256",
         "cert_cn": "httpbin.io",
-        "cert_days_left": 143,
+        "cert_days_left": 41,
         "cert_sans": ["httpbin.io", "*.httpbin.io"],
         "cert_issuer": "WE1",
         "cert_serial": "05BB0F0AA84C8FECE0E72D805BA7A5D2B",
-        "cert_not_before": "2025-04-01T00:00:00+00:00",
-        "cert_not_after": "2025-09-01T00:00:00+00:00",
+        "cert_not_before": "2026-08-01T00:00:00+00:00",
+        "cert_not_after": "2026-10-30T00:00:00+00:00",
         "tls_verified": true,
-        "tls_custom_ca": null,
+        "tls_custom_ca": false,
         "proxy_url": null,
         "proxy_source": null
       },
@@ -684,18 +732,19 @@ The redirect summary includes a total row:
         "bytes": 0,
         "content_type": null,
         "server": null,
-        "date": "2025-10-23T19:20:36+00:00",
+        "date": "2026-09-18T07:59:59+00:00",
         "location": "/get",
         "headers": {
           "access-control-allow-credentials": "true",
           "access-control-allow-origin": "*",
           "location": "/get",
-          "date": "Thu, 23 Oct 2025 19:20:36 GMT",
+          "date": "Fri, 18 Sep 2026 07:59:59 GMT",
           "content-length": "0"
         }
       },
       "error": null,
       "note": null,
+      "redirect_limit_reached": false,
       "proxy": null
     },
     {
@@ -723,14 +772,14 @@ The redirect summary includes a total row:
         "tls_version": "TLSv1.2",
         "tls_cipher": "ECDHE-RSA-AES128-GCM-SHA256",
         "cert_cn": "httpbin.io",
-        "cert_days_left": 143,
+        "cert_days_left": 41,
         "cert_sans": ["httpbin.io", "*.httpbin.io"],
         "cert_issuer": "WE1",
         "cert_serial": "05BB0F0AA84C8FECE0E72D805BA7A5D2B",
-        "cert_not_before": "2025-04-01T00:00:00+00:00",
-        "cert_not_after": "2025-09-01T00:00:00+00:00",
+        "cert_not_before": "2026-08-01T00:00:00+00:00",
+        "cert_not_after": "2026-10-30T00:00:00+00:00",
         "tls_verified": true,
-        "tls_custom_ca": null,
+        "tls_custom_ca": false,
         "proxy_url": null,
         "proxy_source": null
       },
@@ -739,18 +788,19 @@ The redirect summary includes a total row:
         "bytes": 389,
         "content_type": "application/json; charset=utf-8",
         "server": null,
-        "date": "2025-10-23T19:20:37+00:00",
+        "date": "2026-09-18T08:00:00+00:00",
         "location": null,
         "headers": {
           "access-control-allow-credentials": "true",
           "access-control-allow-origin": "*",
           "content-type": "application/json; charset=utf-8",
-          "date": "Thu, 23 Oct 2025 19:20:37 GMT",
+          "date": "Fri, 18 Sep 2026 08:00:00 GMT",
           "content-length": "389"
         }
       },
       "error": null,
       "note": null,
+      "redirect_limit_reached": false,
       "proxy": null
     }
   ],
@@ -795,6 +845,11 @@ analyzer = HTTPTapAnalyzer(dns_resolver=HardcodedDNS())
 steps = analyzer.analyze_url("https://httpbin.io")
 ```
 
+`HardcodedDNS` overrides only `resolve()`, so httptap calls it instead of the inherited `resolve_all()` and connects to
+that single address. Override `resolve_all()` as well to return several addresses for connection fallback, and raise
+`DNSResolutionError` when a name cannot be resolved; see
+[Protocol Interfaces](https://docs.httptap.dev/api/interfaces/#dnsresolver).
+
 ---
 
 ## Development
@@ -808,7 +863,13 @@ uv run ruff check
 uv run ruff format .
 ```
 
-Tests expect outbound network access; you can mock `SystemDNSResolver` / `SocketTLSInspector` when running offline.
+The test suite does not need outbound network access: HTTP calls are mocked with `pytest-httpx`, and TLS and proxy tests use local servers.
+
+The end-to-end tests in `tests/e2e` run the `httptap` CLI as a subprocess against local HTTP, TLS, proxy and OTLP servers, so they need no outbound network access either. A plain `uv run pytest` skips them; run them with:
+
+```shell
+uv run --extra otel pytest tests/e2e --no-cov -n auto
+```
 
 ---
 
@@ -834,7 +895,7 @@ details.
 
 - Built on the shoulders of fantastic
   libraries: [httpx](https://www.python-httpx.org/), [httpcore](https://github.com/encode/httpcore),
-  [dnspython](https://www.dnspython.org/), and [Rich](https://github.com/Textualize/rich).
+  [cryptography](https://cryptography.io/), and [Rich](https://github.com/Textualize/rich).
 - Inspired by the tooling ecosystem around web performance (e.g., DevTools waterfalls, `curl --trace`).
 - Special thanks to everyone who opens issues, shares ideas, or contributes patches.