vnode

package
v0.1.23 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 5, 2026 License: AGPL-3.0, AGPL-3.0-or-later Imports: 20 Imported by: 0

Documentation

Overview

Package vnode provides virtual filesystem nodes for the FUSE layer.

SourcesVNode handles /sources/{integration}/ paths as a query-based filesystem. Content is accessed ONLY through filesystem queries - native provider content (like messages/, labels/) is not exposed directly.

Usage: 

mkdir /sources/gmail/unread-emails    <- creates query via LLM inference
ls /sources/gmail/unread-emails/      <- executes query, shows results
cat /sources/gmail/unread-emails/.query.as <- shows query definition
cat /sources/gmail/unread-emails/msg.txt <- reads materialized result

Structure: 

/sources/                            <- lists available integrations
/sources/gmail/                      <- lists user-created queries only
/sources/gmail/unread-emails/        <- query folder (mkdir creates)
  .query.as                          <- query definition (JSON)
  2026-01-28_invoice_abc.txt         <- materialized search results

Index

Constants

View Source 
const (
	ToolsPath         = "/tools"
	ToolsPathPrefix   = "/tools/"
	SkillsPath        = "/skills"
	SkillsPathPrefix  = "/skills/"
	TasksPath         = "/tasks"
	TasksPathPrefix   = "/tasks/"
	SourcesPath       = "/sources"
	SourcesPathPrefix = "/sources/"
	ConfigDir         = "/.airstore"
	ConfigFile        = "/.airstore/config"
)

Reserved paths in the virtual filesystem

View Source 
const (
	// ToolsCacheTTL is the time-to-live for the tools cache
	ToolsCacheTTL = 5 * time.Second
)

Variables

View Source 
var (
	ErrReadOnly     = syscall.EROFS
	ErrNotSupported = syscall.ENOTSUP
	ErrNotFound     = syscall.ENOENT
)
View Source 
var Owner struct{ Uid, Gid uint32 }

Owner holds the uid/gid for all filesystem entries. Access through GetOwner() for thread-safe reads. Initialized to current user by default; override with InitOwner().

Functions

func GetOwner added in v0.1.23 

func GetOwner() (uid, gid uint32)

GetOwner returns the current owner uid/gid (thread-safe).

func InitOwner added in v0.1.23 

func InitOwner(uid, gid *uint32)

InitOwner sets file ownership for this mount (thread-safe). If uid/gid are nil, defaults to the current user. To explicitly set root ownership, pass pointers to 0.

func PathIno 

func PathIno(path string) uint64

PathIno generates a stable inode from a path (FNV-1a).

Types

type CacheEntry 

type CacheEntry struct {
	Info      *FileInfo
	Children  []DirEntry
	ChildMeta map[string]*FileInfo
}

CacheEntry holds cached metadata

type Config 

type Config struct {
	GatewayAddr string `json:"gateway_addr"`
	Token       string `json:"token,omitempty"`
}

Config holds the filesystem configuration exposed to tools

type ConfigVNode 

type ConfigVNode struct {
	ReadOnlyBase // Embeds read-only defaults for write operations
	// contains filtered or unexported fields
}

ConfigVNode exposes filesystem configuration at /.airstore Tools read /.airstore/config to discover gateway settings

func NewConfigVNode 

func NewConfigVNode(gatewayAddr, token string) *ConfigVNode

NewConfigVNode creates a ConfigVNode with the given settings

func (*ConfigVNode) Getattr 

func (c *ConfigVNode) Getattr(path string) (*FileInfo, error)

Getattr returns file attributes

func (*ConfigVNode) Open 

func (c *ConfigVNode) Open(path string, flags int) (FileHandle, error)

Open opens a file

func (*ConfigVNode) Prefix 

func (c *ConfigVNode) Prefix() string

Prefix returns the path prefix this node handles

func (*ConfigVNode) Read 

func (c *ConfigVNode) Read(path string, buf []byte, off int64, fh FileHandle) (int, error)

Read reads from the config file

func (*ConfigVNode) Readdir 

func (c *ConfigVNode) Readdir(path string) ([]DirEntry, error)

Readdir returns directory entries

type ContentCache added in v0.1.17 

type ContentCache struct {
	// contains filtered or unexported fields
}

ContentCache is a small in-memory cache for file contents. Entries are served only if the current mtime matches.

func NewContentCache added in v0.1.17 

func NewContentCache() *ContentCache

NewContentCache creates a new content cache for small files.

func (*ContentCache) Get added in v0.1.17 

