unsupported opt-in backend

.github/workflows/build.yml

@@ -273,3 +273,16 @@ jobs:
       - env:
           RUSTFLAGS: -Dwarnings --cfg getrandom_backend="custom"
         run: cargo build --target riscv32i-unknown-none-elf
+
+  unsupported:
+    name: Runtime error
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+      - uses: Swatinem/rust-cache@v2
+      - env:
+          RUSTFLAGS: -Dwarnings --cfg getrandom_backend="unsupported"
+        run: cargo build --target wasm32-unknown-unknown

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.4] - UNRELEASED
+
+### Added
+- `unsupported` opt-in backend [#667]
+
+[#667]: https://github.com/rust-random/getrandom/pull/667
+
 ## [0.3.3] - 2025-05-09
 
 ### Changed
@@ -587,6 +594,7 @@ Publish initial implementation.
 ## [0.0.0] - 2019-01-19
 Publish an empty template library.
 
+[0.3.4]: https://github.com/rust-random/getrandom/compare/v0.3.3...HEAD
 [0.3.3]: https://github.com/rust-random/getrandom/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/rust-random/getrandom/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/rust-random/getrandom/compare/v0.3.0...v0.3.1

Cargo.toml

@@ -83,7 +83,7 @@ wasm-bindgen-test = "0.3"
 [lints.rust.unexpected_cfgs]
 level = "warn"
 check-cfg = [
-  'cfg(getrandom_backend, values("custom", "efi_rng", "rdrand", "rndr", "linux_getrandom", "linux_raw", "wasm_js"))',
+  'cfg(getrandom_backend, values("custom", "efi_rng", "rdrand", "rndr", "linux_getrandom", "linux_raw", "wasm_js", "unsupported"))',
   'cfg(getrandom_msan)',
   'cfg(getrandom_windows_legacy)',
   'cfg(getrandom_test_linux_fallback)',

README.md

@@ -87,6 +87,7 @@ of randomness based on their specific needs:
 | `wasm_js`         | Web Browser, Node.js | `wasm32‑unknown‑unknown`, `wasm32v1-none` | [`Crypto.getRandomValues`]. Requires feature `wasm_js` ([see below](#webassembly-support)).
 | `efi_rng`         | UEFI                 | `*-unknown‑uefi`         | [`EFI_RNG_PROTOCOL`] with `EFI_RNG_ALGORITHM_RAW` (requires `std` and Nigthly compiler)
 | `custom`          | All targets          | `*`                      | User-provided custom implementation (see [custom backend])
+| `unsupported`     | All targets          | `*`                      | Always returns `Err(Error::UNSUPPORTED)` (see [unsupported backend])
 
 Opt-in backends can be enabled using the `getrandom_backend` configuration flag.
 The flag can be set either by specifying the `rustflags` field in [`.cargo/config.toml`]:
@@ -203,20 +204,14 @@ unsafe extern "Rust" fn __getrandom_v03_custom(
 }
 ```
 
-If you are confident that `getrandom` is not used in your project, but
-it gets pulled nevertheless by one of your dependencies, then you can
-use the following custom backend, which always returns the "unsupported" error:
-```rust
-use getrandom::Error;
+### Unsupported backend
 
-#[no_mangle]
-unsafe extern "Rust" fn __getrandom_v03_custom(
-    dest: *mut u8,
-    len: usize,
-) -> Result<(), Error> {
-    Err(Error::UNSUPPORTED)
-}
-```
+In some rare scenarios you might be compiling this crate in a constrained
+environment (e.g. `wasm32-unknown-unknown`), but this crate's functionality
+is not actually used by your code. If you are confident that `getrandom` is
+not used in your project, but it gets pulled nevertheless by one of your
+dependencies, then you can enable the `unsupported` backend, which always
+returns `Err(Error::UNSUPPORTED)`.
 
 ### Platform Support
 
@@ -373,6 +368,7 @@ dual licensed as above, without any additional terms or conditions.
 [`get-random-u64`]: https://github.com/WebAssembly/WASI/blob/v0.2.1/wasip2/random/random.wit#L23-L28
 [configuration flags]: #configuration-flags
 [custom backend]: #custom-backend
+[unsupported backend]: #unsupported-backend
 [`wasm-bindgen`]: https://github.com/rustwasm/wasm-bindgen
 [`module`]: https://rustwasm.github.io/wasm-bindgen/reference/attributes/on-js-imports/module.html
 [`sys_read_entropy`]: https://github.com/hermit-os/kernel/blob/315f58ff5efc81d9bf0618af85a59963ff55f8b1/src/syscalls/entropy.rs#L47-L55

src/backends.rs

@@ -38,6 +38,9 @@ cfg_if! {
                 ));
             }
         }
+    } else if #[cfg(getrandom_backend = "unsupported")] {
+        mod unsupported;
+        pub use unsupported::*;
     } else if #[cfg(all(target_os = "linux", target_env = ""))] {
         mod linux_raw;
         pub use linux_raw::*;

src/backends/unsupported.rs

@@ -0,0 +1,9 @@
+//! Implementation that errors at runtime.
+use crate::Error;
+use core::mem::MaybeUninit;
+
+pub use crate::util::{inner_u32, inner_u64};
+
+pub fn fill_inner(_dest: &mut [MaybeUninit<u8>]) -> Result<(), Error> {
+    Err(Error::UNSUPPORTED)
+}