add support for UUID v7 in RequestId (#116)

* feat(request_id): add support for UUID v7 in `RequestId`

feature flag `uuid_v7` is introduced which inturn enables `v7` feature flag in the `uuid` dependency
Support documentation is added in `README.md`, `src/lib.rs` and `src/request_id.rs`

This feature only works if this crate or any crate dependent on this crate has enabled the compile time configuration flag provided to the rust compiler. `RUSTFLAGS="--cfg uuid_unstable"`.

* chore: add github action to test UUID v7 feature flag

* chore: add the uuid_unstable cfg in the request id impl

* chore: add compiler_error for undesired state in configuration flags

* chore: move the compiler error in request_id module

* chore: fix formatting

* fix(action): fix github action for uuid_v7 with RUSTDOCFLAGS

.github/workflows/general.yml

@@ -77,6 +77,33 @@ jobs:
           command: test
           args: --features ${{ matrix.otel_version }}
 
+  test_uuid_v7:
+    name: Test
+    runs-on: ubuntu-latest
+    env:
+      RUSTFLAGS: "--cfg uuid_unstable"
+      RUSTDOCFLAGS: "--cfg uuid_unstable"
+    steps:
+      - uses: actions/checkout@v2
+      - name: Cache dependencies
+        id: cache-dependencies
+        uses: actions/cache@v2
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+      - uses: actions-rs/cargo@v1
+        with:
+          command: test
+          args: --features uuid_v7
+
   fmt:
     name: Rustfmt
     runs-on: ubuntu-latest

Cargo.toml

@@ -29,6 +29,7 @@ opentelemetry_0_18 = ["opentelemetry_0_18_pkg", "tracing-opentelemetry_0_18_pkg"
 opentelemetry_0_19 = ["opentelemetry_0_19_pkg", "tracing-opentelemetry_0_19_pkg"]
 opentelemetry_0_20 = ["opentelemetry_0_20_pkg", "tracing-opentelemetry_0_21_pkg"]
 emit_event_on_error = []
+uuid_v7 = ["uuid/v7"]
 
 [dependencies]
 actix-web = { version = "4", default-features = false }

README.md

@@ -54,7 +54,7 @@ actix-web = "4"
 - `opentelemetry_0_18`: same as above but using `opentelemetry` 0.18;
 - `opentelemetry_0_19`: same as above but using `opentelemetry` 0.19;
 - `emit_event_on_error`: emit a [`tracing`] event when request processing fails with an error (enabled by default).
-
+- `uuid_v7`: use the UUID v7 implementation inside [`RequestId`] instead of UUID v4 (disabled by default).
 ## Quickstart
 
 ```rust,compile_fail
@@ -284,6 +284,11 @@ async fn index(request_id: RequestId) -> String {
 The request id is meant to identify all operations related to a particular request **within the boundary of your API**.  
 If you need to **trace** a request across multiple services (e.g. in a microservice architecture), you want to look at the `trace_id` field - see the next section on OpenTelemetry for more details.
 
+
+Optionally, using the `uuid_v7` feature flag will allow [`RequestId`] to use UUID v7 instead of the currently used UUID v4.
+
+However, the [`uuid`] crate requires a compile time flag `uuid_unstable` to be passed in `RUSTFLAGS="--cfg uuid_unstable"` in order to compile. You can read more about it [here](https://docs.rs/uuid/latest/uuid/#unstable-features).
+
 ## Trace Id
 
 To fulfill a request you often have to perform additional I/O operations - e.g. calls to other REST or gRPC APIs, database queries, etc.  
@@ -318,3 +323,4 @@ dual licensed as above, without any additional terms or conditions.
 [`root_span!`]: https://docs.rs/tracing-actix-web/4.0.0-beta.1/tracing_actix_web/macro.root_span.html
 [root span]: https://docs.rs/tracing-actix-web/4.0.0-beta.1/tracing_actix_web/struct.RootSpan.html
 [`actix-web`]: https://docs.rs/actix-web/4.0.0-beta.6/actix_web/index.html
+[`uuid`]: https://docs.rs/uuid

src/lib.rs

@@ -28,6 +28,7 @@
 //! - `opentelemetry_0_19`: same as above but using `opentelemetry` 0.19;
 //! - `opentelemetry_0_20`: same as above but using `opentelemetry` 0.20;
 //! - `emit_event_on_error`: emit a [`tracing`] event when request processing fails with an error (enabled by default).
+//! - `uuid_v7`: use the UUID v7 implementation inside [`RequestId`] instead of UUID v4 (disabled by default).
 //!
 //! ## Quickstart
 //!
@@ -254,6 +255,10 @@
 //! The request id is meant to identify all operations related to a particular request **within the boundary of your API**.
 //! If you need to **trace** a request across multiple services (e.g. in a microservice architecture), you want to look at the `trace_id` field - see the next section on OpenTelemetry for more details.
 //!
+//! Optionally, using the `uuid_v7` feature flag will allow [`RequestId`] to use UUID v7 instead of the currently used UUID v4.
+//!
+//! However, the [`uuid`] crate requires a compile time flag `uuid_unstable` to be passed in `RUSTFLAGS="--cfg uuid_unstable"` in order to compile. You can read more about it [here](https://docs.rs/uuid/latest/uuid/#unstable-features).
+//!
 //! ## Trace Id
 //!
 //! To fulfill a request you often have to perform additional I/O operations - e.g. calls to other REST or gRPC APIs, database queries, etc.

src/request_id.rs

@@ -25,12 +25,28 @@ use uuid::Uuid;
 ///   format!("{}", uuid)
 /// }
 /// ```
+///
+/// Optionally, using the `uuid_v7` feature flag will allow [`RequestId`] to use UUID v7 instead of the currently used UUID v4.
+///
+/// However, the [`uuid`] crate requires a compile time flag `uuid_unstable` to be passed in `RUSTFLAGS="--cfg uuid_unstable"` in order to compile. You can read more about it [here](https://docs.rs/uuid/latest/uuid/#unstable-features).
+///
 #[derive(Clone, Copy, Debug)]
 pub struct RequestId(Uuid);
 
 impl RequestId {
     pub(crate) fn generate() -> Self {
-        Self(Uuid::new_v4())
+        // Compiler error for providing context on requirements to enable the `uuid_v7` feature flag
+        #[cfg(all(feature = "uuid_v7", not(uuid_unstable)))]
+        compile_error!("feature \"uuid_v7\" requires \"uuid_unstable\" to be passed as configuration in rustflags");
+
+        #[cfg(not(feature = "uuid_v7"))]
+        {
+            Self(Uuid::new_v4())
+        }
+        #[cfg(all(uuid_unstable, feature = "uuid_v7"))]
+        {
+            Self(Uuid::now_v7())
+        }
     }
 }