Documentation
¶
Overview ¶
Package keyspace provides a logical directory tree abstraction over FDB.
KeySpace defines a schema of named directories with typed keys. KeySpacePath navigates the tree to produce FDB-ready tuples and subspaces.
Matches Java's com.apple.foundationdb.record.provider.foundationdb.keyspace package.
Index ¶
- type Directory
- func (d *Directory) AddSubdirectories(children ...*Directory) *Directory
- func (d *Directory) AddSubdirectory(child *Directory) *Directory
- func (d *Directory) Depth() int
- func (d *Directory) FindChildForValue(value any) *Directory
- func (d *Directory) GetSubdirectories() []*Directory
- func (d *Directory) GetSubdirectory(name string) *Directory
- func (d *Directory) IsConstant() bool
- func (d *Directory) IsLeaf() bool
- func (d *Directory) NameInTree() string
- func (d *Directory) Parent() *Directory
- func (d *Directory) ToPathString() string
- func (d *Directory) ToTree() string
- type FDBResolver
- type KeySpace
- type KeyType
- type LocatableResolver
- type MemoryResolver
- type Path
- func (p *Path) Add(name string, value any) (*Path, error)
- func (p *Path) Depth() int
- func (p *Path) Directory() *Directory
- func (p *Path) DirectoryName() string
- func (p *Path) Equal(other *Path) bool
- func (p *Path) Flatten() []*Path
- func (p *Path) GetValue() any
- func (p *Path) HasSubdirectory(name string) bool
- func (p *Path) IsSameDirectory(other *Path) bool
- func (p *Path) ListSubdirectories() []string
- func (p *Path) Parent() *Path
- func (p *Path) String() string
- func (p *Path) ToRange() (fdb.KeyRange, error)
- func (p *Path) ToSubspace() subspace.Subspace
- func (p *Path) ToTuple() tuple.Tuple
- type ResolverFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Directory ¶
type Directory struct {
Name string
KeyType KeyType
Value any // constant value, or nil for any-value
Resolver ResolverFunc // optional resolver for value transformation
// contains filtered or unexported fields
}
Directory is a node in the KeySpace tree. Each directory has a name, a key type, optional constant value, and optional children.
Matches Java's KeySpaceDirectory.
func NewConstantDirectory ¶
NewConstantDirectory creates a directory node with a fixed constant value.
func NewDirectory ¶
NewDirectory creates a new directory node that accepts any value of the given type.
func ResolverDirectory ¶
func ResolverDirectory(name string, resolver LocatableResolver) *Directory
ResolverDirectory creates a Directory node whose values are resolved through a LocatableResolver — strings in, int64 values stored in FDB.
Input must be a string (the logical name). Output stored in FDB is int64. Matches Java's DirectoryLayerDirectory.isValueValid which rejects non-strings.
The declared KeyType is LONG because that's how the value is stored, but input validation accepts only strings (matching Java).
func (*Directory) AddSubdirectories ¶
AddSubdirectories adds multiple child directories in one call. Returns the parent for chaining. Panics on duplicate names.
func (*Directory) AddSubdirectory ¶
AddSubdirectory adds a child directory. Returns the parent for chaining. Panics if a child with the same name already exists.
func (*Directory) Depth ¶
Depth returns the distance from this directory to the root (0 for root). Matches Java's KeySpaceDirectory.depth().
func (*Directory) FindChildForValue ¶
FindChildForValue returns the child directory that accepts the given value, or nil if no child matches. Constant directories are checked first (matches Java's findChildForValue which prioritizes exact constant matches over open-type matches). Used for reverse resolution.
func (*Directory) GetSubdirectories ¶
GetSubdirectories returns all child directories.
func (*Directory) GetSubdirectory ¶
GetSubdirectory returns a child directory by name, or nil if not found.
func (*Directory) IsConstant ¶
IsConstant returns true if this directory has a fixed value.
func (*Directory) IsLeaf ¶
IsLeaf returns true if this directory has no children. Matches Java's KeySpaceDirectory.isLeaf().
func (*Directory) NameInTree ¶
NameInTree returns the dot-separated path from root to this directory. Matches Java's KeySpaceDirectory.getNameInTree().
func (*Directory) Parent ¶
Parent returns the parent directory, or nil if this is the root. Matches Java's KeySpaceDirectory.getParent().
func (*Directory) ToPathString ¶
ToPathString returns a slash-separated path from root to this directory. Matches Java's KeySpaceDirectory.toPathString().
type FDBResolver ¶
type FDBResolver struct {
// contains filtered or unexported fields
}
FDBResolver is a persistent LocatableResolver backed by an FDB subspace. It stores name→int64 mappings directly (no DirectoryLayer complexity), providing a simpler alternative to Java's ScopedDirectoryLayer.
Storage layout under the given subspace:
subspace.Pack({"n", name}) → int64 value (big-endian)
subspace.Pack({"r", value}) → name (reverse lookup)
subspace.Pack({"c"}) → int64 counter (next value to allocate)
An in-memory cache fronts the FDB reads for hot keys. The cache is transactional-aware: newly allocated mappings are only cached after commit.
func NewFDBResolver ¶
func NewFDBResolver(db fdb.Database, ss subspace.Subspace) *FDBResolver
NewFDBResolver creates a persistent resolver under the given subspace. The database is used for transactions; the subspace holds the mappings.
func (*FDBResolver) CacheSize ¶
func (r *FDBResolver) CacheSize() int
CacheSize returns the number of mappings currently cached in memory.
func (*FDBResolver) InvalidateCache ¶
func (r *FDBResolver) InvalidateCache()
InvalidateCache clears the in-memory cache. Useful for testing or when you know the resolver mappings have been externally modified.
func (*FDBResolver) Resolve ¶
Resolve returns the value for name, allocating and persisting a new one if absent. Safe for concurrent use — FDB transactions handle cross-process contention.
ctx is accepted for LocatableResolver interface compliance but is NOT forwarded to the FDB transaction — db.Transact uses the database's internal context. Use NewFDBResolver with a database configured for the desired deadline.
func (*FDBResolver) ReverseLookup ¶
ReverseLookup returns the name for a value, reading from FDB if not cached.
ctx is accepted for LocatableResolver interface compliance but is NOT forwarded to the FDB transaction — db.ReadTransact uses the database's internal context.
type KeySpace ¶
type KeySpace struct {
// contains filtered or unexported fields
}
KeySpace is the root of a directory tree. It holds one or more root directories.
Matches Java's KeySpace.
func NewKeySpace ¶
NewKeySpace creates a new key space with the given root directory.
func (*KeySpace) Path ¶
Path starts navigating the key space from a named root subdirectory with a value.
func (*KeySpace) PathFromTuple ¶
PathFromTuple resolves a tuple back to a path by matching values against the directory tree. Returns the deepest matching path and any remaining tuple elements that didn't match a directory.
Matches Java's KeySpace.resolveFromKey / KeySpaceDirectory.pathFromKey.
type KeyType ¶
type KeyType int
KeyType defines the FDB tuple type for a directory's key. Matches Java's KeySpaceDirectory.KeyType enum.
func (KeyType) ValidateValue ¶
ValidateValue checks if a value is compatible with this key type.
type LocatableResolver ¶
type LocatableResolver interface {
// Resolve maps a name to a compact int64. Creates the mapping if absent.
Resolve(ctx context.Context, name string) (int64, error)
// ReverseLookup maps a value back to its name. Returns ("", false, nil)
// if the value is not in the resolver.
ReverseLookup(ctx context.Context, value int64) (string, bool, error)
}
LocatableResolver maps string names to compact int64 values and back. Used by DirectoryLayerDirectory for string→long key compression.
Phase 2: this interface defines the contract. Phase 3 will add ScopedDirectoryLayer that uses FDB's directory layer for persistent resolution with metadata.
Matches Java's LocatableResolver (abstract class).
type MemoryResolver ¶
type MemoryResolver struct {
// contains filtered or unexported fields
}
MemoryResolver is an in-memory LocatableResolver for testing. Not persistent — data is lost on restart. Safe for concurrent use.
func NewMemoryResolver ¶
func NewMemoryResolver(startValue int64) *MemoryResolver
NewMemoryResolver creates an in-memory resolver starting at startValue.
func (*MemoryResolver) Resolve ¶
Resolve returns the value for name, allocating a new one if needed.
func (*MemoryResolver) ReverseLookup ¶
ReverseLookup returns the name for a value, or false if not found.
func (*MemoryResolver) Size ¶
func (r *MemoryResolver) Size() int
Size returns the number of mappings stored.
type Path ¶
type Path struct {
// contains filtered or unexported fields
}
Path represents a position in the key space tree with a resolved value.
Matches Java's KeySpacePath.
func (*Path) Directory ¶
Directory returns the directory schema at this path position. Matches Java's KeySpacePath.getDirectory().
func (*Path) DirectoryName ¶
DirectoryName returns the name of the current directory.
func (*Path) Equal ¶
Equal reports whether two paths reference the same directories with the same values at each level. Directories are compared by pointer identity (schema reuse) and values via recordTypeKeyEquals (reflect.DeepEqual + int type normalization, safe for []byte and other non-comparable types).
func (*Path) Flatten ¶
Flatten returns all path elements from root to this position, in order. Matches Java's KeySpacePath.flatten().
func (*Path) HasSubdirectory ¶
HasSubdirectory returns true if a child directory with the given name exists.
func (*Path) IsSameDirectory ¶
IsSameDirectory returns true if two paths reference the same directory in the schema tree (ignoring values).
func (*Path) ListSubdirectories ¶
ListSubdirectories returns the names of available child directories at this position.
func (*Path) String ¶
FullPath returns a human-readable representation of the path from root to here. E.g., "/state=CA/office_id=1234".
func (*Path) ToRange ¶
ToRange returns an FDB key range that covers all entries under this path. Useful for scanning or clearing all data in a directory subtree.
func (*Path) ToSubspace ¶
ToSubspace converts this path to an FDB subspace.
type ResolverFunc ¶
ResolverFunc resolves a directory value before storing it in the path. For example, a DirectoryLayerDirectory would resolve a string name to a compact int64 via FDB's directory layer.
The function receives the raw value and returns the resolved value. Phase 2 (LocatableResolver) will plug into this hook.
Source Files