ioutil

package
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Mar 30, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidPath is shared with policy to keep behavior consistent.
	ErrInvalidPath      = fspolicy.ErrInvalidPath
	ErrInvalidDir       = errors.New("invalid dir")
	ErrUnknownExtension = errors.New("unknown extension")
)
View Source 
var (
	// ErrNotUTF8Text indicates a file could be read but is not valid UTF‑8.
	ErrNotUTF8Text        = errors.New("file is not valid UTF-8 text")
	ErrFileExceedsMaxSize = errors.New("file exceeds maximum allowed size")
)
View Source 
var AllExtensionModes = []ExtensionMode{
	ExtensionModeText,
	ExtensionModeImage,
	ExtensionModeDocument,
	ExtensionModeDefault,
}
View Source 
var BaseMIMEToMode = map[string]ExtensionMode{
	"":                         ExtensionModeDefault,
	"application/octet-stream": ExtensionModeDefault,

	"text/plain":             ExtensionModeText,
	"text/markdown":          ExtensionModeText,
	"text/html":              ExtensionModeText,
	"text/css":               ExtensionModeText,
	"application/json":       ExtensionModeText,
	"application/xml":        ExtensionModeText,
	"application/x-yaml":     ExtensionModeText,
	"application/yaml":       ExtensionModeText,
	"application/toml":       ExtensionModeText,
	"application/sql":        ExtensionModeText,
	"application/javascript": ExtensionModeText,

	"image/jpeg":    ExtensionModeImage,
	"image/png":     ExtensionModeImage,
	"image/gif":     ExtensionModeImage,
	"image/webp":    ExtensionModeImage,
	"image/bmp":     ExtensionModeImage,
	"image/svg+xml": ExtensionModeImage,

	"application/pdf":               ExtensionModeDocument,
	"application/msword":            ExtensionModeDocument,
	"application/vnd.ms-powerpoint": ExtensionModeDocument,
	"application/vnd.ms-excel":      ExtensionModeDocument,
	"application/vnd.openxmlformats-officedocument.wordprocessingml.document":   ExtensionModeDocument,
	"application/vnd.openxmlformats-officedocument.presentationml.presentation": ExtensionModeDocument,
	"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":         ExtensionModeDocument,
	"application/vnd.oasis.opendocument.text":                                   ExtensionModeDocument,
	"application/vnd.oasis.opendocument.spreadsheet":                            ExtensionModeDocument,
}

BaseMIMEToMode maps base mime types (no parameters) to a coarse mode.

View Source 
var ExtensionToMIMEType = map[FileExt]MIMEType{
	ExtTxt:      MIMETextPlain,
	ExtMd:       MIMETextMarkdown,
	ExtMarkdown: MIMETextMarkdown,
	ExtLog:      MIMETextPlain,
	ExtJSON:     MIMEApplicationJSON,
	ExtYAML:     MIMEApplicationYAML,
	ExtYML:      MIMEApplicationYAML,
	ExtTOML:     MIMEApplicationTOML,
	ExtJS:       MIMEApplicationJS,
	ExtTS:       MIMETextPlain,
	ExtTSX:      MIMETextPlain,
	ExtJSX:      MIMETextPlain,
	ExtPY:       MIMETextPlain,
	ExtGO:       MIMETextPlain,
	ExtRS:       MIMETextPlain,
	ExtJAVA:     MIMETextPlain,
	ExtC:        MIMETextPlain,
	ExtCPP:      MIMETextPlain,
	ExtH:        MIMETextPlain,
	ExtHPP:      MIMETextPlain,
	ExtCS:       MIMETextPlain,
	ExtRB:       MIMETextPlain,
	ExtPHP:      MIMETextPlain,
	ExtHTML:     MIMETextHTML,
	ExtHTM:      MIMETextHTML,
	ExtCSS:      MIMETextCSS,
	ExtSCSS:     MIMETextPlain,
	ExtLESS:     MIMETextPlain,
	ExtSQL:      MIMEApplicationSQL,
	ExtMod:      MIMETextPlain,
	ExtSum:      MIMETextPlain,
	ExtJSONL:    MIMETextPlain,
	ExtShell:    MIMETextPlain,
	ExtSWIFT:    MIMETextPlain,
	ExtM:        MIMETextPlain,
	ExtKT:       MIMETextPlain,
	ExtPL:       MIMETextPlain,
	ExtSCALA:    MIMETextPlain,
	ExtHS:       MIMETextPlain,
	ExtLUA:      MIMETextPlain,
	ExtDART:     MIMETextPlain,
	ExtCmake:    MIMETextPlain,
	ExtBazel:    MIMETextPlain,
	ExtXML:      MIMEApplicationXML,

	ExtJPG:  MIMEImageJPEG,
	ExtJPEG: MIMEImageJPEG,
	ExtPNG:  MIMEImagePNG,
	ExtGIF:  MIMEImageGIF,
	ExtWEBP: MIMEImageWEBP,
	ExtBMP:  MIMEImageBMP,
	ExtSVG:  MIMEImageSVG,

	ExtPDF:  MIMEApplicationPDF,
	ExtDOC:  MIMEApplicationMSWord,
	ExtDOCX: MIMEApplicationOpenXMLDoc,
	ExtPPT:  MIMEApplicationMSPowerPt,
	ExtPPTX: MIMEApplicationOpenXMLPPT,
	ExtXLS:  MIMEApplicationMSExcel,
	ExtXLSX: MIMEApplicationOpenXMLXLS,
	ExtODT:  MIMEApplicationODT,
	ExtODS:  MIMEApplicationODS,
}

