r00t2/go_goutils
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

v1.16.7

Browse Source 
ADDED:
* uuidx
FIXED:
* sprigx docs consistency
This commit is contained in:
brent saner
2026-02-11 10:21:29 -05:00
parent 67c7faf449
commit 1eea0c2672
18 changed files with 4446 additions and 1659 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
uuidx/consts.go Normal file
View File

@@ -0,0 +1,11 @@
package uuidx
const (
RfcNone RfcGen = iota
Rfc4122
Rfc9562
)
const (
MsGuidThreshold int = 4
)

73
uuidx/doc.go Normal file
View File

@@ -0,0 +1,73 @@
/*
Package uuidx intends to supplement [github.com/google/uuid].
# Microsoft GUID Shenanigans
The following functions are provided to deal with [Microsoft's incompetence]:
* [DetectMsGuid] (a confidence'd determination if a UUID is a Microsoft GUID or not)
* [IsFlippedEndian] for flipped-endian [uuid.UUID] comparison (e.g. a is the Microsoft-flipped-endian version of b)
* [IsMsGuid] (wraps [DetectMsGuid] and returns true if confidence is reasonably strong that it's a Microsoft GUID)
* [IsRfc] (the inverse of IsMsGuid, but also checks for strict RFC compliance and returns which RFC)
* [MsGuidToUuid] (explicitly convert/ensure a GUID/UUID is likely a UUID)
* [ToggleUuidMsGuid] (blindly flip the endianness of selected byte ranges for MS GUID <-> UUID conversion)
* [UuidToMsGuid] (explicitly convert/ensure a GUID/UUID is likely an MS GUID)
Microsoft, in their typical insanity, uses a proprietary UUID format (usually referred to as the "Microsoft GUID Format"
or "Mixed-Endian Format").
Normally for, for example a UUIDv4, it's structured as thus per RFC 9562 [§ 5.4] (which obsoletes RFC 4122 [§ 4.4]):
A B C D E
HEX(BE(uint32))-HEX(BE(uint16))-HEX(BE(uint16))-HEX(BE(<uint16>), BE(<6 bytes>))
(where <BE> is big-endian packing).
However, thanks to Microsoft we can't have nice things. They decided to completely ignore the standard, and
instead keep D/E as big-endian *but use little-endian* for A through C inclusive:
A B C D E
HEX(LE(uint32))-HEX(LE(uint16))-HEX(LE(uint16))-HEX(BE(<uint16>), BE(<6 bytes>))
"Surely that had SOME reason to do that," you may say to yourself, "they wouldn't make some arbitrary formatting
change from a standard just because."
You would be wrong. To my knowledge, they have never provided any technological justfification to this insanity,
and now it's infected its way into a slew of other technologies they've had their grubby little hands involved in
(e.g. UEFI). And it's of course too late to change.
So anyways here's a library to make dealing with Microsoft's hubris a little easier.
# Validation/Verification
Aside from trying to address Microsoft silliness, there are some additional functions:
* [Equal] for [uuid.UUID] comparison
* [IsMaxUUID] (if a given [uuid.UUID] is an RFC 9562 [§ 5.10] UUID)
* [IsNilUUID] (if a given [uuid.UUID] is an RFC 9562 [§ 5.9] UUID)
* [IsValid] (If an RFC can be considered safely conformant to RFC spec)
# Future Incorporation/Deprecation/Obsolescence
Worth keeping an eye on are:
* https://github.com/google/uuid/pull/192
* https://github.com/golang/go/issues/62026
* https://github.com/golang/go/issues/76319
(generally it's a bad idea for an API addition overall, but some good ideas were raised)
Some of these additions may deprecate/obsolete components of this package.
I'll try to keep them around but mark as deprecated as they are (if they are),
but I make no concrete promises - I hate making new major releases in Go's
[silly module architecture] even more than I do keeping old deprecated code around.
So caveat emptor.
[Microsoft's incompetence]: https://learn.microsoft.com/en-us/windows/win32/api/guiddef/ns-guiddef-guid
[§ 5.4]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.4
[§ 4.4]: https://datatracker.ietf.org/doc/html/rfc4122#section-4.4
[§ 5.9]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.9
[§ 5.10]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.10
[github:google/uuid#192]: https://github.com/google/uuid/pull/192
[silly module architecture]: https://go.dev/doc/modules/major-version
*/
package uuidx

