core/go-io
8
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

[agent/codex] A specs/ folder has been injected into this workspace with R... #15

Merged
Virgil merged 1 commit from agent/a-specs--folder-has-been-injected-into-t into dev 2026-03-27 19:01:55 +00:00
Conversation 1 Commits 1 Files changed 9 +1117
9 changed files with 1117 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

167
specs/RFC.md Normal file
View file

@ -0,0 +1,167 @@
# io
**Import:** `dappco.re/go/core/io`
**Files:** 1
No package doc comment in source.
## Types
### Medium
- **File:** io.go
- **Purpose:** Medium defines the standard interface for a storage backend. This allows for different implementations (e.g., local disk, S3, SFTP) to be used interchangeably.
- **Methods:**
- `Read func(path string) (string, error)` — Read retrieves the content of a file as a string.
- `Write func(path, content string) error` — Write saves the given content to a file, overwriting it if it exists. Default permissions: 0644. For sensitive files, use WriteMode.
- `WriteMode func(path, content string, mode os.FileMode) error` — WriteMode saves content with explicit file permissions. Use 0600 for sensitive files (keys, secrets, encrypted output).
- `EnsureDir func(path string) error` — EnsureDir makes sure a directory exists, creating it if necessary.
- `IsFile func(path string) bool` — IsFile checks if a path exists and is a regular file.
- `FileGet func(path string) (string, error)` — FileGet is a convenience function that reads a file from the medium.
- `FileSet func(path, content string) error` — FileSet is a convenience function that writes a file to the medium.
- `Delete func(path string) error` — Delete removes a file or empty directory.
- `DeleteAll func(path string) error` — DeleteAll removes a file or directory and all its contents recursively.
- `Rename func(oldPath, newPath string) error` — Rename moves a file or directory from oldPath to newPath.
- `List func(path string) ([]fs.DirEntry, error)` — List returns the directory entries for the given path.
- `Stat func(path string) (fs.FileInfo, error)` — Stat returns file information for the given path.
- `Open func(path string) (fs.File, error)` — Open opens the named file for reading.
- `Create func(path string) (goio.WriteCloser, error)` — Create creates or truncates the named file.
- `Append func(path string) (goio.WriteCloser, error)` — Append opens the named file for appending, creating it if it doesn't exist.
- `ReadStream func(path string) (goio.ReadCloser, error)` — ReadStream returns a reader for the file content. Use this for large files to avoid loading the entire content into memory.
- `WriteStream func(path string) (goio.WriteCloser, error)` — WriteStream returns a writer for the file content. Use this for large files to avoid loading the entire content into memory.
- `Exists func(path string) bool` — Exists checks if a path exists (file or directory).
- `IsDir func(path string) bool` — IsDir checks if a path exists and is a directory.
### FileInfo
- **File:** io.go
- **Purpose:** FileInfo provides a simple implementation of fs.FileInfo for mock testing.
- **Fields:**
- `name string` — No doc comment in source.
- `size int64` — No doc comment in source.
- `mode fs.FileMode` — No doc comment in source.
- `modTime time.Time` — No doc comment in source.
- `isDir bool` — No doc comment in source.
- **Associated Methods:**
- `func (fi FileInfo) Name() string` — No doc comment in source.
- `func (fi FileInfo) Size() int64` — No doc comment in source.
- `func (fi FileInfo) Mode() fs.FileMode` — No doc comment in source.
- `func (fi FileInfo) ModTime() time.Time` — No doc comment in source.
- `func (fi FileInfo) IsDir() bool` — No doc comment in source.
- `func (fi FileInfo) Sys() any` — No doc comment in source.
### DirEntry
- **File:** io.go
- **Purpose:** DirEntry provides a simple implementation of fs.DirEntry for mock testing.
- **Fields:**
- `name string` — No doc comment in source.
- `isDir bool` — No doc comment in source.
- `mode fs.FileMode` — No doc comment in source.
- `info fs.FileInfo` — No doc comment in source.
- **Associated Methods:**
- `func (de DirEntry) Name() string` — No doc comment in source.
- `func (de DirEntry) IsDir() bool` — No doc comment in source.
- `func (de DirEntry) Type() fs.FileMode` — No doc comment in source.
- `func (de DirEntry) Info() (fs.FileInfo, error)` — No doc comment in source.
### MockMedium
- **File:** io.go
- **Purpose:** MockMedium is an in-memory implementation of Medium for testing.
- **Fields:**
- `Files map[string]string` — No doc comment in source.
- `Dirs map[string]bool` — No doc comment in source.
- `ModTimes map[string]time.Time` — No doc comment in source.
- **Associated Methods:**
- `func (m *MockMedium) Read(path string) (string, error)` — Read retrieves the content of a file from the mock filesystem.
- `func (m *MockMedium) Write(path, content string) error` — Write saves the given content to a file in the mock filesystem.
- `func (m *MockMedium) WriteMode(path, content string, mode os.FileMode) error` — No doc comment in source.
- `func (m *MockMedium) EnsureDir(path string) error` — EnsureDir records that a directory exists in the mock filesystem.
- `func (m *MockMedium) IsFile(path string) bool` — IsFile checks if a path exists as a file in the mock filesystem.
- `func (m *MockMedium) FileGet(path string) (string, error)` — FileGet is a convenience function that reads a file from the mock filesystem.
- `func (m *MockMedium) FileSet(path, content string) error` — FileSet is a convenience function that writes a file to the mock filesystem.
- `func (m *MockMedium) Delete(path string) error` — Delete removes a file or empty directory from the mock filesystem.
- `func (m *MockMedium) DeleteAll(path string) error` — DeleteAll removes a file or directory and all contents from the mock filesystem.
- `func (m *MockMedium) Rename(oldPath, newPath string) error` — Rename moves a file or directory in the mock filesystem.
- `func (m *MockMedium) Open(path string) (fs.File, error)` — Open opens a file from the mock filesystem.
- `func (m *MockMedium) Create(path string) (goio.WriteCloser, error)` — Create creates a file in the mock filesystem.
- `func (m *MockMedium) Append(path string) (goio.WriteCloser, error)` — Append opens a file for appending in the mock filesystem.
- `func (m *MockMedium) ReadStream(path string) (goio.ReadCloser, error)` — ReadStream returns a reader for the file content in the mock filesystem.
- `func (m *MockMedium) WriteStream(path string) (goio.WriteCloser, error)` — WriteStream returns a writer for the file content in the mock filesystem.
- `func (m *MockMedium) List(path string) ([]fs.DirEntry, error)` — List returns directory entries for the mock filesystem.
- `func (m *MockMedium) Stat(path string) (fs.FileInfo, error)` — Stat returns file information for the mock filesystem.
- `func (m *MockMedium) Exists(path string) bool` — Exists checks if a path exists in the mock filesystem.
- `func (m *MockMedium) IsDir(path string) bool` — IsDir checks if a path is a directory in the mock filesystem.
### MockFile
- **File:** io.go
- **Purpose:** MockFile implements fs.File for MockMedium.
- **Fields:**
- `name string` — No doc comment in source.
- `content []byte` — No doc comment in source.
- `offset int64` — No doc comment in source.
- **Associated Methods:**
- `func (f *MockFile) Stat() (fs.FileInfo, error)` — No doc comment in source.
- `func (f *MockFile) Read(b []byte) (int, error)` — No doc comment in source.
- `func (f *MockFile) Close() error` — No doc comment in source.
### MockWriteCloser
- **File:** io.go
- **Purpose:** MockWriteCloser implements WriteCloser for MockMedium.
- **Fields:**
- `medium *MockMedium` — No doc comment in source.
- `path string` — No doc comment in source.
- `data []byte` — No doc comment in source.
- **Associated Methods:**
- `func (w *MockWriteCloser) Write(p []byte) (int, error)` — No doc comment in source.
- `func (w *MockWriteCloser) Close() error` — No doc comment in source.
## Functions
### init
- **File:** io.go
- **Signature:** `func init()`
- **Purpose:** No doc comment in source.
### NewSandboxed
- **File:** io.go
- **Signature:** `func NewSandboxed(root string) (Medium, error)`
- **Purpose:** NewSandboxed creates a new Medium sandboxed to the given root directory. All file operations are restricted to paths within the root. The root directory will be created if it doesn't exist.
### Read
- **File:** io.go
- **Signature:** `func Read(m Medium, path string) (string, error)`
- **Purpose:** Read retrieves the content of a file from the given medium.
### Write
- **File:** io.go
- **Signature:** `func Write(m Medium, path, content string) error`
- **Purpose:** Write saves the given content to a file in the given medium.
### ReadStream
- **File:** io.go
- **Signature:** `func ReadStream(m Medium, path string) (goio.ReadCloser, error)`
- **Purpose:** ReadStream returns a reader for the file content from the given medium.
### WriteStream
- **File:** io.go
- **Signature:** `func WriteStream(m Medium, path string) (goio.WriteCloser, error)`
- **Purpose:** WriteStream returns a writer for the file content in the given medium.
### EnsureDir
- **File:** io.go
- **Signature:** `func EnsureDir(m Medium, path string) error`
- **Purpose:** EnsureDir makes sure a directory exists in the given medium.
### IsFile
- **File:** io.go
- **Signature:** `func IsFile(m Medium, path string) bool`
- **Purpose:** IsFile checks if a path exists and is a regular file in the given medium.
### Copy
- **File:** io.go
- **Signature:** `func Copy(src Medium, srcPath string, dst Medium, dstPath string) error`
- **Purpose:** Copy copies a file from one medium to another.
### NewMockMedium
- **File:** io.go
- **Signature:** `func NewMockMedium() *MockMedium`
- **Purpose:** NewMockMedium creates a new MockMedium instance.