ExtensionToMIMEType is an internal registry of common/explicitly-supported extensions.

View Source 
var ModeToExtensions = func() map[ExtensionMode][]FileExt {
	m := make(map[ExtensionMode][]FileExt, len(AllExtensionModes))
	for ext, mt := range ExtensionToMIMEType {
		mode := GetModeForMIME(mt)
		m[mode] = append(m[mode], ext)
	}
	return m
}()

Functions

func BuildBlockMatchDiagnosticJSON added in v0.13.0 

func BuildBlockMatchDiagnosticJSON(
	lines []string,
	matchIdxs []int,
	matchWidth int,
	hint *MaybeStartLineDiagnostic,
	maxCandidates int,
	contextLines int,
) string

func CopyFileCtx 

func CopyFileCtx(ctx context.Context, src, dst string, perm os.FileMode) (written int64, err error)

CopyFileCtx copies src->dst, creating dst with O_EXCL. It checks ctx between read iterations.

NOTE: This is a raw IO helper; callers should resolve/enforce policy before calling.

func CopyFileToExistingCtx 

func CopyFileToExistingCtx(ctx context.Context, src, dst string) (int64, error)

CopyFileToExistingCtx copies src -> dst where dst is expected to already exist (typically a placeholder reserved with O_EXCL). "dst" is truncated and overwritten.

NOTE: This is a raw IO helper; callers should resolve/enforce policy before calling.

func EnsureNonOverlappingFixedWidth 

func EnsureNonOverlappingFixedWidth(matchIdxs []int, width int) error

func FindTrimmedAdjacentBlockMatches 

func FindTrimmedAdjacentBlockMatches(lines, before, match, after []string) []int

func FindTrimmedBlockMatches 

func FindTrimmedBlockMatches(lines, block []string) []int

func GetBaseMIME 

func GetBaseMIME(mt MIMEType) string

func GetTrimmedLines 

func GetTrimmedLines(lines []string) []string

func IsBlockEqualsAt 

func IsBlockEqualsAt(haystack, needle []string, start int) bool

func MIMEForLocalFile 

func MIMEForLocalFile(path string) (mimeType MIMEType, mode ExtensionMode, method MIMEDetectMethod, err error)

func MIMEForPath 

func MIMEForPath(
	p fspolicy.FSPolicy,
	path string,
) (abs string, mimeType MIMEType, mode ExtensionMode, method MIMEDetectMethod, err error)

MIMEForPath returns a best-effort MIME type for a filesystem path with FSPolicy enforcement.