func (c *ContentCache) Get(path string, currentMtime int64) ([]byte, bool)

Get returns cached content only if mtime matches.

func (*ContentCache) Set added in v0.1.17 

func (c *ContentCache) Set(path string, data []byte, mtime int64)

Set stores content if it is small enough to cache.

type ContentEntry added in v0.1.17 

type ContentEntry struct {
	Data     []byte
	Mtime    int64
	Size     int64
	CachedAt time.Time
}

ContentEntry holds cached file contents with mtime validation.

type ContextVNodeGRPC 

type ContextVNodeGRPC struct {
	// contains filtered or unexported fields
}

ContextVNodeGRPC implements VirtualNode for S3-backed context storage. It supports all read and write operations.

func NewContextVNodeGRPC 

func NewContextVNodeGRPC(conn *grpc.ClientConn, token string) *ContextVNodeGRPC

NewContextVNodeGRPC creates a new context virtual node.

func (*ContextVNodeGRPC) Create 

func (c *ContextVNodeGRPC) Create(path string, flags int, mode uint32) (FileHandle, error)

Create creates a new file

func (*ContextVNodeGRPC) Fsync 

func (c *ContextVNodeGRPC) Fsync(path string, fh FileHandle) error

Fsync is a no-op (writes go directly to S3)

func (*ContextVNodeGRPC) Getattr 

func (c *ContextVNodeGRPC) Getattr(path string) (*FileInfo, error)

Getattr returns file attributes with caching

func (*ContextVNodeGRPC) Mkdir 

func (c *ContextVNodeGRPC) Mkdir(path string, mode uint32) error

Mkdir creates a directory

func (*ContextVNodeGRPC) Open 

func (c *ContextVNodeGRPC) Open(path string, flags int) (FileHandle, error)

Open opens a file, using cache to avoid redundant Stat calls. On macOS, some paths use Open with O_CREAT instead of Create, so we handle that here.

func (*ContextVNodeGRPC) Prefix 

func (c *ContextVNodeGRPC) Prefix() string

func (*ContextVNodeGRPC) Read 

func (c *ContextVNodeGRPC) Read(path string, buf []byte, off int64, fh FileHandle) (int, error)

Read reads file data

func (*ContextVNodeGRPC) Readdir 

func (c *ContextVNodeGRPC) Readdir(path string) ([]DirEntry, error)

Readdir returns directory entries, caching child metadata from enriched response 

func (c *ContextVNodeGRPC) Readlink(path string) (string, error)

Readlink reads symlink target

func (*ContextVNodeGRPC) Release 

func (c *ContextVNodeGRPC) Release(path string, fh FileHandle) error

Release closes a file handle

func (*ContextVNodeGRPC) Rename 

func (c *ContextVNodeGRPC) Rename(oldpath, newpath string) error

Rename moves or renames a file or directory

func (*ContextVNodeGRPC) Rmdir 

func (c *ContextVNodeGRPC) Rmdir(path string) error

Rmdir removes a directory 

func (c *ContextVNodeGRPC) Symlink(target, linkPath string) error

Symlink creates a symbolic link

func (*ContextVNodeGRPC) Truncate 

func (c *ContextVNodeGRPC) Truncate(path string, size int64, fh FileHandle) error

Truncate changes file size

func (*ContextVNodeGRPC) Type 

func (c *ContextVNodeGRPC) Type() VNodeType
func (c *ContextVNodeGRPC) Unlink(path string) error

Unlink removes a file

func (*ContextVNodeGRPC) Write 

func (c *ContextVNodeGRPC) Write(path string, buf []byte, off int64, fh FileHandle) (int, error)

Write writes file data

type DirEntry 

type DirEntry struct {
	Name  string
	Mode  uint32
	Ino   uint64
	Size  int64 // File size (0 for directories)
	Mtime int64 // Unix timestamp (0 = use current time)
}

type FileHandle 

type FileHandle uint64

type FileInfo 

type FileInfo struct {
	Ino                 uint64
	Size                int64
	Mode, Nlink         uint32
	Uid, Gid            uint32
	Atime, Mtime, Ctime time.Time
}

func NewDirInfo 

func NewDirInfo(ino uint64) *FileInfo

func NewExecFileInfo 

func NewExecFileInfo(ino uint64, size int64) *FileInfo

func NewFileInfo 

func NewFileInfo(ino uint64, size int64, mode uint32) *FileInfo

func NewSymlinkInfo 

func NewSymlinkInfo(ino uint64, targetLen int64) *FileInfo

type MetadataCache 