106
specs/datanode/RFC.md Normal file
View file

@ -0,0 +1,106 @@
# datanode
**Import:** `dappco.re/go/core/io/datanode`
**Files:** 1
Package datanode provides an in-memory io.Medium backed by Borg's DataNode.
DataNode is an in-memory fs.FS that serializes to tar. Wrapping it as a
Medium lets any code that works with io.Medium transparently operate on
an in-memory filesystem that can be snapshotted, shipped as a crash report,
or wrapped in a TIM container for runc execution.
## Types
### Medium
- **File:** client.go
- **Purpose:** Medium is an in-memory storage backend backed by a Borg DataNode. All paths are relative (no leading slash). Thread-safe via RWMutex.
- **Fields:**
- `dn *borgdatanode.DataNode` — No doc comment in source.
- `dirs map[string]bool` — explicit directory tracking
- `mu sync.RWMutex` — No doc comment in source.
- **Associated Methods:**
- `func (m *Medium) Snapshot() ([]byte, error)` — Snapshot serializes the entire filesystem to a tarball. Use this for crash reports, workspace packaging, or TIM creation.
- `func (m *Medium) Restore(data []byte) error` — Restore replaces the filesystem contents from a tarball.
- `func (m *Medium) DataNode() *borgdatanode.DataNode` — DataNode returns the underlying Borg DataNode. Use this to wrap the filesystem in a TIM container.
- `func (m *Medium) Read(p string) (string, error)` — No doc comment in source.
- `func (m *Medium) Write(p, content string) error` — No doc comment in source.
- `func (m *Medium) WriteMode(p, content string, mode os.FileMode) error` — No doc comment in source.
- `func (m *Medium) EnsureDir(p string) error` — No doc comment in source.
- `func (m *Medium) ensureDirsLocked(p string)` — ensureDirsLocked marks a directory and all ancestors as existing. Caller must hold m.mu.
- `func (m *Medium) IsFile(p string) bool` — No doc comment in source.
- `func (m *Medium) FileGet(p string) (string, error)` — No doc comment in source.
- `func (m *Medium) FileSet(p, content string) error` — No doc comment in source.
- `func (m *Medium) Delete(p string) error` — No doc comment in source.
- `func (m *Medium) DeleteAll(p string) error` — No doc comment in source.
- `func (m *Medium) Rename(oldPath, newPath string) error` — No doc comment in source.
- `func (m *Medium) List(p string) ([]fs.DirEntry, error)` — No doc comment in source.
- `func (m *Medium) Stat(p string) (fs.FileInfo, error)` — No doc comment in source.
- `func (m *Medium) Open(p string) (fs.File, error)` — No doc comment in source.
- `func (m *Medium) Create(p string) (goio.WriteCloser, error)` — No doc comment in source.
- `func (m *Medium) Append(p string) (goio.WriteCloser, error)` — No doc comment in source.
- `func (m *Medium) ReadStream(p string) (goio.ReadCloser, error)` — No doc comment in source.
- `func (m *Medium) WriteStream(p string) (goio.WriteCloser, error)` — No doc comment in source.
- `func (m *Medium) Exists(p string) bool` — No doc comment in source.
- `func (m *Medium) IsDir(p string) bool` — No doc comment in source.
- `func (m *Medium) hasPrefixLocked(prefix string) (bool, error)` — hasPrefixLocked checks if any file path starts with prefix. Caller holds lock.
- `func (m *Medium) collectAllLocked() ([]string, error)` — collectAllLocked returns all file paths in the DataNode. Caller holds lock.
- `func (m *Medium) readFileLocked(name string) ([]byte, error)` — No doc comment in source.
- `func (m *Medium) removeFileLocked(target string) error` — removeFileLocked removes a single file by rebuilding the DataNode. This is necessary because Borg's DataNode doesn't expose a Remove method. Caller must hold m.mu write lock.
### writeCloser
- **File:** client.go
- **Purpose:** No doc comment in source.
- **Fields:**
- `m *Medium` — No doc comment in source.
- `path string` — No doc comment in source.
- `buf []byte` — No doc comment in source.
- **Associated Methods:**
- `func (w *writeCloser) Write(p []byte) (int, error)` — No doc comment in source.
- `func (w *writeCloser) Close() error` — No doc comment in source.
### dirEntry
- **File:** client.go
- **Purpose:** No doc comment in source.
- **Fields:**
- `name string` — No doc comment in source.
- **Associated Methods:**
- `func (d *dirEntry) Name() string` — No doc comment in source.
- `func (d *dirEntry) IsDir() bool` — No doc comment in source.
- `func (d *dirEntry) Type() fs.FileMode` — No doc comment in source.
- `func (d *dirEntry) Info() (fs.FileInfo, error)` — No doc comment in source.
### fileInfo
- **File:** client.go
- **Purpose:** No doc comment in source.
- **Fields:**
- `name string` — No doc comment in source.
- `size int64` — No doc comment in source.
- `mode fs.FileMode` — No doc comment in source.
- `modTime time.Time` — No doc comment in source.
- `isDir bool` — No doc comment in source.
- **Associated Methods:**
- `func (fi *fileInfo) Name() string` — No doc comment in source.
- `func (fi *fileInfo) Size() int64` — No doc comment in source.
- `func (fi *fileInfo) Mode() fs.FileMode` — No doc comment in source.
- `func (fi *fileInfo) ModTime() time.Time` — No doc comment in source.
- `func (fi *fileInfo) IsDir() bool` — No doc comment in source.
- `func (fi *fileInfo) Sys() any` — No doc comment in source.
## Functions
### New
- **File:** client.go
- **Signature:** `func New() *Medium`
- **Purpose:** New creates a new empty DataNode Medium.
### FromTar
- **File:** client.go
- **Signature:** `func FromTar(data []byte) (*Medium, error)`
- **Purpose:** FromTar creates a Medium from a tarball, restoring all files.
### clean
- **File:** client.go
- **Signature:** `func clean(p string) string`
- **Purpose:** clean normalises a path: strips leading slash, cleans traversal.

104
specs/local/RFC.md Normal file
View file

