obrimbasecli/essential/visible/service/helper/log/log.go

/*
|--------------------------------------------------------------------------
| Log
|--------------------------------------------------------------------------
|
| Name:
|   - Log
|
| Purpose:
|   - Provide a framework-level logging utility that records structured
|     plaintext log entries to a persistent filesystem location using a
|     deterministic and platform-aware storage strategy.
|
| Guidelines:
|   - Use application metadata to resolve application identity.
|   - Persist UTF-8 plaintext log entries.
|   - Preserve existing log content.
|   - Use append-only write operations.
|   - Create required directories and files when missing.
|
| Examples:
|   - ObrimLog("service/create", "resource created")
|   - ObrimLog("helper/status", "status updated")
|
|--------------------------------------------------------------------------
*/

/*
|--------------------------------------------------------------------------
| Credit
|--------------------------------------------------------------------------
|
| Contributor:
|   - Rajon Ahmed
|   - Scionite
|
|--------------------------------------------------------------------------
*/

package log

import (
	"fmt"
	"os"
	"path/filepath"
	"runtime"
	"strings"
	"time"

	"go/module/name/essential/visible/service/helper/retriever"
)

// Function Name: ObrimLog
// Function Purpose: Write a structured log entry.
func ObrimLog(label string, message string) {
	applicationName := ""

	applicationValue := retriever.ObrimRetriever(
		"json",
		map[string]any{
			"resource": "application/metadata",
			"path":     "application.lower",
		},
	)

	if applicationValue != nil {
		applicationName = fmt.Sprint(applicationValue)
	}

	if strings.TrimSpace(applicationName) == "" {
		return
	}

	timestamp := obrimLogTimestampGenerate()
	entry := obrimLogEntryBuild(timestamp, label, message)

	logDirectoryPath := obrimLogDirectoryResolve(applicationName)
	if logDirectoryPath == "" {
		return
	}

	logFilePath := obrimLogFileResolve(logDirectoryPath, applicationName)

	if !obrimLogFileEnsure(logDirectoryPath, logFilePath) {
		return
	}

	obrimLogWrite(logFilePath, entry)
}

// Function Name: obrimLogTimestampGenerate
// Function Purpose: Generate deterministic timestamps.
func obrimLogTimestampGenerate() string {
	return time.Now().UTC().Format(time.RFC3339)
}

// Function Name: obrimLogEntryBuild
// Function Purpose: Construct formatted log entries.
func obrimLogEntryBuild(timestamp string, label string, message string) string {
	return fmt.Sprintf("[%s] [%s] %s\n", timestamp, label, message)
}

// Function Name: obrimLogDirectoryResolve
// Function Purpose: Resolve platform-specific log directory paths.
func obrimLogDirectoryResolve(applicationName string) string {
	switch runtime.GOOS {
	case "linux":
		xdgStateHome := strings.TrimSpace(os.Getenv("XDG_STATE_HOME"))

		if xdgStateHome != "" {
			return filepath.Join(
				xdgStateHome,
				"."+applicationName,
				"logs",
			)
		}

		homeDirectory, errorValue := os.UserHomeDir()
		if errorValue != nil {
			return ""
		}

		return filepath.Join(
			homeDirectory,
			".local",
			"state",
			"."+applicationName,
			"logs",
		)

	case "windows":
		localApplicationData := strings.TrimSpace(os.Getenv("LOCALAPPDATA"))
		if localApplicationData == "" {
			return ""
		}

		return filepath.Join(
			localApplicationData,
			applicationName,
			"Logs",
		)

	case "darwin":
		homeDirectory, errorValue := os.UserHomeDir()
		if errorValue != nil {
			return ""
		}

		return filepath.Join(
			homeDirectory,
			"Library",
			"Logs",
			"."+applicationName,
		)
	}

	return ""
}

// Function Name: obrimLogFileResolve
// Function Purpose: Resolve platform-specific log file paths.
func obrimLogFileResolve(logDirectoryPath string, applicationName string) string {
	return filepath.Join(
		logDirectoryPath,
		applicationName+".log",
	)
}

// Function Name: obrimLogFileEnsure
// Function Purpose: Create and verify required log directories and files.
func obrimLogFileEnsure(logDirectoryPath string, logFilePath string) bool {
	if errorValue := os.MkdirAll(logDirectoryPath, 0755); errorValue != nil {
		return false
	}

	fileHandle, errorValue := os.OpenFile(
		logFilePath,
		os.O_CREATE,
		0644,
	)

	if errorValue != nil {
		return false
	}

	defer fileHandle.Close()

	return true
}

// Function Name: obrimLogWrite
// Function Purpose: Persist log entries to the filesystem.
func obrimLogWrite(logFilePath string, entry string) {
	fileHandle, errorValue := os.OpenFile(
		logFilePath,
		os.O_CREATE|os.O_APPEND|os.O_WRONLY,
		0644,
	)

	if errorValue != nil {
		return
	}

	defer fileHandle.Close()

	// Logic: Persist the complete log entry as a single appended line.
	_, _ = fileHandle.WriteString(entry)
}