Add Natvis definitions for some of the core types in the http crate…

…. Add tests and a testing framework to ensure the Natvis definitions do not become stale and/or broken. Add a README.md to describe how to define Natvis visualizations, embed them into the `http` crate, and test them to ensure they do not become stale and/or broken.
hyperium · Aug 3, 2022 · ed04b40 · ed04b40
1 parent 34a9d6b
commit ed04b40
Show file tree

Hide file tree

Showing 6 changed files with 377 additions and 2 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -11,10 +11,12 @@ env:
 jobs:
 
   test:
-    name: Test ${{ matrix.rust }}
+    name: Test ${{ matrix.os }}-${{ matrix.rust }}
     #needs: [style]
     strategy:
       matrix:
+
+        os: [ubuntu-latest]
         rust:
           - stable
           - beta
@@ -26,8 +28,11 @@ jobs:
         include:
           - rust: nightly
             benches: true
+          # Add testing for the nightly toolchain on windows to test debugger_visualizer support.
+          - rust: nightly
+            os: windows-latest
 
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
 
     steps:
       - name: Checkout
@@ -52,6 +57,17 @@ jobs:
           command: test
           args: --benches ${{ matrix.features }}
 
+    # The #[debugger_visualizer] attribute is currently gated behind an unstable feature flag.
+    # In order to test the visualizers for the http crate, they have to be tested on a nightly build.
+      - name: Run tests with debugger_visualizer feature
+        if: |
+          matrix.os == 'windows-latest' &&
+          matrix.rust == 'nightly'
+        uses: actions-rs/cargo@v1
+        with:
+          command: test
+          args: --test debugger_visualizer --features 'debugger_visualizer' -- --test-threads=1
+
   wasm:
     name: WASM
     #needs: [style]

diff --git a/Cargo.toml b/Cargo.toml
@@ -37,6 +37,13 @@ serde = "1.0"
 serde_json = "1.0"
 doc-comment = "0.3"
 criterion = "0.3.2"
+debugger_test = "0.1.0"
+debugger_test_parser = "0.1.0"
+
+[features]
+# UNSTABLE FEATURES (requires Rust nightly)
+# Enable to use the #[debugger_visualizer] attribute.
+debugger_visualizer = []
 
 [[bench]]
 name = "header_map"
@@ -62,3 +69,13 @@ path = "benches/method.rs"
 [[bench]]
 name = "uri"
 path = "benches/uri.rs"
