contract

Documentation

Overview

Package contract defines the ESFS filesystem and routed-command contract in code: path encoding, path classification, the error model, and the syscall error mapping. These types are the single source of truth shared by the FUSE daemon (esfsd), the shared query core (escore), the routed command shims (esfs-grep/ls/find), and the CLI (esfs).

ESFS exposes Elasticsearch as an SMFS-style filesystem:

/esfs/                         -> visible indices and aliases + virtual files
/esfs/<index>/                 -> documents in <index> + virtual files
/esfs/<index>/<id>             -> a single document rendered as JSON
/esfs/profile.md               -> mount-scope orientation digest (virtual)
/esfs/<index>/profile.md       -> index-scope orientation digest (virtual)
/esfs/<index>/.mapping.json    -> optional local mapping diagnostic (virtual)
/esfs/<index>/.fields.json     -> optional local field-caps diagnostic (virtual)
/esfs/.sync.json               -> mount-scope sync status (virtual)
/esfs/<index>/.sync.json       -> index-scope sync status (virtual)

Document IDs are reversibly encoded to filesystem-safe names (see pathenc.go). Reserved virtual filenames never shadow real documents; a document whose ID collides with a reserved name is exposed through its escaped form.

Index

• Constants
• Variables
• func DecodeID(name string) (id string, hashed bool, err error)
• func EncodeID(id string) (name string, hashed bool)
• func Errno(err error) syscall.Errno
• func ExitCode(err error) int
• func IsHashedName(name string) bool
• func IsReserved(name string) bool
• type Error
  • func Errf(k Kind, format string, args ...any) *Error
  • func Wrap(k Kind, cause error, format string, args ...any) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type Kind
  • func KindOf(err error) Kind
• type Node
  • func ParsePath(rel string) Node
• type NodeKind

Constants

const (
	FileProfile = "profile.md"
	FileSync    = ".sync.json"
	FileMapping = ".mapping.json"
	FileFields  = ".fields.json"
)

Virtual filenames recognized at the mount root.

const MaxNameLen = 255

MaxNameLen is the conservative cross-platform filename byte limit (NAME_MAX is 255 on Linux ext4/APFS). Encoded names must not exceed it.

Variables

var ReservedNames = map[string]struct{}{
	"profile.md":    {},
	".mapping.json": {},
	".fields.json":  {},
	".sync.json":    {},
	".esfs-info":    {},
}

ReservedNames are virtual filenames that never refer to a document. A document whose ID equals one of these is exposed through its encoded form instead.

Functions

func DecodeID

func DecodeID(name string) (id string, hashed bool, err error)

DecodeID reverses EncodeID for raw and reversible names. Hashed names cannot be decoded from the name alone; callers must consult the reverse map and should surface a KindNameTooLong/KindNotFound diagnostic otherwise.

func EncodeID

func EncodeID(id string) (name string, hashed bool)

EncodeID renders a document ID as a filesystem-safe name.

• Safe IDs are returned verbatim.
• Otherwise a reversible "@e=" percent encoding is used when it fits.
• Over-long IDs use a deterministic "@h=" short name; the (name -> id) mapping must be recorded by the caller (DocStore) so reads can resolve it.

hashed reports whether the result is a hashed short name requiring a reverse lookup to decode.

func Errno

func Errno(err error) syscall.Errno

Errno maps an error to the POSIX errno used by the FUSE layer.

func ExitCode

func ExitCode(err error) int

ExitCode maps an error to a CLI/shim exit code. ESFS follows grep's broad convention: 0 match, 1 no match, 2 error. All errors here are exit code 2; callers represent "no match" separately.

func IsHashedName

func IsHashedName(name string) bool

IsHashedName reports whether a name is a hashed short name.

func IsReserved

func IsReserved(name string) bool

IsReserved reports whether name is a reserved virtual filename.

Types

type Error

type Error struct {
	Kind Kind
	Msg  string
	Err  error // optional wrapped cause
}

Error is the canonical ESFS error. It carries a Kind for errno/exit mapping plus a human-readable, diagnostic-friendly message.

func Errf

func Errf(k Kind, format string, args ...any) *Error

Errf builds an *Error with a formatted message.

func Wrap

func Wrap(k Kind, cause error, format string, args ...any) *Error

Wrap builds an *Error wrapping a cause.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Kind

type Kind int

Kind classifies an ESFS error so it can be mapped consistently to a POSIX errno for filesystem callers and to an exit code / diagnostic for the CLI and routed command shims.

const (
	// KindInternal is an unexpected ESFS bug; mapped to EIO.
	KindInternal Kind = iota
	// KindNotFound is a missing document, index, or path; mapped to ENOENT.
	KindNotFound
	// KindPermission is an authn/authz failure; mapped to EACCES.
	KindPermission
	// KindReadOnly is a write to a read-only profile/mount; mapped to EROFS.
	KindReadOnly
	// KindUnsupported is an operation ESFS does not implement (chmod, rename to
	// a new ID, multi-index alias write, etc.); mapped to EPERM.
	KindUnsupported
	// KindInvalidJSON is a flush of content that is not a JSON object; mapped to
	// EINVAL.
	KindInvalidJSON
	// KindConflict is an optimistic-concurrency version conflict; mapped to
	// EAGAIN.
	KindConflict
	// KindUpstream is an Elasticsearch timeout/unavailable/shard failure; mapped
	// to EIO.
	KindUpstream
	// KindNameTooLong is an unencodable/over-long path segment; mapped to
	// ENAMETOOLONG.
	KindNameTooLong
	// KindUsage is a CLI/grep usage or query-planning diagnostic; not a
	// filesystem error. Mapped to EINVAL for FS callers and exit code 2 for the
	// CLI.
	KindUsage
)

func KindOf

func KindOf(err error) Kind

KindOf extracts the Kind from any error, defaulting to KindInternal.

type Node

type Node struct {
	Kind  NodeKind
	Index string // populated for index/document/index-virtual nodes
	ID    string // decoded document ID for NodeDocument
	// HashedName is the on-disk name when the document is exposed via a hashed
	// short name (ID could not be recovered from the name alone).
	HashedName string
}

Node is the parsed result of an ESFS-relative path.

func ParsePath

func ParsePath(rel string) Node

ParsePath classifies a mount-relative slash path (without a leading slash). The empty string is the mount root.

It intentionally does not consult Elasticsearch; it only does structural classification and reversible ID decoding. Existence is resolved later by the catalog/doc store.

type NodeKind

type NodeKind int

NodeKind classifies a path inside the ESFS mount.

const (
	NodeRoot         NodeKind = iota // /esfs
	NodeIndexDir                     // /esfs/<index>
	NodeDocument                     // /esfs/<index>/<id>
	NodeMountProfile                 // /esfs/profile.md
	NodeMountSync                    // /esfs/.sync.json
	NodeIndexProfile                 // /esfs/<index>/profile.md
	NodeIndexSync                    // /esfs/<index>/.sync.json
	NodeIndexMapping                 // /esfs/<index>/.mapping.json
	NodeIndexFields                  // /esfs/<index>/.fields.json
	NodeInvalid                      // not a valid ESFS path
)