fsutil

Documentation

Index

• func DetectContentType(r io.Reader, fileName string) (string, error)
• func DetectContentTypeByExtension(fileName string) string
• func FileExists(fs fs.StatFS, file string) bool
• func GetFileExtension(filename string) string
• func GetMIMEType(filesystem fs.FS, file string) (contentType string, size int64, err error)
• func IsDirectory(fs fs.StatFS, path string) bool
• type Embed
  • func NewEmbed(fs fs.ReadDirFS) Embed
  • func (e Embed) Open(name string) (fs.File, error)
  • func (e Embed) ReadDir(name string) ([]fs.DirEntry, error)
  • func (e Embed) Stat(name string) (fileinfo fs.FileInfo, err error)
  • func (e Embed) Sub(dir string) (Embed, error)
• type FS
• type File
  • func ParseMultipartFiles(headers []*multipart.FileHeader) ([]File, error)
  • func (file File) MarshalJSON() ([]byte, error)
  • func (file *File) Save(fs WritableFS, path string, name string) (filename string, err error)
  • func (file *File) UnmarshalJSON(data []byte) error
• type MkdirFS
• type RemoveFS
• type WorkingDirFS
• type WritableFS

Functions

func DetectContentType

func DetectContentType(r io.Reader, fileName string) (string, error)

DetectContentType by sniffing the first 512 bytes of the given reader using `http.DetectContentType`.

If the detected content type is `"application/octet-stream"` or `"text/plain"`, this function will attempt to find a more precise one using `fsutil.DetectContentTypeByExtension`. The header parameter is retained (e.g: `charset=utf-8`).

If there is no error, this function always returns a valid MIME type. If it cannot determine a more specific one, it returns `"application/octet-stream"`.

If the given reader implements `io.Seeker`, the reader's offset is reset to the start.

func DetectContentTypeByExtension

func DetectContentTypeByExtension(fileName string) string

DetectContentTypeByExtension returns a MIME type associated with the extension (suffix) of the given file name. Note that this function should be used as a fallback if sniffing using `fsutil.DetectContentType` isn't possible due to:

• the file being empty (size of 0)
• the file requiring to be read after the sniffing but its reader doesn't implement `io.Seeker` for rewinding.

The local database covers the most common MIME types. If the extension is not known to the `fsutil` package, returns `"application/octet-stream"`.

func FileExists

func FileExists(fs fs.StatFS, file string) bool

FileExists returns true if the file at the given path exists and is readable. Returns false if the given file is a directory.

func GetFileExtension

func GetFileExtension(filename string) string

GetFileExtension returns the last part of a file name. If the file doesn't have an extension, returns an empty string.

func GetMIMEType

func GetMIMEType(filesystem fs.FS, file string) (contentType string, size int64, err error)

GetMIMEType get the mime type and size of the given file. This function opens the file, stats it and calls `fsutil.DetectContentType`. If the file is empty (size of 0), the content-type will be detected using `fsutil.DetectContentTypeByExtension`. If a specific MIME type cannot be determined, returns "application/octet-stream" as a fallback.

func IsDirectory

func IsDirectory(fs fs.StatFS, path string) bool

IsDirectory returns true if the file at the given path exists, is a directory and is readable.

Types

type Embed

type Embed struct {
	FS fs.ReadDirFS
}

Embed is an extension of aimed at improving `embed.FS` by implementing `fs.StatFS` and a `Sub()` function.

func NewEmbed

func NewEmbed(fs fs.ReadDirFS) Embed

NewEmbed returns a new Embed with the given FS.

func (Embed) Open

func (e Embed) Open(name string) (fs.File, error)

Open opens the named file.

When Open returns an error, it should be of type *PathError with the Op field set to "open", the Path field set to name, and the Err field describing the problem.

Open should reject attempts to open names that do not satisfy ValidPath(name), returning a *PathError with Err set to ErrInvalid or ErrNotExist.

func (Embed) ReadDir

func (e Embed) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir reads the named directory and returns a list of directory entries sorted by filename.

func (Embed) Stat

func (e Embed) Stat(name string) (fileinfo fs.FileInfo, err error)

