[feature] update proof-of-work to allow setting required rounds (#4186)

# Description

This updates our proof-of-work middleware, NoLLaMas, to work on a more easily configurable algorithm (thank you f0x for bringing this to my attention!). Instead of requiring that a solution with pre-determined number of '0' chars be found, it now pre-computes a result with a pre-determined nonce value that it expects the client to iterate up-to. (though with some level of jitter applied, to prevent it being too-easily gamed). This allows the user to configure roughly how many hash-encode rounds they want their clients to have to complete.

## Checklist

- [x] I/we have read the [GoToSocial contribution guidelines](https://codeberg.org/superseriousbusiness/gotosocial/src/branch/main/CONTRIBUTING.md).
- [x] I/we have discussed the proposed changes already, either in an issue on the repository, or in the Matrix chat.
- [x] I/we have not leveraged AI to create the proposed changes.
- [x] I/we have performed a self-review of added code.
- [x] I/we have written code that is legible and maintainable by others.
- [x] I/we have commented the added code, particularly in hard-to-understand areas.
- [x] I/we have made any necessary changes to documentation.
- [ ] I/we have added tests that cover new code.
- [x] I/we have run tests and they pass locally with the changes.
- [x] I/we have run `go fmt ./...` and `golangci-lint run`.

Reviewed-on: https://codeberg.org/superseriousbusiness/gotosocial/pulls/4186
Co-authored-by: kim <grufwub@gmail.com>
Co-committed-by: kim <grufwub@gmail.com>

vendor/codeberg.org/gruf/go-bitutil/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2022 gruf
+
+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.

vendor/codeberg.org/gruf/go-bitutil/README.md

@@ -0,0 +1,3 @@
+# go-bitutil
+
+This library provides helpful methods and types for performing typical bitwise operations on integers, e.g. packing/unpacking, bit flags.

vendor/codeberg.org/gruf/go-bitutil/abs.go

@@ -0,0 +1,29 @@
+package bitutil
+
+// Abs8 returns the absolute value of i (calculated without branching).
+func Abs8(i int8) int8 {
+	const bits = 8
+	u := uint64(i >> (bits - 1))
+	return (i ^ int8(u)) + int8(u&1)
+}
+
+// Abs16 returns the absolute value of i (calculated without branching).
+func Abs16(i int16) int16 {
+	const bits = 16
+	u := uint64(i >> (bits - 1))
+	return (i ^ int16(u)) + int16(u&1)
+}
+
+// Abs32 returns the absolute value of i (calculated without branching).
+func Abs32(i int32) int32 {
+	const bits = 32
+	u := uint64(i >> (bits - 1))
+	return (i ^ int32(u)) + int32(u&1)
+}
+
+// Abs64 returns the absolute value of i (calculated without branching).
+func Abs64(i int64) int64 {
+	const bits = 64
+	u := uint64(i >> (bits - 1))
+	return (i ^ int64(u)) + int64(u&1)
+}

vendor/codeberg.org/gruf/go-bitutil/flag.tpl

@@ -0,0 +1,117 @@
+package bitutil
+
+import (
+    "strings"
+    "unsafe"
+)
+
+{{ range $idx, $size := . }}
+
+// Flags{{ $size.Size }} is a type-casted unsigned integer with helper
+// methods for easily managing up to {{ $size.Size }} bit-flags.
+type Flags{{ $size.Size }} uint{{ $size.Size }}
+
+// Get will fetch the flag bit value at index 'bit'.
+func (f Flags{{ $size.Size }}) Get(bit uint8) bool {
+    mask := Flags{{ $size.Size }}(1) << bit
+    return (f & mask != 0)
+}
+
+// Set will set the flag bit value at index 'bit'.
+func (f Flags{{ $size.Size }}) Set(bit uint8) Flags{{ $size.Size }} {
+    mask := Flags{{ $size.Size }}(1) << bit
+    return f | mask
+}
+
+// Unset will unset the flag bit value at index 'bit'.
+func (f Flags{{ $size.Size }}) Unset(bit uint8) Flags{{ $size.Size }} {
+    mask := Flags{{ $size.Size }}(1) << bit
+    return f & ^mask
+}
+
+{{ range $idx := $size.Bits }}
+
+// Get{{ $idx }} will fetch the flag bit value at index {{ $idx }}.
+func (f Flags{{ $size.Size }}) Get{{ $idx }}() bool {
+    const mask = Flags{{ $size.Size }}(1) << {{ $idx }}
+    return (f & mask != 0)
+}
+
+// Set{{ $idx }} will set the flag bit value at index {{ $idx }}.
+func (f Flags{{ $size.Size }}) Set{{ $idx }}() Flags{{ $size.Size }} {
+    const mask = Flags{{ $size.Size }}(1) << {{ $idx }}
+    return f | mask
+}
+
+// Unset{{ $idx }} will unset the flag bit value at index {{ $idx }}.
+func (f Flags{{ $size.Size }}) Unset{{ $idx }}() Flags{{ $size.Size }} {
+    const mask = Flags{{ $size.Size }}(1) << {{ $idx }}
+    return f & ^mask
+}
+
+{{ end }}
+
+// String returns a human readable representation of Flags{{ $size.Size }}.
+func (f Flags{{ $size.Size }}) String() string {
+    var (
+        i   int
+        val bool
+        buf []byte
+    )
+
+    // Make a prealloc est. based on longest-possible value
+    const prealloc = 1+(len("false ")*{{ $size.Size }})-1+1
+    buf = make([]byte, prealloc)
+
+    buf[i] = '{'
+    i++
+
+    {{ range $idx := .Bits }}
+    val = f.Get{{ $idx }}()
+    i += copy(buf[i:], bool2str(val))
+    buf[i] = ' '
+    i++
+    {{ end }}
+
+    buf[i-1] = '}'
+    buf = buf[:i]
+
+    return *(*string)(unsafe.Pointer(&buf))
+}
+
+// GoString returns a more verbose human readable representation of Flags{{ $size.Size }}.
+func (f Flags{{ $size.Size }})GoString() string {
+    var (
+        i   int
+        val bool
+        buf []byte
+    )
+
+    // Make a prealloc est. based on longest-possible value
+    const prealloc = len("bitutil.Flags{{ $size.Size }}{")+(len("{{ sub $size.Size 1 }}=false ")*{{ $size.Size }})-1+1
+    buf = make([]byte, prealloc)
+
+    i += copy(buf[i:], "bitutil.Flags{{ $size.Size }}{")
+
+    {{ range $idx := .Bits }}
+    val = f.Get{{ $idx }}()
+    i += copy(buf[i:], "{{ $idx }}=")
+    i += copy(buf[i:], bool2str(val))
+    buf[i] = ' '
+    i++
+    {{ end }}
+ 
+    buf[i-1] = '}'
+    buf = buf[:i]
+
+    return *(*string)(unsafe.Pointer(&buf))
+}
+
+{{ end }}
+
+func bool2str(b bool) string {
+    if b {
+        return "true"
+    }
+    return "false"
+}

vendor/codeberg.org/gruf/go-bitutil/flag_test.tpl

@@ -0,0 +1,98 @@
+package bitutil_test
+
+import (
+    "strings"
+    "testing"
+
+    "codeberg.org/gruf/go-bytes"
+)
+
+{{ range $idx, $size := . }}
+
+func TestFlags{{ $size.Size }}Get(t *testing.T) {
+    var mask, flags bitutil.Flags{{ $size.Size }}
+
+    {{ range $idx := $size.Bits }}
+
+    mask = bitutil.Flags{{ $size.Size }}(1) << {{ $idx }}
+
+    flags = 0
+
+    flags |= mask
+    if !flags.Get({{ $idx }}) {
+        t.Error("failed .Get() set Flags{{ $size.Size }} bit at index {{ $idx }}")
+    }
+
+    flags = ^bitutil.Flags{{ $size.Size }}(0)
+
+    flags &= ^mask
+    if flags.Get({{ $idx }}) {
+        t.Error("failed .Get() unset Flags{{ $size.Size }} bit at index {{ $idx }}")
+    }
+
+    flags = 0
+
+    flags |= mask
+    if !flags.Get{{ $idx }}() {
+        t.Error("failed .Get{{ $idx }}() set Flags{{ $size.Size }} bit at index {{ $idx }}")
+    }
+
+    flags = ^bitutil.Flags{{ $size.Size }}(0)
+
+    flags &= ^mask
+    if flags.Get{{ $idx }}() {
+        t.Error("failed .Get{{ $idx }}() unset Flags{{ $size.Size }} bit at index {{ $idx }}")
+    }
+
+    {{ end }}
+}
+
+func TestFlags{{ $size.Size }}Set(t *testing.T) {
+    var mask, flags bitutil.Flags{{ $size.Size }}
+
+    {{ range $idx := $size.Bits }}
+
+    mask = bitutil.Flags{{ $size.Size }}(1) << {{ $idx }}
+
+    flags = 0
+
+    flags = flags.Set({{ $idx }})
+    if flags & mask == 0 {
+        t.Error("failed .Set() Flags{{ $size.Size }} bit at index {{ $idx }}")
+    }
+
+    flags = 0
+
+    flags = flags.Set{{ $idx }}()
+    if flags & mask == 0 {
+        t.Error("failed .Set{{ $idx }}() Flags{{ $size.Size }} bit at index {{ $idx }}")
+    }
+
+    {{ end }}
+}
+
+func TestFlags{{ $size.Size }}Unset(t *testing.T) {
+    var mask, flags bitutil.Flags{{ $size.Size }}
+
+    {{ range $idx := $size.Bits }}
+
+    mask = bitutil.Flags{{ $size.Size }}(1) << {{ $idx }}
+
+    flags = ^bitutil.Flags{{ $size.Size }}(0)
+
+    flags = flags.Unset({{ $idx }})
+    if flags & mask != 0 {
+        t.Error("failed .Unset() Flags{{ $size.Size }} bit at index {{ $idx }}")
+    }
+
+    flags = ^bitutil.Flags{{ $size.Size }}(0)
+
+    flags = flags.Unset{{ $idx }}()
+    if flags & mask != 0 {
+        t.Error("failed .Unset{{ $idx }}() Flags{{ $size.Size }} bit at index {{ $idx }}")
+    }
+
+    {{ end }}
+}
+
+{{ end }}

vendor/codeberg.org/gruf/go-bitutil/pack.go

@@ -0,0 +1,85 @@
+package bitutil
+
+// PackInt8s will pack two signed 8bit integers into an unsigned 16bit integer.
+func PackInt8s(i1, i2 int8) uint16 {
+	const bits = 8
+	const mask = (1 << bits) - 1
+	return uint16(i1)<<bits | uint16(i2)&mask
+}
+
+// UnpackInt8s will unpack two signed 8bit integers from an unsigned 16bit integer.
+func UnpackInt8s(i uint16) (int8, int8) {
+	const bits = 8
+	const mask = (1 << bits) - 1
+	return int8(i >> bits), int8(i & mask)
+}
+
+// PackInt16s will pack two signed 16bit integers into an unsigned 32bit integer.
+func PackInt16s(i1, i2 int16) uint32 {
+	const bits = 16
+	const mask = (1 << bits) - 1
+	return uint32(i1)<<bits | uint32(i2)&mask
+}
+
+// UnpackInt16s will unpack two signed 16bit integers from an unsigned 32bit integer.
+func UnpackInt16s(i uint32) (int16, int16) {
+	const bits = 16
+	const mask = (1 << bits) - 1
+	return int16(i >> bits), int16(i & mask)
+}
+
+// PackInt32s will pack two signed 32bit integers into an unsigned 64bit integer.
+func PackInt32s(i1, i2 int32) uint64 {
+	const bits = 32
+	const mask = (1 << bits) - 1
+	return uint64(i1)<<bits | uint64(i2)&mask
+}
+
+// UnpackInt32s will unpack two signed 32bit integers from an unsigned 64bit integer.
+func UnpackInt32s(i uint64) (int32, int32) {
+	const bits = 32
+	const mask = (1 << bits) - 1
+	return int32(i >> bits), int32(i & mask)
+}
+
+// PackUint8s will pack two unsigned 8bit integers into an unsigned 16bit integer.
+func PackUint8s(u1, u2 uint8) uint16 {
+	const bits = 8
+	const mask = (1 << bits) - 1
+	return uint16(u1)<<bits | uint16(u2)&mask
+}
+
+// UnpackUint8s will unpack two unsigned 8bit integers from an unsigned 16bit integer.
+func UnpackUint8s(u uint16) (uint8, uint8) {
+	const bits = 8
+	const mask = (1 << bits) - 1
+	return uint8(u >> bits), uint8(u & mask)
+}
+
+// PackUint16s will pack two unsigned 16bit integers into an unsigned 32bit integer.
+func PackUint16s(u1, u2 uint16) uint32 {
+	const bits = 16
+	const mask = (1 << bits) - 1
+	return uint32(u1)<<bits | uint32(u2)&mask
+}
+
+// UnpackUint16s will unpack two unsigned 16bit integers from an unsigned 32bit integer.
+func UnpackUint16s(u uint32) (uint16, uint16) {
+	const bits = 16
+	const mask = (1 << bits) - 1
+	return uint16(u >> bits), uint16(u & mask)
+}
+
+// PackUint32s will pack two unsigned 32bit integers into an unsigned 64bit integer.
+func PackUint32s(u1, u2 uint32) uint64 {
+	const bits = 32
+	const mask = (1 << bits) - 1
+	return uint64(u1)<<bits | uint64(u2)&mask
+}
+
+// UnpackUint32s will unpack two unsigned 32bit integers from an unsigned 64bit integer.
+func UnpackUint32s(u uint64) (uint32, uint32) {
+	const bits = 32
+	const mask = (1 << bits) - 1
+	return uint32(u >> bits), uint32(u & mask)
+}

vendor/codeberg.org/gruf/go-bitutil/test.tpl

@@ -0,0 +1,60 @@
+package atomics_test
+
+import (
+    "atomic"
+    "unsafe"
+    "testing"
+
+    "codeberg.org/gruf/go-atomics"
+)
+
+func Test{{ .Name }}StoreLoad(t *testing.T) {
+    for _, test := range {{ .Name }}Tests {
+        val := atomics.New{{ .Name }}()
+
+        val.Store(test.V1)
+
+        if !({{ call .Compare "val.Load()" "test.V1" }}) {
+            t.Fatalf("failed testing .Store and .Load: expect=%v actual=%v", val.Load(), test.V1)
+        }
+
+        val.Store(test.V2)
+
+        if !({{ call .Compare "val.Load()" "test.V2" }}) {
+            t.Fatalf("failed testing .Store and .Load: expect=%v actual=%v", val.Load(), test.V2)
+        }
+    }
+}
+
+func Test{{ .Name }}CAS(t *testing.T) {
+    for _, test := range {{ .Name }}Tests {
+        val := atomics.New{{ .Name }}()
+
+        val.Store(test.V1)
+
+        if val.CAS(test.V2, test.V1) {
+            t.Fatalf("failed testing negative .CAS: test=%+v state=%v", test, val.Load())
+        }
+
+        if !val.CAS(test.V1, test.V2) {
+            t.Fatalf("failed testing positive .CAS: test=%+v state=%v", test, val.Load())
+        }
+    }
+}
+
+func Test{{ .Name }}Swap(t *testing.T) {
+    for _, test := range {{ .Name }}Tests {
+        val := atomics.New{{ .Name }}()
+
+        val.Store(test.V1)
+
+        if !({{ call .Compare "val.Swap(test.V2)" "test.V1" }}) {
+            t.Fatal("failed testing .Swap")
+        }
+
+        if !({{ call .Compare "val.Swap(test.V1)" "test.V2" }}) {
+            t.Fatal("failed testing .Swap")
+        }
+    }
+}
+