go-io/specs/node/RFC.md

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.