@ -0,0 +1,104 @@
# local
**Import:** `dappco.re/go/core/io/local`
**Files:** 1
Package local provides a local filesystem implementation of the io.Medium interface.
## Types
### Medium
- **File:** client.go
- **Purpose:** Medium is a local filesystem storage backend.
- **Fields:**
- `root string` — No doc comment in source.
- **Associated Methods:**
- `func (m *Medium) path(p string) string` — path sanitises and returns the full path. Absolute paths are sandboxed under root (unless root is "/").
- `func (m *Medium) validatePath(p string) (string, error)` — validatePath ensures the path is within the sandbox, following symlinks if they exist.
- `func (m *Medium) Read(p string) (string, error)` — Read returns file contents as string.
- `func (m *Medium) Write(p, content string) error` — Write saves content to file, creating parent directories as needed. Files are created with mode 0644. For sensitive files (keys, secrets), use WriteMode with 0600.
- `func (m *Medium) WriteMode(p, content string, mode os.FileMode) error` — WriteMode saves content to file with explicit permissions. Use 0600 for sensitive files (encryption output, private keys, auth hashes).
- `func (m *Medium) EnsureDir(p string) error` — EnsureDir creates directory if it doesn't exist.
- `func (m *Medium) IsDir(p string) bool` — IsDir returns true if path is a directory.
- `func (m *Medium) IsFile(p string) bool` — IsFile returns true if path is a regular file.
- `func (m *Medium) Exists(p string) bool` — Exists returns true if path exists.
- `func (m *Medium) List(p string) ([]fs.DirEntry, error)` — List returns directory entries.
- `func (m *Medium) Stat(p string) (fs.FileInfo, error)` — Stat returns file info.
- `func (m *Medium) Open(p string) (fs.File, error)` — Open opens the named file for reading.
- `func (m *Medium) Create(p string) (goio.WriteCloser, error)` — Create creates or truncates the named file.
- `func (m *Medium) Append(p string) (goio.WriteCloser, error)` — Append opens the named file for appending, creating it if it doesn't exist.
- `func (m *Medium) ReadStream(path string) (goio.ReadCloser, error)` — ReadStream returns a reader for the file content. This is a convenience wrapper around Open that exposes a streaming-oriented API, as required by the io.Medium interface, while Open provides the more general filesystem-level operation. Both methods are kept for semantic clarity and backward compatibility.
- `func (m *Medium) WriteStream(path string) (goio.WriteCloser, error)` — WriteStream returns a writer for the file content. This is a convenience wrapper around Create that exposes a streaming-oriented API, as required by the io.Medium interface, while Create provides the more general filesystem-level operation. Both methods are kept for semantic clarity and backward compatibility.
- `func (m *Medium) Delete(p string) error` — Delete removes a file or empty directory.
- `func (m *Medium) DeleteAll(p string) error` — DeleteAll removes a file or directory recursively.
- `func (m *Medium) Rename(oldPath, newPath string) error` — Rename moves a file or directory.
- `func (m *Medium) FileGet(p string) (string, error)` — FileGet is an alias for Read.
- `func (m *Medium) FileSet(p, content string) error` — FileSet is an alias for Write.
## Functions
### New
- **File:** client.go
- **Signature:** `func New(root string) (*Medium, error)`
- **Purpose:** New creates a new local Medium rooted at the given directory. Pass "/" for full filesystem access, or a specific path to sandbox.
### dirSeparator
- **File:** client.go
- **Signature:** `func dirSeparator() string`
- **Purpose:** No doc comment in source.
### normalisePath
- **File:** client.go
- **Signature:** `func normalisePath(p string) string`
- **Purpose:** No doc comment in source.
### currentWorkingDir
- **File:** client.go
- **Signature:** `func currentWorkingDir() string`
- **Purpose:** No doc comment in source.
### absolutePath
- **File:** client.go
- **Signature:** `func absolutePath(p string) string`
- **Purpose:** No doc comment in source.
### cleanSandboxPath
- **File:** client.go
- **Signature:** `func cleanSandboxPath(p string) string`
- **Purpose:** No doc comment in source.
### splitPathParts
- **File:** client.go
- **Signature:** `func splitPathParts(p string) []string`
- **Purpose:** No doc comment in source.
### resolveSymlinksPath
- **File:** client.go
- **Signature:** `func resolveSymlinksPath(p string) (string, error)`
- **Purpose:** No doc comment in source.
### resolveSymlinksRecursive
- **File:** client.go
- **Signature:** `func resolveSymlinksRecursive(p string, seen map[string]struct{}) (string, error)`
- **Purpose:** No doc comment in source.
### isWithinRoot
- **File:** client.go
- **Signature:** `func isWithinRoot(root, target string) bool`
- **Purpose:** No doc comment in source.
### canonicalPath
- **File:** client.go
- **Signature:** `func canonicalPath(p string) string`
- **Purpose:** No doc comment in source.
### isProtectedPath
- **File:** client.go
- **Signature:** `func isProtectedPath(full string) bool`
- **Purpose:** No doc comment in source.
### logSandboxEscape
- **File:** client.go
- **Signature:** `func logSandboxEscape(root, path, attempted string)`
- **Purpose:** No doc comment in source.

138
specs/node/RFC.md Normal file
View file

