Documentation
¶
Overview ¶
Package keys provides deterministic, collision-resistant cache key construction for OpenFGA's storage layer. It encodes heterogeneous fields into a compact TLV (type-length-value) byte sequence that is then hex-encoded for use as a cache key string.
Index ¶
- Variables
- type Array
- type Bool
- type Builder
- func (kb *Builder) Bytes() []byte
- func (kb *Builder) EncodeArray(a []Serializable)
- func (kb *Builder) EncodeArrayHeader(n int)
- func (kb *Builder) EncodeBool(b bool)
- func (kb *Builder) EncodeByte(b byte)
- func (kb *Builder) EncodeBytes(b []byte)
- func (kb *Builder) EncodeMap(entries []MapEntry)
- func (kb *Builder) EncodeMapHeader(n int)
- func (kb *Builder) EncodeNull()
- func (kb *Builder) EncodePair(key Serializable, value Serializable)
- func (kb *Builder) EncodeString(s string)
- func (kb *Builder) EncodeUint64(i uint64)
- func (kb *Builder) EncodeUnset()
- func (kb *Builder) Grow(n int)
- func (kb *Builder) Key() Key
- func (kb *Builder) Reset()
- func (kb *Builder) Serialize(value Serializable)
- func (kb *Builder) Write(b []byte) (int, error)
- func (kb *Builder) WriteByte(b byte) error
- func (kb *Builder) WriteString(s string) (int, error)
- type Byte
- type Bytes
- type Digest
- type Key
- type Map
- type MapEntry
- type Null
- type Pair
- type PbValue
- type PooledBuilder
- type PooledDigest
- type Serializable
- type String
- type Tuple
- type Uint64
- type Unset
Constants ¶
This section is empty.
Variables ¶
var Seed uint64
Seed is the per-process random seed applied to all Digest instances. Randomizing prevents external observers from predicting or deliberately colliding hash outputs (hash-flooding mitigation).
Exported solely so tests can pin it to a known value for deterministic hash output. Production code must not modify Seed: Digest.Reset re-reads it on every call, so changing Seed at runtime invalidates the continuity of any in-flight or already-emitted digests.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder accumulates a TLV-encoded byte sequence from which a cache key can be derived. Each field is self-describing (tagged with type and length where applicable), so keys are unambiguous without delimiters.
func (*Builder) Bytes ¶
Bytes returns the accumulated buffer contents. The returned slice is valid only until the next mutating call on the Builder.
func (*Builder) EncodeArray ¶
func (kb *Builder) EncodeArray(a []Serializable)
EncodeArray writes a as a tagged sequence (tag + element count + each element's own TLV representation).
func (*Builder) EncodeArrayHeader ¶
EncodeArrayHeader writes the tagArray framing (tag + element count) only. The caller must then write exactly n element encodings into the Builder. Mismatched counts produce an unparseable key — this is a discipline contract, not a checked invariant. Prefer EncodeArray when a []Serializable is already in hand; use the header when streaming elements directly to avoid materializing the slice.
func (*Builder) EncodeBool ¶
EncodeBool writes b as a tagged boolean (0x00 for false, 0x01 for true).
func (*Builder) EncodeByte ¶
EncodeByte writes b as a tagged single-byte value.
func (*Builder) EncodeBytes ¶
EncodeBytes writes b as a tagged, length-prefixed byte slice.
func (*Builder) EncodeMap ¶
EncodeMap writes entries as a tagged map (tag + entry count + flat key/value TLVs). The tagMap framing distinguishes maps from arrays, preventing collision between a dictionary and a positional sequence that happen to contain the same values. Use Pair only as a standalone Serializable; map entries are unframed inside tagMap.
func (*Builder) EncodeMapHeader ¶
EncodeMapHeader writes the tagMap framing (tag + entry count) only. The caller must then write exactly 2*n TLVs into the Builder, alternating key and value (flat layout — no per-entry tagPair framing inside tagMap). Mismatched counts or interleaving produce an unparseable key — this is a discipline contract, not a checked invariant.
func (*Builder) EncodeNull ¶
func (kb *Builder) EncodeNull()
EncodeNull emits a bare tagNull marker. Distinct from EncodeBool(false) and EncodeByte(0) so that JSON-style null, boolean false, and the byte 0x00 never collide in the encoded key.
func (*Builder) EncodePair ¶
func (kb *Builder) EncodePair(key Serializable, value Serializable)
EncodePair writes a key-value pair with structural markers separating the key and value portions.
func (*Builder) EncodeString ¶
EncodeString writes s as a tagged, length-prefixed UTF-8 string.
func (*Builder) EncodeUint64 ¶
EncodeUint64 writes i as a tagged 8-byte little-endian integer.
func (*Builder) EncodeUnset ¶
func (kb *Builder) EncodeUnset()
EncodeUnset emits a bare tagUnset marker. Distinct from EncodeNull so that "value absent / kind unset" (e.g., a structpb.Value with no Kind set) and an explicit JSON-style null cannot collide in the encoded key.
func (*Builder) Grow ¶
Grow increases the capacity of the internal buffer by at least n bytes, guaranteeing space for n more bytes of writes without reallocation.
func (*Builder) Reset ¶
func (kb *Builder) Reset()
Reset discards all accumulated content, returning the buffer to empty while retaining its underlying storage for reuse.
func (*Builder) Serialize ¶
func (kb *Builder) Serialize(value Serializable)
Serialize delegates encoding to the value's own WriteTo implementation.
func (*Builder) Write ¶
Write appends raw bytes to the buffer without type-tagging or length-prefixing. Use this for pre-encoded data or fixed prefixes that do not require TLV framing.
type Digest ¶
type Digest struct {
// contains filtered or unexported fields
}
Digest wraps xxhash.Digest with the package-level Seed applied automatically on construction and reset.
func NewDigest ¶
func NewDigest() *Digest
NewDigest returns a new Digest initialized with the package-level Seed.
type Key ¶
type Key struct {
// contains filtered or unexported fields
}
Key is an opaque, immutable cache key derived from TLV-encoded fields. It is comparable and safe for use as a map key or in concurrent data structures.
type Map ¶
type Map []MapEntry
Map is an ordered collection of key-value entries that serializes with the tagMap framing (tagMap + entry count + alternating key/value TLVs). Use Map (rather than Array of Pairs) when the source data is a dictionary or struct-like object whose entries must be distinguishable from a positional sequence.
type MapEntry ¶
type MapEntry struct {
Key Serializable
Value Serializable
}
MapEntry is one entry inside a Map. Map entries use a flat key/value layout inside tagMap framing — no per-entry tagPair/tagKey/tagValue markers — so MapEntry is a plain value struct rather than a Serializable.
type Null ¶
type Null struct{}
Null is a singleton sentinel that serializes as a bare tagNull marker. Use it (instead of Byte(0) or Bool(false)) when the source value is semantically "absence" rather than the boolean false or the byte 0x00.
type Pair ¶
type Pair struct {
Key Serializable
Value Serializable
}
Pair encodes a standalone key/value with tagPair/tagKey/tagValue framing. It is used when a pair must appear outside a Map (for example, as an element of an Array or as a top-level value) and the pair boundary must remain unambiguous. Inside a Map, use MapEntry instead.
type PbValue ¶
PbValue serializes an arbitrary structpb.Value (including nested structs and lists) into the Builder's TLV format. It uses an explicit stack rather than recursion to bound memory growth on deeply nested inputs.
type PooledBuilder ¶
type PooledBuilder struct {
*Builder
// contains filtered or unexported fields
}
PooledBuilder is a Builder obtained from a sync.Pool. Callers must call Close when finished to return it to the pool. The typical pattern:
b := keys.GetBuilder() defer b.Close()
func GetBuilder ¶
func GetBuilder() *PooledBuilder
GetBuilder retrieves a Builder from the pool, ready for use. The returned wrapper must not be copied: each copy carries its own closed flag, so calling Close on more than one copy would return the same Builder to the pool twice.
func (*PooledBuilder) Close ¶
func (b *PooledBuilder) Close()
Close resets the builder and returns it to the pool. Close is idempotent; subsequent calls are no-ops.
type PooledDigest ¶
type PooledDigest struct {
*Digest
// contains filtered or unexported fields
}
PooledDigest is a Digest obtained from a sync.Pool. Callers must call Close when finished to return it to the pool.
func GetDigest ¶
func GetDigest() *PooledDigest
GetDigest retrieves a Digest from the pool, ready for use. Reset is called to ensure the digest uses the current package-level Seed. The returned wrapper must not be copied: each copy carries its own closed flag, so calling Close on more than one copy would return the same Digest to the pool twice.
func (*PooledDigest) Close ¶
func (d *PooledDigest) Close()
Close resets the digest and returns it to the pool. Close is idempotent; subsequent calls are no-ops.
type Serializable ¶
type Serializable interface {
WriteTo(*Builder)
}
Serializable is implemented by types that can encode themselves into the Builder's TLV wire format.
Source Files