Behavior:

  • Path is resolved via policy (base dir + allowed roots).
  • If the extension maps to a non-generic MIME type and a non-default mode, it returns without IO (so it may succeed even if the file doesn't exist).
  • Otherwise it requires an existing regular file via policy (enforcing BlockSymlinks rules) and sniffs bytes.

func NormalizeLineBlockInput 

func NormalizeLineBlockInput(in []string) []string

func OneBasedLineNumbers added in v0.13.0 

func OneBasedLineNumbers(idxs []int) []int

func ReadFile 

func ReadFile(path string, encoding ReadEncoding, maxBytes int64) (string, error)

ReadFile reads a file and returns its contents. If maxBytes > 0, it enforces a hard cap during reading.

NOTE: This is a raw IO helper; callers should resolve/enforce policy before calling.

func RequireSingleMatch 

func RequireSingleMatch(idxs []int, name string) (int, error)

func RequireSingleTrimmedBlockMatch 

func RequireSingleTrimmedBlockMatch(lines, block []string, name string) (int, error)

func SniffFileMIME 

func SniffFileMIME(path string) (MIMEType, ExtensionMode, error)

func UniquePathInDir 

func UniquePathInDir(dir, base string) (string, error)

func WriteFileAtomicBytesResolved 

func WriteFileAtomicBytesResolved(
	p fspolicy.FSPolicy,
	dst string,
	data []byte,
	perm fs.FileMode,
	overwrite bool,
) error

WriteFileAtomicBytesResolved is like WriteFileAtomicBytes but assumes dst is already an absolute, policy-resolved path (i.e. returned from p.ResolvePath).

This avoids re-resolving (and re-checking allowed roots) at higher layers.

func WriteFileAtomicBytesWithParents 

func WriteFileAtomicBytesWithParents(
	p fspolicy.FSPolicy,
	path string,
	data []byte,
	perm fs.FileMode,
	overwrite bool,
	createParents bool,
	maxNewDirs int,
) (dst string, err error)

WriteFileAtomicBytesWithParents is a policy-aware convenience wrapper that:

  • resolves path once via policy
  • either verifies parent exists (createParents=false) or creates it (createParents=true)
  • then performs the atomic write

It returns the resolved absolute destination path (even on many error paths) so callers can use it in messages/outputs.

Types

type ExtensionMode 

type ExtensionMode string
const (
	ExtensionModeText     ExtensionMode = "text"
	ExtensionModeImage    ExtensionMode = "image"
	ExtensionModeDocument ExtensionMode = "document"
	ExtensionModeDefault  ExtensionMode = "default"
)

func GetModeForMIME 

func GetModeForMIME(mt MIMEType) ExtensionMode

type FileExt 

type FileExt string
const (
	ExtTxt      FileExt = ".txt"
	ExtMd       FileExt = ".md"
	ExtMarkdown FileExt = ".markdown"
	ExtLog      FileExt = ".log"
	ExtJSON     FileExt = ".json"
	ExtYAML     FileExt = ".yaml"
	ExtYML      FileExt = ".yml"
	ExtTOML     FileExt = ".toml"
	ExtJS       FileExt = ".js"
	ExtTS       FileExt = ".ts"
	ExtTSX      FileExt = ".tsx"
	ExtJSX      FileExt = ".jsx"
	ExtPY       FileExt = ".py"
	ExtGO       FileExt = ".go"
	ExtRS       FileExt = ".rs"
	ExtJAVA     FileExt = ".java"
	ExtC        FileExt = ".c"
	ExtCPP      FileExt = ".cpp"
	ExtH        FileExt = ".h"
	ExtHPP      FileExt = ".hpp"
	ExtCS       FileExt = ".cs"
	ExtRB       FileExt = ".rb"
	ExtPHP      FileExt = ".php"
	ExtHTML     FileExt = ".html"
	ExtHTM      FileExt = ".htm"
	ExtCSS      FileExt = ".css"
	ExtSCSS     FileExt = ".scss"
	ExtLESS     FileExt = ".less"
	ExtSQL      FileExt = ".sql"
	ExtMod      FileExt = ".mod"
	ExtSum      FileExt = ".sum"
	ExtJSONL    FileExt = ".jsonl"
	ExtShell    FileExt = ".sh"
	ExtSWIFT    FileExt = ".swift"
	ExtM        FileExt = ".m"
	ExtKT       FileExt = ".kt"
	ExtPL       FileExt = ".pl"
	ExtSCALA    FileExt = ".scala"
	ExtHS       FileExt = ".hs"
	ExtLUA      FileExt = ".lua"
	ExtDART     FileExt = ".dart"
	ExtCmake    FileExt = ".cmake"
	ExtBazel    FileExt = ".bazel"
	ExtXML      FileExt = ".xml"

	ExtJPG  FileExt = ".jpg"
	ExtJPEG FileExt = ".jpeg"
	ExtPNG  FileExt = ".png"
	ExtGIF  FileExt = ".gif"
	ExtWEBP FileExt = ".webp"
	ExtBMP  FileExt = ".bmp"
	ExtSVG  FileExt = ".svg"

	ExtPDF  FileExt = ".pdf"
	ExtDOC  FileExt = ".doc"
	ExtDOCX FileExt = ".docx"
	ExtPPT  FileExt = ".ppt"
	ExtPPTX FileExt = ".pptx"
	ExtXLS  FileExt = ".xls"
	ExtXLSX FileExt = ".xlsx"
	ExtODT  FileExt = ".odt"
	ExtODS  FileExt = ".ods"
)

func GetNormalizedExt 

func GetNormalizedExt(ext string) FileExt

type ImageData 

type ImageData struct {
	ImageInfo

	Base64Data string `json:"base64Data,omitempty"` // optional, if requested
}

ImageData holds metadata (and optionally content) for an image file.

func ReadImage 

func ReadImage(
	p fspolicy.FSPolicy,
	path string,
	includeBase64Data bool,
	maxBytes int64,
) (*ImageData, error)

ReadImage inspects an image file and returns its intrinsic metadata. If includeBase64 is true, Base64Data will contain the base64-encoded file contents. If the file does not exist, Exists == false and err == nil.

FSPolicy enforcement:

  • path is resolved via policy (base dir + allowed roots)
  • if policy.BlockSymlinks == true: refuses symlink parent components and refuses symlink file.
  • even if symlinks are allowed, symlink files are refused (strict).

type ImageInfo 

type ImageInfo struct {
	PathInfo

	Width    int      `json:"width,omitempty"`
	Height   int      `json:"height,omitempty"`
	Format   string   `json:"format,omitempty"`   // e.g. "jpeg", "png"
	MIMEType MIMEType `json:"mimeType,omitempty"` // e.g. "image/jpeg"
}

type ListDirectoryEntry added in v0.13.0 

type ListDirectoryEntry struct {
	Name string            `json:"name"`
	Kind ListDirectoryKind `json:"kind"`
}

func ListDirectoryDetailedNormalized added in v0.13.0 

func ListDirectoryDetailedNormalized(dir string, opts ListDirectoryOptions) ([]ListDirectoryEntry, bool, error)

ListDirectoryDetailedNormalized lists and filters immediate directory entries in a directory that is assumed to already be normalized.

type ListDirectoryKind added in v0.13.0 

type ListDirectoryKind string
const (
	ListDirectoryKindAll       ListDirectoryKind = "all"
	ListDirectoryKindFile      ListDirectoryKind = "file"
	ListDirectoryKindDirectory ListDirectoryKind = "directory"
	ListDirectoryKindOther     ListDirectoryKind = "other"
)

type ListDirectoryOptions added in v0.13.0 

type ListDirectoryOptions struct {
	NameGlob          string
	IncludeDotEntries bool
	Kind              ListDirectoryKind
	MaxEntries        int
}

type MIMEDetectMethod 

type MIMEDetectMethod string
const (
	MIMEDetectMethodExtension MIMEDetectMethod = "extension"
	MIMEDetectMethodSniff     MIMEDetectMethod = "sniff"
)

type MIMEType 

type MIMEType string
const (
	MIMEEmpty                  MIMEType = ""
	MIMEApplicationOctetStream MIMEType = "application/octet-stream"

	MIMETextPlain    MIMEType = "text/plain; charset=utf-8"
	MIMETextMarkdown MIMEType = "text/markdown; charset=utf-8"
	MIMETextHTML     MIMEType = "text/html; charset=utf-8"
	MIMETextCSS      MIMEType = "text/css; charset=utf-8"

	MIMEApplicationJSON MIMEType = "application/json"
	MIMEApplicationXML  MIMEType = "application/xml"
	MIMEApplicationYAML MIMEType = "application/x-yaml"
	MIMEApplicationTOML MIMEType = "application/toml"
	MIMEApplicationSQL  MIMEType = "application/sql"
	MIMEApplicationJS   MIMEType = "application/javascript"

	MIMEImageJPEG MIMEType = "image/jpeg"
	MIMEImagePNG  MIMEType = "image/png"
	MIMEImageGIF  MIMEType = "image/gif"
	MIMEImageWEBP MIMEType = "image/webp"
	MIMEImageBMP  MIMEType = "image/bmp"
	MIMEImageSVG  MIMEType = "image/svg+xml"

	MIMEApplicationPDF        MIMEType = "application/pdf"
	MIMEApplicationMSWord     MIMEType = "application/msword"
	MIMEApplicationMSPowerPt  MIMEType = "application/vnd.ms-powerpoint"
	MIMEApplicationMSExcel    MIMEType = "application/vnd.ms-excel"
	MIMEApplicationOpenXMLDoc MIMEType = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
	MIMEApplicationOpenXMLPPT MIMEType = "application/vnd.openxmlformats-officedocument.presentationml.presentation"
	MIMEApplicationOpenXMLXLS MIMEType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
	MIMEApplicationODT        MIMEType = "application/vnd.oasis.opendocument.text"
	MIMEApplicationODS        MIMEType = "application/vnd.oasis.opendocument.spreadsheet"
)

func MIMEFromExtensionString 

func MIMEFromExtensionString(ext string) (MIMEType, error)

type MaybeStartLineDiagnostic added in v0.13.0 

type MaybeStartLineDiagnostic struct {
	RequestedLine     int   `json:"requestedLine"`
	Tolerance         int   `json:"tolerance"`
	ClosestDistance   int   `json:"closestDistance"`
	ClosestStartLines []int `json:"closestStartLines,omitempty"`
	Applied           bool  `json:"applied"`
}

func NarrowMatchIndicesByMaybeStartLine added in v0.13.0 

func NarrowMatchIndicesByMaybeStartLine(
	idxs []int,
	maybeStartLine *int,
	tolerance int,
) ([]int, *MaybeStartLineDiagnostic)

NarrowMatchIndicesByMaybeStartLine applies a soft start-line hint.

Behavior:

  • if maybeStartLine is nil or invalid, no narrowing is applied
  • if there is a unique closest candidate within tolerance, returns only that candidate
  • otherwise returns the original candidates and emits diagnostics explaining the closest set

type NewlineKind 

type NewlineKind string

NewlineKind describes the newline convention detected in a file. 

const (
	NewlineLF   NewlineKind = "lf"
	NewlineCRLF NewlineKind = "crlf"
)

type PathInfo 

type PathInfo struct {
	Path    string     `json:"path"`
	Name    string     `json:"name"`
	Exists  bool       `json:"exists"`
	IsDir   bool       `json:"isDir"`
	Size    int64      `json:"size,omitempty"`
	ModTime *time.Time `json:"modTime,omitempty"`
}

func StatPath 

func StatPath(p fspolicy.FSPolicy, path string) (pathInfo *PathInfo, err error)

StatPath returns basic metadata for the supplied path without mutating the filesystem. If the path does not exist, exists == false and err == nil.

FSPolicy enforcement:

  • path resolved via policy (base dir + allowed roots)
  • if policy.BlockSymlinks == true: refuses symlink targets (Lstat + reject).

type ReadEncoding 

type ReadEncoding string
const (
	ReadEncodingText   ReadEncoding = "text"
	ReadEncodingBinary ReadEncoding = "binary"
)

type SearchFileMatch added in v0.13.0 

type SearchFileMatch struct {
	Path      string              `json:"path"`
	MatchKind SearchFileMatchKind `json:"matchKind"`
}

func SearchFilesDetailed added in v0.13.0 

func SearchFilesDetailed(
	ctx context.Context,
	p fspolicy.FSPolicy,
	opts SearchFilesOptions,
) (matchedFiles []SearchFileMatch, reachedLimit bool, err error)

SearchFilesDetailed walks root recursively and returns up to MaxResults file matches.

type SearchFileMatchKind added in v0.13.0 

type SearchFileMatchKind string
const (
	SearchFileMatchKindPath           SearchFileMatchKind = "path"
	SearchFileMatchKindContent        SearchFileMatchKind = "content"
	SearchFileMatchKindPathAndContent SearchFileMatchKind = "pathAndContent"
)

type SearchFilesOptions added in v0.13.0 

type SearchFilesOptions struct {
	Root              string
	Query             string
	Regexp            bool
	SearchIn          SearchFilesSearchIn
	MaxResults        int
	IncludeDotEntries bool
	NameGlob          string
	CaseSensitive     bool
}

type SearchFilesSearchIn added in v0.13.0 

type SearchFilesSearchIn string
const (
	SearchFilesSearchInPath          SearchFilesSearchIn = "path"
	SearchFilesSearchInContent       SearchFilesSearchIn = "content"
	SearchFilesSearchInPathOrContent SearchFilesSearchIn = "pathOrContent"
)

type TextFile 

type TextFile struct {
	Path            string
	Perm            fs.FileMode
	Newline         NewlineKind
	HasFinalNewline bool
	Lines           []string
	SizeBytes       int64
	ModTimeUTC      *time.Time
}

TextFile is a normalized in-memory view of a UTF‑8 text file. Lines never include trailing newline characters.

func ReadTextFileUTF8 

func ReadTextFileUTF8(p fspolicy.FSPolicy, path string, maxBytes int64) (*TextFile, error)

ReadTextFileUTF8 reads a file as UTF‑8 text and returns a normalized TextFile view. It preserves newline kind (LF vs CRLF) and whether the file ended with a final newline.

Safety behavior (policy-driven):

  • Enforces maxBytes if > 0.
  • Uses policy.RequireExistingRegularFile (which enforces symlink rules if enabled).

func (*TextFile) Render 

func (t *TextFile) Render() string

Render converts Lines back into a file string preserving newline style and final newline presence.

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.