461
uuidx/funcs.go Normal file
View File

@@ -0,0 +1,461 @@
package uuidx
import (
"github.com/google/uuid"
)
/*
DetectMsGuid tries to guess if a given [uuid.UUID] is actually a Microsoft GUID or not.
Note that there are technically *two* types of Microsoft GUIDs:
* One is predictable, and defined in RFC 9562 [§ 4.2] as a known variant.
Detecting this is very easy and (assuming an RFC-compliant UUID is originally passed) is detectable with 100% confidence.
It's also legacy, and Microsoft no longer uses this format. Because they are insane and enjoy the suffering of others.
* The other, MODERN Microsoft GUID currently in use is the endianness-flipped version (see [ToggleUuidMsGuid]).
This is impossible to 100% determine, but analysis can get *pretty* close.
cs is a confidence scoring. As more logic is added, it *is* mathematically possible
(though unlikely) that cs == 0, so the caller is then responsible for making further
guesswork based on contextual analysis ("Did I get this UUID/GUID from an Active Directory attribute?"
"Is it a SID constant?" etc.).
A score > 0 indicates a confidence leaning towards the provided UUID/GUID being a Microsoft GUID.
A score < 0 indicates a confidence leaning towards the provided UUID/GUID *not* being a Microsoft GUID.
Note that a score of < 0 does not necessarily indicate it is a *proper, standard RFC-compliant UUID*,
simply that it is likely NOT a Microsoft GUID. [IsRfc] will be of further help in these cases.
csFlip indicates a score for the [ToggleUuidMsGuid]-flipped version of u.
It follows the same rules for thresholds and such as cs, but may be awarded different confidence levels
internally due to different chances of false positives.
If both cs and csFlip are > 0 but csFlip > cs, it is better to assume that u is *not* in the flipped-endian format
but *is* a Microsoft GUID (in other words, it is likely that u has *already been flipped* to proper/consistent endianness
instead of being a mixed-endian GUID).
In some cases where flipped-endianness does not matter (e.g. [IsNilUUID], [IsMaxUUID]),
cs and csFlip will be equal.
*Randomly-generated* GUIDs on Windows Server 2000-family and up are almost always UUIDv4.
Pre-Windows Server 2000 family *OR* any *statically-defined* GUIDs (schemaIDGUID, rightsGUID, CLSID constants, etc.)
are all over the place - TYPICALLY UUIDv1, but it's nothing predictable enough to be useful in definitive classification.
COM interfaces are all OVER the place in UUID version, but usually *not* UUIDv4.
A target/expected UUID version can be provided via tgtVer. To disable version analysis, use 0 (or 0x00, etc.).
It is *highly* recommended to provide a tgtVer if it is known; it can significantly boost confidence in the correct direction.
A warning, though - if a *wrong* tgtVer IS specified, it can negatively affect confidence accuracy.
Thus if you aren't ABSOLUTELY certain of the target UUID version, it's better to use 0/0x00 to disable the check.
Providing a target version is key to breaking some ties (e.g. both cs and csFlip are equal).
For example, the given RFC-compliant UUIDv4:
8d8e35ae-58d2-4d28-b09d-ffffffffffff
when flipped evaluates to an RFC-compliant UUIDv2:
ae358e8d-d258-284d-b09d-ffffffffffff
and in this case, cs and csFlip will both end up as 0.
Providing a tgtVer of 4 shifts this to a proper "tie-breaker" of cs == -3 and csFlip == 0.
Similarly, the endian-flipped UUIDv4 evaluates as a UUIDv2:
9856ea36-c2ca-2347-af0c-3b42f76c9eca
from the original unflipped UUIDv4:
36ea5698-cac2-4723-af0c-3b42f76c9eca
which results in a cs == 1 and csFlip == 0 - not very high confidence (but at least a correct and non-zero lean).
Providing a tgtVer == 4 changes this to cs == 7 and csFlip == 0, which is *much* more decisive.
UUIDs/GUIDs found to be strictly RFC-conforming (via [IsRfc], which returns false for Microsoft GUIDs)
are *heavily* weighted negatively.
Confidence levels can be generally considered as the following:
cs >= 7: Likely Microsoft GUID (mixed-endian)
cs >= 4: Likely Microsoft GUID
0 < cs < 4: Leans Microsoft GUID, but untrusted
cs == 0: Entirely ambiguous/indeterminate
-4 < cs < 0: Leans UUID/non-Microsoft GUID but untrusted
cs <= -5: Likely UUID/not Microsoft GUID
csFlip >=cs && csFlip >= 4: Likely a pre-flipped (ToggleUuidMsGuid'd) Microsoft GUID
[§ 4.2]: https://datatracker.ietf.org/doc/html/rfc9562#section-4.2
*/
func DetectMsGuid(u uuid.UUID, tgtVer uuid.Version) (cs, csFlip int) {
var isRfc bool
var flippedRfc bool
var flipped uuid.UUID = ToggleUuidMsGuid(u)
// These are the exact same when flipped, and are statically defined.
if IsNilUUID(u) || IsMaxUUID(u) {
cs = -12
csFlip = -12
return
}
// Most/all(?) Microsoft GUIDs are not NCS.
if IsNcs(u) {
cs -= 2
}
if IsNcs(flipped) {
// The flipped has a higher likelihood of false-pos, so we don't score it as confidently.
csFlip -= 1
}
if u.Version() == 0 {
if u.Variant() == uuid.Microsoft {
cs += 10
} else {
cs -= 2
}
}
if flipped.Version() == 0 {
if flipped.Variant() == uuid.Microsoft {
csFlip += 4
} else {
csFlip -= 1
}
}
// Valid RFC version and variant. IsRfc returns false for the Microsoft Variant and version == 0.
// Modern MS uses an RFC 4122 variant indicator but flips the endianness.
isRfc, _ = IsRfc(u)
flippedRfc, _ = IsRfc(flipped)
if u.Variant() == uuid.RFC4122 { // This might be the strongest indicator.
if isRfc && !flippedRfc {
// This is *very* strong of being an MS GUID.
cs -= 8
csFlip += 4
} else if !isRfc && flippedRfc {
// It probably is an MS GUID but was already flipped.
csFlip += 6
} else if isRfc && flippedRfc {
/*
If both are RFC-compat, it's a weird case where
it actually IS RFC compliant and by chance the flipped is *also* RFC compat.
An example of this is:
8d8e35ae-58d2-4d28-b09d-ffffffffffff
Which has the flipped version of:
ae358e8d-d258-284d-b09d-ffffffffffff
The original is a v4, the flipped evaluates as a v2!
Providing a target version breaks this away to a definitive score.
*/
}
}
// *HEAVILY* weigh a provided version.
if tgtVer != 0 {
// NCS does some weird things to the versioning field. We return early on it though.
// MS GUIDs have a pretty small chance of matching,
// but their flipped counterpart SHOULD match versions.
if flipped.Version() == tgtVer {
cs += 7
} else {
cs -= 3
}
} else {
// Give a *very small* boost to flippedRfc and flipped.Version() == 4, since it's so common.
// Don't make this too high though since the version is explicitly specified as unknown.
if flippedRfc && flipped.Version() == 4 {
cs += 1
}
}
return
}
/*
Equal returns `true` if [uuid.UUID] the two provided [uuid.UUID] are the same.
Currently it just wraps:
eq = a == b
but is provided as a safety guarantee if the underlying structures/types should change.
*/
func Equal(a, b uuid.UUID) (eq bool) {
eq = a == b
return
}
/*
IsFlippedEndian can be used to check if [uuid.UUID] is a direct endian-flipped ([ToggleUuidMsGuid])
of b (or vice versa, obviously).
It simply wraps:
isFlipped = Equal(a, ToggleUuidMsGuid(b))
but can be useful for shorthand/readability.
*/
func IsFlippedEndian(a, b uuid.UUID) (isFlipped bool) {
isFlipped = Equal(a, ToggleUuidMsGuid(b))
return
}
/*
IsMaxUUID returns `true` if the specified UUID is explicitly an RFC-defined
"Max UUID". (You may also see it specified in some places as the "Omni UUID".)
For details, see RFC 9562 [§ 5.10].
[§ 5.10]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.10
*/
func IsMaxUUID(u uuid.UUID) (isMax bool) {
isMax = u == uuid.Max
return
}
/*
IsMsGuid wraps
if cmp, _ = DetectMsGuid(msGUID, tgtVer); cmp < -3 {
isMs = true
}
Note that [uuid.Microsoft] is an actual RFC-defined variant, but *Microsoft no longer uses it*
and in MODERN implementations do the endianness flip [ToggleUuidMsGuid] of (USUALLY) a UUIDv4.
See [DetectMsGuid] for a more in-depth result that will let you use the confidence level directly,
and for details on the weird things that can go wrong with this guesswork.
Note that this won't be 100% reliable due to math things, but it should be reliable enough most of the time.
See also [MsGuidToUuid] and [UuidToMsGuid].
*/
func IsMsGuid(msGUID uuid.UUID, tgtVer uuid.Version) (isMs bool) {
var cmp int
if cmp, _ = DetectMsGuid(msGUID, tgtVer); cmp < -3 {
isMs = true
}
return
}
/*
IsNcs is shorthand for:
isNcs = u.Variant() == uuid.Reserved
See also the notes in [IsRfc].
*/
func IsNcs(u uuid.UUID) (isNcs bool) {
// https://archive.org/details/networkcomputing0000zahn/page/10/mode/1up
isNcs = u.Variant() == uuid.Reserved
return
}
/*
IsNilUUID returns `true` if the specified UUID is explicitly an RFC-defined
"Nil UUID".
For details, see RFC 9562 [§ 5.9].
[§ 5.9]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.9
*/
func IsNilUUID(u uuid.UUID) (isNil bool) {
isNil = u == uuid.Nil
return
}
/*
IsRfc returns `true` if the specified UUID is a proper standard RFC UUID.
Because Microsoft is insane, rfc will be false even if it's a (legacy) Microsoft form
of an RFC UUID. Use [IsMsGuid] for that.
In the special case of u being a valid NCS UUID, rfc will be false but gen will be [Rfc4122].
This is because RFC 9652 deprecates the NCS UUID. See [IsNcs].
(You are highly unlikely to encounter an NCS UUID "in the wild" unless you are receiving
a UUID from someone who severely misunderstands that UUIDs are structured/versioned/typed
and thinks they're just random byes in hex with hyphens in certain places.)
(They aren't that, if you're one of those someones.)
Nil UUID ([IsNilUUID]) and Max UUID ([IsMaxUUID]) return true with RFCs 4122 and RFC 9562 respectively.
*/
func IsRfc(u uuid.UUID) (rfc bool, gen RfcGen) {
if IsNilUUID(u) {
rfc = true
gen = Rfc4122
return
}
if IsMaxUUID(u) {
rfc = true
gen = Rfc9562
return
}
if IsNcs(u) {
gen = Rfc4122
return
}
// TODO: Are there any sub-version checks that can be applied?
switch u.Variant() {
case uuid.Invalid, uuid.Microsoft, uuid.Future:
return
case uuid.RFC4122:
if !(0x01 <= u.Version() && u.Version() <= 0x08) {
return
}
rfc = true
gen = Rfc4122
// 4122 only covers UUIDv1 through UUIDv5.
if 0x06 <= u.Version() && u.Version() <= 0x08 {
gen = Rfc9562
}
default: // Safety net in case upstream adds a uuid.RFC9562 variant or something.
if !(0x01 <= u.Version() && u.Version() <= 0x08) {
return
}
if u.Variant() < uuid.Future {
return
}
rfc = true
gen = RfcNone
// 4122 only covers UUIDv1 through UUIDv5.
if 0x06 <= u.Version() && u.Version() <= 0x08 {
gen = Rfc9562
}
}
return
}
/*
IsValid indicates if the given [uuid.UUID] strictly conforms to RFC.
A Nil UUID (as in RFC 9562 [§ 5.9], not a `nil` *uuid.UUID) will return `true`
as it IS technically defined per RFC despite not conforming to a version.
Use [IsNilUUID] to further determine that.
Likewise, a Max UUID (RFC 9562 [§ 5.10]) will return `true` as it is also
defined per RFC despite not conforming to a version.
Use [IsMaxUUID] to further determine that.
Microsoft GUIDs will always return false since they defy RFC.
Use [IsMsGuid] to check for that condition.
[§ 5.9]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.9
[§ 5.10]: https://datatracker.ietf.org/doc/html/rfc9562#section-5.10
*/
func IsValid(u uuid.UUID) (valid bool) {
if IsNilUUID(u) {
valid = true
return
}
if IsMaxUUID(u) {
valid = true
return
}
switch u.Variant() {
case uuid.Invalid, uuid.Reserved, uuid.Microsoft, uuid.Future:
return
case uuid.RFC4122:
valid = true
// TODO: If they add an RFC9562 or something, need a case here.
default:
return
}
// If we got here, it *should* be RFC.
if valid, _ = IsRfc(u); !valid {
return
}
return
}
/*
MsGuidToUuid converts a Microsoft GUID to a UUID.
If [IsMsGuid] is false for msGUID, u will be equal to msGUID.
See [UuidToMsGuid] for the inverse, and [IsRfc] to check
if the result is a strictly conforming UUID.
*/
func MsGuidToUuid(msGUID uuid.UUID) (u uuid.UUID) {
if !IsMsGuid(msGUID, 0x00) {
u = msGUID
return
}
u = ToggleUuidMsGuid(msGUID)
return
}
/*
ToggleUuidMsGuid switches the src to it's "other" format:
* if it's a Microsoft GUID, it will be converted to a UUID
* if it's a UUID, it will be converted to a Microsoft GUID
No detection ([IsRfc], [IsMsGuid], etc.) nor validation/verification ([IsValid]) is performed,
which is why this is a "toggle" - it just flips some endianness for certain byte ranges.
If you prefer something a little more explicit, see [MsGuidToUuid] and/or [UuidToMsGuid].
Alternatively call [IsMsGuid] or [IsRfc] directly.
*/
func ToggleUuidMsGuid(orig uuid.UUID) (converted uuid.UUID) {
var cb [16]byte
var ob [16]byte = orig
// Can just directly map the allocations;
// the operation is the exact same regardless of whether the original is RFC and target is MS or vice versa.
cb = [16]byte{
// THESE GET ENDIAN-SWAPPED
ob[3], ob[2], ob[1], ob[0], // "A"
ob[5], ob[4], // "B"
ob[7], ob[6], // "C"
// THESE STAY THE SAME (should be BE for both)
ob[8], ob[9], ob[10], ob[11], // "D"
ob[12], ob[13], ob[14], ob[15], // "E"
}
converted = uuid.UUID(cb)
return
}
/*
UuidToMsGuid converts a UUID to a Microsoft GUID.
If [DetectMsGuid] indicates a good likelihood for u already being a Microsoft GUID
(greater than or equal) to [MsGuidThreshold], msGUID will be equal to u.
(If it detects it as unflipped endianness, it will automatically be flipped by this function.)
See [MsGuidToUuid] for the inverse.
*/
func UuidToMsGuid(u uuid.UUID) (msGUID uuid.UUID) {
var msCmp int
var flipped int
if msCmp, flipped = DetectMsGuid(u, 0x00); msCmp >= MsGuidThreshold && msCmp > flipped {
msGUID = u
return
}
msGUID = ToggleUuidMsGuid(u)
return
}

22
uuidx/funcs_rfcgen.go Normal file
View File

@@ -0,0 +1,22 @@
package uuidx
// String conforms an [RfcGen] to a [fmt.Stringer] interface.
func (g *RfcGen) String() (s string) {
if g == nil {
s = "UNSPECIFIED_NIL"
}
switch *g {
case RfcNone:
s = "INVALID"
case Rfc4122:
s = "RFC 4122"
case Rfc9562:
s = "RFC 9562"
default:
s = "UNKNOWN"
}
return
}

5
uuidx/types.go Normal file
View File

@@ -0,0 +1,5 @@
package uuidx
type (
RfcGen uint8
)