@ -0,0 +1,138 @@
# node
**Import:** `dappco.re/go/core/io/node`
**Files:** 1
Package node provides an in-memory filesystem implementation of io.Medium
ported from Borg's DataNode. It stores files in memory with implicit
directory structure and supports tar serialisation.
## Types
### Node
- **File:** node.go
- **Purpose:** Node is an in-memory filesystem that implements coreio.Node (and therefore coreio.Medium). Directories are implicit -- they exist whenever a file path contains a "/".
- **Fields:**
- `files map[string]*dataFile` — No doc comment in source.
- **Associated Methods:**
- `func (n *Node) AddData(name string, content []byte)` — AddData stages content in the in-memory filesystem.
- `func (n *Node) ToTar() ([]byte, error)` — ToTar serialises the entire in-memory tree to a tar archive.
- `func (n *Node) LoadTar(data []byte) error` — LoadTar replaces the in-memory tree with the contents of a tar archive.
- `func (n *Node) WalkNode(root string, fn fs.WalkDirFunc) error` — WalkNode walks the in-memory tree, calling fn for each entry.
- `func (n *Node) Walk(root string, fn fs.WalkDirFunc, opts ...WalkOptions) error` — Walk walks the in-memory tree with optional WalkOptions.
- `func (n *Node) ReadFile(name string) ([]byte, error)` — ReadFile returns the content of the named file as a byte slice. Implements fs.ReadFileFS.
- `func (n *Node) CopyFile(src, dst string, perm fs.FileMode) error` — CopyFile copies a file from the in-memory tree to the local filesystem.
- `func (n *Node) CopyTo(target coreio.Medium, sourcePath, destPath string) error` — CopyTo copies a file (or directory tree) from the node to any Medium.
- `func (n *Node) Open(name string) (fs.File, error)` — Open opens a file from the Node. Implements fs.FS.
- `func (n *Node) Stat(name string) (fs.FileInfo, error)` — Stat returns file information for the given path.
- `func (n *Node) ReadDir(name string) ([]fs.DirEntry, error)` — ReadDir reads and returns all directory entries for the named directory.
- `func (n *Node) Read(p string) (string, error)` — Read retrieves the content of a file as a string.
- `func (n *Node) Write(p, content string) error` — Write saves the given content to a file, overwriting it if it exists.
- `func (n *Node) WriteMode(p, content string, mode os.FileMode) error` — WriteMode saves content with explicit permissions (no-op for in-memory node).
- `func (n *Node) FileGet(p string) (string, error)` — FileGet is an alias for Read.
- `func (n *Node) FileSet(p, content string) error` — FileSet is an alias for Write.
- `func (n *Node) EnsureDir(_ string) error` — EnsureDir is a no-op because directories are implicit in Node.
- `func (n *Node) Exists(p string) bool` — Exists checks if a path exists (file or directory).
- `func (n *Node) IsFile(p string) bool` — IsFile checks if a path exists and is a regular file.
- `func (n *Node) IsDir(p string) bool` — IsDir checks if a path exists and is a directory.
- `func (n *Node) Delete(p string) error` — Delete removes a single file.
- `func (n *Node) DeleteAll(p string) error` — DeleteAll removes a file or directory and all children.
- `func (n *Node) Rename(oldPath, newPath string) error` — Rename moves a file from oldPath to newPath.
- `func (n *Node) List(p string) ([]fs.DirEntry, error)` — List returns directory entries for the given path.
- `func (n *Node) Create(p string) (goio.WriteCloser, error)` — Create creates or truncates the named file, returning a WriteCloser. Content is committed to the Node on Close.
- `func (n *Node) Append(p string) (goio.WriteCloser, error)` — Append opens the named file for appending, creating it if needed. Content is committed to the Node on Close.
- `func (n *Node) ReadStream(p string) (goio.ReadCloser, error)` — ReadStream returns a ReadCloser for the file content.
- `func (n *Node) WriteStream(p string) (goio.WriteCloser, error)` — WriteStream returns a WriteCloser for the file content.
### WalkOptions
- **File:** node.go
- **Purpose:** WalkOptions configures the behaviour of Walk.
- **Fields:**
- `MaxDepth int` — MaxDepth limits how many directory levels to descend. 0 means unlimited.
- `Filter func(path string, d fs.DirEntry) bool` — Filter, if set, is called for each entry. Return true to include the entry (and descend into it if it is a directory).
- `SkipErrors bool` — SkipErrors suppresses errors (e.g. nonexistent root) instead of propagating them through the callback.
### nodeWriter
- **File:** node.go
- **Purpose:** nodeWriter buffers writes and commits them to the Node on Close.
- **Fields:**
- `node *Node` — No doc comment in source.
- `path string` — No doc comment in source.
- `buf []byte` — No doc comment in source.
- **Associated Methods:**
- `func (w *nodeWriter) Write(p []byte) (int, error)` — No doc comment in source.
- `func (w *nodeWriter) Close() error` — No doc comment in source.
### dataFile
- **File:** node.go
- **Purpose:** dataFile represents a file in the Node.
- **Fields:**
- `name string` — No doc comment in source.
- `content []byte` — No doc comment in source.
- `modTime time.Time` — No doc comment in source.
- **Associated Methods:**
- `func (d *dataFile) Stat() (fs.FileInfo, error)` — No doc comment in source.
- `func (d *dataFile) Read(_ []byte) (int, error)` — No doc comment in source.
- `func (d *dataFile) Close() error` — No doc comment in source.
### dataFileInfo
- **File:** node.go
- **Purpose:** dataFileInfo implements fs.FileInfo for a dataFile.
- **Fields:**
- `file *dataFile` — No doc comment in source.
- **Associated Methods:**
- `func (d *dataFileInfo) Name() string` — No doc comment in source.
- `func (d *dataFileInfo) Size() int64` — No doc comment in source.
- `func (d *dataFileInfo) Mode() fs.FileMode` — No doc comment in source.
- `func (d *dataFileInfo) ModTime() time.Time` — No doc comment in source.
- `func (d *dataFileInfo) IsDir() bool` — No doc comment in source.
- `func (d *dataFileInfo) Sys() any` — No doc comment in source.
### dataFileReader
- **File:** node.go
- **Purpose:** dataFileReader implements fs.File for reading a dataFile.
- **Fields:**
- `file *dataFile` — No doc comment in source.
- `reader *bytes.Reader` — No doc comment in source.
- **Associated Methods:**
- `func (d *dataFileReader) Stat() (fs.FileInfo, error)` — No doc comment in source.
- `func (d *dataFileReader) Read(p []byte) (int, error)` — No doc comment in source.
- `func (d *dataFileReader) Close() error` — No doc comment in source.
### dirInfo
- **File:** node.go
- **Purpose:** dirInfo implements fs.FileInfo for an implicit directory.
- **Fields:**
- `name string` — No doc comment in source.
- `modTime time.Time` — No doc comment in source.
- **Associated Methods:**
- `func (d *dirInfo) Name() string` — No doc comment in source.
- `func (d *dirInfo) Size() int64` — No doc comment in source.
- `func (d *dirInfo) Mode() fs.FileMode` — No doc comment in source.
- `func (d *dirInfo) ModTime() time.Time` — No doc comment in source.
- `func (d *dirInfo) IsDir() bool` — No doc comment in source.
- `func (d *dirInfo) Sys() any` — No doc comment in source.
### dirFile
- **File:** node.go
- **Purpose:** dirFile implements fs.File for a directory.
- **Fields:**
- `path string` — No doc comment in source.
- `modTime time.Time` — No doc comment in source.
- **Associated Methods:**
- `func (d *dirFile) Stat() (fs.FileInfo, error)` — No doc comment in source.
- `func (d *dirFile) Read([]byte) (int, error)` — No doc comment in source.
- `func (d *dirFile) Close() error` — No doc comment in source.
## Functions
### New
- **File:** node.go
- **Signature:** `func New() *Node`
- **Purpose:** New creates a new, empty Node.
### FromTar
- **File:** node.go
- **Signature:** `func FromTar(data []byte) (*Node, error)`
- **Purpose:** FromTar creates a new Node from a tar archive.

137
specs/s3/RFC.md Normal file
View file

