Fsutils (#98)

* Add: fsutils package with function FormatFileSize

* Update: implement FindFiles function

* Update: implement GetDirectorySize function

* Update: implement FilesIdentical function

* Update: implement DirsIdentical function

* Update: Add validation for directory traversal security.

* Optimize memory usage for large file comparisons.

* Add symlink handling and optimize directory comparison

* Update: Enhance DirsIdentical test coverage

* Enhance error handling tests for FindFiles

* Update: Check error return value from os.Chmod

* Update: Implement GetFileMetadata function

* Update: enhanced error handling and input validation

* Update: Add test cases for better coverage

* Update: Handle non-Unix systems gracefully

Author: danilovict2

EXAMPLES.md

@@ -18,6 +18,8 @@ This document provides practical examples of how to use the library's features.
 14. [Time](#14-time)
 15. [Loggin](#15-logging)
 16. [File System Utilities](#16-fsutils)
+15. [Loggin](#15-logging)
+16. [File System Utilities](#16-fsutils)
 
 ## 1. Boolean
 
@@ -2583,3 +2585,114 @@ func main() {
 ```
 The directories /path/to/your/dir1 and /path/to/your/dir2 are identical.
 ```
+
+### Get File Metadata
+```go
+package main
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/kashifkhan0771/utils/fsutils"
+)
+
+func main() {
+	file := "example.txt"
+	metadata, err := fsutils.GetFileMetadata(file)
+	if err != nil {
+		log.Fatal(err)
+		return
+	}
+
+	fmt.Printf(
+		"Name: %s, Size: %d, IsDir: %t, ModTime: %s, Mode: %v, Path: %s, Ext: %s, Owner: %s\n",
+		metadata.Name, metadata.Size, 
+		metadata.IsDir, metadata.ModTime.String(), 
+		metadata.Mode, metadata.Path, 
+		metadata.Ext, metadata.Owner,
+	)
+}
+
+```
+#### Output:
+```
+Name: example.txt, Size: 172, IsDir: false, ModTime: 2025-01-20 15:03:00.189199994 +0100 CET, Mode: -rw-rw-r--, Path: /path/to/your/dir/example.txt, Ext: .txt, Owner: owner
+```
+
+### Get Directory Metadata
+```go
+package main
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/kashifkhan0771/utils/fsutils"
+)
+
+func main() {
+	dir := "example/"
+	metadata, err := fsutils.GetFileMetadata(dir)
+	if err != nil {
+		log.Fatal(err)
+		return
+	}
+
+	fmt.Printf(
+		"Name: %s, Size: %d, IsDir: %t, ModTime: %s, Mode: %v, Path: %s, Ext: %s, Owner: %s\n",
+		metadata.Name, metadata.Size, 
+		metadata.IsDir, metadata.ModTime.String(), 
+		metadata.Mode, metadata.Path, 
+		metadata.Ext, metadata.Owner,
+	)
+}
+
+```
+#### Output:
+```
+Name: example, Size: 4096, IsDir: true, ModTime: 2025-01-20 15:06:23.057206656 +0100 CET, Mode: drwxrwxr-x, Path: /path/to/your/dir/example, Ext: , Owner: owner
+```
+
+### Marshal File's Metadata to JSON
+```go
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+
+	"github.com/kashifkhan0771/utils/fsutils"
+)
+
+func main() {
+	file := "example.txt"
+	metadata, err := fsutils.GetFileMetadata(file)
+	if err != nil {
+		log.Fatal(err)
+		return
+	}
+
+	json, err := json.Marshal(&metadata)
+	if err != nil {
+		log.Fatal(err)
+		return
+	}
+
+	fmt.Println(string(json))
+}
+
+```
+#### Output:
+```json
+{
+   "name": "example.txt",
+   "size": 172,
+   "is_dir": false,
+   "mod_time": "2025-01-20T15:06:34.812677487+01:00",
+   "mode": 436,
+   "path": "/path/to/your/dir/example.txt",
+   "ext": ".txt",
+}
+```

fsutils/fsutils.go

@@ -6,7 +6,10 @@ import (
 	"io"
 	"io/fs"
 	"os"
+	"os/user"
 	"path/filepath"
+	"syscall"
+	"time"
 )
 
 type ByteSize int64
@@ -203,3 +206,57 @@ func DirsIdentical(dir1, dir2 string) (bool, error) {
 
 	return len(matched) == len(files1), nil
 }
+
+type FileMetadata struct {
+	Name    string      `json:"name"`
+	Size    int64       `json:"size"`
+	IsDir   bool        `json:"is_dir"`
+	ModTime time.Time   `json:"mod_time"`
+	Mode    os.FileMode `json:"mode"`
+	Path    string      `json:"path"`
+	Ext     string      `json:"ext"`
+	Owner   string      `json:"owner"`
+}
+
+// GetFileMetadata retrieves metadata for the specified file path.
+// It returns a FileMetadata struct containing details about the file.
+func GetFileMetadata(filePath string) (FileMetadata, error) {
+	if filePath == "" {
+		return FileMetadata{}, fmt.Errorf("file path cannot be empty")
+	}
+
+	filePath = filepath.Clean(filePath)
+
+	info, err := os.Lstat(filePath)
+	if err != nil {
+		return FileMetadata{}, err
+	}
+
+	path, err := filepath.Abs(filePath)
+	if err != nil {
+		return FileMetadata{}, err
+	}
+
+	metadata := FileMetadata{
+		Name:    info.Name(),
+		Size:    info.Size(),
+		IsDir:   info.IsDir(),
+		ModTime: info.ModTime(),
+		Mode:    info.Mode(),
+		Path:    path,
+		Ext:     filepath.Ext(info.Name()),
+	}
+
+	if stat, ok := info.Sys().(*syscall.Stat_t); ok {
+		owner, err := user.LookupId(fmt.Sprint(stat.Uid))
+		if err != nil {
+			return metadata, fmt.Errorf("failed to lookup owner: %w", err)
+		}
+
+		metadata.Owner = owner.Username
+	} else {
+		metadata.Owner = "unknown"
+	}
+
+	return metadata, nil
+}

fsutils/fsutils_test.go

@@ -396,3 +396,107 @@ func setupNestedDirs(t *testing.T) (string, string) {
 
 	return tempDir1, tempDir2
 }
+
+func TestGetFileMetadata(t *testing.T) {
+	// Create a temporary directory for testing
+	tempDir, err := os.MkdirTemp("", "testdir")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	// Create a test file
+	filePath := filepath.Join(tempDir, "testfile.txt")
+	contents := "test file contents"
+	if err := os.WriteFile(filePath, []byte(contents), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	t.Run("Get file metadata", func(t *testing.T) {
+		metadata, err := GetFileMetadata(filePath)
+		if err != nil {
+			t.Fatalf("GetFileMetadata() error = %v", err)
+		}
+
+		if metadata.Name != "testfile.txt" {
+			t.Errorf("GetFileMetadata() Name = %v; want %v", metadata.Name, "testfile.txt")
+		}
+
+		if metadata.Size != int64(len(contents)) {
+			t.Errorf("GetFileMetadata() Size = %v; want %v", metadata.Size, len(contents))
+		}
+
+		if metadata.IsDir {
+			t.Errorf("GetFileMetadata() IsDir = %v; want %v", metadata.IsDir, false)
+		}
+
+		if metadata.Ext != ".txt" {
+			t.Errorf("GetFileMetadata() Ext = %v; want %v", metadata.Ext, ".txt")
+		}
+
+		if metadata.Path != filePath {
+			t.Errorf("GetFileMetadata() Path = %v; want %v", metadata.Path, filePath)
+		}
+
+		if metadata.Owner == "" {
+			t.Errorf("GetFileMetadata() Owner should not be empty")
+		}
+	})
+
+	t.Run("Get directory metadata", func(t *testing.T) {
+		metadata, err := GetFileMetadata(tempDir)
+		if err != nil {
+			t.Fatalf("GetFileMetadata() error = %v", err)
+		}
+
+		if metadata.Name != filepath.Base(tempDir) {
+			t.Errorf("GetFileMetadata() Name = %v; want %v", metadata.Name, filepath.Base(tempDir))
+		}
+
+		if !metadata.IsDir {
+			t.Errorf("GetFileMetadata() IsDir = %v; want %v", metadata.IsDir, true)
+		}
+	})
+
+	t.Run("Nonexistent file", func(t *testing.T) {
+		_, err := GetFileMetadata(filepath.Join(tempDir, "nonexistent.txt"))
+		if err == nil {
+			t.Error("Expected error for nonexistent file")
+		}
+	})
+
+	t.Run("Empty path", func(t *testing.T) {
+		_, err := GetFileMetadata("")
+		if err == nil {
+			t.Error("Expected error for empty path")
+		}
+	})
+
+	t.Run("Symlink", func(t *testing.T) {
+		tempDir, err := os.MkdirTemp("", "testdir")
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer os.RemoveAll(tempDir)
+
+		// Create a file and a symlink to it
+		filePath := filepath.Join(tempDir, "testfile.txt")
+		if err := os.WriteFile(filePath, []byte("test"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		linkPath := filepath.Join(tempDir, "testlink")
+		if err := os.Symlink(filePath, linkPath); err != nil {
+			t.Fatal(err)
+		}
+
+		metadata, err := GetFileMetadata(linkPath)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		if metadata.Mode&os.ModeSymlink == 0 {
+			t.Error("Expected symlink mode")
+		}
+	})
+}

readME.md

@@ -255,6 +255,8 @@ The `logging` package provides a simple, flexible, and color-coded logging syste
 
 - **DirsIdentical**: Compares two directories to determine if they are identical.
 
+- **GetFileMetadata**: Retrieves metadata for a specified file path. Returns a `FileMetadata` struct that can be marshaled to JSON.
+
 ---
 
 ## Examples: