hyperuuid 0.6.1-x86_64-linux-gnu → 0.8.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d627ef885171a5aa3d5f12c8f53ac9cb6ba13da8d1c497e009dec0703d4f22dd
-  data.tar.gz: 34fca766efc82f71027cc2a5c4140b9858030bd7b67a1657fc604bd515eb3d03
+  metadata.gz: 50210cbd12da585faab8ec401c564d290567a02569e3fa4fec76a0e7224262e1
+  data.tar.gz: 308948d1efd694544584b612de86ff9edd9541d18531f7d826a4acea34b74b33
 SHA512:
-  metadata.gz: d3bc230eb26b9804d3294b75818b5519ac110c5f3dc7b4a9c6a071863e0ecb0c452ece80f151f9ad2758e8248d2bcc9343431d04141453dd2bba05123562abe7
-  data.tar.gz: dd4e4f93ce8d87b77ad4cab6b6958b569cc5aee052ff5e666b92e9c7bf3002dcfb84c03fde16e2d903935ed585bdb85da867c02360e3906d9ab80b8366b9b602
+  metadata.gz: 7b9a3a0f5b880809af66e26c75d962b0b28437adfa47448cfefb31f6724ff16146a1eae883c48885af2fe0d279b64b963c89f65e309f0e9873615f34b65cda85
+  data.tar.gz: 29ac37f97a5a6d9821c5580702e8a51155b9da9e72add1423ebbc1003616c3826fd0e57dcc0ee0b5a5e09ef3fbda9f7175d3c780a75eb13eb41b1cf6e3b90bbe

data/README.md

