core

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Feb 6, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ComputeZipHash 

func ComputeZipHash(zipPath string) (string, error)

ComputeZipHash computes the SHA-256 hash of a zip file.

func ContentsDir 

func ContentsDir(sessionID string) (string, error)

ContentsDir returns the contents/ directory within a session workspace.

func CreateWorkspace 

func CreateWorkspace(session *Session, dirName string) error

CreateWorkspace creates the directory structure for a session workspace.

func DataDir 

func DataDir() (string, error)

DataDir returns the base data directory for zipfs. It follows the XDG Base Directory Specification: - $ZIPFS_DATA_DIR (full override) - $XDG_DATA_HOME/zipfs - ~/.local/share/zipfs (fallback)

func DeleteFile 

func DeleteFile(contentsDir, relativePath string, recursive bool) error

DeleteFile deletes a file or directory from the workspace.

func DeleteSession 

func DeleteSession(id string) error

DeleteSession removes a session workspace.

func Extract 

func Extract(zipPath, destDir string, limits security.Limits) (int, uint64, error)

Extract extracts a zip file to the destination directory. Returns the number of files extracted and the total size in bytes. Uses fail-closed security validation - any single invalid path aborts the entire extraction.

func LockPath 

func LockPath(sessionID string) (string, error)

LockPath returns the path to the lock file for a session.

func MetadataPath 

func MetadataPath(sessionID string) (string, error)

MetadataPath returns the path to the metadata.json file for a session.

func OriginalZipPath 

func OriginalZipPath(sessionID string) (string, error)

OriginalZipPath returns the path to the original.zip file for a session.

func ReadFile 

func ReadFile(contentsDir, relativePath string) ([]byte, error)

ReadFile reads a file from the workspace.

func RemoveWorkspace 

func RemoveWorkspace(session *Session, dirName string) error

RemoveWorkspace removes the entire workspace directory for a session.

func Repack 

func Repack(contentsDir, destZipPath string) error

Repack creates a zip file from the contents of a directory. Does NOT follow symlinks for security.

func RotateBackups 

func RotateBackups(sourcePath string, maxDepth int) (string, error)

RotateBackups rotates backup files for a source zip. Returns the path to the new backup file.

func TouchSession 

func TouchSession(session *Session) error

TouchSession updates the last_accessed_at timestamp.

func TreeView 

func TreeView(contentsDir, relativePath string, maxDepth int) (string, int, int, error)

TreeView generates a tree view of the directory structure.

func UpdateSession 

func UpdateSession(session *Session, dirName string) error

UpdateSession writes the session metadata to disk.

func WorkspaceDir 

func WorkspaceDir(sessionID string) (string, error)

WorkspaceDir returns the directory for a specific session workspace.

func WorkspacesDir 

func WorkspacesDir() (string, error)

WorkspacesDir returns the directory containing all session workspaces.

func WriteFile 

func WriteFile(contentsDir, relativePath string, content []byte, createDirs bool) error

WriteFile writes data to a file in the workspace.

Types

type Config 

type Config struct {
	Security SecurityConfig `json:"security"`
	Defaults DefaultsConfig `json:"defaults"`
}

Config holds global configuration for zipfs.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns the default configuration as specified in ADR-002.

func LoadConfig 

func LoadConfig(dataDir string) (*Config, error)

LoadConfig loads configuration from config.json in the data directory. Falls back to default configuration if config.json doesn't exist. Environment variables override both file and default values.

func (*Config) ToSecurityLimits 

func (c *Config) ToSecurityLimits() security.Limits

ToSecurityLimits converts the config to security.Limits for use with security package.

type DefaultsConfig 

type DefaultsConfig struct {
	BackupRotationDepth int `json:"backup_rotation_depth"`
}

DefaultsConfig holds default values for operations.

type FileEntry 

type FileEntry struct {
	Name       string `json:"name"`
	Type       string `json:"type"` // "file" or "dir"
	SizeBytes  uint64 `json:"size_bytes"`
	ModifiedAt int64  `json:"modified_at"` // Unix timestamp
}

FileEntry represents a file or directory entry.

func ListFiles 

