(1)-masquerade: allocate each public pair once

.gitignore

@@ -1,5 +1,8 @@
 **.profraw
 **/__fuzz__/**
+# libfuzzer writes one of these per worker into the working directory when
+# `just fuzz` is given -j; the corpus itself lives under __fuzz__.
+fuzz-*.log
 # qemu-user core dumps from SIGABRT under emulated tests.
 **/qemu_*.core
 result*

concurrency-macros/src/lib.rs

@@ -193,6 +193,89 @@ pub fn test(_attr: TokenStream, item: TokenStream) -> TokenStream {
                 fn shuttle() {
                     #krate::stress(|| #block);
                 }
+
+            }
+        }
+    }
+    .into()
+}
+
+/// Give a test the backend-named module shape of [`macro@test`] without touching its body.
+///
+/// [`macro@test`] wraps the whole body in [`stress`](../dataplane_concurrency/fn.stress.html),
+/// which is what you want when the body *is* the thing being model-checked. It is the wrong shape
+/// when a generator has to be the outer loop:
+///
+/// ```ignore
+/// bolero::check!().with_type().cloned().for_each(|scenario: Scenario| {
+///     concurrency::stress(move || scenario.run());   // one exploration per generated shape
+/// });
+/// ```
+///
+/// Wrapping *that* in `stress` would put the whole generator campaign inside a single
+/// model-checking execution, making the generator's own choices part of the explored state space.
+/// So such tests call `stress` themselves, and until now paid for it by losing the backend-named
+/// leaf that `just features=shuttle test` filters on: the suite compiled under the model checker
+/// and was never selected to run.
+///
+/// This attribute emits the module shape and nothing else, leaving the body verbatim:
+///
+/// ```ignore
+/// #[concurrency::model_test]
+/// fn stress_it() { /* ... calls stress itself ... */ }
+/// ```
+///
+/// becomes `mod stress_it { mod concurrency_model { #[test] fn <backend>() { /* body */ } } }`,
+/// where `<backend>` is `loom`, `shuttle` or `plain`. Unlike [`macro@test`], the wrapper is emitted
+/// on every backend, so the name does not change shape between them; there is no existing flat
+/// name to keep compatible here.
+#[proc_macro_attribute]
+pub fn model_test(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    let func = parse_macro_input!(item as ItemFn);
+
+    let attrs = &func.attrs;
+    let sig = &func.sig;
+    let block = &func.block;
+    let fn_name = &sig.ident;
+
+    if let Some(asyncness) = sig.asyncness {
+        return syn::Error::new_spanned(
+            asyncness,
+            "#[concurrency::model_test] does not support async functions yet",
+        )
+        .to_compile_error()
+        .into();
+    }
+    if !sig.inputs.is_empty() {
+        return syn::Error::new_spanned(
+            &sig.inputs,
+            "#[concurrency::model_test] functions must take no arguments",
+        )
+        .to_compile_error()
+        .into();
+    }
+
+    quote! {
+        #[allow(non_snake_case)]
+        mod #fn_name {
+            use super::*;
+            mod concurrency_model {
+                use super::*;
+
+                #[cfg(feature = "loom")]
+                #[::core::prelude::v1::test]
+                #(#attrs)*
+                fn loom() #block
+
+                #[cfg(feature = "shuttle")]
+                #[::core::prelude::v1::test]
+                #(#attrs)*
+                fn shuttle() #block
+
+                #[cfg(not(any(feature = "loom", feature = "shuttle")))]
+                #[::core::prelude::v1::test]
+                #(#attrs)*
+                fn plain() #block
             }
         }
     }

concurrency/src/macros.rs

@@ -160,4 +160,4 @@ macro_rules! with_std {
     ($($item:item)*) => {};
 }
 
-pub use concurrency_macros::{concurrency_mode, test};
+pub use concurrency_macros::{concurrency_mode, model_test, test};