@ -0,0 +1,137 @@
# s3
**Import:** `dappco.re/go/core/io/s3`
**Files:** 1
Package s3 provides an S3-backed implementation of the io.Medium interface.
## Types
### s3API
- **File:** s3.go
- **Purpose:** s3API is the subset of the S3 client API used by this package. This allows for interface-based mocking in tests.
- **Methods:**
- `GetObject func(ctx context.Context, params *s3.GetObjectInput, optFns ...func(*s3.Options)) (*s3.GetObjectOutput, error)` — No doc comment in source.
- `PutObject func(ctx context.Context, params *s3.PutObjectInput, optFns ...func(*s3.Options)) (*s3.PutObjectOutput, error)` — No doc comment in source.
- `DeleteObject func(ctx context.Context, params *s3.DeleteObjectInput, optFns ...func(*s3.Options)) (*s3.DeleteObjectOutput, error)` — No doc comment in source.
- `DeleteObjects func(ctx context.Context, params *s3.DeleteObjectsInput, optFns ...func(*s3.Options)) (*s3.DeleteObjectsOutput, error)` — No doc comment in source.
- `HeadObject func(ctx context.Context, params *s3.HeadObjectInput, optFns ...func(*s3.Options)) (*s3.HeadObjectOutput, error)` — No doc comment in source.
- `ListObjectsV2 func(ctx context.Context, params *s3.ListObjectsV2Input, optFns ...func(*s3.Options)) (*s3.ListObjectsV2Output, error)` — No doc comment in source.
- `CopyObject func(ctx context.Context, params *s3.CopyObjectInput, optFns ...func(*s3.Options)) (*s3.CopyObjectOutput, error)` — No doc comment in source.
### Medium
- **File:** s3.go
- **Purpose:** Medium is an S3-backed storage backend implementing the io.Medium interface.
- **Fields:**
- `client s3API` — No doc comment in source.
- `bucket string` — No doc comment in source.
- `prefix string` — No doc comment in source.
- **Associated Methods:**
- `func (m *Medium) key(p string) string` — key returns the full S3 object key for a given path.
- `func (m *Medium) Read(p string) (string, error)` — Read retrieves the content of a file as a string.
- `func (m *Medium) Write(p, content string) error` — Write saves the given content to a file, overwriting it if it exists.
- `func (m *Medium) EnsureDir(_ string) error` — EnsureDir is a no-op for S3 (S3 has no real directories).
- `func (m *Medium) IsFile(p string) bool` — IsFile checks if a path exists and is a regular file (not a "directory" prefix).
- `func (m *Medium) FileGet(p string) (string, error)` — FileGet is a convenience function that reads a file from the medium.
- `func (m *Medium) FileSet(p, content string) error` — FileSet is a convenience function that writes a file to the medium.
- `func (m *Medium) Delete(p string) error` — Delete removes a single object.
- `func (m *Medium) DeleteAll(p string) error` — DeleteAll removes all objects under the given prefix.
- `func (m *Medium) Rename(oldPath, newPath string) error` — Rename moves an object by copying then deleting the original.
- `func (m *Medium) List(p string) ([]fs.DirEntry, error)` — List returns directory entries for the given path using ListObjectsV2 with delimiter.
- `func (m *Medium) Stat(p string) (fs.FileInfo, error)` — Stat returns file information for the given path using HeadObject.
- `func (m *Medium) Open(p string) (fs.File, error)` — Open opens the named file for reading.
- `func (m *Medium) Create(p string) (goio.WriteCloser, error)` — Create creates or truncates the named file. Returns a writer that uploads the content on Close.
- `func (m *Medium) Append(p string) (goio.WriteCloser, error)` — Append opens the named file for appending. It downloads the existing content (if any) and re-uploads the combined content on Close.
- `func (m *Medium) ReadStream(p string) (goio.ReadCloser, error)` — ReadStream returns a reader for the file content.
- `func (m *Medium) WriteStream(p string) (goio.WriteCloser, error)` — WriteStream returns a writer for the file content. Content is uploaded on Close.
- `func (m *Medium) Exists(p string) bool` — Exists checks if a path exists (file or directory prefix).
- `func (m *Medium) IsDir(p string) bool` — IsDir checks if a path exists and is a directory (has objects under it as a prefix).
### Option
- **File:** s3.go
- **Purpose:** Option configures a Medium.
- **Underlying:** `func(*Medium)`
### fileInfo
- **File:** s3.go
- **Purpose:** fileInfo implements fs.FileInfo for S3 objects.
- **Fields:**
- `name string` — No doc comment in source.
- `size int64` — No doc comment in source.
- `mode fs.FileMode` — No doc comment in source.
- `modTime time.Time` — No doc comment in source.
- `isDir bool` — No doc comment in source.
- **Associated Methods:**
- `func (fi *fileInfo) Name() string` — No doc comment in source.
- `func (fi *fileInfo) Size() int64` — No doc comment in source.
- `func (fi *fileInfo) Mode() fs.FileMode` — No doc comment in source.
- `func (fi *fileInfo) ModTime() time.Time` — No doc comment in source.
- `func (fi *fileInfo) IsDir() bool` — No doc comment in source.
- `func (fi *fileInfo) Sys() any` — No doc comment in source.
### dirEntry
- **File:** s3.go
- **Purpose:** dirEntry implements fs.DirEntry for S3 listings.
- **Fields:**
- `name string` — No doc comment in source.
- `isDir bool` — No doc comment in source.
- `mode fs.FileMode` — No doc comment in source.
- `info fs.FileInfo` — No doc comment in source.
- **Associated Methods:**
- `func (de *dirEntry) Name() string` — No doc comment in source.
- `func (de *dirEntry) IsDir() bool` — No doc comment in source.
- `func (de *dirEntry) Type() fs.FileMode` — No doc comment in source.
- `func (de *dirEntry) Info() (fs.FileInfo, error)` — No doc comment in source.
### s3File
- **File:** s3.go
- **Purpose:** s3File implements fs.File for S3 objects.
- **Fields:**
- `name string` — No doc comment in source.
- `content []byte` — No doc comment in source.
- `offset int64` — No doc comment in source.
- `size int64` — No doc comment in source.
- `modTime time.Time` — No doc comment in source.
- **Associated Methods:**
- `func (f *s3File) Stat() (fs.FileInfo, error)` — No doc comment in source.
- `func (f *s3File) Read(b []byte) (int, error)` — No doc comment in source.
- `func (f *s3File) Close() error` — No doc comment in source.
### s3WriteCloser
- **File:** s3.go
- **Purpose:** s3WriteCloser buffers writes and uploads to S3 on Close.
- **Fields:**
- `medium *Medium` — No doc comment in source.
- `key string` — No doc comment in source.
- `data []byte` — No doc comment in source.
- **Associated Methods:**
- `func (w *s3WriteCloser) Write(p []byte) (int, error)` — No doc comment in source.
- `func (w *s3WriteCloser) Close() error` — No doc comment in source.
## Functions
### deleteObjectsError
- **File:** s3.go
- **Signature:** `func deleteObjectsError(prefix string, errs []types.Error) error`
- **Purpose:** No doc comment in source.
### WithPrefix
- **File:** s3.go
- **Signature:** `func WithPrefix(prefix string) Option`
- **Purpose:** WithPrefix sets an optional key prefix for all operations.
### WithClient
- **File:** s3.go
- **Signature:** `func WithClient(client *s3.Client) Option`
- **Purpose:** WithClient sets the S3 client for dependency injection.
### withAPI
- **File:** s3.go
- **Signature:** `func withAPI(api s3API) Option`
- **Purpose:** withAPI sets the s3API interface directly (for testing with mocks).
### New
- **File:** s3.go
- **Signature:** `func New(bucket string, opts ...Option) (*Medium, error)`
- **Purpose:** New creates a new S3 Medium for the given bucket.

171
specs/sigil/RFC.md Normal file
View file