type MetadataCache struct {
	// contains filtered or unexported fields
}

MetadataCache wraps an LRU cache for filesystem metadata with parent-child awareness.

func NewMetadataCache 

func NewMetadataCache() *MetadataCache

NewMetadataCache creates a new cache

func (*MetadataCache) AddChild added in v0.1.17 

func (c *MetadataCache) AddChild(parentPath string, child DirEntry, childInfo *FileInfo)

AddChild adds a new child entry to parent's cache without invalidating existing siblings. This is useful after creating a new file/directory.

func (*MetadataCache) Get 

func (c *MetadataCache) Get(p string) *CacheEntry

Get returns cached entry or nil

func (*MetadataCache) GetInfo 

func (c *MetadataCache) GetInfo(p string) *FileInfo

GetInfo returns FileInfo from cache, checking parent's ChildMeta on miss

func (*MetadataCache) Invalidate 

func (c *MetadataCache) Invalidate(p string)

Invalidate removes path and parent's children cache

func (*MetadataCache) InvalidateChild added in v0.1.17 

func (c *MetadataCache) InvalidateChild(parentPath, childName string)

InvalidateChild removes a specific child from parent's cache without invalidating siblings. This is more efficient than Invalidate when only one child has changed.

func (*MetadataCache) IsNegative 

func (c *MetadataCache) IsNegative(p string) bool

IsNegative returns true if path is known to not exist

func (*MetadataCache) Set 

func (c *MetadataCache) Set(p string, info *FileInfo)

Set caches metadata for a path

func (*MetadataCache) SetNegative 

func (c *MetadataCache) SetNegative(p string)

SetNegative marks path as non-existent

func (*MetadataCache) SetWithChildren 

func (c *MetadataCache) SetWithChildren(p string, children []DirEntry, childMeta map[string]*FileInfo)

SetWithChildren caches directory with enriched child metadata

type ReadOnlyBase 

type ReadOnlyBase struct{}

ReadOnlyBase returns ErrReadOnly for all write operations. Embed this in VNodes that don't support writes (e.g., /tools/).

func (ReadOnlyBase) Create 

func (ReadOnlyBase) Create(string, int, uint32) (FileHandle, error)

func (ReadOnlyBase) Fsync 

func (ReadOnlyBase) Fsync(string, FileHandle) error

func (ReadOnlyBase) Mkdir 

func (ReadOnlyBase) Mkdir(string, uint32) error
func (ReadOnlyBase) Readlink(string) (string, error)

func (ReadOnlyBase) Release 

func (ReadOnlyBase) Release(string, FileHandle) error

func (ReadOnlyBase) Rename 

func (ReadOnlyBase) Rename(string, string) error

func (ReadOnlyBase) Rmdir 

func (ReadOnlyBase) Rmdir(string) error
func (ReadOnlyBase) Symlink(string, string) error

func (ReadOnlyBase) Truncate 

func (ReadOnlyBase) Truncate(string, int64, FileHandle) error

func (ReadOnlyBase) Type 

func (ReadOnlyBase) Type() VNodeType
func (ReadOnlyBase) Unlink(string) error

func (ReadOnlyBase) Write 

func (ReadOnlyBase) Write(string, []byte, int64, FileHandle) (int, error)

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry matches paths to virtual nodes.

func NewRegistry 

func NewRegistry() *Registry

func (*Registry) Fallback 

func (r *Registry) Fallback() VirtualNode

func (*Registry) List 

func (r *Registry) List() []VirtualNode

func (*Registry) Match 

func (r *Registry) Match(path string) VirtualNode

func (*Registry) MatchOrFallback 

func (r *Registry) MatchOrFallback(path string) VirtualNode

func (*Registry) Register 

func (r *Registry) Register(node VirtualNode)

func (*Registry) SetFallback 

func (r *Registry) SetFallback(node VirtualNode)

type SmartQueryBase 

type SmartQueryBase struct{}

SmartQueryBase provides default implementations for smart query VNodes. Embed this in VNodes that support smart queries (e.g., /sources/). Mkdir and Create should be overridden to create smart queries.

func (SmartQueryBase) Fsync 

func (SmartQueryBase) Fsync(string, FileHandle) error
func (SmartQueryBase) Readlink(string) (string, error)

func (SmartQueryBase) Release 

func (SmartQueryBase) Release(string, FileHandle) error

func (SmartQueryBase) Rename 

func (SmartQueryBase) Rename(string, string) error

func (SmartQueryBase) Rmdir 

func (SmartQueryBase) Rmdir(string) error
func (SmartQueryBase) Symlink(string, string) error