Stat returns a FileInfo describing the file.

func (Embed) Sub

func (e Embed) Sub(dir string) (Embed, error)

Sub returns an Embed FS corresponding to the subtree rooted at dir. Returns and error if the underlying sub FS doesn't implement `fs.ReadDirFS`.

type FS

type FS interface {
	fs.ReadDirFS
	fs.StatFS
}

An FS provides access to a hierarchical file system and implements `io/fs`'s `FS`, `ReadDirFS` and `StatFS` interfaces.

type File

type File struct {
	Header   *multipart.FileHeader
	MIMEType string
}

File represents a file received from client.

File implements `json.Marshaler` and `json.Unmarshaler` to be able to be used in DTO conversion (`typeutil.Convert()`). This works with a global concurrency-safe map that acts as a cache for the `*multipart.FileHeader`. When marshaling, a UUID v1 is generated and used as a key. This UUID is the actual value used when marhsaling the `Header` field. When unmarshaling, the `*multipart.FileHeader` is retrieved then deleted from the cache. To avoid orphans clogging up the cache, you should never JSON marshal this type outside of `typeutil.Convert()`: if a marshaled File never gets unmarshaled, its UUID would remain in the cache forever.

func ParseMultipartFiles

func ParseMultipartFiles(headers []*multipart.FileHeader) ([]File, error)

ParseMultipartFiles parse a single file field in a request.

func (File) MarshalJSON

func (file File) MarshalJSON() ([]byte, error)

MarshalJSON implementation of `json.Marhsaler`.

func (*File) Save

func (file *File) Save(fs WritableFS, path string, name string) (filename string, err error)

Save writes the file's content to a new file in the given file system. Appends a timestamp to the given file name to avoid duplicate file names. The file is not readable anymore once saved as its FileReader has already been closed.

Creates directories if needed.

Returns the actual file name.

func (*File) UnmarshalJSON

func (file *File) UnmarshalJSON(data []byte) error

UnmarshalJSON implementation of `json.Unmarhsaler`.

type MkdirFS

type MkdirFS interface {
	// MkdirAll creates a directory named path,
	// along with any necessary parents, and returns `nil`,
	// or else returns an error.
	// The permission bits perm (before umask) are used for all
	// directories that `MkdirAll` creates.
	// If path is already a directory, `MkdirAll` does nothing
	// and returns `nil`.
	MkdirAll(path string, perm fs.FileMode) error

	// Mkdir creates a new directory with the specified name and permission
	// bits (before umask).
	// If there is an error, it will be of type `*PathError`.
	Mkdir(path string, perm fs.FileMode) error
}

A MkdirFS is a file system with a `Mkdir()` and a `MkdirAll()` methods.

type RemoveFS

type RemoveFS interface {
	// Remove removes the named file or (empty) directory.
	// If there is an error, it will be of type `*PathError`.
	Remove(path string) error

	// RemoveAll removes path and any children it contains.
	// It removes everything it can but returns the first error
	// it encounters. If the path does not exist, `RemoveAll`
	// returns `nil` (no error).
	// If there is an error, it will be of type `*PathError`.
	RemoveAll(path string) error
}

A RemoveFS is a file system with a `Remove()` and a `RemoveAll()` methods.

type WorkingDirFS

type WorkingDirFS interface {
	// Getwd returns a rooted path name corresponding to the
	// current directory. If the current directory can be
	// reached via multiple paths (due to symbolic links),
	// Getwd may return any one of them.
	Getwd() (dir string, err error)
}

A WorkingDirFS is a file system with a `Getwd()` method.

type WritableFS

type WritableFS interface {
	// OpenFile is the generalized open call. It opens the named file with specified flag
	// (`O_RDONLY` etc.). If the file does not exist, and the `O_CREATE` flag
	// is passed, it is created with mode perm (before umask). If successful,
	// methods on the returned file can be used for I/O.
	// If there is an error, it will be of type `*PathError`.
	OpenFile(path string, flag int, perm fs.FileMode) (io.ReadWriteCloser, error)
}

A WritableFS is a file system with a `OpenFile()` method.