@ -0,0 +1,171 @@
# sigil
**Import:** `dappco.re/go/core/io/sigil`
**Files:** 3
This file implements the Pre-Obfuscation Layer Protocol with
XChaCha20-Poly1305 encryption. The protocol applies a reversible transformation
to plaintext BEFORE it reaches CPU encryption routines, providing defense-in-depth
against side-channel attacks.
The encryption flow is:
plaintext -> obfuscate(nonce) -> encrypt -> [nonce || ciphertext || tag]
The decryption flow is:
[nonce || ciphertext || tag] -> decrypt -> deobfuscate(nonce) -> plaintext
Package sigil provides the Sigil transformation framework for composable,
reversible data transformations.
Sigils are the core abstraction - each sigil implements a specific transformation
(encoding, compression, hashing, encryption) with a uniform interface. Sigils can
be chained together to create transformation pipelines.
Example usage:
hexSigil, _ := sigil.NewSigil("hex")
base64Sigil, _ := sigil.NewSigil("base64")
result, _ := sigil.Transmute(data, []sigil.Sigil{hexSigil, base64Sigil})
## Types
### PreObfuscator
- **File:** crypto_sigil.go
- **Purpose:** PreObfuscator applies a reversible transformation to data before encryption. This ensures that raw plaintext patterns are never sent directly to CPU encryption routines, providing defense against side-channel attacks. Implementations must be deterministic: given the same entropy, the transformation must be perfectly reversible: Deobfuscate(Obfuscate(x, e), e) == x
- **Methods:**
- `Obfuscate func(data []byte, entropy []byte) []byte` — Obfuscate transforms plaintext before encryption using the provided entropy. The entropy is typically the encryption nonce, ensuring the transformation is unique per-encryption without additional random generation.
- `Deobfuscate func(data []byte, entropy []byte) []byte` — Deobfuscate reverses the transformation after decryption. Must be called with the same entropy used during Obfuscate.
### XORObfuscator
- **File:** crypto_sigil.go
- **Purpose:** XORObfuscator performs XOR-based obfuscation using an entropy-derived key stream. The key stream is generated using SHA-256 in counter mode: keyStream[i*32:(i+1)*32] = SHA256(entropy || BigEndian64(i)) This provides a cryptographically uniform key stream that decorrelates plaintext patterns from the data seen by the encryption routine. XOR is symmetric, so obfuscation and deobfuscation use the same operation.
- **Fields:**
- None.
- **Associated Methods:**
- `func (x *XORObfuscator) Obfuscate(data []byte, entropy []byte) []byte` — Obfuscate XORs the data with a key stream derived from the entropy.
- `func (x *XORObfuscator) Deobfuscate(data []byte, entropy []byte) []byte` — Deobfuscate reverses the XOR transformation (XOR is symmetric).
- `func (x *XORObfuscator) transform(data []byte, entropy []byte) []byte` — transform applies XOR with an entropy-derived key stream.
- `func (x *XORObfuscator) deriveKeyStream(entropy []byte, length int) []byte` — deriveKeyStream creates a deterministic key stream from entropy.
### ShuffleMaskObfuscator
- **File:** crypto_sigil.go
- **Purpose:** ShuffleMaskObfuscator provides stronger obfuscation through byte shuffling and masking. The obfuscation process: 1. Generate a mask from entropy using SHA-256 in counter mode 2. XOR the data with the mask 3. Generate a deterministic permutation using Fisher-Yates shuffle 4. Reorder bytes according to the permutation This provides both value transformation (XOR mask) and position transformation (shuffle), making pattern analysis more difficult than XOR alone.
- **Fields:**
- None.
- **Associated Methods:**
- `func (s *ShuffleMaskObfuscator) Obfuscate(data []byte, entropy []byte) []byte` — Obfuscate shuffles bytes and applies a mask derived from entropy.
- `func (s *ShuffleMaskObfuscator) Deobfuscate(data []byte, entropy []byte) []byte` — Deobfuscate reverses the shuffle and mask operations.
- `func (s *ShuffleMaskObfuscator) generatePermutation(entropy []byte, length int) []int` — generatePermutation creates a deterministic permutation from entropy.
- `func (s *ShuffleMaskObfuscator) deriveMask(entropy []byte, length int) []byte` — deriveMask creates a mask byte array from entropy.
### ChaChaPolySigil
- **File:** crypto_sigil.go
- **Purpose:** ChaChaPolySigil is a Sigil that encrypts/decrypts data using ChaCha20-Poly1305. It applies pre-obfuscation before encryption to ensure raw plaintext never goes directly to CPU encryption routines. The output format is: [24-byte nonce][encrypted(obfuscated(plaintext))] Unlike demo implementations, the nonce is ONLY embedded in the ciphertext, not exposed separately in headers.
- **Fields:**
- `Key []byte` — No doc comment in source.
- `Obfuscator PreObfuscator` — No doc comment in source.
- `randReader io.Reader` — for testing injection
- **Associated Methods:**
- `func (s *ChaChaPolySigil) In(data []byte) ([]byte, error)` — In encrypts the data with pre-obfuscation. The flow is: plaintext -> obfuscate -> encrypt
- `func (s *ChaChaPolySigil) Out(data []byte) ([]byte, error)` — Out decrypts the data and reverses obfuscation. The flow is: decrypt -> deobfuscate -> plaintext
### Sigil
- **File:** sigil.go
- **Purpose:** Sigil defines the interface for a data transformer. A Sigil represents a single transformation unit that can be applied to byte data. Sigils may be reversible (encoding, compression, encryption) or irreversible (hashing). For reversible sigils: Out(In(x)) == x for all valid x For irreversible sigils: Out returns the input unchanged For symmetric sigils: In(x) == Out(x) Implementations must handle nil input by returning nil without error, and empty input by returning an empty slice without error.
- **Methods:**
- `In func(data []byte) ([]byte, error)` — In applies the forward transformation to the data. For encoding sigils, this encodes the data. For compression sigils, this compresses the data. For hash sigils, this computes the digest.
- `Out func(data []byte) ([]byte, error)` — Out applies the reverse transformation to the data. For reversible sigils, this recovers the original data. For irreversible sigils (e.g., hashing), this returns the input unchanged.
### ReverseSigil
- **File:** sigils.go
- **Purpose:** ReverseSigil is a Sigil that reverses the bytes of the payload. It is a symmetrical Sigil, meaning that the In and Out methods perform the same operation.
- **Fields:**
- None.
- **Associated Methods:**
- `func (s *ReverseSigil) In(data []byte) ([]byte, error)` — In reverses the bytes of the data.
- `func (s *ReverseSigil) Out(data []byte) ([]byte, error)` — Out reverses the bytes of the data.
### HexSigil
- **File:** sigils.go
- **Purpose:** HexSigil is a Sigil that encodes/decodes data to/from hexadecimal. The In method encodes the data, and the Out method decodes it.
- **Fields:**
- None.
- **Associated Methods:**
- `func (s *HexSigil) In(data []byte) ([]byte, error)` — In encodes the data to hexadecimal.
- `func (s *HexSigil) Out(data []byte) ([]byte, error)` — Out decodes the data from hexadecimal.
### Base64Sigil
- **File:** sigils.go
- **Purpose:** Base64Sigil is a Sigil that encodes/decodes data to/from base64. The In method encodes the data, and the Out method decodes it.
- **Fields:**
- None.
- **Associated Methods:**
- `func (s *Base64Sigil) In(data []byte) ([]byte, error)` — In encodes the data to base64.
- `func (s *Base64Sigil) Out(data []byte) ([]byte, error)` — Out decodes the data from base64.
### GzipSigil
- **File:** sigils.go
- **Purpose:** GzipSigil is a Sigil that compresses/decompresses data using gzip. The In method compresses the data, and the Out method decompresses it.
- **Fields:**
- `writer io.Writer` — No doc comment in source.
- **Associated Methods:**
- `func (s *GzipSigil) In(data []byte) ([]byte, error)` — In compresses the data using gzip.
- `func (s *GzipSigil) Out(data []byte) ([]byte, error)` — Out decompresses the data using gzip.
### JSONSigil
- **File:** sigils.go
- **Purpose:** JSONSigil is a Sigil that compacts or indents JSON data. The Out method is a no-op.
- **Fields:**
- `Indent bool` — No doc comment in source.
- **Associated Methods:**
- `func (s *JSONSigil) In(data []byte) ([]byte, error)` — In compacts or indents the JSON data.
- `func (s *JSONSigil) Out(data []byte) ([]byte, error)` — Out is a no-op for JSONSigil.
### HashSigil
- **File:** sigils.go
- **Purpose:** HashSigil is a Sigil that hashes the data using a specified algorithm. The In method hashes the data, and the Out method is a no-op.
- **Fields:**
- `Hash crypto.Hash` — No doc comment in source.
- **Associated Methods:**
- `func (s *HashSigil) In(data []byte) ([]byte, error)` — In hashes the data.
- `func (s *HashSigil) Out(data []byte) ([]byte, error)` — Out is a no-op for HashSigil.
## Functions
### NewChaChaPolySigil
- **File:** crypto_sigil.go
- **Signature:** `func NewChaChaPolySigil(key []byte) (*ChaChaPolySigil, error)`
- **Purpose:** NewChaChaPolySigil creates a new encryption sigil with the given key. The key must be exactly 32 bytes.
### NewChaChaPolySigilWithObfuscator
- **File:** crypto_sigil.go
- **Signature:** `func NewChaChaPolySigilWithObfuscator(key []byte, obfuscator PreObfuscator) (*ChaChaPolySigil, error)`
- **Purpose:** NewChaChaPolySigilWithObfuscator creates a new encryption sigil with custom obfuscator.
### GetNonceFromCiphertext
- **File:** crypto_sigil.go
- **Signature:** `func GetNonceFromCiphertext(ciphertext []byte) ([]byte, error)`
- **Purpose:** GetNonceFromCiphertext extracts the nonce from encrypted output. This is provided for debugging/logging purposes only. The nonce should NOT be stored separately in headers.
### Transmute
- **File:** sigil.go
- **Signature:** `func Transmute(data []byte, sigils []Sigil) ([]byte, error)`
- **Purpose:** Transmute applies a series of sigils to data in sequence. Each sigil's In method is called in order, with the output of one sigil becoming the input of the next. If any sigil returns an error, Transmute stops immediately and returns nil with that error. To reverse a transmutation, call each sigil's Out method in reverse order.
### Untransmute
- **File:** sigil.go
- **Signature:** `func Untransmute(data []byte, sigils []Sigil) ([]byte, error)`
- **Purpose:** Untransmute reverses a transmutation by applying Out in reverse order. Each sigil's Out method is called in reverse order, with the output of one sigil becoming the input of the next. If any sigil returns an error, Untransmute stops immediately and returns nil with that error.
### NewHashSigil
- **File:** sigils.go
- **Signature:** `func NewHashSigil(h crypto.Hash) *HashSigil`
- **Purpose:** NewHashSigil creates a new HashSigil.
### NewSigil
- **File:** sigils.go
- **Signature:** `func NewSigil(name string) (Sigil, error)`
- **Purpose:** NewSigil is a factory function that returns a Sigil based on a string name. It is the primary way to create Sigil instances.

