Custom FNV-1 hash implementation for use with unique checks (#4)

Just to make sure there are no copyright issues with vendoring code into
the repository, here replace the third party FNV-1 hash implementation
with one that I've written from scratch based on my version over in
Ruby.

Other niceties that go along with the change are:

* I found a small bug wherein River Python had been using FNV-1a hashes
  instead of FNV-1 hashes like the main Go codebase and Python, which
  would have made the unique checks incompatible.

* We get type annotations on the API so more of the project is type
  checked.

* We bring in a test suite to check the correctness of the hashes.

Author: brandur

src/riverqueue/client.py

@@ -2,7 +2,7 @@
 from typing import Optional, Tuple, List, Callable
 
 from .driver import Driver
-from .fnv import fnv1a_64, fnv1a_32
+from .fnv import fnv1_hash
 from .models import (
     InsertOpts,
     Args,
@@ -102,10 +102,10 @@ def check_unique_job(
 
         with self.driver.transaction():
             if self.advisory_lock_prefix is None:
-                lock_key = fnv1a_64(lock_str.encode("utf-8"))
+                lock_key = fnv1_hash(lock_str.encode("utf-8"), 64)
             else:
                 prefix = self.advisory_lock_prefix
-                lock_key = (prefix << 32) | fnv1a_32(lock_str.encode("utf-8"))
+                lock_key = (prefix << 32) | fnv1_hash(lock_str.encode("utf-8"), 32)
 
             lock_key = self.uint64_to_int64(lock_key)
             self.driver.advisory_lock(lock_key)

src/riverqueue/fnv.py

@@ -1,99 +1,42 @@
 """
-Copyright (c) 2015 Lorenz Schori
+FNV is the Fowler–Noll–Vo hash function, a simple hash that's very easy to
+implement, and hash the perfect characteristics for use with the 64 bits of
+available space in a PG advisory lock.
 
-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.
+I'm implemented it myself so that the River package can stay dependency free
+(and because it's quite easy to do).
 """
 
-FNV_32_PRIME = 0x01000193
-FNV_64_PRIME = 0x100000001B3
+from typing import Dict, Literal
 
-FNV0_32_INIT = 0
-FNV0_64_INIT = 0
-FNV1_32_INIT = 0x811C9DC5
-FNV1_32A_INIT = FNV1_32_INIT
-FNV1_64_INIT = 0xCBF29CE484222325
-FNV1_64A_INIT = FNV1_64_INIT
 
-
-def fnv(data, hval_init, fnv_prime, fnv_size):
+def fnv1_hash(data: bytes, size: Literal[32] | Literal[64]) -> int:
     """
-    Core FNV hash algorithm used in FNV0 and FNV1.
+    Hashes data as a 32-bit or 64-bit FNV hash and returns the result. Data
+    should be bytes rather than a string, so encode a string with something like
+    `input_str.encode("utf-8")` or `b"string as bytes"`.
     """
-    assert isinstance(data, bytes)
 
-    hval = hval_init
-    for byte in data:
-        hval = (hval * fnv_prime) % fnv_size
-        hval = hval ^ byte
-    return hval
-
-
-def fnva(data, hval_init, fnv_prime, fnv_size):
-    """
-    Alternative FNV hash algorithm used in FNV-1a.
-    """
     assert isinstance(data, bytes)
 
-    hval = hval_init
-    for byte in data:
-        hval = hval ^ byte
-        hval = (hval * fnv_prime) % fnv_size
-    return hval
-
-
-def fnv0_32(data, hval_init=FNV0_32_INIT):
-    """
-    Returns the 32 bit FNV-0 hash value for the given data.
-    """
-    return fnv(data, hval_init, FNV_32_PRIME, 2**32)
-
+    hash = __OFFSET_BASIS[size]
+    mask = 2**size - 1  # creates a mask of 1s of `size` bits long like 0xffffffff
+    prime = __PRIME[size]
 
-def fnv1_32(data, hval_init=FNV1_32_INIT):
-    """
-    Returns the 32 bit FNV-1 hash value for the given data.
-    """
-    return fnv(data, hval_init, FNV_32_PRIME, 2**32)
-
-
-def fnv1a_32(data, hval_init=FNV1_32_INIT):
-    """
-    Returns the 32 bit FNV-1a hash value for the given data.
-    """
-    return fnva(data, hval_init, FNV_32_PRIME, 2**32)
-
-
-def fnv0_64(data, hval_init=FNV0_64_INIT):
-    """
-    Returns the 64 bit FNV-0 hash value for the given data.
-    """
-    return fnv(data, hval_init, FNV_64_PRIME, 2**64)
+    for byte in data:
+        hash *= prime
+        hash &= mask  # take lower N bits of multiplication product
+        hash ^= byte
 
+    return hash
 
-def fnv1_64(data, hval_init=FNV1_64_INIT):
-    """
-    Returns the 64 bit FNV-1 hash value for the given data.
-    """
-    return fnv(data, hval_init, FNV_64_PRIME, 2**64)
 
+__OFFSET_BASIS: Dict[Literal[32] | Literal[64], int] = {
+    32: 0x811C9DC5,
+    64: 0xCBF29CE484222325,
+}
 
-def fnv1a_64(data, hval_init=FNV1_64_INIT):
-    """
-    Returns the 64 bit FNV-1a hash value for the given data.
-    """
-    return fnva(data, hval_init, FNV_64_PRIME, 2**64)
+__PRIME: Dict[Literal[32] | Literal[64], int] = {
+    32: 0x01000193,
+    64: 0x00000100000001B3,
+}