development/code/running-tests.md

@@ -62,8 +62,75 @@ change this.
 The major downside is that these processes are very computationally intensive and can take a long time to run.
 In fact, the [afl] fuzzer runs until you terminate it.
 
+## Running a real fuzzing campaign
+
+To run a target under [libfuzzer], which is coverage guided and explores far deeper than the random
+driver the test suite uses, list the targets and pick one:
+
+```shell
+just fuzz-list -p dataplane-nat
+just fuzz 'masquerade::apalloc::region::bolero_tests::decompose_properties' 10min -p dataplane-nat
+```
+
+The duration defaults to `60s`; anything after it is forwarded to `cargo bolero test`. As a sense of
+the difference, a property that manages a few thousand cases per second under `just test` reaches
+several hundred thousand per minute here, because libfuzzer mutates towards inputs that reach new
+code rather than sampling blindly.
+
+Findings are written to a `__fuzz__` directory beside the test. That directory is gitignored: the
+corpus is a local artifact that seeds later runs on the same machine, not something to commit.
+
+Pass `-j` to spread the campaign over more cores, which is the cheapest way to reach deeper:
+
+```shell
+just fuzz 'some::module::tests::some_property' 10min -p some-package -j 60
+```
+
+Each worker then writes a `fuzz-<n>.log` into the directory you ran from, rather than into
+`__fuzz__`. Those are gitignored too, and are only worth reading when a run reports a crash.
+
+### Sanitizers
+
+`cargo bolero` builds with the `fuzz` profile and links [AddressSanitizer] unless told otherwise, so
+a plain `just fuzz` is already an asan campaign. To swap sanitizers, set the same `sanitize`
+variable the rest of the justfile uses:
+
+```shell
+just sanitize=thread fuzz 'some::module::tests::some_property' 5min -p some-package
+```
+
+[ThreadSanitizer] only reports on a target that actually spawns threads, so it is worth the extra
+cost on a concurrency suite and close to pointless on a single-threaded property. It also takes
+much longer to get going, because thread instrumentation changes the ABI: `just` therefore adds
+`--build-std` for it, since a std left uninstrumented fails the build on a mismatch against `core`.
+
+A sanitizer is not free. Instrumentation costs roughly a factor of four in executions per second,
+so it is worth spending some of a campaign with none at all, reaching deeper into the input space
+in exchange for only catching what the test's own assertions catch:
+
+```shell
+just sanitize=NONE fuzz 'some::module::tests::some_property' 30min -p some-package
+```
+
+The two are complementary: asan for memory errors the assertions cannot see, `NONE` for depth.
+
+The suite as a whole can also be run under either sanitizer with the standard runner, which is what
+CI's `sanitize/fuzz/*` jobs do:
+
+```shell
+just profile=fuzz sanitize=thread test
+just profile=fuzz sanitize=address test
+```
+
+That covers far more code than a single fuzz target, but only with the brief random driver rather
+than a real campaign. The two are complementary.
+
 > [!NOTE]
-> Dedicated `just` recipes for running full fuzz campaigns (with libfuzzer/afl) are planned for a future PR.
+> `just fuzz` passes `--rustc-bootstrap`, because libfuzzer wants a nightly compiler for its
+> sanitizer coverage flags while the pinned toolchain is stable. An [afl] recipe is still to come.
+
+[AddressSanitizer]: https://clang.llvm.org/docs/AddressSanitizer.html
+[ThreadSanitizer]: https://clang.llvm.org/docs/ThreadSanitizer.html
 
 [README.md]: ../../README.md
 [afl]: https://github.com/AFLplusplus/AFLplusplus

flow-entry/src/flow_table/concurrent_fuzz.rs