114
specs/sqlite/RFC.md Normal file
View file

@ -0,0 +1,114 @@
# sqlite
**Import:** `dappco.re/go/core/io/sqlite`
**Files:** 1
Package sqlite provides a SQLite-backed implementation of the io.Medium interface.
## Types
### Medium
- **File:** sqlite.go
- **Purpose:** Medium is a SQLite-backed storage backend implementing the io.Medium interface.
- **Fields:**
- `db *sql.DB` — No doc comment in source.
- `table string` — No doc comment in source.
- **Associated Methods:**
- `func (m *Medium) Close() error` — Close closes the underlying database connection.
- `func (m *Medium) Read(p string) (string, error)` — Read retrieves the content of a file as a string.
- `func (m *Medium) Write(p, content string) error` — Write saves the given content to a file, overwriting it if it exists.
- `func (m *Medium) EnsureDir(p string) error` — EnsureDir makes sure a directory exists, creating it if necessary.
- `func (m *Medium) IsFile(p string) bool` — IsFile checks if a path exists and is a regular file.
- `func (m *Medium) FileGet(p string) (string, error)` — FileGet is a convenience function that reads a file from the medium.
- `func (m *Medium) FileSet(p, content string) error` — FileSet is a convenience function that writes a file to the medium.
- `func (m *Medium) Delete(p string) error` — Delete removes a file or empty directory.
- `func (m *Medium) DeleteAll(p string) error` — DeleteAll removes a file or directory and all its contents recursively.
- `func (m *Medium) Rename(oldPath, newPath string) error` — Rename moves a file or directory from oldPath to newPath.
- `func (m *Medium) List(p string) ([]fs.DirEntry, error)` — List returns the directory entries for the given path.
- `func (m *Medium) Stat(p string) (fs.FileInfo, error)` — Stat returns file information for the given path.
- `func (m *Medium) Open(p string) (fs.File, error)` — Open opens the named file for reading.
- `func (m *Medium) Create(p string) (goio.WriteCloser, error)` — Create creates or truncates the named file.
- `func (m *Medium) Append(p string) (goio.WriteCloser, error)` — Append opens the named file for appending, creating it if it doesn't exist.
- `func (m *Medium) ReadStream(p string) (goio.ReadCloser, error)` — ReadStream returns a reader for the file content.
- `func (m *Medium) WriteStream(p string) (goio.WriteCloser, error)` — WriteStream returns a writer for the file content. Content is stored on Close.
- `func (m *Medium) Exists(p string) bool` — Exists checks if a path exists (file or directory).
- `func (m *Medium) IsDir(p string) bool` — IsDir checks if a path exists and is a directory.
### Option
- **File:** sqlite.go
- **Purpose:** Option configures a Medium.
- **Underlying:** `func(*Medium)`
### fileInfo
- **File:** sqlite.go
- **Purpose:** fileInfo implements fs.FileInfo for SQLite entries.
- **Fields:**
- `name string` — No doc comment in source.
- `size int64` — No doc comment in source.
- `mode fs.FileMode` — No doc comment in source.
- `modTime time.Time` — No doc comment in source.
- `isDir bool` — No doc comment in source.
- **Associated Methods:**
- `func (fi *fileInfo) Name() string` — No doc comment in source.
- `func (fi *fileInfo) Size() int64` — No doc comment in source.
- `func (fi *fileInfo) Mode() fs.FileMode` — No doc comment in source.
- `func (fi *fileInfo) ModTime() time.Time` — No doc comment in source.
- `func (fi *fileInfo) IsDir() bool` — No doc comment in source.
- `func (fi *fileInfo) Sys() any` — No doc comment in source.
### dirEntry
- **File:** sqlite.go
- **Purpose:** dirEntry implements fs.DirEntry for SQLite listings.
- **Fields:**
- `name string` — No doc comment in source.
- `isDir bool` — No doc comment in source.
- `mode fs.FileMode` — No doc comment in source.
- `info fs.FileInfo` — No doc comment in source.
- **Associated Methods:**
- `func (de *dirEntry) Name() string` — No doc comment in source.
- `func (de *dirEntry) IsDir() bool` — No doc comment in source.
- `func (de *dirEntry) Type() fs.FileMode` — No doc comment in source.
- `func (de *dirEntry) Info() (fs.FileInfo, error)` — No doc comment in source.
### sqliteFile
- **File:** sqlite.go
- **Purpose:** sqliteFile implements fs.File for SQLite entries.
- **Fields:**
- `name string` — No doc comment in source.
- `content []byte` — No doc comment in source.
- `offset int64` — No doc comment in source.
- `mode fs.FileMode` — No doc comment in source.
- `modTime time.Time` — No doc comment in source.
- **Associated Methods:**
- `func (f *sqliteFile) Stat() (fs.FileInfo, error)` — No doc comment in source.
- `func (f *sqliteFile) Read(b []byte) (int, error)` — No doc comment in source.
- `func (f *sqliteFile) Close() error` — No doc comment in source.
### sqliteWriteCloser
- **File:** sqlite.go
- **Purpose:** sqliteWriteCloser buffers writes and stores to SQLite on Close.
- **Fields:**
- `medium *Medium` — No doc comment in source.
- `path string` — No doc comment in source.
- `data []byte` — No doc comment in source.
- **Associated Methods:**
- `func (w *sqliteWriteCloser) Write(p []byte) (int, error)` — No doc comment in source.
- `func (w *sqliteWriteCloser) Close() error` — No doc comment in source.
## Functions
### WithTable
- **File:** sqlite.go
- **Signature:** `func WithTable(table string) Option`
- **Purpose:** WithTable sets the table name (default: "files").
### New
- **File:** sqlite.go
- **Signature:** `func New(dbPath string, opts ...Option) (*Medium, error)`
- **Purpose:** New creates a new SQLite Medium at the given database path. Use ":memory:" for an in-memory database.
### cleanPath
- **File:** sqlite.go
- **Signature:** `func cleanPath(p string) string`
- **Purpose:** cleanPath normalises a path for consistent storage. Uses a leading "/" before Clean to sandbox traversal attempts.

120
specs/store/RFC.md Normal file
View file

