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 ArgumentError
- type Directory
- func (d *Directory) AddSubdirectories(children ...*Directory) error
- func (d *Directory) AddSubdirectory(child *Directory) error
- 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 KeySpace
- type KeyType
- type LocatableResolver
- type MemoryResolver
- type Path
- func (p *Path) Add(ctx context.Context, 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 ArgumentError ¶
type ArgumentError struct {
Message string
ParentDir string // PARENT_DIR
DirName string // DIR_NAME, when the error names a directory
DirType *KeyType // DIR_TYPE, when the error names a type
DirValue any // DIR_VALUE, for an overlapping constant
KeyTuple tuple.Tuple // key_tuple, for a key no subdirectory holds
KeyPos int // key_tuple_pos
}
ArgumentError is Java's RecordCoreArgumentException from building or reading a key space, with the LogMessageKeys it carries.
func (*ArgumentError) Error ¶
func (e *ArgumentError) Error() string
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 child directories in order, stopping at the first AddSubdirectory error.
func (*Directory) AddSubdirectory ¶
AddSubdirectory adds a child directory, refusing a duplicate name or a same-type sibling unless both are distinct constants, as Java's KeySpaceDirectory.addSubdirectory does.
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 holds the stored value, or nil if none does: Java's findChildForValue, which matches like pathFromKey.
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 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; ctx bounds the directory's resolver, if it has one.
func (*KeySpace) PathFromTuple ¶
PathFromTuple resolves a tuple to its leaf-most path and the elements left past a leaf, as Java's KeySpace.resolveFromKey does; an element no subdirectory holds is an ArgumentError.
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) Add ¶
Add navigates to a child directory with the given value; ctx bounds the directory's resolver, if it has one.
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 caller's context and the raw value and returns the resolved value.
Source Files