@@ -296,7 +296,7 @@ impl Scenario {
 /// Drive one bolero shape per iteration through [`concurrency::stress`]:
 /// a single direct run on the std backend (real OS threads — build with
 /// `just test sanitize=thread`), or the full portfolio under shuttle.
-#[test]
+#[concurrency::model_test]
 fn stress_test_concurrency_model() {
     // Single-threaded runtime is enough: we never need the timer task to
     // run, only a context for `insert`'s `tokio::task::spawn` to succeed.

justfile

@@ -160,6 +160,32 @@ test package="tests.all" *args: (build (if package == "tests.all" { "tests.all"
     declare -r target="{{ if package == "tests.all" { "tests.all" } else { "tests.pkg." + package } }}"
     cargo nextest run --archive-file results/${target}/*.tar.zst --workspace-remap $(pwd) {{ filter }}
 
+# List the bolero targets `just fuzz` can run. Args go to `cargo bolero list`
+[script]
+fuzz-list *args="":
+    {{ _just_debuggable_ }}
+    cargo bolero list {{ _cargo_feature_flags }} {{ args }}
+
+# Fuzz one bolero target under libfuzzer. See development/code/running-tests.md
+[script]
+fuzz target time="60s" *args="":
+    {{ _just_debuggable_ }}
+    # libfuzzer wants a nightly compiler for its sanitizer coverage flags, while the
+    # pinned toolchain is stable; --rustc-bootstrap bridges that. cargo-bolero already
+    # builds with the fuzz profile and links AddressSanitizer unless told otherwise, so
+    # a plain `just fuzz` is already an asan run. Findings land in a gitignored
+    # `__fuzz__` directory beside the test.
+    #
+    # `sanitize=thread` additionally rebuilds std: thread instrumentation changes the
+    # ABI, so a std left uninstrumented fails the build on a mismatch against `core`.
+    # asan does not need that, and skipping the std rebuild keeps it far quicker.
+    # `sanitize=NONE` drops instrumentation altogether, which buys roughly four times
+    # the executions per second in exchange for only catching what the test asserts.
+    cargo bolero test '{{ target }}' --rustc-bootstrap -T '{{ time }}' \
+        {{ if sanitize != "" { "--sanitizer " + sanitize } else { "" } }} \
+        {{ if sanitize == "thread" { "--build-std" } else { "" } }} \
+        {{ _cargo_feature_flags }} {{ args }}
+
 # Build and run the criterion benches. The rte_acl benches are gated behind the
 # `dpdk` feature, so run `just features=dpdk bench` to exercise them; a plain
 # `just bench` builds them as empty `main()` and only runs the reference benches.

nat/src/masquerade/allocation.rs

@@ -35,6 +35,32 @@ pub enum AllocatorError {
     NoPoolFound,
 }
 
+impl AllocatorError {
+    /// Whether this error says the space simply ran out, rather than that something is wrong.
+    ///
+    /// A caller holding several allocators over disjoint space may move on to the next one when
+    /// this holds, and only then: any other error is about the allocator rather than about how
+    /// full it is, and would be buried by a later success. The classification is the one
+    /// [`DoneReason`] already draws, where exactly these become `NatOutOfResources`.
+    /// The match is exhaustive on purpose: a new error has to be classified here rather than
+    /// silently defaulting to one side of it.
+    #[must_use]
+    pub fn is_exhaustion(&self) -> bool {
+        match self {
+            AllocatorError::NoFreeIp
+            | AllocatorError::NoPortBlock
+            | AllocatorError::NoFreePort(_) => true,
+            AllocatorError::PortAllocationFailed(_)
+            | AllocatorError::PortReservationFailed(_)
+            | AllocatorError::UnsupportedProtocol(_)
+            | AllocatorError::MissingDiscriminant
+            | AllocatorError::InternalIssue(_)
+            | AllocatorError::Denied
+            | AllocatorError::NoPoolFound => false,
+        }
+    }
+}
+
 impl From<&AllocatorError> for DoneReason {
     fn from(error: &AllocatorError) -> Self {
         match error {