boundedio

Documentation

Overview

Package boundedio provides IO utilities with security limits.

This package consolidates the common pattern of size-limited file reading that was previously duplicated across multiple packages. All functions implement defense-in-depth against:

• Memory exhaustion from large files
• TOCTOU races (file size changes between check and read)
• Truncation attacks

The standard pattern used throughout is:

1. Open file
2. Check size via Fstat on open fd (not separate Stat call)
3. Use LimitReader(maxBytes+1) as defense-in-depth
4. Verify final length to catch growth during read

This package does NOT handle symlink safety - use safefile for that.

Index

• func IsBoundedReadError(err error) bool
• func MustReadWithLimit(f *os.File, name string, limit limits.SizeLimit) []byte
• func ReadFileWithLimit(path string, limit limits.SizeLimit) ([]byte, error)
• func ReadReaderWithLimit(r io.Reader, name string, limit limits.SizeLimit) ([]byte, error)
• func ReadWithLimit(f *os.File, name string, limit limits.SizeLimit) ([]byte, error)
• type BoundedReadError
  • func (e *BoundedReadError) Error() string

Functions

func IsBoundedReadError

func IsBoundedReadError(err error) bool

IsBoundedReadError returns true if err is a BoundedReadError.

func MustReadWithLimit

func MustReadWithLimit(f *os.File, name string, limit limits.SizeLimit) []byte

MustReadWithLimit is like ReadWithLimit but panics on error. Only use this in tests or initialization code where errors are fatal.

func ReadFileWithLimit

func ReadFileWithLimit(path string, limit limits.SizeLimit) ([]byte, error)

ReadFileWithLimit reads a file with TOCTOU-safe size checking.

Security properties:

1. Size checked via Fstat on open fd (not separate Stat call)
2. LimitReader(+1) as defense-in-depth against file growth
3. Final length check catches growth during read

This does NOT check for symlinks - use safefile.ReadFile for that.

func ReadReaderWithLimit

func ReadReaderWithLimit(r io.Reader, name string, limit limits.SizeLimit) ([]byte, error)

ReadReaderWithLimit reads from any io.Reader with a size limit. No Stat phase (reader may not be a file).

The name parameter is used for error messages only.

func ReadWithLimit

func ReadWithLimit(f *os.File, name string, limit limits.SizeLimit) ([]byte, error)

ReadWithLimit reads from an open file with size limits. Uses Fstat on the fd to prevent TOCTOU races.

The name parameter is used for error messages only.

Types

type BoundedReadError

type BoundedReadError struct {
	Path   string // File path or identifier
	Limit  int64  // Maximum allowed size
	Actual int64  // Actual size encountered
	Phase  string // "stat" or "read" - when the limit was hit
}

BoundedReadError is returned when size limits are exceeded.

func (*BoundedReadError) Error

func (e *BoundedReadError) Error() string