nar

Documentation

Overview

Package nar implements access to .nar files.

Nix Archive (nar) is a file format for storing a directory or a single file in a binary reproducible format. This is the format that is being used to pack and distribute Nix build results. It doesn't store any timestamps or similar fields available in conventional filesystems. .nar files can be read and written in a streaming manner.

Index

• Constants
• func DumpPath(w io.Writer, path string) error
• func DumpPathFilter(w io.Writer, path string, filter SourceFilterFunc) error
• func IsValidNodeName(nodeName string) bool
• func PathIsLexicographicallyOrdered(path1 string, path2 string) bool
• type Header
  • func (h *Header) FileInfo() fs.FileInfo
  • func (h *Header) Validate() error
• type NodeType
  • func (t NodeType) String() string
• type Reader
  • func NewReader(r io.Reader) (*Reader, error)
  • func (nr *Reader) Close() error
  • func (nr *Reader) Next() (*Header, error)
  • func (nr *Reader) Read(b []byte) (int, error)
• type SourceFilterFunc
• type Writer
  • func NewWriter(w io.Writer) (*Writer, error)
  • func (nw *Writer) Close() error
  • func (nw *Writer) Write(b []byte) (int, error)
  • func (nw *Writer) WriteHeader(hdr *Header) error

Constants

const (
	// TypeRegular represents a regular file.
	TypeRegular = NodeType("regular")
	// TypeDirectory represents a directory entry.
	TypeDirectory = NodeType("directory")
	// TypeSymlink represents a file symlink.
	TypeSymlink = NodeType("symlink")
)

Functions

func DumpPath

func DumpPath(w io.Writer, path string) error

DumpPath will serialize a path on the local file system to NAR format, and write it to the passed writer.

func DumpPathFilter

func DumpPathFilter(w io.Writer, path string, filter SourceFilterFunc) error

DumpPathFilter will serialize a path on the local file system to NAR format, and write it to the passed writer, filtering out any files where the filter function returns false.

func IsValidNodeName

func IsValidNodeName(nodeName string) bool

IsValidNodeName checks the name of a node it may not contain null bytes or slashes.

func PathIsLexicographicallyOrdered

func PathIsLexicographicallyOrdered(path1 string, path2 string) bool

PathIsLexicographicallyOrdered checks if two paths are lexicographically ordered component by component.

Types

type Header

type Header struct {
	Path       string   // Path of the file entry, relative inside the NAR
	Type       NodeType // Typeflag is the type of header entry.
	LinkTarget string   // Target of symlink (valid for TypeSymlink)
	Size       int64    // Logical file size in bytes
	Executable bool     // Set to true for files that are executable
}

Header represents a single header in a NAR archive. Some fields may not be populated depending on the Type.

func (*Header) FileInfo

func (h *Header) FileInfo() fs.FileInfo

FileInfo returns an fs.FileInfo for the Header.

func (*Header) Validate

func (h *Header) Validate() error

Validate does some consistency checking of the header structure, such as checking for valid paths and inconsistent fields, and returns an error if it fails validation.

type NodeType

type NodeType string

Enum of all the node types possible.

func (NodeType) String

func (t NodeType) String() string

type Reader

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

Reader providers sequential access to the contents of a NAR archive. Reader.Next advances to the next file in the archive (including the first), and then Reader can be treated as an io.Reader to access the file's data.

func NewReader

func NewReader(r io.Reader) (*Reader, error)

NewReader creates a new Reader reading from r. It'll try to detect the magic header and will fail if it can't be read.

func (*Reader) Close

func (nr *Reader) Close() error

Close does all internal cleanup. It doesn't close the underlying reader (which can be any io.Reader).

func (*Reader) Next

func (nr *Reader) Next() (*Header, error)

Next advances to the next entry in the NAR archive. The Header.Size determines how many bytes can be read for the next file. Any remaining data in the current file is automatically discarded.

io.EOF is returned at the end of input. Errors are returned in case invalid data was read. This includes non-canonically sorted NAR files.

func (*Reader) Read

func (nr *Reader) Read(b []byte) (int, error)

Read reads from the current file in the NAR archive. It returns (0, io.EOF) when it reaches the end of that file, until Next is called to advance to the next file.

Calling Read on special types like TypeSymlink or TypeDir returns (0, io.EOF).

type SourceFilterFunc

type SourceFilterFunc func(path string, nodeType NodeType) bool

SourceFilterFunc is the interface for creating source filters. If the function returns true, the file is copied to the Nix store, otherwise it is omitted, this mimics the behaviour of the Nix function builtins.filterSource.

type Writer

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

Writer provides sequential writing of a NAR (Nix Archive) file. Writer.WriteHeader begins a new file with the provided Header, and then Writer can be treated as an io.Writer to supply that file's data.

func NewWriter

func NewWriter(w io.Writer) (*Writer, error)

NewWriter creates a new Writer writing to w.

func (*Writer) Close

func (nw *Writer) Close() error

Close closes the NAR file. If the current file (from a prior call to WriteHeader) is not fully written, then this returns an error.

func (*Writer) Write

func (nw *Writer) Write(b []byte) (int, error)

Write writes to the current file in the NAR. Write returns the ErrWriteTooLong if more than Header.Size bytes are written after WriteHeader.

Calling Write on special types like TypeLink, TypeSymlink, TypeChar, TypeBlock, TypeDir, and TypeFifo returns (0, ErrWriteTooLong) regardless of what the Header.Size claims.

func (*Writer) WriteHeader

func (nw *Writer) WriteHeader(hdr *Header) error

WriteHeader writes hdr and prepares to accept the file's contents. The Header.Size determines how many bytes can be written for the next file. If the current file is not fully written, then this returns an error. This implicitly flushes any padding necessary before writing the header.