@ -0,0 +1,120 @@
# store
**Import:** `dappco.re/go/core/io/store`
**Files:** 2
No package doc comment in source.
## Types
### Medium
- **File:** medium.go
- **Purpose:** Medium wraps a Store to satisfy the io.Medium interface. Paths are mapped as group/key — first segment is the group, the rest is the key. List("") returns groups as directories, List("group") returns keys as files.
- **Fields:**
- `s *Store` — No doc comment in source.
- **Associated Methods:**
- `func (m *Medium) Store() *Store` — Store returns the underlying KV store for direct access.
- `func (m *Medium) Close() error` — Close closes the underlying store.
- `func (m *Medium) Read(p string) (string, error)` — Read retrieves the value at group/key.
- `func (m *Medium) Write(p, content string) error` — Write stores a value at group/key.
- `func (m *Medium) EnsureDir(_ string) error` — EnsureDir is a no-op — groups are created implicitly on Set.
- `func (m *Medium) IsFile(p string) bool` — IsFile returns true if a group/key pair exists.
- `func (m *Medium) FileGet(p string) (string, error)` — FileGet is an alias for Read.
- `func (m *Medium) FileSet(p, content string) error` — FileSet is an alias for Write.
- `func (m *Medium) Delete(p string) error` — Delete removes a key, or checks that a group is empty.
- `func (m *Medium) DeleteAll(p string) error` — DeleteAll removes a key, or all keys in a group.
- `func (m *Medium) Rename(oldPath, newPath string) error` — Rename moves a key from one path to another.
- `func (m *Medium) List(p string) ([]fs.DirEntry, error)` — List returns directory entries. Empty path returns groups. A group path returns keys in that group.
- `func (m *Medium) Stat(p string) (fs.FileInfo, error)` — Stat returns file info for a group (dir) or key (file).
- `func (m *Medium) Open(p string) (fs.File, error)` — Open opens a key for reading.
- `func (m *Medium) Create(p string) (goio.WriteCloser, error)` — Create creates or truncates a key. Content is stored on Close.
- `func (m *Medium) Append(p string) (goio.WriteCloser, error)` — Append opens a key for appending. Content is stored on Close.
- `func (m *Medium) ReadStream(p string) (goio.ReadCloser, error)` — ReadStream returns a reader for the value.
- `func (m *Medium) WriteStream(p string) (goio.WriteCloser, error)` — WriteStream returns a writer. Content is stored on Close.
- `func (m *Medium) Exists(p string) bool` — Exists returns true if a group or key exists.
- `func (m *Medium) IsDir(p string) bool` — IsDir returns true if the path is a group with entries.
### kvFileInfo
- **File:** medium.go
- **Purpose:** No doc comment in source.
- **Fields:**
- `name string` — No doc comment in source.
- `size int64` — No doc comment in source.
- `isDir bool` — No doc comment in source.
- **Associated Methods:**
- `func (fi *kvFileInfo) Name() string` — No doc comment in source.
- `func (fi *kvFileInfo) Size() int64` — No doc comment in source.
- `func (fi *kvFileInfo) Mode() fs.FileMode` — No doc comment in source.
- `func (fi *kvFileInfo) ModTime() time.Time` — No doc comment in source.
- `func (fi *kvFileInfo) IsDir() bool` — No doc comment in source.
- `func (fi *kvFileInfo) Sys() any` — No doc comment in source.
### kvDirEntry
- **File:** medium.go
- **Purpose:** No doc comment in source.
- **Fields:**
- `name string` — No doc comment in source.
- `isDir bool` — No doc comment in source.
- `size int64` — No doc comment in source.
- **Associated Methods:**
- `func (de *kvDirEntry) Name() string` — No doc comment in source.
- `func (de *kvDirEntry) IsDir() bool` — No doc comment in source.
- `func (de *kvDirEntry) Type() fs.FileMode` — No doc comment in source.
- `func (de *kvDirEntry) Info() (fs.FileInfo, error)` — No doc comment in source.
### kvFile
- **File:** medium.go
- **Purpose:** No doc comment in source.
- **Fields:**
- `name string` — No doc comment in source.
- `content []byte` — No doc comment in source.
- `offset int64` — No doc comment in source.
- **Associated Methods:**
- `func (f *kvFile) Stat() (fs.FileInfo, error)` — No doc comment in source.
- `func (f *kvFile) Read(b []byte) (int, error)` — No doc comment in source.
- `func (f *kvFile) Close() error` — No doc comment in source.
### kvWriteCloser
- **File:** medium.go
- **Purpose:** No doc comment in source.
- **Fields:**
- `s *Store` — No doc comment in source.
- `group string` — No doc comment in source.
- `key string` — No doc comment in source.
- `data []byte` — No doc comment in source.
- **Associated Methods:**
- `func (w *kvWriteCloser) Write(p []byte) (int, error)` — No doc comment in source.
- `func (w *kvWriteCloser) Close() error` — No doc comment in source.
### Store
- **File:** store.go
- **Purpose:** Store is a group-namespaced key-value store backed by SQLite.
- **Fields:**
- `db *sql.DB` — No doc comment in source.
- **Associated Methods:**
- `func (s *Store) Close() error` — Close closes the underlying database.
- `func (s *Store) Get(group, key string) (string, error)` — Get retrieves a value by group and key.
- `func (s *Store) Set(group, key, value string) error` — Set stores a value by group and key, overwriting if exists.
- `func (s *Store) Delete(group, key string) error` — Delete removes a single key from a group.
- `func (s *Store) Count(group string) (int, error)` — Count returns the number of keys in a group.
- `func (s *Store) DeleteGroup(group string) error` — DeleteGroup removes all keys in a group.
- `func (s *Store) GetAll(group string) (map[string]string, error)` — GetAll returns all key-value pairs in a group.
- `func (s *Store) Render(tmplStr, group string) (string, error)` — Render loads all key-value pairs from a group and renders a Go template.
## Functions
### NewMedium
- **File:** medium.go
- **Signature:** `func NewMedium(dbPath string) (*Medium, error)`
- **Purpose:** NewMedium creates an io.Medium backed by a KV store at the given SQLite path.
### splitPath
- **File:** medium.go
- **Signature:** `func splitPath(p string) (group, key string)`
- **Purpose:** splitPath splits a medium-style path into group and key. First segment = group, remainder = key.
### New
- **File:** store.go
- **Signature:** `func New(dbPath string) (*Store, error)`
- **Purpose:** New creates a Store at the given SQLite path. Use ":memory:" for tests.

60
specs/workspace/RFC.md Normal file
View file

@ -0,0 +1,60 @@
# workspace
**Import:** `dappco.re/go/core/io/workspace`
**Files:** 1
No package doc comment in source.
## Types
### Workspace
- **File:** service.go
- **Purpose:** Workspace provides management for encrypted user workspaces.
- **Methods:**
- `CreateWorkspace func(identifier, password string) (string, error)` — No doc comment in source.
- `SwitchWorkspace func(name string) error` — No doc comment in source.
- `WorkspaceFileGet func(filename string) (string, error)` — No doc comment in source.
- `WorkspaceFileSet func(filename, content string) error` — No doc comment in source.
### cryptProvider
- **File:** service.go
- **Purpose:** cryptProvider is the interface for PGP key generation.
- **Methods:**
- `CreateKeyPair func(name, passphrase string) (string, error)` — No doc comment in source.
### Service
- **File:** service.go
- **Purpose:** Service implements the Workspace interface.
- **Fields:**
- `core *core.Core` — No doc comment in source.
- `crypt cryptProvider` — No doc comment in source.
- `activeWorkspace string` — No doc comment in source.
- `rootPath string` — No doc comment in source.
- `medium io.Medium` — No doc comment in source.
- `mu sync.RWMutex` — No doc comment in source.
- **Associated Methods:**
- `func (s *Service) CreateWorkspace(identifier, password string) (string, error)` — CreateWorkspace creates a new encrypted workspace. Identifier is hashed (SHA-256) to create the directory name. A PGP keypair is generated using the password.
- `func (s *Service) SwitchWorkspace(name string) error` — SwitchWorkspace changes the active workspace.
- `func (s *Service) activeFilePath(op, filename string) (string, error)` — activeFilePath returns the full path to a file in the active workspace, or an error if no workspace is active.
- `func (s *Service) WorkspaceFileGet(filename string) (string, error)` — WorkspaceFileGet retrieves the content of a file from the active workspace.
- `func (s *Service) WorkspaceFileSet(filename, content string) error` — WorkspaceFileSet saves content to a file in the active workspace.
- `func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) core.Result` — HandleIPCEvents handles workspace-related IPC messages.
- `func (s *Service) workspacePath(op, name string) (string, error)` — No doc comment in source.
## Functions
### New
- **File:** service.go
- **Signature:** `func New(c *core.Core, crypt ...cryptProvider) (any, error)`
- **Purpose:** New creates a new Workspace service instance. An optional cryptProvider can be passed to supply PGP key generation.
### workspaceHome
- **File:** service.go
- **Signature:** `func workspaceHome() string`
- **Purpose:** No doc comment in source.
### joinWithinRoot
- **File:** service.go
- **Signature:** `func joinWithinRoot(root string, parts ...string) (string, error)`
- **Purpose:** No doc comment in source.