func ListFiles(contentsDir, relativePath string, recursive bool) ([]FileEntry, error)

ListFiles lists files and directories in the workspace.

type GrepMatch 

type GrepMatch struct {
	File        string `json:"file"`
	LineContent string `json:"line_content"`
	LineNumber  int    `json:"line_number"`
}

GrepMatch represents a grep search result.

func GrepFiles 

func GrepFiles(contentsDir, relativePath, pattern, glob string, ignoreCase bool, maxResults int) ([]GrepMatch, int, error)

GrepFiles searches for a pattern in files within the workspace.

type Lock 

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

Lock represents a file-based lock using flock.

func AcquireExclusive 

func AcquireExclusive(path string, timeout time.Duration) (*Lock, error)

AcquireExclusive acquires an exclusive lock on the given path. Only one exclusive lock can be held, and it blocks all shared locks. Blocks until the lock is acquired or timeout is reached.

func AcquireShared 

func AcquireShared(path string, timeout time.Duration) (*Lock, error)

AcquireShared acquires a shared lock on the given path. Multiple shared locks can be held simultaneously. Blocks until the lock is acquired or timeout is reached.

func (*Lock) Release 

func (l *Lock) Release() error

Release releases the lock and closes the file.

type SecurityConfig 

type SecurityConfig struct {
	MaxExtractedSizeBytes uint64  `json:"max_extracted_size_bytes"`
	MaxFileCount          int     `json:"max_file_count"`
	MaxCompressionRatio   float64 `json:"max_compression_ratio"`
	MaxTotalDiskBytes     uint64  `json:"max_total_disk_bytes"`
	MaxSessions           int     `json:"max_sessions"`
	AllowSymlinks         bool    `json:"allow_symlinks"`
	RegexTimeoutMS        int     `json:"regex_timeout_ms"`
}

SecurityConfig holds security limits and constraints.

type Session 

type Session struct {
	ID                 string     `json:"id"`
	Name               string     `json:"name"`
	SourcePath         string     `json:"source_path"`
	CreatedAt          time.Time  `json:"created_at"`
	LastSyncedAt       *time.Time `json:"last_synced_at"`
	LastAccessedAt     time.Time  `json:"last_accessed_at"`
	State              string     `json:"state"` // "open", "syncing"
	ZipHashSHA256      string     `json:"zip_hash_sha256"`
	ExtractedSizeBytes uint64     `json:"extracted_size_bytes"`
	FileCount          int        `json:"file_count"`
}

Session represents a zipfs session with metadata.

func CreateSession 

func CreateSession(sourcePath, name string, cfg *Config) (*Session, error)

CreateSession creates a new session for the given zip file. This implements the "open" workflow from ADR-003.

func GetSession 

func GetSession(identifier string) (*Session, error)

GetSession retrieves a session by name, UUID, or UUID prefix.

func ListSessions 

func ListSessions() ([]*Session, error)

ListSessions returns all active sessions.

func ResolveSession 

func ResolveSession(identifier string) (*Session, error)

ResolveSession implements auto-resolution logic from ADR-003. Returns the session if exactly one exists, otherwise returns an error.

func (*Session) DirName added in v0.2.0 

func (s *Session) DirName() string

DirName returns the directory name used for this session's workspace. It prefers the human-readable Name, falling back to the ID.

type StatusResult 

type StatusResult struct {
	Modified       []string `json:"modified"`
	Added          []string `json:"added"`
	Deleted        []string `json:"deleted"`
	UnchangedCount int      `json:"unchanged_count"`
}

StatusResult represents the result of a status check.

func Status 

func Status(session *Session) (*StatusResult, error)

Status compares the current workspace contents with the original zip.

type SyncResult 

type SyncResult struct {
	StatusError     error
	BackupPath      string
	FilesModified   int
	FilesAdded      int
	FilesDeleted    int
	NewZipSizeBytes uint64
}

SyncResult contains the results of a sync operation.

func Sync 

func Sync(session *Session, force bool, cfg *Config) (*SyncResult, error)

Sync synchronizes the workspace contents back to the source zip file. This implements the sync workflow from ADR-004.

Source Files

View all Source files

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.