Initial QSfera import
This commit is contained in:
+24
@@ -0,0 +1,24 @@
|
||||
# Compiled Object files, Static and Dynamic libs (Shared Objects)
|
||||
*.o
|
||||
*.a
|
||||
*.so
|
||||
|
||||
# Folders
|
||||
_obj
|
||||
_test
|
||||
|
||||
# Architecture specific extensions/prefixes
|
||||
*.[568vq]
|
||||
[568vq].out
|
||||
|
||||
*.cgo1.go
|
||||
*.cgo2.c
|
||||
_cgo_defun.c
|
||||
_cgo_gotypes.go
|
||||
_cgo_export.*
|
||||
|
||||
_testmain.go
|
||||
|
||||
*.exe
|
||||
*.test
|
||||
*.prof
|
||||
+116
@@ -0,0 +1,116 @@
|
||||
version: "2"
|
||||
|
||||
formatters:
|
||||
enable:
|
||||
- gofumpt
|
||||
- goimports
|
||||
settings:
|
||||
gofumpt:
|
||||
extra-rules: true
|
||||
|
||||
linters:
|
||||
enable:
|
||||
- asasalint
|
||||
- bidichk
|
||||
- dogsled
|
||||
- dupword
|
||||
- durationcheck
|
||||
- err113
|
||||
- errname
|
||||
- errorlint
|
||||
- fatcontext
|
||||
- forbidigo
|
||||
- gocheckcompilerdirectives
|
||||
- gochecknoinits
|
||||
- gocritic
|
||||
- godot
|
||||
- godox
|
||||
- goheader
|
||||
- gomoddirectives
|
||||
- goprintffuncname
|
||||
- gosec
|
||||
- inamedparam
|
||||
- interfacebloat
|
||||
- ireturn
|
||||
- mirror
|
||||
- misspell
|
||||
- nolintlint
|
||||
- revive
|
||||
- staticcheck
|
||||
- testifylint
|
||||
- thelper
|
||||
- unconvert
|
||||
- unparam
|
||||
- usestdlibvars
|
||||
- whitespace
|
||||
- wsl_v5
|
||||
settings:
|
||||
gocritic:
|
||||
disabled-checks:
|
||||
- paramTypeCombine # already handle by gofumpt.extra-rules
|
||||
- whyNoLint # already handle by nonolint
|
||||
- unnamedResult
|
||||
- hugeParam
|
||||
- sloppyReassign
|
||||
- rangeValCopy
|
||||
- octalLiteral
|
||||
- ptrToRefParam
|
||||
- appendAssign
|
||||
- ruleguard
|
||||
- httpNoBody
|
||||
- exposedSyncMutex
|
||||
enabled-tags:
|
||||
- diagnostic
|
||||
- style
|
||||
- performance
|
||||
godox:
|
||||
keywords:
|
||||
- FIXME
|
||||
goheader:
|
||||
template: |-
|
||||
Copyright 2015 Tim Heckman. All rights reserved.
|
||||
Copyright 2018-{{ YEAR }} The Gofrs. All rights reserved.
|
||||
Use of this source code is governed by the BSD 3-Clause
|
||||
license that can be found in the LICENSE file.
|
||||
gosec:
|
||||
excludes:
|
||||
- G115
|
||||
misspell:
|
||||
locale: US
|
||||
revive:
|
||||
rules:
|
||||
- name: struct-tag
|
||||
- name: blank-imports
|
||||
- name: context-as-argument
|
||||
- name: context-keys-type
|
||||
- name: dot-imports
|
||||
- name: error-return
|
||||
- name: error-strings
|
||||
- name: error-naming
|
||||
- name: exported
|
||||
- name: if-return
|
||||
- name: increment-decrement
|
||||
- name: var-naming
|
||||
- name: var-declaration
|
||||
- name: package-comments
|
||||
- name: range
|
||||
- name: receiver-naming
|
||||
- name: time-naming
|
||||
- name: unexported-return
|
||||
- name: indent-error-flow
|
||||
- name: errorf
|
||||
- name: empty-block
|
||||
- name: superfluous-else
|
||||
- name: unused-parameter
|
||||
- name: unreachable-code
|
||||
- name: redefines-builtin-id
|
||||
exclusions:
|
||||
presets:
|
||||
- comments
|
||||
- common-false-positives
|
||||
- std-error-handling
|
||||
|
||||
issues:
|
||||
max-issues-per-linter: 0
|
||||
max-same-issues: 0
|
||||
|
||||
+28
@@ -0,0 +1,28 @@
|
||||
Copyright (c) 2018-2025, The Gofrs
|
||||
Copyright (c) 2015-2020, Tim Heckman
|
||||
All rights reserved.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without
|
||||
modification, are permitted provided that the following conditions are met:
|
||||
|
||||
* Redistributions of source code must retain the above copyright notice, this
|
||||
list of conditions and the following disclaimer.
|
||||
|
||||
* Redistributions in binary form must reproduce the above copyright notice,
|
||||
this list of conditions and the following disclaimer in the documentation
|
||||
and/or other materials provided with the distribution.
|
||||
|
||||
* Neither the name of gofrs nor the names of its contributors may be used
|
||||
to endorse or promote products derived from this software without
|
||||
specific prior written permission.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
||||
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
||||
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
||||
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
.PHONY: lint test test_race build_cross_os
|
||||
|
||||
default: lint test build_cross_os
|
||||
|
||||
test:
|
||||
go test -v -cover ./...
|
||||
|
||||
test_race:
|
||||
CGO_ENABLED=1 go test -v -race ./...
|
||||
|
||||
lint:
|
||||
golangci-lint run
|
||||
|
||||
build_cross_os:
|
||||
./build.sh
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
# flock
|
||||
|
||||
[](https://pkg.go.dev/github.com/gofrs/flock)
|
||||
[](https://github.com/gofrs/flock/blob/main/LICENSE)
|
||||
[](https://goreportcard.com/report/github.com/gofrs/flock)
|
||||
|
||||
`flock` implements a thread-safe file lock.
|
||||
|
||||
It also includes a non-blocking `TryLock()` function to allow locking without blocking execution.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
go get -u github.com/gofrs/flock
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```go
|
||||
import "github.com/gofrs/flock"
|
||||
|
||||
fileLock := flock.New("/var/lock/go-lock.lock")
|
||||
|
||||
locked, err := fileLock.TryLock()
|
||||
|
||||
if err != nil {
|
||||
// handle locking error
|
||||
}
|
||||
|
||||
if locked {
|
||||
// do work
|
||||
fileLock.Unlock()
|
||||
}
|
||||
```
|
||||
|
||||
For more detailed usage information take a look at the package API docs on
|
||||
[GoDoc](https://pkg.go.dev/github.com/gofrs/flock).
|
||||
|
||||
## License
|
||||
|
||||
`flock` is released under the BSD 3-Clause License. See the [`LICENSE`](./LICENSE) file for more details.
|
||||
|
||||
## Project History
|
||||
|
||||
This project was originally `github.com/theckman/go-flock`, it was transferred to Gofrs by the original author [Tim Heckman ](https://github.com/theckman).
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
# Security Policy
|
||||
|
||||
## Supported Versions
|
||||
|
||||
We support the latest version of this library.
|
||||
We do not guarantee support of previous versions.
|
||||
|
||||
If a defect is reported, it will generally be fixed on the latest version (provided it exists) irrespective of whether it was introduced in a prior version.
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
To report a potential security vulnerability, please create a [security advisory](https://github.com/gofrs/flock/security/advisories/new).
|
||||
|
||||
For us to respond to your report most effectively, please include any of the following:
|
||||
|
||||
- Steps to reproduce or a proof-of-concept
|
||||
- Any relevant information, including the versions used
|
||||
|
||||
## Security Scorecard
|
||||
|
||||
This project submits security [results](https://scorecard.dev/viewer/?uri=github.com/gofrs/flock) to the [OpenSSF Scorecard](https://securityscorecards.dev/).
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
#!/bin/bash -e
|
||||
|
||||
# Not supported by flock:
|
||||
# - plan9/*
|
||||
# - js/wasm
|
||||
# - wasp1/wasm
|
||||
|
||||
for row in $(go tool dist list -json | jq -r '.[] | @base64'); do
|
||||
_jq() {
|
||||
echo ${row} | base64 --decode | jq -r ${1}
|
||||
}
|
||||
|
||||
GOOS=$(_jq '.GOOS')
|
||||
GOARCH=$(_jq '.GOARCH')
|
||||
|
||||
echo "$GOOS/$GOARCH"
|
||||
GOOS=$GOOS GOARCH=$GOARCH go build
|
||||
done
|
||||
+222
@@ -0,0 +1,222 @@
|
||||
// Copyright 2015 Tim Heckman. All rights reserved.
|
||||
// Copyright 2018-2025 The Gofrs. All rights reserved.
|
||||
// Use of this source code is governed by the BSD 3-Clause
|
||||
// license that can be found in the LICENSE file.
|
||||
|
||||
// Package flock implements a thread-safe interface for file locking.
|
||||
// It also includes a non-blocking TryLock() function to allow locking
|
||||
// without blocking execution.
|
||||
//
|
||||
// Package flock is released under the BSD 3-Clause License. See the LICENSE file
|
||||
// for more details.
|
||||
//
|
||||
// While using this library, remember that the locking behaviors are not
|
||||
// guaranteed to be the same on each platform. For example, some UNIX-like
|
||||
// operating systems will transparently convert a shared lock to an exclusive
|
||||
// lock. If you Unlock() the flock from a location where you believe that you
|
||||
// have the shared lock, you may accidentally drop the exclusive lock.
|
||||
package flock
|
||||
|
||||
import (
|
||||
"context"
|
||||
"io/fs"
|
||||
"os"
|
||||
"runtime"
|
||||
"sync"
|
||||
"time"
|
||||
)
|
||||
|
||||
type Option func(f *Flock)
|
||||
|
||||
// SetFlag sets the flag used to create/open the file.
|
||||
func SetFlag(flag int) Option {
|
||||
return func(f *Flock) {
|
||||
f.flag = flag
|
||||
}
|
||||
}
|
||||
|
||||
// SetPermissions sets the OS permissions to set on the file.
|
||||
func SetPermissions(perm fs.FileMode) Option {
|
||||
return func(f *Flock) {
|
||||
f.perm = perm
|
||||
}
|
||||
}
|
||||
|
||||
// Flock is the struct type to handle file locking. All fields are unexported,
|
||||
// with access to some of the fields provided by getter methods (Path() and Locked()).
|
||||
type Flock struct {
|
||||
path string
|
||||
m sync.RWMutex
|
||||
fh *os.File
|
||||
l bool
|
||||
r bool
|
||||
|
||||
// flag is the flag used to create/open the file.
|
||||
flag int
|
||||
// perm is the OS permissions to set on the file.
|
||||
perm fs.FileMode
|
||||
}
|
||||
|
||||
// New returns a new instance of *Flock. The only parameter
|
||||
// it takes is the path to the desired lockfile.
|
||||
func New(path string, opts ...Option) *Flock {
|
||||
// create it if it doesn't exist, and open the file read-only.
|
||||
flags := os.O_CREATE
|
||||
|
||||
switch runtime.GOOS {
|
||||
case "aix", "solaris", "illumos":
|
||||
// AIX cannot preform write-lock (i.e. exclusive) on a read-only file.
|
||||
flags |= os.O_RDWR
|
||||
default:
|
||||
flags |= os.O_RDONLY
|
||||
}
|
||||
|
||||
f := &Flock{
|
||||
path: path,
|
||||
flag: flags,
|
||||
perm: fs.FileMode(0o600),
|
||||
}
|
||||
|
||||
for _, opt := range opts {
|
||||
opt(f)
|
||||
}
|
||||
|
||||
return f
|
||||
}
|
||||
|
||||
// NewFlock returns a new instance of *Flock. The only parameter
|
||||
// it takes is the path to the desired lockfile.
|
||||
//
|
||||
// Deprecated: Use New instead.
|
||||
func NewFlock(path string) *Flock {
|
||||
return New(path)
|
||||
}
|
||||
|
||||
// Close is equivalent to calling Unlock.
|
||||
//
|
||||
// This will release the lock and close the underlying file descriptor.
|
||||
// It will not remove the file from disk, that's up to your application.
|
||||
func (f *Flock) Close() error {
|
||||
return f.Unlock()
|
||||
}
|
||||
|
||||
// Path returns the path as provided in NewFlock().
|
||||
func (f *Flock) Path() string {
|
||||
return f.path
|
||||
}
|
||||
|
||||
// Locked returns the lock state (locked: true, unlocked: false).
|
||||
//
|
||||
// Warning: by the time you use the returned value, the state may have changed.
|
||||
func (f *Flock) Locked() bool {
|
||||
f.m.RLock()
|
||||
defer f.m.RUnlock()
|
||||
|
||||
return f.l
|
||||
}
|
||||
|
||||
// RLocked returns the read lock state (locked: true, unlocked: false).
|
||||
//
|
||||
// Warning: by the time you use the returned value, the state may have changed.
|
||||
func (f *Flock) RLocked() bool {
|
||||
f.m.RLock()
|
||||
defer f.m.RUnlock()
|
||||
|
||||
return f.r
|
||||
}
|
||||
|
||||
// Stat returns the FileInfo structure describing the lock file.
|
||||
// If the lock file does not exist or cannot be accessed, an error is returned.
|
||||
//
|
||||
// This can be used to check the modification time of the lock file,
|
||||
// which is useful for detecting stale locks.
|
||||
func (f *Flock) Stat() (fs.FileInfo, error) {
|
||||
f.m.RLock()
|
||||
defer f.m.RUnlock()
|
||||
|
||||
if f.fh != nil {
|
||||
return f.fh.Stat()
|
||||
}
|
||||
|
||||
return os.Stat(f.path)
|
||||
}
|
||||
|
||||
func (f *Flock) String() string {
|
||||
return f.path
|
||||
}
|
||||
|
||||
// TryLockContext repeatedly tries to take an exclusive lock until one of the conditions is met:
|
||||
// - TryLock succeeds
|
||||
// - TryLock fails with error
|
||||
// - Context Done channel is closed.
|
||||
func (f *Flock) TryLockContext(ctx context.Context, retryDelay time.Duration) (bool, error) {
|
||||
return tryCtx(ctx, f.TryLock, retryDelay)
|
||||
}
|
||||
|
||||
// TryRLockContext repeatedly tries to take a shared lock until one of the conditions is met:
|
||||
// - TryRLock succeeds
|
||||
// - TryRLock fails with error
|
||||
// - Context Done channel is closed.
|
||||
func (f *Flock) TryRLockContext(ctx context.Context, retryDelay time.Duration) (bool, error) {
|
||||
return tryCtx(ctx, f.TryRLock, retryDelay)
|
||||
}
|
||||
|
||||
func tryCtx(ctx context.Context, fn func() (bool, error), retryDelay time.Duration) (bool, error) {
|
||||
if ctx.Err() != nil {
|
||||
return false, ctx.Err()
|
||||
}
|
||||
|
||||
for {
|
||||
if ok, err := fn(); ok || err != nil {
|
||||
return ok, err
|
||||
}
|
||||
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
return false, ctx.Err()
|
||||
case <-time.After(retryDelay):
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func (f *Flock) setFh(flag int) error {
|
||||
// open a new os.File instance
|
||||
fh, err := os.OpenFile(f.path, flag, f.perm)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// set the file handle on the struct
|
||||
f.fh = fh
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// resetFh resets file handle:
|
||||
// - tries to close the file (ignore errors)
|
||||
// - sets fh to nil.
|
||||
func (f *Flock) resetFh() {
|
||||
if f.fh == nil {
|
||||
return
|
||||
}
|
||||
|
||||
_ = f.fh.Close()
|
||||
|
||||
f.fh = nil
|
||||
}
|
||||
|
||||
// ensure the file handle is closed if no lock is held.
|
||||
func (f *Flock) ensureFhState() {
|
||||
if f.l || f.r || f.fh == nil {
|
||||
return
|
||||
}
|
||||
|
||||
f.resetFh()
|
||||
}
|
||||
|
||||
func (f *Flock) reset() {
|
||||
f.l = false
|
||||
f.r = false
|
||||
|
||||
f.resetFh()
|
||||
}
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
// Copyright 2015 Tim Heckman. All rights reserved.
|
||||
// Copyright 2018-2025 The Gofrs. All rights reserved.
|
||||
// Use of this source code is governed by the BSD 3-Clause
|
||||
// license that can be found in the LICENSE file.
|
||||
|
||||
//go:build (!unix && !windows) || plan9
|
||||
|
||||
package flock
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"io/fs"
|
||||
)
|
||||
|
||||
func (f *Flock) Lock() error {
|
||||
return &fs.PathError{
|
||||
Op: "Lock",
|
||||
Path: f.Path(),
|
||||
Err: errors.ErrUnsupported,
|
||||
}
|
||||
}
|
||||
|
||||
func (f *Flock) RLock() error {
|
||||
return &fs.PathError{
|
||||
Op: "RLock",
|
||||
Path: f.Path(),
|
||||
Err: errors.ErrUnsupported,
|
||||
}
|
||||
}
|
||||
|
||||
func (f *Flock) Unlock() error {
|
||||
return &fs.PathError{
|
||||
Op: "Unlock",
|
||||
Path: f.Path(),
|
||||
Err: errors.ErrUnsupported,
|
||||
}
|
||||
}
|
||||
|
||||
func (f *Flock) TryLock() (bool, error) {
|
||||
return false, f.Lock()
|
||||
}
|
||||
|
||||
func (f *Flock) TryRLock() (bool, error) {
|
||||
return false, f.RLock()
|
||||
}
|
||||
+211
@@ -0,0 +1,211 @@
|
||||
// Copyright 2015 Tim Heckman. All rights reserved.
|
||||
// Copyright 2018-2025 The Gofrs. All rights reserved.
|
||||
// Use of this source code is governed by the BSD 3-Clause
|
||||
// license that can be found in the LICENSE file.
|
||||
|
||||
//go:build darwin || dragonfly || freebsd || illumos || linux || netbsd || openbsd
|
||||
|
||||
package flock
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"os"
|
||||
|
||||
"golang.org/x/sys/unix"
|
||||
)
|
||||
|
||||
// Lock is a blocking call to try and take an exclusive file lock.
|
||||
// It will wait until it is able to obtain the exclusive file lock.
|
||||
// It's recommended that TryLock() be used over this function.
|
||||
// This function may block the ability to query the current Locked() or RLocked() status due to a RW-mutex lock.
|
||||
//
|
||||
// If we are already exclusive-locked,
|
||||
// this function short-circuits and returns immediately assuming it can take the mutex lock.
|
||||
//
|
||||
// If the *Flock has a shared lock (RLock),
|
||||
// this may transparently replace the shared lock with an exclusive lock on some UNIX-like operating systems.
|
||||
// Be careful when using exclusive locks in conjunction with shared locks (RLock()),
|
||||
// because calling Unlock() may accidentally release the exclusive lock that was once a shared lock.
|
||||
func (f *Flock) Lock() error {
|
||||
return f.lock(&f.l, unix.LOCK_EX)
|
||||
}
|
||||
|
||||
// RLock is a blocking call to try and take a shared file lock.
|
||||
// It will wait until it is able to obtain the shared file lock.
|
||||
// It's recommended that TryRLock() be used over this function.
|
||||
// This function may block the ability to query the current Locked() or RLocked() status due to a RW-mutex lock.
|
||||
//
|
||||
// If we are already shared-locked,
|
||||
// this function short-circuits and returns immediately assuming it can take the mutex lock.
|
||||
func (f *Flock) RLock() error {
|
||||
return f.lock(&f.r, unix.LOCK_SH)
|
||||
}
|
||||
|
||||
func (f *Flock) lock(locked *bool, flag int) error {
|
||||
f.m.Lock()
|
||||
defer f.m.Unlock()
|
||||
|
||||
if *locked {
|
||||
return nil
|
||||
}
|
||||
|
||||
if f.fh == nil {
|
||||
if err := f.setFh(f.flag); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
defer f.ensureFhState()
|
||||
}
|
||||
|
||||
err := unix.Flock(int(f.fh.Fd()), flag)
|
||||
if err != nil {
|
||||
shouldRetry, reopenErr := f.reopenFDOnError(err)
|
||||
if reopenErr != nil {
|
||||
return reopenErr
|
||||
}
|
||||
|
||||
if !shouldRetry {
|
||||
return err
|
||||
}
|
||||
|
||||
err = unix.Flock(int(f.fh.Fd()), flag)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
*locked = true
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// Unlock is a function to unlock the file.
|
||||
// This file takes a RW-mutex lock,
|
||||
// so while it is running the Locked() and RLocked() functions will be blocked.
|
||||
//
|
||||
// This function short-circuits if we are unlocked already.
|
||||
// If not, it calls unix.LOCK_UN on the file and closes the file descriptor.
|
||||
// It does not remove the file from disk. It's up to your application to do.
|
||||
//
|
||||
// Please note,
|
||||
// if your shared lock became an exclusive lock,
|
||||
// this may unintentionally drop the exclusive lock if called by the consumer that believes they have a shared lock.
|
||||
// Please see Lock() for more details.
|
||||
func (f *Flock) Unlock() error {
|
||||
f.m.Lock()
|
||||
defer f.m.Unlock()
|
||||
|
||||
// If we aren't locked or if the lockfile instance is nil
|
||||
// just return a nil error because we are unlocked.
|
||||
if (!f.l && !f.r) || f.fh == nil {
|
||||
return nil
|
||||
}
|
||||
|
||||
// Mark the file as unlocked.
|
||||
err := unix.Flock(int(f.fh.Fd()), unix.LOCK_UN)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
f.reset()
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// TryLock is the preferred function for taking an exclusive file lock.
|
||||
// This function takes an RW-mutex lock before it tries to lock the file,
|
||||
// so there is the possibility that this function may block for a short time
|
||||
// if another goroutine is trying to take any action.
|
||||
//
|
||||
// The actual file lock is non-blocking.
|
||||
// If we are unable to get the exclusive file lock,
|
||||
// the function will return false instead of waiting for the lock.
|
||||
// If we get the lock, we also set the *Flock instance as being exclusive-locked.
|
||||
func (f *Flock) TryLock() (bool, error) {
|
||||
return f.try(&f.l, unix.LOCK_EX)
|
||||
}
|
||||
|
||||
// TryRLock is the preferred function for taking a shared file lock.
|
||||
// This function takes an RW-mutex lock before it tries to lock the file,
|
||||
// so there is the possibility that this function may block for a short time
|
||||
// if another goroutine is trying to take any action.
|
||||
//
|
||||
// The actual file lock is non-blocking.
|
||||
// If we are unable to get the shared file lock,
|
||||
// the function will return false instead of waiting for the lock.
|
||||
// If we get the lock, we also set the *Flock instance as being share-locked.
|
||||
func (f *Flock) TryRLock() (bool, error) {
|
||||
return f.try(&f.r, unix.LOCK_SH)
|
||||
}
|
||||
|
||||
func (f *Flock) try(locked *bool, flag int) (bool, error) {
|
||||
f.m.Lock()
|
||||
defer f.m.Unlock()
|
||||
|
||||
if *locked {
|
||||
return true, nil
|
||||
}
|
||||
|
||||
if f.fh == nil {
|
||||
if err := f.setFh(f.flag); err != nil {
|
||||
return false, err
|
||||
}
|
||||
|
||||
defer f.ensureFhState()
|
||||
}
|
||||
|
||||
var retried bool
|
||||
|
||||
retry:
|
||||
err := unix.Flock(int(f.fh.Fd()), flag|unix.LOCK_NB)
|
||||
|
||||
switch {
|
||||
case errors.Is(err, unix.EWOULDBLOCK):
|
||||
return false, nil
|
||||
case err == nil:
|
||||
*locked = true
|
||||
return true, nil
|
||||
}
|
||||
|
||||
if !retried {
|
||||
shouldRetry, reopenErr := f.reopenFDOnError(err)
|
||||
if reopenErr != nil {
|
||||
return false, reopenErr
|
||||
} else if shouldRetry {
|
||||
retried = true
|
||||
goto retry
|
||||
}
|
||||
}
|
||||
|
||||
return false, err
|
||||
}
|
||||
|
||||
// reopenFDOnError determines whether we should reopen the file handle in readwrite mode and try again.
|
||||
// This comes from `util-linux/sys-utils/flock.c`:
|
||||
// > Since Linux 3.4 (commit 55725513)
|
||||
// > Probably NFSv4 where flock() is emulated by fcntl().
|
||||
// > https://github.com/util-linux/util-linux/blob/198e920aa24743ef6ace4e07cf6237de527f9261/sys-utils/flock.c#L374-L390
|
||||
func (f *Flock) reopenFDOnError(err error) (bool, error) {
|
||||
if !errors.Is(err, unix.EIO) && !errors.Is(err, unix.EBADF) {
|
||||
return false, nil
|
||||
}
|
||||
|
||||
st, err := f.fh.Stat()
|
||||
if err != nil {
|
||||
return false, nil
|
||||
}
|
||||
|
||||
if st.Mode()&f.perm != f.perm {
|
||||
return false, nil
|
||||
}
|
||||
|
||||
f.resetFh()
|
||||
|
||||
// reopen in read-write mode and set the file handle
|
||||
err = f.setFh(f.flag | os.O_RDWR)
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
|
||||
return true, nil
|
||||
}
|
||||
+393
@@ -0,0 +1,393 @@
|
||||
// Copyright 2015 Tim Heckman. All rights reserved.
|
||||
// Copyright 2018-2025 The Gofrs. All rights reserved.
|
||||
// Use of this source code is governed by the BSD 3-Clause
|
||||
// license that can be found in the LICENSE file.
|
||||
|
||||
// Copyright 2018 The Go Authors. All rights reserved.
|
||||
// Use of this source code is governed by a BSD-style
|
||||
// license that can be found in the LICENSE file.
|
||||
|
||||
// This code implements the filelock API using POSIX 'fcntl' locks,
|
||||
// which attach to an (inode, process) pair rather than a file descriptor.
|
||||
// To avoid unlocking files prematurely when the same file is opened through different descriptors,
|
||||
// we allow only one read-lock at a time.
|
||||
//
|
||||
// This code is adapted from the Go package (go.22):
|
||||
// https://github.com/golang/go/blob/release-branch.go1.22/src/cmd/go/internal/lockedfile/internal/filelock/filelock_fcntl.go
|
||||
|
||||
//go:build aix || (solaris && !illumos)
|
||||
|
||||
package flock
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"io"
|
||||
"io/fs"
|
||||
"math/rand"
|
||||
"sync"
|
||||
"syscall"
|
||||
"time"
|
||||
|
||||
"golang.org/x/sys/unix"
|
||||
)
|
||||
|
||||
// https://github.com/golang/go/blob/09aeb6e33ab426eff4676a3baf694d5a3019e9fc/src/cmd/go/internal/lockedfile/internal/filelock/filelock_fcntl.go#L28
|
||||
type lockType int16
|
||||
|
||||
// String returns the name of the function corresponding to lt
|
||||
// (Lock, RLock, or Unlock).
|
||||
// https://github.com/golang/go/blob/09aeb6e33ab426eff4676a3baf694d5a3019e9fc/src/cmd/go/internal/lockedfile/internal/filelock/filelock.go#L67
|
||||
func (lt lockType) String() string {
|
||||
switch lt {
|
||||
case readLock:
|
||||
return "RLock"
|
||||
case writeLock:
|
||||
return "Lock"
|
||||
default:
|
||||
return "Unlock"
|
||||
}
|
||||
}
|
||||
|
||||
// https://github.com/golang/go/blob/09aeb6e33ab426eff4676a3baf694d5a3019e9fc/src/cmd/go/internal/lockedfile/internal/filelock/filelock_fcntl.go#L30-L33
|
||||
const (
|
||||
readLock lockType = unix.F_RDLCK
|
||||
writeLock lockType = unix.F_WRLCK
|
||||
)
|
||||
|
||||
// https://github.com/golang/go/blob/09aeb6e33ab426eff4676a3baf694d5a3019e9fc/src/cmd/go/internal/lockedfile/internal/filelock/filelock_fcntl.go#L35
|
||||
type inode = uint64
|
||||
|
||||
// https://github.com/golang/go/blob/09aeb6e33ab426eff4676a3baf694d5a3019e9fc/src/cmd/go/internal/lockedfile/internal/filelock/filelock_fcntl.go#L37-L40
|
||||
type inodeLock struct {
|
||||
owner *Flock
|
||||
queue []<-chan *Flock
|
||||
}
|
||||
|
||||
type cmdType int
|
||||
|
||||
const (
|
||||
tryLock cmdType = unix.F_SETLK
|
||||
waitLock cmdType = unix.F_SETLKW
|
||||
)
|
||||
|
||||
var (
|
||||
mu sync.Mutex
|
||||
inodes = map[*Flock]inode{}
|
||||
locks = map[inode]inodeLock{}
|
||||
)
|
||||
|
||||
// Lock is a blocking call to try and take an exclusive file lock.
|
||||
// It will wait until it is able to obtain the exclusive file lock.
|
||||
// It's recommended that TryLock() be used over this function.
|
||||
// This function may block the ability to query the current Locked() or RLocked() status due to a RW-mutex lock.
|
||||
//
|
||||
// If we are already exclusive-locked, this function short-circuits and
|
||||
// returns immediately assuming it can take the mutex lock.
|
||||
//
|
||||
// If the *Flock has a shared lock (RLock),
|
||||
// this may transparently replace the shared lock with an exclusive lock on some UNIX-like operating systems.
|
||||
// Be careful when using exclusive locks in conjunction with shared locks (RLock()),
|
||||
// because calling Unlock() may accidentally release the exclusive lock that was once a shared lock.
|
||||
func (f *Flock) Lock() error {
|
||||
return f.lock(&f.l, writeLock)
|
||||
}
|
||||
|
||||
// RLock is a blocking call to try and take a shared file lock.
|
||||
// It will wait until it is able to obtain the shared file lock.
|
||||
// It's recommended that TryRLock() be used over this function.
|
||||
// This function may block the ability to query the current Locked() or RLocked() status due to a RW-mutex lock.
|
||||
//
|
||||
// If we are already shared-locked, this function short-circuits and
|
||||
// returns immediately assuming it can take the mutex lock.
|
||||
func (f *Flock) RLock() error {
|
||||
return f.lock(&f.r, readLock)
|
||||
}
|
||||
|
||||
func (f *Flock) lock(locked *bool, flag lockType) error {
|
||||
f.m.Lock()
|
||||
defer f.m.Unlock()
|
||||
|
||||
if *locked {
|
||||
return nil
|
||||
}
|
||||
|
||||
if f.fh == nil {
|
||||
if err := f.setFh(f.flag); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
defer f.ensureFhState()
|
||||
}
|
||||
|
||||
_, err := f.doLock(waitLock, flag, true)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
*locked = true
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// https://github.com/golang/go/blob/09aeb6e33ab426eff4676a3baf694d5a3019e9fc/src/cmd/go/internal/lockedfile/internal/filelock/filelock_fcntl.go#L48
|
||||
func (f *Flock) doLock(cmd cmdType, lt lockType, blocking bool) (bool, error) {
|
||||
// POSIX locks apply per inode and process,
|
||||
// and the lock for an inode is released when *any* descriptor for that inode is closed.
|
||||
// So we need to synchronize access to each inode internally,
|
||||
// and must serialize lock and unlock calls that refer to the same inode through different descriptors.
|
||||
fi, err := f.fh.Stat()
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
|
||||
// Note(ldez): don't replace `syscall.Stat_t` by `unix.Stat_t` because `FileInfo.Sys()` returns `syscall.Stat_t`
|
||||
ino := fi.Sys().(*syscall.Stat_t).Ino
|
||||
|
||||
mu.Lock()
|
||||
|
||||
if i, dup := inodes[f]; dup && i != ino {
|
||||
mu.Unlock()
|
||||
return false, &fs.PathError{
|
||||
Op: lt.String(),
|
||||
Path: f.Path(),
|
||||
Err: errors.New("inode for file changed since last Lock or RLock"),
|
||||
}
|
||||
}
|
||||
|
||||
inodes[f] = ino
|
||||
|
||||
var wait chan *Flock
|
||||
|
||||
l := locks[ino]
|
||||
|
||||
switch {
|
||||
case l.owner == f:
|
||||
// This file already owns the lock, but the call may change its lock type.
|
||||
case l.owner == nil:
|
||||
// No owner: it's ours now.
|
||||
l.owner = f
|
||||
|
||||
case !blocking:
|
||||
// Already owned: cannot take the lock.
|
||||
mu.Unlock()
|
||||
return false, nil
|
||||
|
||||
default:
|
||||
// Already owned: add a channel to wait on.
|
||||
wait = make(chan *Flock)
|
||||
l.queue = append(l.queue, wait)
|
||||
}
|
||||
|
||||
locks[ino] = l
|
||||
|
||||
mu.Unlock()
|
||||
|
||||
if wait != nil {
|
||||
wait <- f
|
||||
}
|
||||
|
||||
// Spurious EDEADLK errors arise on platforms that compute deadlock graphs at
|
||||
// the process, rather than thread, level. Consider processes P and Q, with
|
||||
// threads P.1, P.2, and Q.3. The following trace is NOT a deadlock, but will be
|
||||
// reported as a deadlock on systems that consider only process granularity:
|
||||
//
|
||||
// P.1 locks file A.
|
||||
// Q.3 locks file B.
|
||||
// Q.3 blocks on file A.
|
||||
// P.2 blocks on file B. (This is erroneously reported as a deadlock.)
|
||||
// P.1 unlocks file A.
|
||||
// Q.3 unblocks and locks file A.
|
||||
// Q.3 unlocks files A and B.
|
||||
// P.2 unblocks and locks file B.
|
||||
// P.2 unlocks file B.
|
||||
//
|
||||
// These spurious errors were observed in practice on AIX and Solaris in
|
||||
// cmd/go: see https://golang.org/issue/32817.
|
||||
//
|
||||
// We work around this bug by treating EDEADLK as always spurious. If there
|
||||
// really is a lock-ordering bug between the interacting processes, it will
|
||||
// become a livelock instead, but that's not appreciably worse than if we had
|
||||
// a proper flock implementation (which generally does not even attempt to
|
||||
// diagnose deadlocks).
|
||||
//
|
||||
// In the above example, that changes the trace to:
|
||||
//
|
||||
// P.1 locks file A.
|
||||
// Q.3 locks file B.
|
||||
// Q.3 blocks on file A.
|
||||
// P.2 spuriously fails to lock file B and goes to sleep.
|
||||
// P.1 unlocks file A.
|
||||
// Q.3 unblocks and locks file A.
|
||||
// Q.3 unlocks files A and B.
|
||||
// P.2 wakes up and locks file B.
|
||||
// P.2 unlocks file B.
|
||||
//
|
||||
// We know that the retry loop will not introduce a *spurious* livelock
|
||||
// because, according to the POSIX specification, EDEADLK is only to be
|
||||
// returned when “the lock is blocked by a lock from another process”.
|
||||
// If that process is blocked on some lock that we are holding, then the
|
||||
// resulting livelock is due to a real deadlock (and would manifest as such
|
||||
// when using, for example, the flock implementation of this package).
|
||||
// If the other process is *not* blocked on some other lock that we are
|
||||
// holding, then it will eventually release the requested lock.
|
||||
|
||||
nextSleep := 1 * time.Millisecond
|
||||
const maxSleep = 500 * time.Millisecond
|
||||
for {
|
||||
err = setlkw(f.fh.Fd(), cmd, lt)
|
||||
if !errors.Is(err, unix.EDEADLK) {
|
||||
break
|
||||
}
|
||||
|
||||
time.Sleep(nextSleep)
|
||||
|
||||
nextSleep += nextSleep
|
||||
if nextSleep > maxSleep {
|
||||
nextSleep = maxSleep
|
||||
}
|
||||
// Apply 10% jitter to avoid synchronizing collisions when we finally unblock.
|
||||
nextSleep += time.Duration((0.1*rand.Float64() - 0.05) * float64(nextSleep))
|
||||
}
|
||||
|
||||
if err != nil {
|
||||
f.doUnlock()
|
||||
|
||||
if cmd == tryLock && errors.Is(err, unix.EACCES) {
|
||||
return false, nil
|
||||
}
|
||||
|
||||
return false, &fs.PathError{
|
||||
Op: lt.String(),
|
||||
Path: f.Path(),
|
||||
Err: err,
|
||||
}
|
||||
}
|
||||
|
||||
return true, nil
|
||||
}
|
||||
|
||||
func (f *Flock) Unlock() error {
|
||||
f.m.Lock()
|
||||
defer f.m.Unlock()
|
||||
|
||||
// If we aren't locked or if the lockfile instance is nil
|
||||
// just return a nil error because we are unlocked.
|
||||
if (!f.l && !f.r) || f.fh == nil {
|
||||
return nil
|
||||
}
|
||||
|
||||
if err := f.doUnlock(); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
f.reset()
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// https://github.com/golang/go/blob/09aeb6e33ab426eff4676a3baf694d5a3019e9fc/src/cmd/go/internal/lockedfile/internal/filelock/filelock_fcntl.go#L163
|
||||
func (f *Flock) doUnlock() (err error) {
|
||||
var owner *Flock
|
||||
|
||||
mu.Lock()
|
||||
|
||||
ino, ok := inodes[f]
|
||||
if ok {
|
||||
owner = locks[ino].owner
|
||||
}
|
||||
|
||||
mu.Unlock()
|
||||
|
||||
if owner == f {
|
||||
err = setlkw(f.fh.Fd(), waitLock, unix.F_UNLCK)
|
||||
}
|
||||
|
||||
mu.Lock()
|
||||
|
||||
l := locks[ino]
|
||||
|
||||
if len(l.queue) == 0 {
|
||||
// No waiters: remove the map entry.
|
||||
delete(locks, ino)
|
||||
} else {
|
||||
// The first waiter is sending us their file now.
|
||||
// Receive it and update the queue.
|
||||
l.owner = <-l.queue[0]
|
||||
l.queue = l.queue[1:]
|
||||
locks[ino] = l
|
||||
}
|
||||
|
||||
delete(inodes, f)
|
||||
|
||||
mu.Unlock()
|
||||
|
||||
return err
|
||||
}
|
||||
|
||||
// TryLock is the preferred function for taking an exclusive file lock.
|
||||
// This function takes an RW-mutex lock before it tries to lock the file,
|
||||
// so there is the possibility that this function may block for a short time
|
||||
// if another goroutine is trying to take any action.
|
||||
//
|
||||
// The actual file lock is non-blocking.
|
||||
// If we are unable to get the exclusive file lock,
|
||||
// the function will return false instead of waiting for the lock.
|
||||
// If we get the lock, we also set the *Flock instance as being exclusive-locked.
|
||||
func (f *Flock) TryLock() (bool, error) {
|
||||
return f.try(&f.l, writeLock)
|
||||
}
|
||||
|
||||
// TryRLock is the preferred function for taking a shared file lock.
|
||||
// This function takes an RW-mutex lock before it tries to lock the file,
|
||||
// so there is the possibility that this function may block for a short time
|
||||
// if another goroutine is trying to take any action.
|
||||
//
|
||||
// The actual file lock is non-blocking.
|
||||
// If we are unable to get the shared file lock,
|
||||
// the function will return false instead of waiting for the lock.
|
||||
// If we get the lock, we also set the *Flock instance as being share-locked.
|
||||
func (f *Flock) TryRLock() (bool, error) {
|
||||
return f.try(&f.r, readLock)
|
||||
}
|
||||
|
||||
func (f *Flock) try(locked *bool, flag lockType) (bool, error) {
|
||||
f.m.Lock()
|
||||
defer f.m.Unlock()
|
||||
|
||||
if *locked {
|
||||
return true, nil
|
||||
}
|
||||
|
||||
if f.fh == nil {
|
||||
if err := f.setFh(f.flag); err != nil {
|
||||
return false, err
|
||||
}
|
||||
|
||||
defer f.ensureFhState()
|
||||
}
|
||||
|
||||
hasLock, err := f.doLock(tryLock, flag, false)
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
|
||||
*locked = hasLock
|
||||
|
||||
return hasLock, nil
|
||||
}
|
||||
|
||||
// setlkw calls FcntlFlock with cmd for the entire file indicated by fd.
|
||||
// https://github.com/golang/go/blob/09aeb6e33ab426eff4676a3baf694d5a3019e9fc/src/cmd/go/internal/lockedfile/internal/filelock/filelock_fcntl.go#L198
|
||||
func setlkw(fd uintptr, cmd cmdType, lt lockType) error {
|
||||
for {
|
||||
err := unix.FcntlFlock(fd, int(cmd), &unix.Flock_t{
|
||||
Type: int16(lt),
|
||||
Whence: io.SeekStart,
|
||||
Start: 0,
|
||||
Len: 0, // All bytes.
|
||||
})
|
||||
if !errors.Is(err, unix.EINTR) {
|
||||
return err
|
||||
}
|
||||
}
|
||||
}
|
||||
+160
@@ -0,0 +1,160 @@
|
||||
// Copyright 2015 Tim Heckman. All rights reserved.
|
||||
// Copyright 2018-2025 The Gofrs. All rights reserved.
|
||||
// Use of this source code is governed by the BSD 3-Clause
|
||||
// license that can be found in the LICENSE file.
|
||||
|
||||
//go:build windows
|
||||
|
||||
package flock
|
||||
|
||||
import (
|
||||
"errors"
|
||||
|
||||
"golang.org/x/sys/windows"
|
||||
)
|
||||
|
||||
// Use of 0x00000000 for the shared lock is a guess based on some the MS Windows `LockFileEX` docs,
|
||||
// which document the `LOCKFILE_EXCLUSIVE_LOCK` flag as:
|
||||
//
|
||||
// > The function requests an exclusive lock. Otherwise, it requests a shared lock.
|
||||
//
|
||||
// https://msdn.microsoft.com/en-us/library/windows/desktop/aa365203(v=vs.85).aspx
|
||||
const winLockfileSharedLock = 0x00000000
|
||||
|
||||
// ErrorLockViolation is the error code returned from the Windows syscall when a lock would block,
|
||||
// and you ask to fail immediately.
|
||||
//
|
||||
//nolint:errname // It should be renamed to `ErrLockViolation`.
|
||||
const ErrorLockViolation windows.Errno = 0x21 // 33
|
||||
|
||||
// Lock is a blocking call to try and take an exclusive file lock.
|
||||
// It will wait until it is able to obtain the exclusive file lock.
|
||||
// It's recommended that TryLock() be used over this function.
|
||||
// This function may block the ability to query the current Locked() or RLocked() status due to a RW-mutex lock.
|
||||
//
|
||||
// If we are already locked, this function short-circuits and
|
||||
// returns immediately assuming it can take the mutex lock.
|
||||
func (f *Flock) Lock() error {
|
||||
return f.lock(&f.l, windows.LOCKFILE_EXCLUSIVE_LOCK)
|
||||
}
|
||||
|
||||
// RLock is a blocking call to try and take a shared file lock.
|
||||
// It will wait until it is able to obtain the shared file lock.
|
||||
// It's recommended that TryRLock() be used over this function.
|
||||
// This function may block the ability to query the current Locked() or RLocked() status due to a RW-mutex lock.
|
||||
//
|
||||
// If we are already locked, this function short-circuits and
|
||||
// returns immediately assuming it can take the mutex lock.
|
||||
func (f *Flock) RLock() error {
|
||||
return f.lock(&f.r, winLockfileSharedLock)
|
||||
}
|
||||
|
||||
func (f *Flock) lock(locked *bool, flag uint32) error {
|
||||
f.m.Lock()
|
||||
defer f.m.Unlock()
|
||||
|
||||
if *locked {
|
||||
return nil
|
||||
}
|
||||
|
||||
if f.fh == nil {
|
||||
if err := f.setFh(f.flag); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
defer f.ensureFhState()
|
||||
}
|
||||
|
||||
err := windows.LockFileEx(windows.Handle(f.fh.Fd()), flag, 0, 1, 0, &windows.Overlapped{})
|
||||
if err != nil && !errors.Is(err, windows.Errno(0)) {
|
||||
return err
|
||||
}
|
||||
|
||||
*locked = true
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// Unlock is a function to unlock the file.
|
||||
// This file takes a RW-mutex lock,
|
||||
// so while it is running the Locked() and RLocked() functions will be blocked.
|
||||
//
|
||||
// This function short-circuits if we are unlocked already.
|
||||
// If not, it calls UnlockFileEx() on the file and closes the file descriptor.
|
||||
// It does not remove the file from disk.
|
||||
// It's up to your application to do.
|
||||
func (f *Flock) Unlock() error {
|
||||
f.m.Lock()
|
||||
defer f.m.Unlock()
|
||||
|
||||
// if we aren't locked or if the lockfile instance is nil
|
||||
// just return a nil error because we are unlocked
|
||||
if (!f.l && !f.r) || f.fh == nil {
|
||||
return nil
|
||||
}
|
||||
|
||||
// mark the file as unlocked
|
||||
err := windows.UnlockFileEx(windows.Handle(f.fh.Fd()), 0, 1, 0, &windows.Overlapped{})
|
||||
if err != nil && !errors.Is(err, windows.Errno(0)) {
|
||||
return err
|
||||
}
|
||||
|
||||
f.reset()
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// TryLock is the preferred function for taking an exclusive file lock.
|
||||
// This function does take a RW-mutex lock before it tries to lock the file,
|
||||
// so there is the possibility that this function may block for a short time
|
||||
// if another goroutine is trying to take any action.
|
||||
//
|
||||
// The actual file lock is non-blocking.
|
||||
// If we are unable to get the exclusive file lock,
|
||||
// the function will return false instead of waiting for the lock.
|
||||
// If we get the lock, we also set the *Flock instance as being exclusive-locked.
|
||||
func (f *Flock) TryLock() (bool, error) {
|
||||
return f.try(&f.l, windows.LOCKFILE_EXCLUSIVE_LOCK)
|
||||
}
|
||||
|
||||
// TryRLock is the preferred function for taking a shared file lock.
|
||||
// This function does take a RW-mutex lock before it tries to lock the file,
|
||||
// so there is the possibility that this function may block for a short time if another goroutine is trying to take any action.
|
||||
//
|
||||
// The actual file lock is non-blocking.
|
||||
// If we are unable to get the shared file lock,
|
||||
// the function will return false instead of waiting for the lock.
|
||||
// If we get the lock, we also set the *Flock instance as being shared-locked.
|
||||
func (f *Flock) TryRLock() (bool, error) {
|
||||
return f.try(&f.r, winLockfileSharedLock)
|
||||
}
|
||||
|
||||
func (f *Flock) try(locked *bool, flag uint32) (bool, error) {
|
||||
f.m.Lock()
|
||||
defer f.m.Unlock()
|
||||
|
||||
if *locked {
|
||||
return true, nil
|
||||
}
|
||||
|
||||
if f.fh == nil {
|
||||
if err := f.setFh(f.flag); err != nil {
|
||||
return false, err
|
||||
}
|
||||
|
||||
defer f.ensureFhState()
|
||||
}
|
||||
|
||||
err := windows.LockFileEx(windows.Handle(f.fh.Fd()), flag|windows.LOCKFILE_FAIL_IMMEDIATELY, 0, 1, 0, &windows.Overlapped{})
|
||||
if err != nil && !errors.Is(err, windows.Errno(0)) {
|
||||
if errors.Is(err, ErrorLockViolation) || errors.Is(err, windows.ERROR_IO_PENDING) {
|
||||
return false, nil
|
||||
}
|
||||
|
||||
return false, err
|
||||
}
|
||||
|
||||
*locked = true
|
||||
|
||||
return true, nil
|
||||
}
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
# Binaries for programs and plugins
|
||||
*.exe
|
||||
*.exe~
|
||||
*.dll
|
||||
*.so
|
||||
*.dylib
|
||||
|
||||
# Test binary, build with `go test -c`
|
||||
*.test
|
||||
|
||||
# Output of the go coverage tool, specifically when used with LiteIDE
|
||||
*.out
|
||||
|
||||
# binary bundle generated by go-fuzz
|
||||
uuid-fuzz.zip
|
||||
+20
@@ -0,0 +1,20 @@
|
||||
Copyright (C) 2013-2018 by Maxim Bublis <b@codemonkey.ru>
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
"Software"), to deal in the Software without restriction, including
|
||||
without limitation the rights to use, copy, modify, merge, publish,
|
||||
distribute, sublicense, and/or sell copies of the Software, and to
|
||||
permit persons to whom the Software is furnished to do so, subject to
|
||||
the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be
|
||||
included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
||||
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
||||
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
||||
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
+117
@@ -0,0 +1,117 @@
|
||||
# UUID
|
||||
|
||||
[](https://github.com/gofrs/uuid/blob/master/LICENSE)
|
||||
[](https://travis-ci.org/gofrs/uuid)
|
||||
[](http://godoc.org/github.com/gofrs/uuid)
|
||||
[](https://codecov.io/gh/gofrs/uuid/)
|
||||
[](https://goreportcard.com/report/github.com/gofrs/uuid)
|
||||
|
||||
Package uuid provides a pure Go implementation of Universally Unique Identifiers
|
||||
(UUID) variant as defined in RFC-4122. This package supports both the creation
|
||||
and parsing of UUIDs in different formats.
|
||||
|
||||
This package supports the following UUID versions:
|
||||
* Version 1, based on timestamp and MAC address (RFC-4122)
|
||||
* Version 3, based on MD5 hashing of a named value (RFC-4122)
|
||||
* Version 4, based on random numbers (RFC-4122)
|
||||
* Version 5, based on SHA-1 hashing of a named value (RFC-4122)
|
||||
|
||||
This package also supports experimental Universally Unique Identifier implementations based on a
|
||||
[draft RFC](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html) that updates RFC-4122
|
||||
* Version 6, a k-sortable id based on timestamp, and field-compatible with v1 (draft-peabody-dispatch-new-uuid-format, RFC-4122)
|
||||
* Version 7, a k-sortable id based on timestamp (draft-peabody-dispatch-new-uuid-format, RFC-4122)
|
||||
|
||||
The v6 and v7 IDs are **not** considered a part of the stable API, and may be subject to behavior or API changes as part of minor releases
|
||||
to this package. They will be updated as the draft RFC changes, and will become stable if and when the draft RFC is accepted.
|
||||
|
||||
## Project History
|
||||
|
||||
This project was originally forked from the
|
||||
[github.com/satori/go.uuid](https://github.com/satori/go.uuid) repository after
|
||||
it appeared to be no longer maintained, while exhibiting [critical
|
||||
flaws](https://github.com/satori/go.uuid/issues/73). We have decided to take
|
||||
over this project to ensure it receives regular maintenance for the benefit of
|
||||
the larger Go community.
|
||||
|
||||
We'd like to thank Maxim Bublis for his hard work on the original iteration of
|
||||
the package.
|
||||
|
||||
## License
|
||||
|
||||
This source code of this package is released under the MIT License. Please see
|
||||
the [LICENSE](https://github.com/gofrs/uuid/blob/master/LICENSE) for the full
|
||||
content of the license.
|
||||
|
||||
## Recommended Package Version
|
||||
|
||||
We recommend using v2.0.0+ of this package, as versions prior to 2.0.0 were
|
||||
created before our fork of the original package and have some known
|
||||
deficiencies.
|
||||
|
||||
## Installation
|
||||
|
||||
It is recommended to use a package manager like `dep` that understands tagged
|
||||
releases of a package, as well as semantic versioning.
|
||||
|
||||
If you are unable to make use of a dependency manager with your project, you can
|
||||
use the `go get` command to download it directly:
|
||||
|
||||
```Shell
|
||||
$ go get github.com/gofrs/uuid
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
Due to subtests not being supported in older versions of Go, this package is
|
||||
only regularly tested against Go 1.7+. This package may work perfectly fine with
|
||||
Go 1.2+, but support for these older versions is not actively maintained.
|
||||
|
||||
## Go 1.11 Modules
|
||||
|
||||
As of v3.2.0, this repository no longer adopts Go modules, and v3.2.0 no longer has a `go.mod` file. As a result, v3.2.0 also drops support for the `github.com/gofrs/uuid/v3` import path. Only module-based consumers are impacted. With the v3.2.0 release, _all_ gofrs/uuid consumers should use the `github.com/gofrs/uuid` import path.
|
||||
|
||||
An existing module-based consumer will continue to be able to build using the `github.com/gofrs/uuid/v3` import path using any valid consumer `go.mod` that worked prior to the publishing of v3.2.0, but any module-based consumer should start using the `github.com/gofrs/uuid` import path when possible and _must_ use the `github.com/gofrs/uuid` import path prior to upgrading to v3.2.0.
|
||||
|
||||
Please refer to [Issue #61](https://github.com/gofrs/uuid/issues/61) and [Issue #66](https://github.com/gofrs/uuid/issues/66) for more details.
|
||||
|
||||
## Usage
|
||||
|
||||
Here is a quick overview of how to use this package. For more detailed
|
||||
documentation, please see the [GoDoc Page](http://godoc.org/github.com/gofrs/uuid).
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
|
||||
"github.com/gofrs/uuid"
|
||||
)
|
||||
|
||||
// Create a Version 4 UUID, panicking on error.
|
||||
// Use this form to initialize package-level variables.
|
||||
var u1 = uuid.Must(uuid.NewV4())
|
||||
|
||||
func main() {
|
||||
// Create a Version 4 UUID.
|
||||
u2, err := uuid.NewV4()
|
||||
if err != nil {
|
||||
log.Fatalf("failed to generate UUID: %v", err)
|
||||
}
|
||||
log.Printf("generated Version 4 UUID %v", u2)
|
||||
|
||||
// Parse a UUID from a string.
|
||||
s := "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
|
||||
u3, err := uuid.FromString(s)
|
||||
if err != nil {
|
||||
log.Fatalf("failed to parse UUID %q: %v", s, err)
|
||||
}
|
||||
log.Printf("successfully parsed UUID %v", u3)
|
||||
}
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
* [RFC-4122](https://tools.ietf.org/html/rfc4122)
|
||||
* [DCE 1.1: Authentication and Security Services](http://pubs.opengroup.org/onlinepubs/9696989899/chap5.htm#tagcjh_08_02_01_01)
|
||||
* [New UUID Formats RFC Draft (Peabody) Rev 04](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#)
|
||||
+234
@@ -0,0 +1,234 @@
|
||||
// Copyright (C) 2013-2018 by Maxim Bublis <b@codemonkey.ru>
|
||||
//
|
||||
// Permission is hereby granted, free of charge, to any person obtaining
|
||||
// a copy of this software and associated documentation files (the
|
||||
// "Software"), to deal in the Software without restriction, including
|
||||
// without limitation the rights to use, copy, modify, merge, publish,
|
||||
// distribute, sublicense, and/or sell copies of the Software, and to
|
||||
// permit persons to whom the Software is furnished to do so, subject to
|
||||
// the following conditions:
|
||||
//
|
||||
// The above copyright notice and this permission notice shall be
|
||||
// included in all copies or substantial portions of the Software.
|
||||
//
|
||||
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
||||
// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
||||
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
||||
// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
package uuid
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"fmt"
|
||||
)
|
||||
|
||||
// FromBytes returns a UUID generated from the raw byte slice input.
|
||||
// It will return an error if the slice isn't 16 bytes long.
|
||||
func FromBytes(input []byte) (UUID, error) {
|
||||
u := UUID{}
|
||||
err := u.UnmarshalBinary(input)
|
||||
return u, err
|
||||
}
|
||||
|
||||
// FromBytesOrNil returns a UUID generated from the raw byte slice input.
|
||||
// Same behavior as FromBytes(), but returns uuid.Nil instead of an error.
|
||||
func FromBytesOrNil(input []byte) UUID {
|
||||
uuid, err := FromBytes(input)
|
||||
if err != nil {
|
||||
return Nil
|
||||
}
|
||||
return uuid
|
||||
}
|
||||
|
||||
var errInvalidFormat = errors.New("uuid: invalid UUID format")
|
||||
|
||||
func fromHexChar(c byte) byte {
|
||||
switch {
|
||||
case '0' <= c && c <= '9':
|
||||
return c - '0'
|
||||
case 'a' <= c && c <= 'f':
|
||||
return c - 'a' + 10
|
||||
case 'A' <= c && c <= 'F':
|
||||
return c - 'A' + 10
|
||||
}
|
||||
return 255
|
||||
}
|
||||
|
||||
// Parse parses the UUID stored in the string text. Parsing and supported
|
||||
// formats are the same as UnmarshalText.
|
||||
func (u *UUID) Parse(s string) error {
|
||||
switch len(s) {
|
||||
case 32: // hash
|
||||
case 36: // canonical
|
||||
case 34, 38:
|
||||
if s[0] != '{' || s[len(s)-1] != '}' {
|
||||
return fmt.Errorf("uuid: incorrect UUID format in string %q", s)
|
||||
}
|
||||
s = s[1 : len(s)-1]
|
||||
case 41, 45:
|
||||
if s[:9] != "urn:uuid:" {
|
||||
return fmt.Errorf("uuid: incorrect UUID format in string %q", s[:9])
|
||||
}
|
||||
s = s[9:]
|
||||
default:
|
||||
return fmt.Errorf("uuid: incorrect UUID length %d in string %q", len(s), s)
|
||||
}
|
||||
// canonical
|
||||
if len(s) == 36 {
|
||||
if s[8] != '-' || s[13] != '-' || s[18] != '-' || s[23] != '-' {
|
||||
return fmt.Errorf("uuid: incorrect UUID format in string %q", s)
|
||||
}
|
||||
for i, x := range [16]byte{
|
||||
0, 2, 4, 6,
|
||||
9, 11,
|
||||
14, 16,
|
||||
19, 21,
|
||||
24, 26, 28, 30, 32, 34,
|
||||
} {
|
||||
v1 := fromHexChar(s[x])
|
||||
v2 := fromHexChar(s[x+1])
|
||||
if v1|v2 == 255 {
|
||||
return errInvalidFormat
|
||||
}
|
||||
u[i] = (v1 << 4) | v2
|
||||
}
|
||||
return nil
|
||||
}
|
||||
// hash like
|
||||
for i := 0; i < 32; i += 2 {
|
||||
v1 := fromHexChar(s[i])
|
||||
v2 := fromHexChar(s[i+1])
|
||||
if v1|v2 == 255 {
|
||||
return errInvalidFormat
|
||||
}
|
||||
u[i/2] = (v1 << 4) | v2
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// FromString returns a UUID parsed from the input string.
|
||||
// Input is expected in a form accepted by UnmarshalText.
|
||||
func FromString(text string) (UUID, error) {
|
||||
var u UUID
|
||||
err := u.Parse(text)
|
||||
return u, err
|
||||
}
|
||||
|
||||
// FromStringOrNil returns a UUID parsed from the input string.
|
||||
// Same behavior as FromString(), but returns uuid.Nil instead of an error.
|
||||
func FromStringOrNil(input string) UUID {
|
||||
uuid, err := FromString(input)
|
||||
if err != nil {
|
||||
return Nil
|
||||
}
|
||||
return uuid
|
||||
}
|
||||
|
||||
// MarshalText implements the encoding.TextMarshaler interface.
|
||||
// The encoding is the same as returned by the String() method.
|
||||
func (u UUID) MarshalText() ([]byte, error) {
|
||||
var buf [36]byte
|
||||
encodeCanonical(buf[:], u)
|
||||
return buf[:], nil
|
||||
}
|
||||
|
||||
// UnmarshalText implements the encoding.TextUnmarshaler interface.
|
||||
// Following formats are supported:
|
||||
//
|
||||
// "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
|
||||
// "{6ba7b810-9dad-11d1-80b4-00c04fd430c8}",
|
||||
// "urn:uuid:6ba7b810-9dad-11d1-80b4-00c04fd430c8"
|
||||
// "6ba7b8109dad11d180b400c04fd430c8"
|
||||
// "{6ba7b8109dad11d180b400c04fd430c8}",
|
||||
// "urn:uuid:6ba7b8109dad11d180b400c04fd430c8"
|
||||
//
|
||||
// ABNF for supported UUID text representation follows:
|
||||
//
|
||||
// URN := 'urn'
|
||||
// UUID-NID := 'uuid'
|
||||
//
|
||||
// hexdig := '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' |
|
||||
// 'a' | 'b' | 'c' | 'd' | 'e' | 'f' |
|
||||
// 'A' | 'B' | 'C' | 'D' | 'E' | 'F'
|
||||
//
|
||||
// hexoct := hexdig hexdig
|
||||
// 2hexoct := hexoct hexoct
|
||||
// 4hexoct := 2hexoct 2hexoct
|
||||
// 6hexoct := 4hexoct 2hexoct
|
||||
// 12hexoct := 6hexoct 6hexoct
|
||||
//
|
||||
// hashlike := 12hexoct
|
||||
// canonical := 4hexoct '-' 2hexoct '-' 2hexoct '-' 6hexoct
|
||||
//
|
||||
// plain := canonical | hashlike
|
||||
// uuid := canonical | hashlike | braced | urn
|
||||
//
|
||||
// braced := '{' plain '}' | '{' hashlike '}'
|
||||
// urn := URN ':' UUID-NID ':' plain
|
||||
func (u *UUID) UnmarshalText(b []byte) error {
|
||||
switch len(b) {
|
||||
case 32: // hash
|
||||
case 36: // canonical
|
||||
case 34, 38:
|
||||
if b[0] != '{' || b[len(b)-1] != '}' {
|
||||
return fmt.Errorf("uuid: incorrect UUID format in string %q", b)
|
||||
}
|
||||
b = b[1 : len(b)-1]
|
||||
case 41, 45:
|
||||
if string(b[:9]) != "urn:uuid:" {
|
||||
return fmt.Errorf("uuid: incorrect UUID format in string %q", b[:9])
|
||||
}
|
||||
b = b[9:]
|
||||
default:
|
||||
return fmt.Errorf("uuid: incorrect UUID length %d in string %q", len(b), b)
|
||||
}
|
||||
if len(b) == 36 {
|
||||
if b[8] != '-' || b[13] != '-' || b[18] != '-' || b[23] != '-' {
|
||||
return fmt.Errorf("uuid: incorrect UUID format in string %q", b)
|
||||
}
|
||||
for i, x := range [16]byte{
|
||||
0, 2, 4, 6,
|
||||
9, 11,
|
||||
14, 16,
|
||||
19, 21,
|
||||
24, 26, 28, 30, 32, 34,
|
||||
} {
|
||||
v1 := fromHexChar(b[x])
|
||||
v2 := fromHexChar(b[x+1])
|
||||
if v1|v2 == 255 {
|
||||
return errInvalidFormat
|
||||
}
|
||||
u[i] = (v1 << 4) | v2
|
||||
}
|
||||
return nil
|
||||
}
|
||||
for i := 0; i < 32; i += 2 {
|
||||
v1 := fromHexChar(b[i])
|
||||
v2 := fromHexChar(b[i+1])
|
||||
if v1|v2 == 255 {
|
||||
return errInvalidFormat
|
||||
}
|
||||
u[i/2] = (v1 << 4) | v2
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// MarshalBinary implements the encoding.BinaryMarshaler interface.
|
||||
func (u UUID) MarshalBinary() ([]byte, error) {
|
||||
return u.Bytes(), nil
|
||||
}
|
||||
|
||||
// UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
|
||||
// It will return an error if the slice isn't 16 bytes long.
|
||||
func (u *UUID) UnmarshalBinary(data []byte) error {
|
||||
if len(data) != Size {
|
||||
return fmt.Errorf("uuid: UUID must be exactly 16 bytes long, got %d bytes", len(data))
|
||||
}
|
||||
copy(u[:], data)
|
||||
|
||||
return nil
|
||||
}
|
||||
+48
@@ -0,0 +1,48 @@
|
||||
// Copyright (c) 2018 Andrei Tudor Călin <mail@acln.ro>
|
||||
//
|
||||
// Permission is hereby granted, free of charge, to any person obtaining
|
||||
// a copy of this software and associated documentation files (the
|
||||
// "Software"), to deal in the Software without restriction, including
|
||||
// without limitation the rights to use, copy, modify, merge, publish,
|
||||
// distribute, sublicense, and/or sell copies of the Software, and to
|
||||
// permit persons to whom the Software is furnished to do so, subject to
|
||||
// the following conditions:
|
||||
//
|
||||
// The above copyright notice and this permission notice shall be
|
||||
// included in all copies or substantial portions of the Software.
|
||||
//
|
||||
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
||||
// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
||||
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
||||
// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
//go:build gofuzz
|
||||
// +build gofuzz
|
||||
|
||||
package uuid
|
||||
|
||||
// Fuzz implements a simple fuzz test for FromString / UnmarshalText.
|
||||
//
|
||||
// To run:
|
||||
//
|
||||
// $ go get github.com/dvyukov/go-fuzz/...
|
||||
// $ cd $GOPATH/src/github.com/gofrs/uuid
|
||||
// $ go-fuzz-build github.com/gofrs/uuid
|
||||
// $ go-fuzz -bin=uuid-fuzz.zip -workdir=./testdata
|
||||
//
|
||||
// If you make significant changes to FromString / UnmarshalText and add
|
||||
// new cases to fromStringTests (in codec_test.go), please run
|
||||
//
|
||||
// $ go test -seed_fuzz_corpus
|
||||
//
|
||||
// to seed the corpus with the new interesting inputs, then run the fuzzer.
|
||||
func Fuzz(data []byte) int {
|
||||
_, err := FromString(string(data))
|
||||
if err != nil {
|
||||
return 0
|
||||
}
|
||||
return 1
|
||||
}
|
||||
+456
@@ -0,0 +1,456 @@
|
||||
// Copyright (C) 2013-2018 by Maxim Bublis <b@codemonkey.ru>
|
||||
//
|
||||
// Permission is hereby granted, free of charge, to any person obtaining
|
||||
// a copy of this software and associated documentation files (the
|
||||
// "Software"), to deal in the Software without restriction, including
|
||||
// without limitation the rights to use, copy, modify, merge, publish,
|
||||
// distribute, sublicense, and/or sell copies of the Software, and to
|
||||
// permit persons to whom the Software is furnished to do so, subject to
|
||||
// the following conditions:
|
||||
//
|
||||
// The above copyright notice and this permission notice shall be
|
||||
// included in all copies or substantial portions of the Software.
|
||||
//
|
||||
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
||||
// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
||||
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
||||
// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
package uuid
|
||||
|
||||
import (
|
||||
"crypto/md5"
|
||||
"crypto/rand"
|
||||
"crypto/sha1"
|
||||
"encoding/binary"
|
||||
"fmt"
|
||||
"hash"
|
||||
"io"
|
||||
"net"
|
||||
"sync"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Difference in 100-nanosecond intervals between
|
||||
// UUID epoch (October 15, 1582) and Unix epoch (January 1, 1970).
|
||||
const epochStart = 122192928000000000
|
||||
|
||||
// EpochFunc is the function type used to provide the current time.
|
||||
type EpochFunc func() time.Time
|
||||
|
||||
// HWAddrFunc is the function type used to provide hardware (MAC) addresses.
|
||||
type HWAddrFunc func() (net.HardwareAddr, error)
|
||||
|
||||
// DefaultGenerator is the default UUID Generator used by this package.
|
||||
var DefaultGenerator Generator = NewGen()
|
||||
|
||||
// NewV1 returns a UUID based on the current timestamp and MAC address.
|
||||
func NewV1() (UUID, error) {
|
||||
return DefaultGenerator.NewV1()
|
||||
}
|
||||
|
||||
// NewV3 returns a UUID based on the MD5 hash of the namespace UUID and name.
|
||||
func NewV3(ns UUID, name string) UUID {
|
||||
return DefaultGenerator.NewV3(ns, name)
|
||||
}
|
||||
|
||||
// NewV4 returns a randomly generated UUID.
|
||||
func NewV4() (UUID, error) {
|
||||
return DefaultGenerator.NewV4()
|
||||
}
|
||||
|
||||
// NewV5 returns a UUID based on SHA-1 hash of the namespace UUID and name.
|
||||
func NewV5(ns UUID, name string) UUID {
|
||||
return DefaultGenerator.NewV5(ns, name)
|
||||
}
|
||||
|
||||
// NewV6 returns a k-sortable UUID based on a timestamp and 48 bits of
|
||||
// pseudorandom data. The timestamp in a V6 UUID is the same as V1, with the bit
|
||||
// order being adjusted to allow the UUID to be k-sortable.
|
||||
//
|
||||
// This is implemented based on revision 03 of the Peabody UUID draft, and may
|
||||
// be subject to change pending further revisions. Until the final specification
|
||||
// revision is finished, changes required to implement updates to the spec will
|
||||
// not be considered a breaking change. They will happen as a minor version
|
||||
// releases until the spec is final.
|
||||
func NewV6() (UUID, error) {
|
||||
return DefaultGenerator.NewV6()
|
||||
}
|
||||
|
||||
// NewV7 returns a k-sortable UUID based on the current millisecond precision
|
||||
// UNIX epoch and 74 bits of pseudorandom data. It supports single-node batch generation (multiple UUIDs in the same timestamp) with a Monotonic Random counter.
|
||||
//
|
||||
// This is implemented based on revision 04 of the Peabody UUID draft, and may
|
||||
// be subject to change pending further revisions. Until the final specification
|
||||
// revision is finished, changes required to implement updates to the spec will
|
||||
// not be considered a breaking change. They will happen as a minor version
|
||||
// releases until the spec is final.
|
||||
func NewV7() (UUID, error) {
|
||||
return DefaultGenerator.NewV7()
|
||||
}
|
||||
|
||||
// Generator provides an interface for generating UUIDs.
|
||||
type Generator interface {
|
||||
NewV1() (UUID, error)
|
||||
NewV3(ns UUID, name string) UUID
|
||||
NewV4() (UUID, error)
|
||||
NewV5(ns UUID, name string) UUID
|
||||
NewV6() (UUID, error)
|
||||
NewV7() (UUID, error)
|
||||
}
|
||||
|
||||
// Gen is a reference UUID generator based on the specifications laid out in
|
||||
// RFC-4122 and DCE 1.1: Authentication and Security Services. This type
|
||||
// satisfies the Generator interface as defined in this package.
|
||||
//
|
||||
// For consumers who are generating V1 UUIDs, but don't want to expose the MAC
|
||||
// address of the node generating the UUIDs, the NewGenWithHWAF() function has been
|
||||
// provided as a convenience. See the function's documentation for more info.
|
||||
//
|
||||
// The authors of this package do not feel that the majority of users will need
|
||||
// to obfuscate their MAC address, and so we recommend using NewGen() to create
|
||||
// a new generator.
|
||||
type Gen struct {
|
||||
clockSequenceOnce sync.Once
|
||||
hardwareAddrOnce sync.Once
|
||||
storageMutex sync.Mutex
|
||||
|
||||
rand io.Reader
|
||||
|
||||
epochFunc EpochFunc
|
||||
hwAddrFunc HWAddrFunc
|
||||
lastTime uint64
|
||||
clockSequence uint16
|
||||
hardwareAddr [6]byte
|
||||
}
|
||||
|
||||
// GenOption is a function type that can be used to configure a Gen generator.
|
||||
type GenOption func(*Gen)
|
||||
|
||||
// interface check -- build will fail if *Gen doesn't satisfy Generator
|
||||
var _ Generator = (*Gen)(nil)
|
||||
|
||||
// NewGen returns a new instance of Gen with some default values set. Most
|
||||
// people should use this.
|
||||
func NewGen() *Gen {
|
||||
return NewGenWithHWAF(defaultHWAddrFunc)
|
||||
}
|
||||
|
||||
// NewGenWithHWAF builds a new UUID generator with the HWAddrFunc provided. Most
|
||||
// consumers should use NewGen() instead.
|
||||
//
|
||||
// This is used so that consumers can generate their own MAC addresses, for use
|
||||
// in the generated UUIDs, if there is some concern about exposing the physical
|
||||
// address of the machine generating the UUID.
|
||||
//
|
||||
// The Gen generator will only invoke the HWAddrFunc once, and cache that MAC
|
||||
// address for all the future UUIDs generated by it. If you'd like to switch the
|
||||
// MAC address being used, you'll need to create a new generator using this
|
||||
// function.
|
||||
func NewGenWithHWAF(hwaf HWAddrFunc) *Gen {
|
||||
return NewGenWithOptions(WithHWAddrFunc(hwaf))
|
||||
}
|
||||
|
||||
// NewGenWithOptions returns a new instance of Gen with the options provided.
|
||||
// Most people should use NewGen() or NewGenWithHWAF() instead.
|
||||
//
|
||||
// To customize the generator, you can pass in one or more GenOption functions.
|
||||
// For example:
|
||||
//
|
||||
// gen := NewGenWithOptions(
|
||||
// WithHWAddrFunc(myHWAddrFunc),
|
||||
// WithEpochFunc(myEpochFunc),
|
||||
// WithRandomReader(myRandomReader),
|
||||
// )
|
||||
//
|
||||
// NewGenWithOptions(WithHWAddrFunc(myHWAddrFunc)) is equivalent to calling
|
||||
// NewGenWithHWAF(myHWAddrFunc)
|
||||
// NewGenWithOptions() is equivalent to calling NewGen()
|
||||
func NewGenWithOptions(opts ...GenOption) *Gen {
|
||||
gen := &Gen{
|
||||
epochFunc: time.Now,
|
||||
hwAddrFunc: defaultHWAddrFunc,
|
||||
rand: rand.Reader,
|
||||
}
|
||||
|
||||
for _, opt := range opts {
|
||||
opt(gen)
|
||||
}
|
||||
|
||||
return gen
|
||||
}
|
||||
|
||||
// WithHWAddrFunc is a GenOption that allows you to provide your own HWAddrFunc
|
||||
// function.
|
||||
// When this option is nil, the defaultHWAddrFunc is used.
|
||||
func WithHWAddrFunc(hwaf HWAddrFunc) GenOption {
|
||||
return func(gen *Gen) {
|
||||
if hwaf == nil {
|
||||
hwaf = defaultHWAddrFunc
|
||||
}
|
||||
|
||||
gen.hwAddrFunc = hwaf
|
||||
}
|
||||
}
|
||||
|
||||
// WithEpochFunc is a GenOption that allows you to provide your own EpochFunc
|
||||
// function.
|
||||
// When this option is nil, time.Now is used.
|
||||
func WithEpochFunc(epochf EpochFunc) GenOption {
|
||||
return func(gen *Gen) {
|
||||
if epochf == nil {
|
||||
epochf = time.Now
|
||||
}
|
||||
|
||||
gen.epochFunc = epochf
|
||||
}
|
||||
}
|
||||
|
||||
// WithRandomReader is a GenOption that allows you to provide your own random
|
||||
// reader.
|
||||
// When this option is nil, the default rand.Reader is used.
|
||||
func WithRandomReader(reader io.Reader) GenOption {
|
||||
return func(gen *Gen) {
|
||||
if reader == nil {
|
||||
reader = rand.Reader
|
||||
}
|
||||
|
||||
gen.rand = reader
|
||||
}
|
||||
}
|
||||
|
||||
// NewV1 returns a UUID based on the current timestamp and MAC address.
|
||||
func (g *Gen) NewV1() (UUID, error) {
|
||||
u := UUID{}
|
||||
|
||||
timeNow, clockSeq, err := g.getClockSequence(false)
|
||||
if err != nil {
|
||||
return Nil, err
|
||||
}
|
||||
binary.BigEndian.PutUint32(u[0:], uint32(timeNow))
|
||||
binary.BigEndian.PutUint16(u[4:], uint16(timeNow>>32))
|
||||
binary.BigEndian.PutUint16(u[6:], uint16(timeNow>>48))
|
||||
binary.BigEndian.PutUint16(u[8:], clockSeq)
|
||||
|
||||
hardwareAddr, err := g.getHardwareAddr()
|
||||
if err != nil {
|
||||
return Nil, err
|
||||
}
|
||||
copy(u[10:], hardwareAddr)
|
||||
|
||||
u.SetVersion(V1)
|
||||
u.SetVariant(VariantRFC4122)
|
||||
|
||||
return u, nil
|
||||
}
|
||||
|
||||
// NewV3 returns a UUID based on the MD5 hash of the namespace UUID and name.
|
||||
func (g *Gen) NewV3(ns UUID, name string) UUID {
|
||||
u := newFromHash(md5.New(), ns, name)
|
||||
u.SetVersion(V3)
|
||||
u.SetVariant(VariantRFC4122)
|
||||
|
||||
return u
|
||||
}
|
||||
|
||||
// NewV4 returns a randomly generated UUID.
|
||||
func (g *Gen) NewV4() (UUID, error) {
|
||||
u := UUID{}
|
||||
if _, err := io.ReadFull(g.rand, u[:]); err != nil {
|
||||
return Nil, err
|
||||
}
|
||||
u.SetVersion(V4)
|
||||
u.SetVariant(VariantRFC4122)
|
||||
|
||||
return u, nil
|
||||
}
|
||||
|
||||
// NewV5 returns a UUID based on SHA-1 hash of the namespace UUID and name.
|
||||
func (g *Gen) NewV5(ns UUID, name string) UUID {
|
||||
u := newFromHash(sha1.New(), ns, name)
|
||||
u.SetVersion(V5)
|
||||
u.SetVariant(VariantRFC4122)
|
||||
|
||||
return u
|
||||
}
|
||||
|
||||
// NewV6 returns a k-sortable UUID based on a timestamp and 48 bits of
|
||||
// pseudorandom data. The timestamp in a V6 UUID is the same as V1, with the bit
|
||||
// order being adjusted to allow the UUID to be k-sortable.
|
||||
//
|
||||
// This is implemented based on revision 03 of the Peabody UUID draft, and may
|
||||
// be subject to change pending further revisions. Until the final specification
|
||||
// revision is finished, changes required to implement updates to the spec will
|
||||
// not be considered a breaking change. They will happen as a minor version
|
||||
// releases until the spec is final.
|
||||
func (g *Gen) NewV6() (UUID, error) {
|
||||
var u UUID
|
||||
|
||||
if _, err := io.ReadFull(g.rand, u[10:]); err != nil {
|
||||
return Nil, err
|
||||
}
|
||||
|
||||
timeNow, clockSeq, err := g.getClockSequence(false)
|
||||
if err != nil {
|
||||
return Nil, err
|
||||
}
|
||||
|
||||
binary.BigEndian.PutUint32(u[0:], uint32(timeNow>>28)) // set time_high
|
||||
binary.BigEndian.PutUint16(u[4:], uint16(timeNow>>12)) // set time_mid
|
||||
binary.BigEndian.PutUint16(u[6:], uint16(timeNow&0xfff)) // set time_low (minus four version bits)
|
||||
binary.BigEndian.PutUint16(u[8:], clockSeq&0x3fff) // set clk_seq_hi_res (minus two variant bits)
|
||||
|
||||
u.SetVersion(V6)
|
||||
u.SetVariant(VariantRFC4122)
|
||||
|
||||
return u, nil
|
||||
}
|
||||
|
||||
// getClockSequence returns the epoch and clock sequence for V1,V6 and V7 UUIDs.
|
||||
//
|
||||
// When useUnixTSMs is false, it uses the Coordinated Universal Time (UTC) as a count of 100-
|
||||
//
|
||||
// nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to the Christian calendar).
|
||||
func (g *Gen) getClockSequence(useUnixTSMs bool) (uint64, uint16, error) {
|
||||
var err error
|
||||
g.clockSequenceOnce.Do(func() {
|
||||
buf := make([]byte, 2)
|
||||
if _, err = io.ReadFull(g.rand, buf); err != nil {
|
||||
return
|
||||
}
|
||||
g.clockSequence = binary.BigEndian.Uint16(buf)
|
||||
})
|
||||
if err != nil {
|
||||
return 0, 0, err
|
||||
}
|
||||
|
||||
g.storageMutex.Lock()
|
||||
defer g.storageMutex.Unlock()
|
||||
|
||||
var timeNow uint64
|
||||
if useUnixTSMs {
|
||||
timeNow = uint64(g.epochFunc().UnixMilli())
|
||||
} else {
|
||||
timeNow = g.getEpoch()
|
||||
}
|
||||
// Clock didn't change since last UUID generation.
|
||||
// Should increase clock sequence.
|
||||
if timeNow <= g.lastTime {
|
||||
g.clockSequence++
|
||||
}
|
||||
g.lastTime = timeNow
|
||||
|
||||
return timeNow, g.clockSequence, nil
|
||||
}
|
||||
|
||||
// NewV7 returns a k-sortable UUID based on the current millisecond precision
|
||||
// UNIX epoch and 74 bits of pseudorandom data.
|
||||
//
|
||||
// This is implemented based on revision 04 of the Peabody UUID draft, and may
|
||||
// be subject to change pending further revisions. Until the final specification
|
||||
// revision is finished, changes required to implement updates to the spec will
|
||||
// not be considered a breaking change. They will happen as a minor version
|
||||
// releases until the spec is final.
|
||||
func (g *Gen) NewV7() (UUID, error) {
|
||||
var u UUID
|
||||
/* https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#name-uuid-version-7
|
||||
0 1 2 3
|
||||
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| unix_ts_ms |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| unix_ts_ms | ver | rand_a |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
|var| rand_b |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
||||
| rand_b |
|
||||
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ */
|
||||
|
||||
ms, clockSeq, err := g.getClockSequence(true)
|
||||
if err != nil {
|
||||
return Nil, err
|
||||
}
|
||||
//UUIDv7 features a 48 bit timestamp. First 32bit (4bytes) represents seconds since 1970, followed by 2 bytes for the ms granularity.
|
||||
u[0] = byte(ms >> 40) //1-6 bytes: big-endian unsigned number of Unix epoch timestamp
|
||||
u[1] = byte(ms >> 32)
|
||||
u[2] = byte(ms >> 24)
|
||||
u[3] = byte(ms >> 16)
|
||||
u[4] = byte(ms >> 8)
|
||||
u[5] = byte(ms)
|
||||
|
||||
//support batching by using a monotonic pseudo-random sequence
|
||||
//The 6th byte contains the version and partially rand_a data.
|
||||
//We will lose the most significant bites from the clockSeq (with SetVersion), but it is ok, we need the least significant that contains the counter to ensure the monotonic property
|
||||
binary.BigEndian.PutUint16(u[6:8], clockSeq) // set rand_a with clock seq which is random and monotonic
|
||||
|
||||
//override first 4bits of u[6].
|
||||
u.SetVersion(V7)
|
||||
|
||||
//set rand_b 64bits of pseudo-random bits (first 2 will be overridden)
|
||||
if _, err = io.ReadFull(g.rand, u[8:16]); err != nil {
|
||||
return Nil, err
|
||||
}
|
||||
//override first 2 bits of byte[8] for the variant
|
||||
u.SetVariant(VariantRFC4122)
|
||||
|
||||
return u, nil
|
||||
}
|
||||
|
||||
// Returns the hardware address.
|
||||
func (g *Gen) getHardwareAddr() ([]byte, error) {
|
||||
var err error
|
||||
g.hardwareAddrOnce.Do(func() {
|
||||
var hwAddr net.HardwareAddr
|
||||
if hwAddr, err = g.hwAddrFunc(); err == nil {
|
||||
copy(g.hardwareAddr[:], hwAddr)
|
||||
return
|
||||
}
|
||||
|
||||
// Initialize hardwareAddr randomly in case
|
||||
// of real network interfaces absence.
|
||||
if _, err = io.ReadFull(g.rand, g.hardwareAddr[:]); err != nil {
|
||||
return
|
||||
}
|
||||
// Set multicast bit as recommended by RFC-4122
|
||||
g.hardwareAddr[0] |= 0x01
|
||||
})
|
||||
if err != nil {
|
||||
return []byte{}, err
|
||||
}
|
||||
return g.hardwareAddr[:], nil
|
||||
}
|
||||
|
||||
// Returns the difference between UUID epoch (October 15, 1582)
|
||||
// and current time in 100-nanosecond intervals.
|
||||
func (g *Gen) getEpoch() uint64 {
|
||||
return epochStart + uint64(g.epochFunc().UnixNano()/100)
|
||||
}
|
||||
|
||||
// Returns the UUID based on the hashing of the namespace UUID and name.
|
||||
func newFromHash(h hash.Hash, ns UUID, name string) UUID {
|
||||
u := UUID{}
|
||||
h.Write(ns[:])
|
||||
h.Write([]byte(name))
|
||||
copy(u[:], h.Sum(nil))
|
||||
|
||||
return u
|
||||
}
|
||||
|
||||
var netInterfaces = net.Interfaces
|
||||
|
||||
// Returns the hardware address.
|
||||
func defaultHWAddrFunc() (net.HardwareAddr, error) {
|
||||
ifaces, err := netInterfaces()
|
||||
if err != nil {
|
||||
return []byte{}, err
|
||||
}
|
||||
for _, iface := range ifaces {
|
||||
if len(iface.HardwareAddr) >= 6 {
|
||||
return iface.HardwareAddr, nil
|
||||
}
|
||||
}
|
||||
return []byte{}, fmt.Errorf("uuid: no HW address found")
|
||||
}
|
||||
+116
@@ -0,0 +1,116 @@
|
||||
// Copyright (C) 2013-2018 by Maxim Bublis <b@codemonkey.ru>
|
||||
//
|
||||
// Permission is hereby granted, free of charge, to any person obtaining
|
||||
// a copy of this software and associated documentation files (the
|
||||
// "Software"), to deal in the Software without restriction, including
|
||||
// without limitation the rights to use, copy, modify, merge, publish,
|
||||
// distribute, sublicense, and/or sell copies of the Software, and to
|
||||
// permit persons to whom the Software is furnished to do so, subject to
|
||||
// the following conditions:
|
||||
//
|
||||
// The above copyright notice and this permission notice shall be
|
||||
// included in all copies or substantial portions of the Software.
|
||||
//
|
||||
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
||||
// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
||||
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
||||
// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
package uuid
|
||||
|
||||
import (
|
||||
"database/sql"
|
||||
"database/sql/driver"
|
||||
"fmt"
|
||||
)
|
||||
|
||||
var _ driver.Valuer = UUID{}
|
||||
var _ sql.Scanner = (*UUID)(nil)
|
||||
|
||||
// Value implements the driver.Valuer interface.
|
||||
func (u UUID) Value() (driver.Value, error) {
|
||||
return u.String(), nil
|
||||
}
|
||||
|
||||
// Scan implements the sql.Scanner interface.
|
||||
// A 16-byte slice will be handled by UnmarshalBinary, while
|
||||
// a longer byte slice or a string will be handled by UnmarshalText.
|
||||
func (u *UUID) Scan(src interface{}) error {
|
||||
switch src := src.(type) {
|
||||
case UUID: // support gorm convert from UUID to NullUUID
|
||||
*u = src
|
||||
return nil
|
||||
|
||||
case []byte:
|
||||
if len(src) == Size {
|
||||
return u.UnmarshalBinary(src)
|
||||
}
|
||||
return u.UnmarshalText(src)
|
||||
|
||||
case string:
|
||||
uu, err := FromString(src)
|
||||
*u = uu
|
||||
return err
|
||||
}
|
||||
|
||||
return fmt.Errorf("uuid: cannot convert %T to UUID", src)
|
||||
}
|
||||
|
||||
// NullUUID can be used with the standard sql package to represent a
|
||||
// UUID value that can be NULL in the database.
|
||||
type NullUUID struct {
|
||||
UUID UUID
|
||||
Valid bool
|
||||
}
|
||||
|
||||
// Value implements the driver.Valuer interface.
|
||||
func (u NullUUID) Value() (driver.Value, error) {
|
||||
if !u.Valid {
|
||||
return nil, nil
|
||||
}
|
||||
// Delegate to UUID Value function
|
||||
return u.UUID.Value()
|
||||
}
|
||||
|
||||
// Scan implements the sql.Scanner interface.
|
||||
func (u *NullUUID) Scan(src interface{}) error {
|
||||
if src == nil {
|
||||
u.UUID, u.Valid = Nil, false
|
||||
return nil
|
||||
}
|
||||
|
||||
// Delegate to UUID Scan function
|
||||
u.Valid = true
|
||||
return u.UUID.Scan(src)
|
||||
}
|
||||
|
||||
var nullJSON = []byte("null")
|
||||
|
||||
// MarshalJSON marshals the NullUUID as null or the nested UUID
|
||||
func (u NullUUID) MarshalJSON() ([]byte, error) {
|
||||
if !u.Valid {
|
||||
return nullJSON, nil
|
||||
}
|
||||
var buf [38]byte
|
||||
buf[0] = '"'
|
||||
encodeCanonical(buf[1:37], u.UUID)
|
||||
buf[37] = '"'
|
||||
return buf[:], nil
|
||||
}
|
||||
|
||||
// UnmarshalJSON unmarshals a NullUUID
|
||||
func (u *NullUUID) UnmarshalJSON(b []byte) error {
|
||||
if string(b) == "null" {
|
||||
u.UUID, u.Valid = Nil, false
|
||||
return nil
|
||||
}
|
||||
if n := len(b); n >= 2 && b[0] == '"' {
|
||||
b = b[1 : n-1]
|
||||
}
|
||||
err := u.UUID.UnmarshalText(b)
|
||||
u.Valid = (err == nil)
|
||||
return err
|
||||
}
|
||||
+285
@@ -0,0 +1,285 @@
|
||||
// Copyright (C) 2013-2018 by Maxim Bublis <b@codemonkey.ru>
|
||||
//
|
||||
// Permission is hereby granted, free of charge, to any person obtaining
|
||||
// a copy of this software and associated documentation files (the
|
||||
// "Software"), to deal in the Software without restriction, including
|
||||
// without limitation the rights to use, copy, modify, merge, publish,
|
||||
// distribute, sublicense, and/or sell copies of the Software, and to
|
||||
// permit persons to whom the Software is furnished to do so, subject to
|
||||
// the following conditions:
|
||||
//
|
||||
// The above copyright notice and this permission notice shall be
|
||||
// included in all copies or substantial portions of the Software.
|
||||
//
|
||||
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
||||
// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
||||
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
||||
// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
// Package uuid provides implementations of the Universally Unique Identifier
|
||||
// (UUID), as specified in RFC-4122 and the Peabody RFC Draft (revision 03).
|
||||
//
|
||||
// RFC-4122[1] provides the specification for versions 1, 3, 4, and 5. The
|
||||
// Peabody UUID RFC Draft[2] provides the specification for the new k-sortable
|
||||
// UUIDs, versions 6 and 7.
|
||||
//
|
||||
// DCE 1.1[3] provides the specification for version 2, but version 2 support
|
||||
// was removed from this package in v4 due to some concerns with the
|
||||
// specification itself. Reading the spec, it seems that it would result in
|
||||
// generating UUIDs that aren't very unique. In having read the spec it seemed
|
||||
// that our implementation did not meet the spec. It also seems to be at-odds
|
||||
// with RFC 4122, meaning we would need quite a bit of special code to support
|
||||
// it. Lastly, there were no Version 2 implementations that we could find to
|
||||
// ensure we were understanding the specification correctly.
|
||||
//
|
||||
// [1] https://tools.ietf.org/html/rfc4122
|
||||
// [2] https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-03
|
||||
// [3] http://pubs.opengroup.org/onlinepubs/9696989899/chap5.htm#tagcjh_08_02_01_01
|
||||
package uuid
|
||||
|
||||
import (
|
||||
"encoding/binary"
|
||||
"encoding/hex"
|
||||
"fmt"
|
||||
"time"
|
||||
)
|
||||
|
||||
// Size of a UUID in bytes.
|
||||
const Size = 16
|
||||
|
||||
// UUID is an array type to represent the value of a UUID, as defined in RFC-4122.
|
||||
type UUID [Size]byte
|
||||
|
||||
// UUID versions.
|
||||
const (
|
||||
_ byte = iota
|
||||
V1 // Version 1 (date-time and MAC address)
|
||||
_ // Version 2 (date-time and MAC address, DCE security version) [removed]
|
||||
V3 // Version 3 (namespace name-based)
|
||||
V4 // Version 4 (random)
|
||||
V5 // Version 5 (namespace name-based)
|
||||
V6 // Version 6 (k-sortable timestamp and random data, field-compatible with v1) [peabody draft]
|
||||
V7 // Version 7 (k-sortable timestamp and random data) [peabody draft]
|
||||
_ // Version 8 (k-sortable timestamp, meant for custom implementations) [peabody draft] [not implemented]
|
||||
)
|
||||
|
||||
// UUID layout variants.
|
||||
const (
|
||||
VariantNCS byte = iota
|
||||
VariantRFC4122
|
||||
VariantMicrosoft
|
||||
VariantFuture
|
||||
)
|
||||
|
||||
// UUID DCE domains.
|
||||
const (
|
||||
DomainPerson = iota
|
||||
DomainGroup
|
||||
DomainOrg
|
||||
)
|
||||
|
||||
// Timestamp is the count of 100-nanosecond intervals since 00:00:00.00,
|
||||
// 15 October 1582 within a V1 UUID. This type has no meaning for other
|
||||
// UUID versions since they don't have an embedded timestamp.
|
||||
type Timestamp uint64
|
||||
|
||||
const _100nsPerSecond = 10000000
|
||||
|
||||
// Time returns the UTC time.Time representation of a Timestamp
|
||||
func (t Timestamp) Time() (time.Time, error) {
|
||||
secs := uint64(t) / _100nsPerSecond
|
||||
nsecs := 100 * (uint64(t) % _100nsPerSecond)
|
||||
|
||||
return time.Unix(int64(secs)-(epochStart/_100nsPerSecond), int64(nsecs)), nil
|
||||
}
|
||||
|
||||
// TimestampFromV1 returns the Timestamp embedded within a V1 UUID.
|
||||
// Returns an error if the UUID is any version other than 1.
|
||||
func TimestampFromV1(u UUID) (Timestamp, error) {
|
||||
if u.Version() != 1 {
|
||||
err := fmt.Errorf("uuid: %s is version %d, not version 1", u, u.Version())
|
||||
return 0, err
|
||||
}
|
||||
|
||||
low := binary.BigEndian.Uint32(u[0:4])
|
||||
mid := binary.BigEndian.Uint16(u[4:6])
|
||||
hi := binary.BigEndian.Uint16(u[6:8]) & 0xfff
|
||||
|
||||
return Timestamp(uint64(low) + (uint64(mid) << 32) + (uint64(hi) << 48)), nil
|
||||
}
|
||||
|
||||
// TimestampFromV6 returns the Timestamp embedded within a V6 UUID. This
|
||||
// function returns an error if the UUID is any version other than 6.
|
||||
//
|
||||
// This is implemented based on revision 03 of the Peabody UUID draft, and may
|
||||
// be subject to change pending further revisions. Until the final specification
|
||||
// revision is finished, changes required to implement updates to the spec will
|
||||
// not be considered a breaking change. They will happen as a minor version
|
||||
// releases until the spec is final.
|
||||
func TimestampFromV6(u UUID) (Timestamp, error) {
|
||||
if u.Version() != 6 {
|
||||
return 0, fmt.Errorf("uuid: %s is version %d, not version 6", u, u.Version())
|
||||
}
|
||||
|
||||
hi := binary.BigEndian.Uint32(u[0:4])
|
||||
mid := binary.BigEndian.Uint16(u[4:6])
|
||||
low := binary.BigEndian.Uint16(u[6:8]) & 0xfff
|
||||
|
||||
return Timestamp(uint64(low) + (uint64(mid) << 12) + (uint64(hi) << 28)), nil
|
||||
}
|
||||
|
||||
// Nil is the nil UUID, as specified in RFC-4122, that has all 128 bits set to
|
||||
// zero.
|
||||
var Nil = UUID{}
|
||||
|
||||
// Predefined namespace UUIDs.
|
||||
var (
|
||||
NamespaceDNS = Must(FromString("6ba7b810-9dad-11d1-80b4-00c04fd430c8"))
|
||||
NamespaceURL = Must(FromString("6ba7b811-9dad-11d1-80b4-00c04fd430c8"))
|
||||
NamespaceOID = Must(FromString("6ba7b812-9dad-11d1-80b4-00c04fd430c8"))
|
||||
NamespaceX500 = Must(FromString("6ba7b814-9dad-11d1-80b4-00c04fd430c8"))
|
||||
)
|
||||
|
||||
// IsNil returns if the UUID is equal to the nil UUID
|
||||
func (u UUID) IsNil() bool {
|
||||
return u == Nil
|
||||
}
|
||||
|
||||
// Version returns the algorithm version used to generate the UUID.
|
||||
func (u UUID) Version() byte {
|
||||
return u[6] >> 4
|
||||
}
|
||||
|
||||
// Variant returns the UUID layout variant.
|
||||
func (u UUID) Variant() byte {
|
||||
switch {
|
||||
case (u[8] >> 7) == 0x00:
|
||||
return VariantNCS
|
||||
case (u[8] >> 6) == 0x02:
|
||||
return VariantRFC4122
|
||||
case (u[8] >> 5) == 0x06:
|
||||
return VariantMicrosoft
|
||||
case (u[8] >> 5) == 0x07:
|
||||
fallthrough
|
||||
default:
|
||||
return VariantFuture
|
||||
}
|
||||
}
|
||||
|
||||
// Bytes returns a byte slice representation of the UUID.
|
||||
func (u UUID) Bytes() []byte {
|
||||
return u[:]
|
||||
}
|
||||
|
||||
// encodeCanonical encodes the canonical RFC-4122 form of UUID u into the
|
||||
// first 36 bytes dst.
|
||||
func encodeCanonical(dst []byte, u UUID) {
|
||||
const hextable = "0123456789abcdef"
|
||||
dst[8] = '-'
|
||||
dst[13] = '-'
|
||||
dst[18] = '-'
|
||||
dst[23] = '-'
|
||||
for i, x := range [16]byte{
|
||||
0, 2, 4, 6,
|
||||
9, 11,
|
||||
14, 16,
|
||||
19, 21,
|
||||
24, 26, 28, 30, 32, 34,
|
||||
} {
|
||||
c := u[i]
|
||||
dst[x] = hextable[c>>4]
|
||||
dst[x+1] = hextable[c&0x0f]
|
||||
}
|
||||
}
|
||||
|
||||
// String returns a canonical RFC-4122 string representation of the UUID:
|
||||
// xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
|
||||
func (u UUID) String() string {
|
||||
var buf [36]byte
|
||||
encodeCanonical(buf[:], u)
|
||||
return string(buf[:])
|
||||
}
|
||||
|
||||
// Format implements fmt.Formatter for UUID values.
|
||||
//
|
||||
// The behavior is as follows:
|
||||
// The 'x' and 'X' verbs output only the hex digits of the UUID, using a-f for 'x' and A-F for 'X'.
|
||||
// The 'v', '+v', 's' and 'q' verbs return the canonical RFC-4122 string representation.
|
||||
// The 'S' verb returns the RFC-4122 format, but with capital hex digits.
|
||||
// The '#v' verb returns the "Go syntax" representation, which is a 16 byte array initializer.
|
||||
// All other verbs not handled directly by the fmt package (like '%p') are unsupported and will return
|
||||
// "%!verb(uuid.UUID=value)" as recommended by the fmt package.
|
||||
func (u UUID) Format(f fmt.State, c rune) {
|
||||
if c == 'v' && f.Flag('#') {
|
||||
fmt.Fprintf(f, "%#v", [Size]byte(u))
|
||||
return
|
||||
}
|
||||
switch c {
|
||||
case 'x', 'X':
|
||||
b := make([]byte, 32)
|
||||
hex.Encode(b, u[:])
|
||||
if c == 'X' {
|
||||
toUpperHex(b)
|
||||
}
|
||||
_, _ = f.Write(b)
|
||||
case 'v', 's', 'S':
|
||||
b, _ := u.MarshalText()
|
||||
if c == 'S' {
|
||||
toUpperHex(b)
|
||||
}
|
||||
_, _ = f.Write(b)
|
||||
case 'q':
|
||||
b := make([]byte, 38)
|
||||
b[0] = '"'
|
||||
encodeCanonical(b[1:], u)
|
||||
b[37] = '"'
|
||||
_, _ = f.Write(b)
|
||||
default:
|
||||
// invalid/unsupported format verb
|
||||
fmt.Fprintf(f, "%%!%c(uuid.UUID=%s)", c, u.String())
|
||||
}
|
||||
}
|
||||
|
||||
func toUpperHex(b []byte) {
|
||||
for i, c := range b {
|
||||
if 'a' <= c && c <= 'f' {
|
||||
b[i] = c - ('a' - 'A')
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// SetVersion sets the version bits.
|
||||
func (u *UUID) SetVersion(v byte) {
|
||||
u[6] = (u[6] & 0x0f) | (v << 4)
|
||||
}
|
||||
|
||||
// SetVariant sets the variant bits.
|
||||
func (u *UUID) SetVariant(v byte) {
|
||||
switch v {
|
||||
case VariantNCS:
|
||||
u[8] = (u[8]&(0xff>>1) | (0x00 << 7))
|
||||
case VariantRFC4122:
|
||||
u[8] = (u[8]&(0xff>>2) | (0x02 << 6))
|
||||
case VariantMicrosoft:
|
||||
u[8] = (u[8]&(0xff>>3) | (0x06 << 5))
|
||||
case VariantFuture:
|
||||
fallthrough
|
||||
default:
|
||||
u[8] = (u[8]&(0xff>>3) | (0x07 << 5))
|
||||
}
|
||||
}
|
||||
|
||||
// Must is a helper that wraps a call to a function returning (UUID, error)
|
||||
// and panics if the error is non-nil. It is intended for use in variable
|
||||
// initializations such as
|
||||
//
|
||||
// var packageUUID = uuid.Must(uuid.FromString("123e4567-e89b-12d3-a456-426655440000"))
|
||||
func Must(u UUID, err error) UUID {
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
return u
|
||||
}
|
||||
Reference in New Issue
Block a user