@@ -4,7 +4,7 @@
 [![RubyGems](https://img.shields.io/gem/v/hyperuuid.svg)](https://rubygems.org/gems/hyperuuid)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/SkunkWerkx/HyperUuid/blob/master/LICENSE)
 
-**Ruby's own stdlib stops at `SecureRandom.uuid` — random v4, full stop. No v5, no v6, no v7. This gem is the whole RFC, with zero gem dependency beyond `Fiddle` (which ships with every Ruby install) — and it's faster than `SecureRandom.uuid` too.**
+**Ruby's own stdlib stops at `SecureRandom.uuid` and `SecureRandom.uuid_v7` — random v4 and v7, one at a time. No v5, no v6, no batches, no SQL Server order. This gem is the whole RFC, with zero gem dependency beyond `Fiddle` (which ships with every Ruby install) — and it's faster than `SecureRandom.uuid` too.**
 
 RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation, with
 two backends sharing one public surface. Ruby 3.3 is the floor. The fast path is a native
@@ -26,8 +26,10 @@ id3 = HyperUuid.new_v6
 id4 = HyperUuid.new_v7
 
 id4.timestamp # recover the embedded UTC Time
-id4.timestamp(raise_on_mismatch: false) # nil instead of raising if id4 isn't v6/v7
-id4.to_sql_order # byte order SQL Server's uniqueidentifier needs to sort by creation order
+id4.timestamp(raise_on_mismatch: false) # nil instead of raising if id4 isn't an RFC 9562 v6/v7
+id4.rfc?(7) # the RFC 9562 variant and version 7, the guard before trusting its fields
+sql = id4.to_sql_order # byte order SQL Server's uniqueidentifier needs to sort by creation order
+sql.timestamp(layout: :sql_server) # read straight from SQL order, no round trip
 
 # One native call, one random-bytes fetch, one counter reservation for the whole batch:
 batch = HyperUuid.new_v7_batch(1000)
@@ -40,7 +42,7 @@ batch = HyperUuid.new_v7_batch(1000)
 | `new_v4` | `Uuid` | — |
 | `new_v5(namespace, name)` | `Uuid`, the same one for the same pair | a `Uuid` namespace (`Namespaces::DNS`/`URL`/`OID`/`X500`, or your own) and a `String` name — text is hashed as UTF-8, a binary String as its bytes, and it may be empty |
 | `new_v6(time = nil)` `new_v7(time = nil)` | `Uuid` | nothing (now), a `Time`, or an Integer of Unix-epoch milliseconds |
-| `new_v6_batch(count, time = nil)` `new_v7_batch(count, time = nil)` | `Array` of `Uuid` | a count, and the same time forms |
+| `new_v6_batch(count, time = nil)` `new_v7_batch(count, time = nil)` | `Array` of `Uuid` | a count (at most `MAX_V7_BATCH` for v7), and the same time forms |
 | `new_v6_batch_bytes(count, time = nil)` `new_v7_batch_bytes(count, time = nil)` | one binary `String`, 16 bytes per UUID | as the batch doors — see [Bulk generation into bytes](#bulk-generation-into-bytes) |
 | `native_version` | the loaded core's `"major.minor.patch"` | — |
 | `available?` | `true`/`false`, never raising | — |
@@ -53,8 +55,11 @@ runtime dependency on the `uuid` gem:
 | `Uuid.parse(text)` | the 8-4-4-4-12 hyphenated form `#to_s` produces, either case, and nothing else — an `ArgumentError` otherwise |
 | `Uuid.new(bytes)` | wraps 16 raw RFC 9562-ordered bytes |
 | `Uuid::NIL` `Uuid::MAX` | the RFC 9562 §5.9/§5.10 special values |
-| `#bytes` `#to_s` `#version` `#variant` | the frozen binary String, the hyphenated text, the version nibble, the variant bits |
-| `#timestamp(raise_on_mismatch: true)` | the UTC `Time` embedded in a version 6 or 7 UUID; `nil` instead of an `ArgumentError` for any other version when passed `false` |
+| `#bytes` `#to_s` | the frozen binary String, the hyphenated text |
+| `#version(layout: :rfc9562)` | the version in that layout: the nibble, 0-15, in RFC order; 6 or 7 for a SQL-ordered v6/v7 in `:sql_server`, 0 when the bytes don't form one |
+| `#variant` | the RFC 9562 §4.1 variant, as a Symbol: `:rfc9562` (every UUID this gem mints, and the only variant with versions), `:ncs` (Nil among them), `:microsoft`, `:future` (Max among them) |
+| `#rfc?(version, layout: :rfc9562)` | whether it is an RFC 9562 UUID of that version: the variant and the version together. A version outside 0-15 is `false` |
+| `#timestamp(raise_on_mismatch: true, layout: :rfc9562)` | the UTC `Time` embedded in an RFC 9562 version 6 or 7 UUID held in that layout, in one native call that checks the variant as well as the version (a 6 or 7 nibble under another variant has no timestamp); `nil` instead of an `ArgumentError` for anything that isn't one when passed `false` |
 | `#to_sql_order` `#from_sql_order` | to and from the byte order SQL Server's `uniqueidentifier` sorts by |
 | `==` `eql?` `hash` `<=>` | value equality and byte-order comparison (`Comparable`) |
 
@@ -65,9 +70,52 @@ the native Rust core rather than reimplemented in Ruby, and verified there (and
 against the real `System.Data.SqlTypes.SqlGuid` comparator in the C# binding's test suite).
 Same-millisecond v6 UUIDs aren't guaranteed to sort correctly afterward — v6 has no counter,
 so `clock_seq`/`node` (not the timestamp) decide ties, the same pre-existing RFC 9562 v6
-limitation plain order already has. `#from_sql_order` figures out which version to invert by
-checking a byte position that's provably collision-free between the two (see the method's own
-doc comment).
+limitation plain order already has. `#from_sql_order` asks the core which version it holds
+(`#version(layout: :sql_server)`, which checks each version's nibble together with its variant
+bits, so a v6 whose random `clock_seq` byte reads as a v7 nibble is still a v6).
+
+### Layouts
+
+`#version`, `#rfc?` and `#timestamp` take the byte order the value is held in as `layout:`, a
+Symbol: `:rfc9562` (the default, what every other method takes and returns) or `:sql_server`
+(what `#to_sql_order` returns, defined for versions 6 and 7 only). `Uuid::LAYOUTS` lists them.
+Anything else is an `ArgumentError`, never a guess. With the default, `#version` and `#rfc?`
+read the value as RFC 9562 order, which looks at the wrong bytes of a SQL-ordered value (one
+from `#to_sql_order`, or a `uniqueidentifier` read back from SQL Server), so pass
+`layout: :sql_server` at every call site that can see one. There is deliberately no
+layout-agnostic check: whoever holds the value knows its order.
+
+`#variant` reads RFC 9562 order only and has no layout form, because in SQL Server order the
+variant sits at a different byte for each version. Don't hand it a SQL-ordered value or a
+`uniqueidentifier` read-back; to validate one, `#rfc?(version, layout: :sql_server)` checks the
+variant where that version puts it.
+
+```ruby
+sql = HyperUuid.new_v6.to_sql_order
+sql.version(layout: :sql_server)   # => 6
+sql.rfc?(6, layout: :sql_server)   # => true
+sql.timestamp(layout: :sql_server) # the same Time as sql.from_sql_order.timestamp
+```
+
+The bytes alone cannot say which order they are in, so the layout is yours to know: an
+RFC-ordered value can happen to form a SQL-ordered one (a random v4 reads as a SQL-ordered v7
+one time in 16), and `#from_sql_order` then converts it rather than refusing it.
+
+### The version 7 batch limit
+
+`HyperUuid::MAX_V7_BATCH` is 67,108,864 (2²⁶), the size of the counter that orders version 7
+UUIDs within a millisecond, and the most one `new_v7_batch` or `new_v7_batch_bytes` call
+mints. A larger count is an `ArgumentError` naming the limit, raised before anything is
+allocated. Every batch is in strictly increasing order: the counter is one process-wide
+sequence, so a batch can straddle the point where it wraps back to 0, and the UUIDs from there
+on carry a timestamp one millisecond later than the one supplied rather than sorting before the
+ones ahead of them. Version 6 has no counter and no such limit.
+
+That roll-forward orders one batch, not the stream. The next batch or single `new_v7` in the
+same real millisecond starts its counter just past the wrap and carries the supplied timestamp,
+so it sorts before the previous batch's tail, which was stamped a millisecond later. Two single
+`new_v7` calls either side of the wrap in one millisecond sort in reverse the same way. It
+happens at most once per 2²⁶ UUIDs the process mints.
 
 ### Errors
 
@@ -84,8 +132,10 @@ Through 0.3.0 these were reachable only as `HyperUuid::Runtime::TimestampOutOfRa
 Everything else is a caller bug and raises Ruby's own error for it, checked once in the shared
 doors rather than left to whichever backend is live: a `TypeError` for a time that is not a
 `Time`, an Integer or `nil`, for a count that is not an Integer, for a namespace that is not a
-`Uuid` or a name that is not a `String`; an `ArgumentError` for a count outside
-0..2³² − 1.
+`Uuid` or a name that is not a `String`, for a version passed to `#rfc?` that is not an
+Integer; an `ArgumentError` for a count outside 0..2³² − 1 (0..`MAX_V7_BATCH` for version 7),
+for a layout other than `:rfc9562`/`:sql_server`, and for a batch too large for the platform to
+address (a 32-bit target such as ruby.wasm).
 
 ### Is the native core there?
 
@@ -105,14 +155,14 @@ looked for, or `HyperUuid::NativePlatform::UnsupportedPlatformError` naming the
 
 ## Why not `SecureRandom.uuid`?
 
-`SecureRandom.uuid` only ever gives you a random v4 UUID — Ruby's stdlib has no built-in v5, v6, or v7 at all. If you need more than that, the choice is really "which gem":
+`SecureRandom.uuid` gives you a random v4 UUID and `SecureRandom.uuid_v7` a v7 (Ruby 3.3 and later, so every Ruby this gem supports). Ruby's stdlib has no v5 or v6, nothing to read a timestamp back out, no batch form, and no SQL Server ordering. If you need more than that, the choice is really "which gem":
 
 1. **Full RFC 9562 coverage, one gem, zero extra dependency.** v4/v5/v6/v7 plus batch generation plus `Nil`/`Max`, and nothing added to your `Gemfile.lock` beyond `Fiddle` — Ruby's own bundled FFI layer, not a third-party C extension to compile — and on the precompiled platform gems not even that.
 2. **No native-extension compile step.** Third-party UUID gems that go beyond v4 are typically pure Ruby or wrap a C extension compiled at install time; this gem ships its fast path as a prebuilt platform-gem extension and its fallback as a `dlopen`ed prebuilt library — either way, the gem itself compiles nothing at install time ([Install](#install) has the one caveat, which is Fiddle's own).
 3. **Batch generation.** `new_v7_batch(1000)` shares one timestamp capture, one random-bytes fetch, and one counter reservation across the whole batch instead of paying per-item overhead a thousand times over.
 4. **Cross-language consistency.** The same Rust core mints v5 namespace UUIDs for Python, Go, C#, and every other binding in this repo — verified in CI to match Python's own `uuid.uuid5` byte-for-byte. If your system isn't Ruby-only, no Ruby-only gem can offer that.
 
-The honest trade-off: this gem is native code, not pure Ruby — a precompiled extension in each platform gem, and on the universal gem a platform-specific `libhyperuuid.so`/`.dylib`/`.dll` loaded through Fiddle — so it runs only where one of those was built. If plain v4 randomness is all you need, `SecureRandom.uuid` is simpler and already in stdlib — that's a completely reasonable choice.
+The honest trade-off: this gem is native code, not pure Ruby — a precompiled extension in each platform gem, and on the universal gem a platform-specific `libhyperuuid.so`/`.dylib`/`.dll` loaded through Fiddle — so it runs only where one of those was built. If one v4 or v7 at a time is all you need, `SecureRandom.uuid` and `SecureRandom.uuid_v7` are simpler and already in stdlib — that's a completely reasonable choice.
 
 ## Bulk generation into bytes
 
@@ -123,7 +173,7 @@ bytes = HyperUuid.new_v7_batch_bytes(1000)
 first = bytes[0, 16]        # ready for a BINARY(16) bind parameter
 ```
 
-**About 20x faster than `new_v7_batch`** for a 1000-UUID batch (10.4 µs versus 210 µs). The native call is identical — the difference is that `new_v7_batch` then allocates a `Uuid` object and its byte Strings for every item on top of it. This hands back the bytes the native core already produced, untouched.
+**About 40x faster than `new_v7_batch`** for a 1000-UUID batch (4.9 µs versus 202 µs). The native call is identical — the difference is that `new_v7_batch` then allocates a `Uuid` object and its byte Strings for every item on top of it. This hands back the bytes the native core already produced, untouched.
 
 The catch, and it inverts the advice: **if you need `Uuid` objects, keep using `new_v7_batch`.** Slicing these bytes into objects yourself just relocates the identical allocations into your own code, and measures no better — sometimes worse. Reach for the byte form only when bytes are the destination: a bind parameter, a wire format, a bulk load.
 
@@ -139,30 +189,30 @@ Real numbers, `benchmark-ips` on Ruby 4.0.7, linux-x64 on an Intel Core i9-11900
 
 | Call | i/s | vs `SecureRandom.uuid` |
 |---|---:|---:|
-| `SecureRandom.uuid` | 872,365 | baseline |
-| `HyperUuid.new_v4` | 4,278,000 | **4.9x faster** |
-| `HyperUuid.new_v7` (explicit ms) | 3,517,000 | **4.0x faster** |
-| `HyperUuid.new_v6` (explicit ms) | 3,487,000 | **4.0x faster** |
-| `HyperUuid.new_v6` (current time) | 3,324,000 | **3.8x faster** |
-| `HyperUuid.new_v7` (current time) | 3,320,000 | **3.8x faster** |
-| `HyperUuid.new_v5` | 1,838,000 | 2.1x faster |
+| `SecureRandom.uuid` | 943,917 | baseline |
+| `HyperUuid.new_v4` | 5,236,000 | **5.5x faster** |
+| `HyperUuid.new_v6` (explicit ms) | 3,811,000 | **4.0x faster** |
+| `HyperUuid.new_v7` (explicit ms) | 3,785,000 | **4.0x faster** |
+| `HyperUuid.new_v6` (current time) | 3,677,000 | **3.9x faster** |
+| `HyperUuid.new_v7` (current time) | 3,574,000 | **3.8x faster** |
+| `HyperUuid.new_v5` | 1,942,000 | 2.1x faster |
 
-A `HyperUuid.new_v4` — real entropy, correct version/variant bits, minted by the shared Rust core — costs a fifth of what `SecureRandom.uuid` does, because the Magnus extension is an ordinary native method call with nothing marshalled around it.
+A `HyperUuid.new_v4` — real entropy, correct version/variant bits, minted by the shared Rust core — costs less than a fifth of what `SecureRandom.uuid` does, because the Magnus extension is an ordinary native method call with nothing marshalled around it.
 
 The "current time" rows deserve a footnote, because they will not look like this everywhere. Here they land beside the explicit-ms rows: the only difference between the two is one `Process.clock_gettime(CLOCK_REALTIME)` wall-clock read, and on this machine that read is too cheap to see. On a machine with a slow clock it is the whole story — where a virtualized clock defeats the vDSO fast path the same read costs ~1µs, which puts both current-time rows at parity with `SecureRandom.uuid` while the explicit-ms rows stay well ahead of it. `SecureRandom.uuid` never reads a clock — random v4 is the only thing it does. If your clock is slow and you are minting many, read it once and pass the timestamp, or use the batch doors.
 
-The Fiddle fallback (`HYPERUUID_PURE=1`, and any platform without a prebuilt extension) keeps its own diet — a reused thread-local scratch buffer instead of two GC-finalizer-registering mallocs per call, zero-copy `String` passes for read-only inputs, an unsynchronized fast path past the load mutex — landing at 1.25x slower than `SecureRandom.uuid` for v4 (1.26 µs against 1.01 µs in its own run) and 1.45x slower for v6/v7, with the same structural story as before: `Fiddle`'s interpreted marshalling is the floor, and the batch doors are how you amortize it.
+The Fiddle fallback (`HYPERUUID_PURE=1`, and any platform without a prebuilt extension) keeps its own diet — a reused thread-local scratch buffer instead of two GC-finalizer-registering mallocs per call, zero-copy `String` passes for read-only inputs, an unsynchronized fast path past the load mutex — landing at 1.16x slower than `SecureRandom.uuid` for v4 (1.24 µs against 1.07 µs in its own run) and about 1.3x slower for v6/v7, with the same structural story as before: `Fiddle`'s interpreted marshalling is the floor, and the batch doors are how you amortize it.
 
 Batch generation still amortizes per-call cost on both backends — one native call for the whole batch:
 
 | Call | i/s (Magnus backend) |
 |---|---:|
-| `new_v6` × 1000 (individual) | 3,498 |
-| `new_v6_batch(1000)` | 4,633 (**1.3x**) |
-| `new_v7` × 1000 (individual) | 3,539 |
-| `new_v7_batch(1000)` | 4,677 (**1.3x**) |
+| `new_v6` × 1000 (individual) | 3,761 |
+| `new_v6_batch(1000)` | 4,857 (**1.3x**) |
+| `new_v7` × 1000 (individual) | 3,742 |
+| `new_v7_batch(1000)` | 4,850 (**1.3x**) |
 
-The multiplier is small on this backend for the best reason available: the individual calls are cheap, so there is little waste left to amortize, and what `new_v7_batch` spends its 214 µs on is building a thousand `Uuid` objects — the byte form above does the same native work in 10 µs. On the Fiddle backend, where each call costs 1.4 µs, the same batch is 6.7x the loop. If you need v5/v6/v7, need many at once, or need this Ruby service's IDs to agree byte-for-byte with a Go or Python service's, that's what this gem is for — and now it's the fast option too, not just the capable one.
+The multiplier is small on this backend for the best reason available: the individual calls are cheap, so there is little waste left to amortize, and what `new_v7_batch` spends its 206 µs on is building a thousand `Uuid` objects — the byte form above does the same native work in 5 µs. On the Fiddle backend, where each call costs 1.4 µs, the same batch is 6.7x the loop. If you need v5/v6/v7, need many at once, or need this Ruby service's IDs to agree byte-for-byte with a Go or Python service's, that's what this gem is for — and now it's the fast option too, not just the capable one.
 
 ## Backends
 
@@ -248,8 +298,7 @@ one at `require` time:
 | 3.4 (until its EOL 2028-03-31) | Magnus, `BACKEND == :native` | platform |
 | 3.3 (the floor, until its EOL 2027-03-31) | Fiddle | universal |
 
-What stands behind each cell: CI runs the whole suite through each Magnus extension on every
-push — Ruby 3.4 and 4.0 on all seven platform-gem platforms, the two musl ones inside each
+What stands behind each cell: CI runs the whole suite through each Magnus extension — Ruby 4.0 on every pull request and Ruby 3.4 in the weekly and release builds, on all seven platform-gem platforms, the two musl ones inside each
 Ruby's own Alpine image — and the Fiddle suite on Ruby 4.0 on every one of them, plus on Ruby
 3.3 inside Alpine. Intel macOS has no CI leg: its library is cross-built and tested at the
 core, and Ruby there runs the universal gem's Fiddle backend over it. Anywhere else — a platform with no native build at
@@ -367,6 +416,7 @@ bundle install
 bundle exec rake native:dev          # build the Magnus extension for this Ruby and stage it
 bundle exec rspec                    # BACKEND == :native
 HYPERUUID_PURE=1 bundle exec rspec   # BACKEND == :fiddle
+HYPERUUID_BIG_BATCH=1 bundle exec rspec spec/inspection_spec.rb  # adds the 1 GiB MAX_V7_BATCH batch
 bundle exec rake docs:check          # every public object carries a doc comment
 ruby benchmark/uuid_benchmark.rb     # prints the backend it measured
 ```
@@ -393,11 +443,12 @@ flags in the forge's `build-magnus.sh`, which is also what CI uses on every plat
 
 The musl build has no host to run on outside a container. With the core built for musl at
 `rust/target/musl/linux-musl-x64/libhyperuuid.so`, this runs the Fiddle suite against it on
-Alpine, with the checkout mounted read-only:
+Alpine, with the checkout mounted read-only (`corpus/` comes along: `spec/corpus_spec.rb` finds
+it by walking up from the spec):
 
 ```sh
 docker run --rm -v "$PWD/..":/src:ro ruby:4.0-alpine sh -euc '
-  mkdir /work && cp -r /src/ruby /work/ruby
+  mkdir /work && cp -r /src/ruby /src/corpus /work/
   mkdir -p /work/ruby/lib/hyperuuid/native/linux-musl-x64
   cp /src/rust/target/musl/linux-musl-x64/libhyperuuid.so /work/ruby/lib/hyperuuid/native/linux-musl-x64/
   cd /work/ruby && rm -f Gemfile.lock
@@ -411,7 +462,7 @@ Fiddle that Ruby 3.3 ships:
 
 ```sh
 docker run --rm -v "$PWD/..":/src:ro ruby:3.3-alpine sh -euc '
-  mkdir /work && cp -r /src/ruby /work/ruby
+  mkdir /work && cp -r /src/ruby /src/corpus /work/
   mkdir -p /work/ruby/lib/hyperuuid/native/linux-musl-x64
   cp /src/rust/target/musl/linux-musl-x64/libhyperuuid.so /work/ruby/lib/hyperuuid/native/linux-musl-x64/
   cd /work/ruby && rm -f Gemfile Gemfile.lock

data/lib/hyperuuid/runtime.rb

@@ -28,6 +28,17 @@ module HyperUuid
     V6_TIMESTAMP_OUT_OF_RANGE = "unix_millis does not fit the 60-bit v6 timestamp field"
     V7_TIMESTAMP_OUT_OF_RANGE = "unix_millis must fit within the RFC 9562 48-bit field"
 
+    # The two batch-size refusals, shared the same way: a version 7 batch past the 26-bit
+    # counter space (the core's return code 4, which the doors in hyperuuid.rb refuse before
+    # either backend sees it), and a batch whose byte length the platform cannot address
+    # (code 3, reachable only on a 32-bit target such as ruby.wasm). Both are argument
+    # errors, never a random source failure.
+    V7_BATCH_TOO_LARGE = "a single version 7 batch takes at most 67108864 UUIDs (the 26-bit counter space)"
+    BATCH_TOO_LARGE_TO_ADDRESS = "the batch is too large to address on this platform"
+
+    # The core's v7::MAX_BATCH, which hyperuuid.rb publishes as HyperUuid::MAX_V7_BATCH.
+    MAX_V7_BATCH = 1 << 26
+
     NATIVE_DIR = File.join(__dir__, "native")
 
     @mutex = Mutex.new
@@ -38,6 +49,7 @@ module HyperUuid
         out = scratch
         rc = functions[:new_v4].call(out)
         raise random_source_failure("uuid_new_v4") unless rc.zero?
+
         out[0, 16]
       end
 
@@ -49,6 +61,7 @@ module HyperUuid
         # contract.
         rc = functions[:new_v5].call(namespace_bytes, name_bytes, name_bytes.bytesize, out)
         raise random_source_failure("uuid_new_v5") unless rc.zero?
+
         out[0, 16]
       end
 
@@ -68,11 +81,13 @@ module HyperUuid
 
       def new_v6_batch(count, unix_millis)
         return "" if count.zero?
+
         out = buffer(count * 16)
         rc = functions[:new_v6_batch].call(unix_millis, count, out)
         case rc
         when 0 then out[0, count * 16]
         when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+        when 3 then raise ArgumentError, BATCH_TOO_LARGE_TO_ADDRESS
         else raise random_source_failure("uuid_new_v6_batch")
         end
       end
@@ -93,15 +108,55 @@ module HyperUuid
 
       def new_v7_batch(count, unix_millis)
         return "" if count.zero?
+        # Before the buffer: a count past the counter space would otherwise allocate up to
+        # 64 GiB only for the core to refuse it with code 4.
+        raise ArgumentError, V7_BATCH_TOO_LARGE if count > MAX_V7_BATCH
+
         out = buffer(count * 16)
         rc = functions[:new_v7_batch].call(unix_millis, count, out)
         case rc
         when 0 then out[0, count * 16]
         when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+        when 3 then raise ArgumentError, BATCH_TOO_LARGE_TO_ADDRESS
+        when 4 then raise ArgumentError, V7_BATCH_TOO_LARGE
         else raise random_source_failure("uuid_new_v7_batch")
         end
       end
 
+      # The inspection exports. +layout+ is the core's layout code (1 RFC 9562, 2 SQL Server),
+      # which Uuid has already validated; +bytes+ are 16, held in that layout's order.
+      def version(bytes, layout)
+        functions[:version].call(bytes, layout)
+      end
+
+      # The core's variant code: 1 NCS, 2 RFC 9562, 3 Microsoft, 4 future (Uuid#variant maps
+      # it to a Symbol, for both backends).
+      def variant(bytes)
+        functions[:variant].call(bytes)
+      end
+
+      # +version+ is 0-15 here: Uuid#rfc? answers false for anything else without asking.
+      def is_rfc(bytes, version, layout)
+        functions[:is_rfc].call(bytes, version, layout) == 1
+      end
+
+      # The Unix ms of an RFC 9562 version 6 or 7 UUID held in +layout+'s order, or nil for
+      # anything else — another version, another variant. One core call; the version it
+      # answers with is not needed above Runtime, so it is dropped here.
+      def get_timestamp(bytes, layout)
+        out = millis_scratch
+        version = functions[:get_timestamp].call(bytes, layout, out)
+        version.zero? ? nil : out[0, 8].unpack1("Q")
+      end
+
+      def v6_unix_millis_in(bytes, layout)
+        functions[:v6_unix_millis_in].call(bytes, layout)
+      end
+
+      def v7_unix_millis_in(bytes, layout)
+        functions[:v7_unix_millis_in].call(bytes, layout)
+      end
+
       def v7_to_sql_order(bytes)
         rewrite(:v7_to_sql_order, bytes)
       end
@@ -122,7 +177,7 @@ module HyperUuid
       # library's zero-argument hyperuuid_version export. HyperUuid.native_version unpacks
       # it; like every method here, each backend replaces this one in place.
       def packed_version
-        functions[:version].call
+        functions[:packed_version].call
       end
 
       # The one failure every generating export shares, with the one message every backend
@@ -183,6 +238,12 @@ module HyperUuid
         Thread.current[:hyperuuid_scratch] ||= buffer(16)
       end
 
+      # The u64 get_timestamp writes, per thread for the same reason as #scratch, and apart from
+      # it so the UUID bytes passed in are never the buffer being written.
+      def millis_scratch
+        Thread.current[:hyperuuid_millis_scratch] ||= buffer(8)
+      end
+
       # Every Fiddle allocation goes through here, and loads the library first: that is what
       # keeps a missing library reported as missing_library_message instead of as whatever
       # touching Fiddle raises first. The scratch buffer pays for it once per thread.
@@ -270,8 +331,34 @@ module HyperUuid
             [Fiddle::TYPE_VOIDP],
             Fiddle::TYPE_VOID
           ),
+          version: Fiddle::Function.new(
+            handle["uuid_version"],
+            [Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT32_T],
+            Fiddle::TYPE_UINT32_T
+          ),
+          variant: Fiddle::Function.new(handle["uuid_variant"], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_UINT32_T),
+          is_rfc: Fiddle::Function.new(
+            handle["uuid_is_rfc"],
+            [Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_UINT32_T],
+            Fiddle::TYPE_UINT32_T
+          ),
+          get_timestamp: Fiddle::Function.new(
+            handle["uuid_get_timestamp"],
+            [Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_UINT32_T
+          ),
+          v6_unix_millis_in: Fiddle::Function.new(
+            handle["uuid_v6_unix_millis_in"],
+            [Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT32_T],
+            Fiddle::TYPE_UINT64_T
+          ),
+          v7_unix_millis_in: Fiddle::Function.new(
+            handle["uuid_v7_unix_millis_in"],
+            [Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT32_T],
+            Fiddle::TYPE_UINT64_T
+          ),
           # The one export that mints nothing: the zero-argument version probe.
-          version: Fiddle::Function.new(handle["hyperuuid_version"], [], Fiddle::TYPE_UINT32_T),
+          packed_version: Fiddle::Function.new(handle["hyperuuid_version"], [], Fiddle::TYPE_UINT32_T),
         }
       end
     end

data/lib/hyperuuid/uuid.rb

@@ -38,6 +38,17 @@ module HyperUuid
     HYPHENATED = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
     private_constant :HYPHENATED
 
+    # The byte orders a Uuid can hold, as the +layout:+ keyword of #version, #rfc? and
+    # #timestamp takes them, mapped to the native core's layout codes. +:rfc9562+ is RFC 9562
+    # order, what every other method here takes and returns. +:sql_server+ is the order
+    # #to_sql_order returns, defined for versions 6 and 7 only.
+    LAYOUTS = { rfc9562: 1, sql_server: 2 }.freeze
+
+    # The Symbols #variant returns, indexed by the native core's variant code (1-4; 0 is
+    # reserved and never returned). The one place that code becomes a Symbol, for both backends.
+    VARIANTS = [nil, :ncs, :rfc9562, :microsoft, :future].freeze
+    private_constant :VARIANTS
+
     # Parses an 8-4-4-4-12 hyphenated hex UUID string — exactly the shape #to_s produces, in
     # either case. Nothing else parses: not the bare 32 hex digits, not hyphens anywhere but
     # those four positions, not braces or a `urn:uuid:` prefix.
@@ -51,14 +62,56 @@ module HyperUuid
       new([string.delete("-")].pack("H*"))
     end
 
-    # The RFC 9562 version nibble (bits 48-51, the high nibble of octet 6).
-    def version
-      (bytes.getbyte(6) >> 4) & 0x0F
+    # The version of this UUID, read by the native core in +layout+'s byte order.
+    #
+    # In +:rfc9562+ (the default) it is the version nibble (bits 48-51, the high nibble of
+    # octet 6), 0 through 15: Nil reads as 0 and Max as 15. It says nothing about the variant;
+    # #rfc? checks both. In +:sql_server+, the order #to_sql_order returns, it is 6 or 7 for a
+    # SQL-ordered version 6 or 7 UUID and 0 when the bytes don't form one, since no other
+    # version has a SQL Server order. It reads the bytes as given: an RFC-ordered value can
+    # happen to form a SQL-ordered v6 or v7, so the layout is the caller's to know.
+    #
+    # With the default layout, the value is read as RFC 9562 order. A SQL-ordered value — from
+    # #to_sql_order, or a +uniqueidentifier+ read back from SQL Server — needs
+    # +layout: :sql_server+, because the RFC-order read looks at the wrong bytes there. There
+    # is deliberately no layout-agnostic check: whoever holds the value knows its order.
+    #
+    # @raise [ArgumentError] if +layout+ isn't one of LAYOUTS' keys.
+    def version(layout: :rfc9562)
+      Runtime.version(bytes, layout_code(layout))
     end
 
-    # The RFC 9562 variant bits (top two bits of octet 8). +0b10+ means RFC 9562/4122.
+    # The variant of this UUID (RFC 9562 §4.1), read by the native core in RFC 9562 order, as a
+    # Symbol: +:rfc9562+ (+10xx+, every UUID this gem mints, and the only variant that has
+    # versions), +:ncs+ (+0xxx+, Nil among them), +:microsoft+ (+110x+) or +:future+ (+111x+,
+    # Max among them).
+    #
+    # RFC 9562 order only. There is no layout form, because in SQL Server order the variant
+    # sits at a different byte for each version, so don't hand it a SQL-ordered value or a
+    # +uniqueidentifier+ read back from SQL Server. To validate one of those, use
+    # <tt>rfc?(version, layout: :sql_server)</tt>, which checks the variant where that version
+    # puts it.
     def variant
-      (bytes.getbyte(8) >> 6) & 0b11
+      VARIANTS.fetch(Runtime.variant(bytes))
+    end
+
+    # Whether this is an RFC 9562 UUID of version +version+, read in +layout+'s byte order —
+    # the RFC 9562 variant and that version together, the guard to run before trusting a
+    # value's version-specific fields. In +:sql_server+ only 6 and 7 can be true. A version
+    # outside 0-15 is simply false.
+    #
+    # With the default layout, the value is read as RFC 9562 order. A SQL-ordered value — from
+    # #to_sql_order, or a +uniqueidentifier+ read back from SQL Server — needs
+    # +layout: :sql_server+, because the RFC-order read looks at the wrong bytes there. There
+    # is deliberately no layout-agnostic check: whoever holds the value knows its order.
+    #
+    # @raise [TypeError] if +version+ isn't an Integer.
+    # @raise [ArgumentError] if +layout+ isn't one of LAYOUTS' keys.
+    def rfc?(version, layout: :rfc9562)
+      raise TypeError, "version must be an Integer; got #{version.class}" unless version.is_a?(Integer)
+
+      code = layout_code(layout)
+      version.between?(0, 15) && Runtime.is_rfc(bytes, version, code)
     end
 
     # The 8-4-4-4-12 hyphenated hex string representation.
@@ -68,24 +121,24 @@ module HyperUuid
     end
     alias_method :to_str, :to_s
 
-    # The UTC timestamp embedded in a version 6 or 7 UUID's timestamp field. Only meaningful
-    # when `version` is 6 or 7 — the RFC 9562 bit layout doesn't distinguish "not a time-based
-    # UUID" from "time-based UUID with a very early timestamp", so the caller is responsible
-    # for checking `version` first if that matters.
-    #
-    # Raises by default for any other version; pass `raise_on_mismatch: false` to get `nil`
-    # back instead — for a caller that doesn't already know (or want to separately check)
-    # whether this UUID is time-based.
-    def timestamp(raise_on_mismatch: true)
-      millis =
-        case version
-        when 6 then Runtime.v6_unix_millis(bytes)
-        when 7 then Runtime.v7_unix_millis(bytes)
-        else
-          raise ArgumentError, "timestamp is only defined for version 6 or 7 UUIDs, got version #{version}" if raise_on_mismatch
-          return nil
-        end
-      Time.at(millis / 1000, millis % 1000, :millisecond).utc
+    # The UTC timestamp embedded in an RFC 9562 version 6 or 7 UUID, held in +layout+'s byte
+    # order: +:rfc9562+ (the default), or +:sql_server+ for a value #to_sql_order returned. One
+    # native call that checks the variant as well as the version: a 6 or 7 in the version
+    # nibble under any variant but +:rfc9562+ is not a version 6 or 7 UUID, so it has no
+    # timestamp (#rfc? is the same check on its own).
+    #
+    # Raises by default for anything that isn't an RFC 9562 version 6 or 7 UUID; pass
+    # `raise_on_mismatch: false` to get `nil` back instead — for a caller that doesn't already
+    # know (or want to separately check) whether this UUID is time-based.
+    #
+    # @raise [ArgumentError] if this isn't an RFC 9562 version 6 or 7 UUID in +layout+ (unless
+    #   +raise_on_mismatch+ is false), or +layout+ isn't one of LAYOUTS' keys.
+    def timestamp(raise_on_mismatch: true, layout: :rfc9562)
+      millis = Runtime.get_timestamp(bytes, layout_code(layout))
+      return Time.at(millis / 1000, millis % 1000, :millisecond).utc if millis
+      return nil unless raise_on_mismatch
+
+      raise ArgumentError, timestamp_mismatch(layout)
     end
 
     # Converts an RFC 9562-ordered version 6 or 7 UUID to the byte order SQL Server's
@@ -128,29 +181,22 @@ module HyperUuid
     # Inverse of #to_sql_order — converts a SQL-Server-ordered version 6 or 7 UUID back to
     # RFC 9562 order.
     #
-    # A SQL-ordered value's version nibble sits at a different octet depending on which
-    # version produced it (octet 7's top nibble = 7 for v7-sql-order, octet 8's top nibble =
-    # 6 for v6-sql-order — #version itself assumes RFC order's octet 6 and can't tell these
-    # apart), so this checks both fixed positions directly rather than calling #version.
-    #
-    # Order matters here and isn't arbitrary: octet 8 must be checked *first*. For v6-sql-order
-    # it's deterministic (top nibble always 0x6, by construction), and for v7-sql-order it's
-    # also deterministic but structurally excluded from ever reading 0x6 (its top two bits are
-    # the fixed variant `10`, so the nibble only ever lands in 0x8-0xB) — no collision either
-    # way. Octet 7, by contrast, is *not* safe to check first: for v7-sql-order it's
-    # deterministically 0x7, but for v6-sql-order it holds `clock_seq`'s fully random low
-    # byte, which has a real (~1-in-16) chance of a top nibble that also happens to read 0x7 —
-    # confirmed by an actual test failure during development, not a hypothetical. Checking
-    # octet 8 first rules v6 in or out unambiguously before octet 7's reading can matter.
+    # A SQL-ordered value's version sits at a different octet depending on which version
+    # produced it, so this asks the native core which one it is — `version(layout:
+    # :sql_server)`, which checks each version's nibble together with its variant bits and
+    # so never mistakes a v6 whose random `clock_seq` byte happens to read as a v7 nibble.
+    #
+    # The layout is the caller's to know: bytes alone cannot say which order they are in. A
+    # value that was never SQL-ordered can still read as one, and is then converted rather
+    # than refused (a random RFC-ordered v4 reads as a SQL-ordered v7 one time in 16, since its
+    # octet 8 already carries the RFC variant and its octet 7 is random).
+    #
+    # @raise [ArgumentError] if this isn't a SQL-ordered version 6 or 7 UUID.
     def from_sql_order
-      octet8_version = (bytes.getbyte(8) >> 4) & 0x0F
-      octet7_version = (bytes.getbyte(7) >> 4) & 0x0F
-      if octet8_version == 6
-        self.class.new(Runtime.v6_to_rfc_order(bytes), true)
-      elsif octet7_version == 7
-        self.class.new(Runtime.v7_to_rfc_order(bytes), true)
-      else
-        raise ArgumentError, "from_sql_order: not a recognized version 6 or 7 SQL-ordered UUID"
+      case Runtime.version(bytes, LAYOUTS[:sql_server])
+      when 6 then self.class.new(Runtime.v6_to_rfc_order(bytes), true)
+      when 7 then self.class.new(Runtime.v7_to_rfc_order(bytes), true)
+      else raise ArgumentError, "from_sql_order: not a recognized version 6 or 7 SQL-ordered UUID"
       end
     end
 
@@ -168,6 +214,7 @@ module HyperUuid
     # Byte-order comparison against +other+, or +nil+ if +other+ isn't a Uuid.
     def <=>(other)
       return nil unless other.is_a?(Uuid)
+
       bytes <=> other.bytes
     end
 
@@ -175,5 +222,24 @@ module HyperUuid
     def inspect
       "#<HyperUuid::Uuid #{self}>"
     end
+
+    private
+
+    # Why #timestamp found none: the message is worked out only once it is going to be raised.
+    def timestamp_mismatch(layout)
+      return "timestamp: not a SQL-ordered version 6 or 7 UUID" if layout == :sql_server
+
+      found = version
+      message = "timestamp is only defined for version 6 or 7 UUIDs, got version #{found}"
+      [6, 7].include?(found) ? "#{message} with the #{variant.inspect} variant" : message
+    end
+
+    # The native core's code for +layout+, the one place a layout is checked: an unknown one
+    # is refused here, never passed through to the core.
+    def layout_code(layout)
+      LAYOUTS.fetch(layout) do
+        raise ArgumentError, "layout must be one of #{LAYOUTS.keys.map(&:inspect).join(', ')}; got #{layout.inspect}"
+      end
+    end
   end
 end

data/lib/hyperuuid.rb

@@ -18,13 +18,28 @@ require_relative "hyperuuid/runtime"
 module HyperUuid
   # This gem's own version — distinct from the RFC 9562 UUID *versions* (v4/v5/v6/v7) the
   # rest of this module generates.
-  VERSION = "0.6.1"
+  VERSION = "0.8.0"
 
   # The widest batch count, and the longest v5 name in bytes, the native ABI carries (a u32).
   # (The millisecond count is a u64; unix_millis_from refuses anything wider.)
   U32_MAX = 0xFFFF_FFFF
   private_constant :U32_MAX
 
+  # The most UUIDs one version 7 batch (#new_v7_batch, #new_v7_batch_bytes) mints:
+  # 67,108,864, the size of the 26-bit counter that orders UUIDs within a millisecond. A larger
+  # count is refused with ArgumentError before anything is allocated. Version 6 has no counter
+  # and no such limit.
+  #
+  # Every batch up to this size is in strictly increasing order: the counter is one
+  # process-wide sequence, so a batch can straddle the point where it wraps back to 0, and the
+  # UUIDs from there on carry a timestamp one millisecond later than the one supplied.
+  # The roll-forward orders one batch, not the stream: the next batch or single #new_v7 in
+  # the same real millisecond starts its counter just past the wrap and carries the supplied
+  # timestamp, so it sorts before this batch's tail, which was stamped a millisecond later.
+  # Two single #new_v7 calls either side of the wrap in one millisecond sort in reverse the
+  # same way. It happens at most once per 2**26 UUIDs the process mints.
+  MAX_V7_BATCH = Runtime::MAX_V7_BATCH
+
   # Creates a random UUID version 4 (RFC 9562 §5.4).
   def self.new_v4
     Uuid.new(Runtime.new_v4, true)
@@ -125,7 +140,18 @@ module HyperUuid
   # instead of `count` of each. Defaults to the current time; pass an explicit `Time` or
   # Unix-epoch millisecond integer to embed a specific time instead.
   #
-  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # Every batch is in strictly increasing order. The counter is one process-wide sequence, so
+  # a batch can straddle the point where it wraps back to 0; the UUIDs from there on carry a
+  # timestamp one millisecond later than the one supplied rather than sorting before the ones
+  # ahead of them. That is also why one batch takes at most MAX_V7_BATCH.
+  #
+  # The roll-forward orders one batch, not the stream: the next batch or single #new_v7 in
+  # the same real millisecond starts its counter just past the wrap and carries the supplied
+  # timestamp, so it sorts before this batch's tail, which was stamped a millisecond later.
+  # Two single #new_v7 calls either side of the wrap in one millisecond sort in reverse the
+  # same way. It happens at most once per 2**26 UUIDs the process mints.
+  #
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and MAX_V7_BATCH.
   # @raise [TimestampOutOfRangeError] if the time is negative or past the 48-bit v7 field.
   def self.new_v7_batch(count, unix_millis = nil)
     bytes = new_v7_batch_bytes(count, unix_millis)
@@ -145,11 +171,15 @@ module HyperUuid
   # format, a bulk COPY. If you need Uuid objects, keep using #new_v7_batch — slicing this
   # String into them yourself just moves the same allocations into your own code.
   #
-  # Slice it with `bytes[i * 16, 16]`, which is what #new_v7_batch does internally.
+  # Slice it with `bytes[i * 16, 16]`, which is what #new_v7_batch does internally. The
+  # order, the possible extra millisecond and the MAX_V7_BATCH limit are #new_v7_batch's.
   #
-  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and MAX_V7_BATCH.
   # @raise [TimestampOutOfRangeError] if the time is negative or past the 48-bit v7 field.
   def self.new_v7_batch_bytes(count, unix_millis = nil)
+    # First, so any count past the limit (2**32 and beyond included) names the limit itself.
+    raise ArgumentError, Runtime::V7_BATCH_TOO_LARGE if count.is_a?(Integer) && count > MAX_V7_BATCH
+
     count = batch_count(count)
     Runtime.new_v7_batch(count, unix_millis_from(unix_millis, Runtime::V7_TIMESTAMP_OUT_OF_RANGE))
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperuuid
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.8.0
 platform: x86_64-linux-gnu
 authors:
 - Brian Buvinghausen