+
+[[test]]
+name = "debugger_visualizer"
+path = "tests/debugger_visualizer.rs"
+# Do not run these tests by default. These tests need to
+# be run with the additional rustc flag `--test-threads=1`
+# since each test causes a debugger to attach to the current
+# test process. If multiple debuggers try to attach at the same
+# time, the test will fail.
+test = false
diff --git a/debug_metadata/README.md b/debug_metadata/README.md
@@ -0,0 +1,111 @@
+## Debugger Visualizers
+
+Many languages and debuggers enable developers to control how a type is
+displayed in a debugger. These are called "debugger visualizations" or "debugger
+views".
+
+The Windows debuggers (WinDbg\CDB) support defining custom debugger visualizations using
+the `Natvis` framework. To use Natvis, developers write XML documents using the natvis
+schema that describe how debugger types should be displayed with the `.natvis` extension.
+(See: https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2019)
+The Natvis files provide patterns which match type names a description of how to display
+those types.
+
+The Natvis schema can be found either online (See: https://code.visualstudio.com/docs/cpp/natvis#_schema)
+or locally at `<VS Installation Folder>\Xml\Schemas\1033\natvis.xsd`.
+
+The GNU debugger (GDB) supports defining custom debugger views using Pretty Printers.
+Pretty printers are written as python scripts that describe how a type should be displayed
+when loaded up in GDB/LLDB. (See: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html#Pretty-Printing)
+The pretty printers provide patterns, which match type names, and for matching
+types, descibe how to display those types. (For writing a pretty printer, see: https://sourceware.org/gdb/onlinedocs/gdb/Writing-a-Pretty_002dPrinter.html#Writing-a-Pretty_002dPrinter).
+
+### Embedding Visualizers
+
+Through the use of the currently unstable `#[debugger_visualizer]` attribute, the `http`
+crate can embed debugger visualizers into the crate metadata.
+
+Currently the two types of visualizers supported are Natvis and Pretty printers.
+
+For Natvis files, when linking an executable with a crate that includes Natvis files,
+the MSVC linker will embed the contents of all Natvis files into the generated `PDB`.
+
+For pretty printers, the compiler will encode the contents of the pretty printer
+in the `.debug_gdb_scripts` section of the `ELF` generated.
+
+### Testing Visualizers
+
+The `http` crate supports testing debugger visualizers defined for this crate. The entry point for
+these tests are `tests/debugger_visualizer.rs`. These tests are defined using the `debugger_test` and
+`debugger_test_parser` crates. The `debugger_test` crate is a proc macro crate which defines a
+single proc macro attribute, `#[debugger_test]`. For more detailed information about this crate,
+see https://crates.io/crates/debugger_test. The CI pipeline for the `http` crate has been updated
+to run the debugger visualizer tests to ensure debugger visualizers do not become broken/stale.
+
+The `#[debugger_test]` proc macro attribute may only be used on test functions and will run the
+function under the debugger specified by the `debugger` meta item.
+
+This proc macro attribute has 3 required values:
+
+1. The first required meta item, `debugger`, takes a string value which specifies the debugger to launch.
+2. The second required meta item, `commands`, takes a string of new line (`\n`) separated list of debugger
+commands to run.
+3. The third required meta item, `expected_statements`, takes a string of new line (`\n`) separated list of
+statements that must exist in the debugger output. Pattern matching through regular expressions is also
+supported by using the `pattern:` prefix for each expected statement.
+
+#### Example:
+
+```rust
+#[debugger_test(
+    debugger = "cdb",
+    commands = "command1\ncommand2\ncommand3",
+    expected_statements = "statement1\nstatement2\nstatement3")]
+fn test() {
+
+}
+```
+
+Using a multiline string is also supported, with a single debugger command/expected statement per line:
+
+```rust
+#[debugger_test(
+    debugger = "cdb",
+    commands = "
+command1
+command2
+command3",
+    expected_statements = "
+statement1
+pattern:statement[0-9]+
+statement3")]
+fn test() {
+
+}
+```
+
+In the example above, the second expected statement uses pattern matching through a regular expression
+by using the `pattern:` prefix.
+
+#### Testing Locally
+
+Currently, only Natvis visualizations have been defined for the `http` crate via `debug_metadata/http.natvis`,
+which means the `tests/debugger_visualizer.rs` tests need to be run on Windows using the `*-pc-windows-msvc` targets.
+To run these tests locally, first ensure the debugging tools for Windows are installed or install them following
+the steps listed here, [Debugging Tools for Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/).
+Once the debugging tools have been installed, the tests can be run in the same manner as they are in the CI
+pipeline.
+
+#### Note
+
+When running the debugger visualizer tests, `tests/debugger_visualizer.rs`, they need to be run consecutively
+and not in parallel. This can be achieved by passing the flag `--test-threads=1` to rustc. This is due to
+how the debugger tests are run. Each test marked with the `#[debugger_test]` attribute launches a debugger
+and attaches it to the current test process. If tests are running in parallel, the test will try to attach
+a debugger to the current process which may already have a debugger attached causing the test to fail.
+
+For example:
+
+```
+cargo test --test debugger_visualizer --features debugger_visualizer -- --test-threads=1
+```
diff --git a/debug_metadata/http.natvis b/debug_metadata/http.natvis
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="utf-8"?>
+<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
+  <Type Name="http::byte_str::ByteStr">
+    <DisplayString>{bytes.ptr,[bytes.len]sb}</DisplayString>
+  </Type>
+
+  <Type Name="http::header::map::Bucket&lt;*&gt;">
+    <DisplayString>{{ key={key}, value={value} }}</DisplayString>
+    <Expand>
+      <Item Name="[hash]">hash</Item>
+      <Item Name="[key]">key</Item>
+      <Item Name="[value]">value</Item>
+      <Item Name="[links]">links</Item>
+    </Expand>
+  </Type>
+
+  <Type Name="http::header::map::HeaderMap&lt;*&gt;">
+    <Expand>
+      <ExpandedItem>entries</ExpandedItem>
+      <Item Name="[extra_values]">extra_values</Item>
+    </Expand>
+  </Type>
+
+  <Type Name="http::header::name::HeaderName">
+    <Intrinsic Name="inner_tag" Expression="inner.discriminant" />
+    <DisplayString Condition="inner_tag() == 0">{inner.variant0.__0,en}</DisplayString>
+    <DisplayString Condition="inner_tag() == 1">{inner.variant1.__0.__0.bytes.ptr,[inner.variant1.__0.__0.bytes.len]s8}</DisplayString>
+  </Type>
+
+  <Type Name="http::header::value::HeaderValue">
+    <DisplayString>{(char*)inner.ptr,[inner.len]}</DisplayString>
+    <Expand>
+      <Item Name="[is_sensitive]">is_sensitive</Item>
+    </Expand>
+  </Type>
+
+  <Type Name="http::method::Method">
+    <DisplayString>{__0}</DisplayString>
+  </Type>
+
+  <Type Name="http::request::Builder">
+    <Expand>
+      <ExpandedItem>inner</ExpandedItem>
+    </Expand>
+  </Type>
+
+  <Type Name="http::request::Parts">
+    <DisplayString>{{ method={method}, uri={uri} }}</DisplayString>
+    <Expand>
+      <Item Name="[method]">method</Item>
+      <Item Name="[uri]">uri</Item>
+      <Item Name="[version]">version</Item>
+      <Item Name="[headers]">headers</Item>
+      <Item Name="[extensions]">extensions</Item>
+    </Expand>
+  </Type>
+
+  <Type Name="http::response::Parts">
+    <DisplayString>{{ status={status} }}</DisplayString>
+    <Expand>
+      <Item Name="[status]">status</Item>
+      <Item Name="[version]">version</Item>
+      <Item Name="[headers]">headers</Item>
+      <Item Name="[extensions]">extensions</Item>
+    </Expand>
+  </Type>
+
+  <Type Name="http::status::StatusCode">
+    <DisplayString>{__0,d}</DisplayString>
+  </Type>
+
+  <Type Name="http::uri::authority::Authority">
+    <DisplayString Condition="data.bytes.len &gt; 0">{data.bytes.ptr,[data.bytes.len]sb}</DisplayString>
+  </Type>
+
+  <Type Name="http::uri::path::PathAndQuery">
+    <Intrinsic Name="path_length" Expression="data.bytes.len" />
+    <DisplayString Condition="path_length() == 0">/</DisplayString>
+    <DisplayString>{data.bytes.ptr,[data.bytes.len]sb}</DisplayString>
+  </Type>
+
+  <Type Name="http::uri::scheme::Scheme">
+    <Intrinsic Name="inner_tag" Expression="inner.discriminant" />
+    <DisplayString Condition="inner_tag() == 0">{inner.variant0,en}</DisplayString>
+    <DisplayString Condition="inner_tag() == 1">{inner.variant1.__0,en}</DisplayString>
+    <DisplayString Condition="inner_tag() == 2">{inner.variant2.__0,en}</DisplayString>
+  </Type>
+
+  <Type Name="http::uri::Uri">
+    <Intrinsic Name="scheme_tag" Expression="scheme.inner.discriminant" />
+    <Intrinsic Name="protocol_tag" Expression="scheme.inner.variant1.__0" />
+    <DisplayString Condition="scheme_tag() == 0">{authority}{path_and_query}</DisplayString>
+    <DisplayString Condition="scheme_tag() == 1 &amp;&amp; protocol_tag() == 0">http://{authority}{path_and_query}</DisplayString>
+    <DisplayString Condition="scheme_tag() == 1 &amp;&amp; protocol_tag() == 1">https://{authority}{path_and_query}</DisplayString>
+    <DisplayString>{scheme}://{authority}{path_and_query}</DisplayString>
+    <Expand>
+      <Item Name="[scheme]">scheme</Item>
+      <Item Name="[authority]">authority</Item>
+      <Item Name="[path_and_query]">path_and_query</Item>
+    </Expand>
+  </Type>
+
+  <Type Name="http::version::Version">
+    <DisplayString>{__0,en}</DisplayString>
+  </Type>
+</AutoVisualizer>
diff --git a/src/lib.rs b/src/lib.rs
@@ -158,6 +158,12 @@
 //! assert_eq!(uri.query(), None);
 //! ```
 
+#![cfg_attr(feature = "debugger_visualizer", feature(debugger_visualizer))]
+#![cfg_attr(
+    feature = "debugger_visualizer",
+    debugger_visualizer(natvis_file = "../debug_metadata/http.natvis")
+)]
+
 #![deny(warnings, missing_docs, missing_debug_implementations)]
 
 #[cfg(test)]