func (SmartQueryBase) Truncate 

func (SmartQueryBase) Truncate(string, int64, FileHandle) error

func (SmartQueryBase) Type 

func (SmartQueryBase) Type() VNodeType
func (SmartQueryBase) Unlink(string) error

func (SmartQueryBase) Write 

func (SmartQueryBase) Write(string, []byte, int64, FileHandle) (int, error)

type SourcesVNode 

type SourcesVNode struct {
	SmartQueryBase
	// contains filtered or unexported fields
}

SourcesVNode handles /sources/ - both native content and smart queries.

func NewSourcesVNode 

func NewSourcesVNode(conn *grpc.ClientConn, token string) *SourcesVNode

NewSourcesVNode creates a new SourcesVNode.

func (*SourcesVNode) Cleanup 

func (v *SourcesVNode) Cleanup()

Cleanup stops background goroutines. Called when filesystem is unmounted.

func (*SourcesVNode) Create 

func (v *SourcesVNode) Create(path string, flags int, mode uint32) (FileHandle, error)

Create creates a smart query file.

func (*SourcesVNode) Getattr 

func (v *SourcesVNode) Getattr(path string) (*FileInfo, error)

Getattr returns file/directory attributes.

func (*SourcesVNode) Mkdir 

func (v *SourcesVNode) Mkdir(path string, mode uint32) error

Mkdir creates a smart query folder.

func (*SourcesVNode) Open 

func (v *SourcesVNode) Open(path string, flags int) (FileHandle, error)

Open opens a file.

func (*SourcesVNode) Prefix 

func (v *SourcesVNode) Prefix() string

func (*SourcesVNode) Read 

func (v *SourcesVNode) Read(path string, buf []byte, off int64, fh FileHandle) (int, error)

Read reads file data.

func (*SourcesVNode) Readdir 

func (v *SourcesVNode) Readdir(path string) ([]DirEntry, error)

Readdir lists directory contents. 

func (v *SourcesVNode) Readlink(path string) (string, error)

Readlink reads symlink target. Note: Symlinks are not supported in the query-only model.

func (*SourcesVNode) Release added in v0.1.23 

func (v *SourcesVNode) Release(path string, fh FileHandle) error

Release closes a file handle.

type StorageVNode 

type StorageVNode struct {
	// contains filtered or unexported fields
}

StorageVNode handles S3-backed storage for any path via gRPC. Used as a fallback for paths not matched by specific vnodes.

func NewStorageVNode 

func NewStorageVNode(conn *grpc.ClientConn, token string) *StorageVNode

NewStorageVNode creates a new StorageVNode.

func (*StorageVNode) Cleanup added in v0.1.17 

func (s *StorageVNode) Cleanup()

Cleanup stops background goroutines. Called when filesystem is unmounted.

func (*StorageVNode) Create 

func (s *StorageVNode) Create(path string, flags int, mode uint32) (FileHandle, error)

func (*StorageVNode) Fsync 

func (s *StorageVNode) Fsync(path string, fh FileHandle) error

func (*StorageVNode) Getattr 

func (s *StorageVNode) Getattr(path string) (*FileInfo, error)

func (*StorageVNode) Mkdir 

func (s *StorageVNode) Mkdir(path string, mode uint32) error

func (*StorageVNode) Open 

func (s *StorageVNode) Open(path string, flags int) (FileHandle, error)

func (*StorageVNode) Prefix 

func (s *StorageVNode) Prefix() string

Prefix returns empty - this is a fallback handler

func (*StorageVNode) Read 

func (s *StorageVNode) Read(path string, buf []byte, off int64, fh FileHandle) (int, error)

func (*StorageVNode) Readdir 

func (s *StorageVNode) Readdir(path string) ([]DirEntry, error)
func (s *StorageVNode) Readlink(path string) (string, error)

func (*StorageVNode) Release 

func (s *StorageVNode) Release(path string, fh FileHandle) error

func (*StorageVNode) Rename 

func (s *StorageVNode) Rename(oldpath, newpath string) error

Rename moves or renames a file or directory

func (*StorageVNode) Rmdir 

func (s *StorageVNode) Rmdir(path string) error
func (s *StorageVNode) Symlink(target, linkPath string) error

func (*StorageVNode) Truncate 

func (s *StorageVNode) Truncate(path string, size int64, fh FileHandle) error

func (*StorageVNode) Type 

func (s *StorageVNode) Type() VNodeType
func (s *StorageVNode) Unlink(path string) error

func (*StorageVNode) Write 

func (s *StorageVNode) Write(path string, buf []byte, off int64, fh FileHandle) (int, error)

type TasksVNode 

type TasksVNode struct {
	ReadOnlyBase
	// contains filtered or unexported fields
}

TasksVNode provides /tasks directory listing tasks as files. Each task appears as a file named {task_id}.task Reading the file returns the task logs.

func NewTasksVNode 

func NewTasksVNode(backend repository.BackendRepository, token string) *TasksVNode

NewTasksVNode creates a TasksVNode with database access for task listing. Use this when the backend is available (e.g., in gateway).

func NewTasksVNodeGRPC 

func NewTasksVNodeGRPC(conn *grpc.ClientConn, token string) *TasksVNode

NewTasksVNodeGRPC creates a TasksVNode that fetches tasks via gRPC from the gateway. Use this for CLI mounts where we don't have direct DB access.

func (*TasksVNode) Getattr 

func (t *TasksVNode) Getattr(path string) (*FileInfo, error)

func (*TasksVNode) Open 

func (t *TasksVNode) Open(path string, flags int) (FileHandle, error)

func (*TasksVNode) Prefix 

func (t *TasksVNode) Prefix() string

func (*TasksVNode) Read 

func (t *TasksVNode) Read(path string, buf []byte, off int64, fh FileHandle) (int, error)

func (*TasksVNode) Readdir 

func (t *TasksVNode) Readdir(path string) ([]DirEntry, error)

type ToolsVNode 

type ToolsVNode struct {
	ReadOnlyBase // Embeds read-only defaults for write operations
	// contains filtered or unexported fields
}

ToolsVNode implements VirtualNode for the /tools directory. It serves tool binaries directly via FUSE. Tools are cached with a TTL to allow dynamic updates without remount.

func NewToolsVNode 

func NewToolsVNode(gatewayAddr string, token string, shimBinary []byte) *ToolsVNode

NewToolsVNode creates a new ToolsVNode.

func (*ToolsVNode) Getattr 

func (t *ToolsVNode) Getattr(path string) (*FileInfo, error)

Getattr returns file attributes for paths under /tools

func (*ToolsVNode) Open 

func (t *ToolsVNode) Open(path string, flags int) (FileHandle, error)

Open opens a tool file

func (*ToolsVNode) Prefix 

func (t *ToolsVNode) Prefix() string

Prefix returns the path prefix this node handles

func (*ToolsVNode) Read 

func (t *ToolsVNode) Read(path string, buf []byte, off int64, fh FileHandle) (int, error)

Read reads bytes from a tool binary (served from memory)

func (*ToolsVNode) Readdir 

func (t *ToolsVNode) Readdir(path string) ([]DirEntry, error)

Readdir returns entries in /tools directory

type VNodeType 

type VNodeType int

VNodeType defines the behavior category of a virtual node 

const (
	// VNodeReadOnly is for read-only paths like /tools/, /.airstore/
	VNodeReadOnly VNodeType = iota
	// VNodeSmartQuery is for /sources/{integration}/ - mkdir/touch creates smart queries
	VNodeSmartQuery
	// VNodeWritable is for fully writable paths like /skills/
	VNodeWritable
)

type VirtualNode 

type VirtualNode interface {
	Prefix() string
	Type() VNodeType

	// Read operations
	Getattr(path string) (*FileInfo, error)
	Readdir(path string) ([]DirEntry, error)
	Open(path string, flags int) (FileHandle, error)
	Read(path string, buf []byte, off int64, fh FileHandle) (int, error)
	Readlink(path string) (string, error)

	// Write operations (behavior depends on VNodeType)
	Create(path string, flags int, mode uint32) (FileHandle, error)
	Write(path string, buf []byte, off int64, fh FileHandle) (int, error)
	Truncate(path string, size int64, fh FileHandle) error
	Mkdir(path string, mode uint32) error
	Rmdir(path string) error
	Unlink(path string) error
	Rename(oldpath, newpath string) error
	Symlink(target, linkPath string) error

	// Lifecycle
	Release(path string, fh FileHandle) error
	Fsync(path string, fh FileHandle) error
}

VirtualNode handles a path prefix in the virtual filesystem.

Write semantics by VNodeType:

  • VNodeReadOnly: All writes return ErrReadOnly (e.g., /tools/, /.airstore/)
  • VNodeSmartQuery: Mkdir/Create create smart queries, Write/Unlink/Rmdir not supported
  • VNodeWritable: Full read/write access (e.g., /skills/)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.