v0.1.3 formatter exported, docs updated
This commit is contained in:
370
formatter/formatter.go
Normal file
370
formatter/formatter.go
Normal file
@ -0,0 +1,370 @@
|
||||
// FILE: lixenwraith/log/formatter/formatter.go
|
||||
package formatter
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strconv"
|
||||
"time"
|
||||
"unicode/utf8"
|
||||
|
||||
"github.com/lixenwraith/log/sanitizer"
|
||||
)
|
||||
|
||||
// Format flags for controlling output structure
|
||||
const (
|
||||
FlagRaw int64 = 0b0001
|
||||
FlagShowTimestamp int64 = 0b0010
|
||||
FlagShowLevel int64 = 0b0100
|
||||
FlagStructuredJSON int64 = 0b1000
|
||||
FlagDefault = FlagShowTimestamp | FlagShowLevel
|
||||
)
|
||||
|
||||
// Formatter manages the buffered writing and formatting of log entries
|
||||
type Formatter struct {
|
||||
sanitizer *sanitizer.Sanitizer
|
||||
format string
|
||||
timestampFormat string
|
||||
showTimestamp bool
|
||||
showLevel bool
|
||||
buf []byte
|
||||
}
|
||||
|
||||
// New creates a formatter with the provided sanitizer
|
||||
func New(s ...*sanitizer.Sanitizer) *Formatter {
|
||||
var san *sanitizer.Sanitizer
|
||||
if len(s) > 0 && s[0] != nil {
|
||||
san = s[0]
|
||||
} else {
|
||||
san = sanitizer.New() // Default passthrough sanitizer
|
||||
}
|
||||
return &Formatter{
|
||||
sanitizer: san,
|
||||
format: "txt",
|
||||
timestampFormat: time.RFC3339Nano,
|
||||
showTimestamp: true,
|
||||
showLevel: true,
|
||||
buf: make([]byte, 0, 1024),
|
||||
}
|
||||
}
|
||||
|
||||
// Type sets the output format ("txt", "json", or "raw")
|
||||
func (f *Formatter) Type(format string) *Formatter {
|
||||
f.format = format
|
||||
return f
|
||||
}
|
||||
|
||||
// TimestampFormat sets the timestamp format string
|
||||
func (f *Formatter) TimestampFormat(format string) *Formatter {
|
||||
if format != "" {
|
||||
f.timestampFormat = format
|
||||
}
|
||||
return f
|
||||
}
|
||||
|
||||
// ShowLevel sets whether to include level in output
|
||||
func (f *Formatter) ShowLevel(show bool) *Formatter {
|
||||
f.showLevel = show
|
||||
return f
|
||||
}
|
||||
|
||||
// ShowTimestamp sets whether to include timestamp in output
|
||||
func (f *Formatter) ShowTimestamp(show bool) *Formatter {
|
||||
f.showTimestamp = show
|
||||
return f
|
||||
}
|
||||
|
||||
// Format formats a log entry using configured options and explicit flags
|
||||
func (f *Formatter) Format(flags int64, timestamp time.Time, level int64, trace string, args []any) []byte {
|
||||
// Override configured values with explicit flags
|
||||
effectiveShowTimestamp := (flags&FlagShowTimestamp) != 0 || (flags == 0 && f.showTimestamp)
|
||||
effectiveShowLevel := (flags&FlagShowLevel) != 0 || (flags == 0 && f.showLevel)
|
||||
|
||||
// Build effective flags
|
||||
effectiveFlags := flags
|
||||
if effectiveShowTimestamp {
|
||||
effectiveFlags |= FlagShowTimestamp
|
||||
}
|
||||
if effectiveShowLevel {
|
||||
effectiveFlags |= FlagShowLevel
|
||||
}
|
||||
|
||||
return f.FormatWithOptions(f.format, effectiveFlags, timestamp, level, trace, args)
|
||||
}
|
||||
|
||||
// FormatWithOptions formats with explicit format and flags, ignoring configured values
|
||||
func (f *Formatter) FormatWithOptions(format string, flags int64, timestamp time.Time, level int64, trace string, args []any) []byte {
|
||||
f.Reset()
|
||||
|
||||
// FlagRaw completely bypasses formatting and sanitization
|
||||
if flags&FlagRaw != 0 {
|
||||
for i, arg := range args {
|
||||
if i > 0 {
|
||||
f.buf = append(f.buf, ' ')
|
||||
}
|
||||
// Direct conversion without sanitization
|
||||
switch v := arg.(type) {
|
||||
case string:
|
||||
f.buf = append(f.buf, v...)
|
||||
case []byte:
|
||||
f.buf = append(f.buf, v...)
|
||||
case fmt.Stringer:
|
||||
f.buf = append(f.buf, v.String()...)
|
||||
case error:
|
||||
f.buf = append(f.buf, v.Error()...)
|
||||
default:
|
||||
f.buf = append(f.buf, fmt.Sprint(v)...)
|
||||
}
|
||||
}
|
||||
return f.buf
|
||||
}
|
||||
|
||||
// Create the serializer based on the effective format
|
||||
serializer := sanitizer.NewSerializer(format, f.sanitizer)
|
||||
|
||||
switch format {
|
||||
case "raw":
|
||||
// Raw formatting serializes the arguments and adds NO metadata or newlines
|
||||
for i, arg := range args {
|
||||
f.convertValue(&f.buf, arg, serializer, i > 0)
|
||||
}
|
||||
return f.buf
|
||||
|
||||
case "json":
|
||||
return f.formatJSON(flags, timestamp, level, trace, args, serializer)
|
||||
|
||||
case "txt":
|
||||
return f.formatTxt(flags, timestamp, level, trace, args, serializer)
|
||||
}
|
||||
|
||||
return nil // forcing panic on unrecognized format
|
||||
}
|
||||
|
||||
// FormatValue formats a single value according to the formatter's configuration
|
||||
func (f *Formatter) FormatValue(v any) []byte {
|
||||
f.Reset()
|
||||
serializer := sanitizer.NewSerializer(f.format, f.sanitizer)
|
||||
f.convertValue(&f.buf, v, serializer, false)
|
||||
return f.buf
|
||||
}
|
||||
|
||||
// FormatArgs formats multiple arguments as space-separated values
|
||||
func (f *Formatter) FormatArgs(args ...any) []byte {
|
||||
f.Reset()
|
||||
serializer := sanitizer.NewSerializer(f.format, f.sanitizer)
|
||||
for i, arg := range args {
|
||||
f.convertValue(&f.buf, arg, serializer, i > 0)
|
||||
}
|
||||
return f.buf
|
||||
}
|
||||
|
||||
// Reset clears the formatter buffer for reuse
|
||||
func (f *Formatter) Reset() {
|
||||
f.buf = f.buf[:0]
|
||||
}
|
||||
|
||||
// LevelToString converts integer level values to string
|
||||
func LevelToString(level int64) string {
|
||||
switch level {
|
||||
case -4:
|
||||
return "DEBUG"
|
||||
case 0:
|
||||
return "INFO"
|
||||
case 4:
|
||||
return "WARN"
|
||||
case 8:
|
||||
return "ERROR"
|
||||
case 12:
|
||||
return "PROC"
|
||||
case 16:
|
||||
return "DISK"
|
||||
case 20:
|
||||
return "SYS"
|
||||
default:
|
||||
return fmt.Sprintf("LEVEL(%d)", level)
|
||||
}
|
||||
}
|
||||
|
||||
// convertValue provides unified type conversion
|
||||
func (f *Formatter) convertValue(buf *[]byte, v any, serializer *sanitizer.Serializer, needsSpace bool) {
|
||||
if needsSpace && len(*buf) > 0 {
|
||||
*buf = append(*buf, ' ')
|
||||
}
|
||||
|
||||
switch val := v.(type) {
|
||||
case string:
|
||||
serializer.WriteString(buf, val)
|
||||
|
||||
case []byte:
|
||||
serializer.WriteString(buf, string(val))
|
||||
|
||||
case rune:
|
||||
var runeStr [utf8.UTFMax]byte
|
||||
n := utf8.EncodeRune(runeStr[:], val)
|
||||
serializer.WriteString(buf, string(runeStr[:n]))
|
||||
|
||||
case int:
|
||||
num := strconv.AppendInt(nil, int64(val), 10)
|
||||
serializer.WriteNumber(buf, string(num))
|
||||
|
||||
case int64:
|
||||
num := strconv.AppendInt(nil, val, 10)
|
||||
serializer.WriteNumber(buf, string(num))
|
||||
|
||||
case uint:
|
||||
num := strconv.AppendUint(nil, uint64(val), 10)
|
||||
serializer.WriteNumber(buf, string(num))
|
||||
|
||||
case uint64:
|
||||
num := strconv.AppendUint(nil, val, 10)
|
||||
serializer.WriteNumber(buf, string(num))
|
||||
|
||||
case float32:
|
||||
num := strconv.AppendFloat(nil, float64(val), 'f', -1, 32)
|
||||
serializer.WriteNumber(buf, string(num))
|
||||
|
||||
case float64:
|
||||
num := strconv.AppendFloat(nil, val, 'f', -1, 64)
|
||||
serializer.WriteNumber(buf, string(num))
|
||||
|
||||
case bool:
|
||||
serializer.WriteBool(buf, val)
|
||||
|
||||
case nil:
|
||||
serializer.WriteNil(buf)
|
||||
|
||||
case time.Time:
|
||||
timeStr := val.Format(f.timestampFormat)
|
||||
serializer.WriteString(buf, timeStr)
|
||||
|
||||
case error:
|
||||
serializer.WriteString(buf, val.Error())
|
||||
|
||||
case fmt.Stringer:
|
||||
serializer.WriteString(buf, val.String())
|
||||
|
||||
default:
|
||||
serializer.WriteComplex(buf, val)
|
||||
}
|
||||
}
|
||||
|
||||
// formatJSON unifies JSON output
|
||||
func (f *Formatter) formatJSON(flags int64, timestamp time.Time, level int64, trace string, args []any, serializer *sanitizer.Serializer) []byte {
|
||||
f.buf = append(f.buf, '{')
|
||||
needsComma := false
|
||||
|
||||
if flags&FlagShowTimestamp != 0 {
|
||||
f.buf = append(f.buf, `"time":"`...)
|
||||
f.buf = timestamp.AppendFormat(f.buf, f.timestampFormat)
|
||||
f.buf = append(f.buf, '"')
|
||||
needsComma = true
|
||||
}
|
||||
|
||||
if flags&FlagShowLevel != 0 {
|
||||
if needsComma {
|
||||
f.buf = append(f.buf, ',')
|
||||
}
|
||||
f.buf = append(f.buf, `"level":"`...)
|
||||
f.buf = append(f.buf, LevelToString(level)...)
|
||||
f.buf = append(f.buf, '"')
|
||||
needsComma = true
|
||||
}
|
||||
|
||||
if trace != "" {
|
||||
if needsComma {
|
||||
f.buf = append(f.buf, ',')
|
||||
}
|
||||
f.buf = append(f.buf, `"trace":`...)
|
||||
serializer.WriteString(&f.buf, trace)
|
||||
needsComma = true
|
||||
}
|
||||
|
||||
// Handle structured JSON if flag is set and args match pattern
|
||||
if flags&FlagStructuredJSON != 0 && len(args) >= 2 {
|
||||
if message, ok := args[0].(string); ok {
|
||||
if fields, ok := args[1].(map[string]any); ok {
|
||||
if needsComma {
|
||||
f.buf = append(f.buf, ',')
|
||||
}
|
||||
f.buf = append(f.buf, `"message":`...)
|
||||
serializer.WriteString(&f.buf, message)
|
||||
|
||||
f.buf = append(f.buf, ',')
|
||||
f.buf = append(f.buf, `"fields":`...)
|
||||
|
||||
marshaledFields, err := json.Marshal(fields)
|
||||
if err != nil {
|
||||
f.buf = append(f.buf, `{"_marshal_error":"`...)
|
||||
serializer.WriteString(&f.buf, err.Error())
|
||||
f.buf = append(f.buf, `"}`...)
|
||||
} else {
|
||||
f.buf = append(f.buf, marshaledFields...)
|
||||
}
|
||||
|
||||
f.buf = append(f.buf, '}', '\n')
|
||||
return f.buf
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Regular JSON with fields array
|
||||
if len(args) > 0 {
|
||||
if needsComma {
|
||||
f.buf = append(f.buf, ',')
|
||||
}
|
||||
f.buf = append(f.buf, `"fields":[`...)
|
||||
for i, arg := range args {
|
||||
if i > 0 {
|
||||
f.buf = append(f.buf, ',')
|
||||
}
|
||||
f.convertValue(&f.buf, arg, serializer, false)
|
||||
}
|
||||
f.buf = append(f.buf, ']')
|
||||
}
|
||||
|
||||
f.buf = append(f.buf, '}', '\n')
|
||||
return f.buf
|
||||
}
|
||||
|
||||
// formatTxt handles txt format output
|
||||
func (f *Formatter) formatTxt(flags int64, timestamp time.Time, level int64, trace string, args []any, serializer *sanitizer.Serializer) []byte {
|
||||
needsSpace := false
|
||||
|
||||
if flags&FlagShowTimestamp != 0 {
|
||||
f.buf = timestamp.AppendFormat(f.buf, f.timestampFormat)
|
||||
needsSpace = true
|
||||
}
|
||||
|
||||
if flags&FlagShowLevel != 0 {
|
||||
if needsSpace {
|
||||
f.buf = append(f.buf, ' ')
|
||||
}
|
||||
f.buf = append(f.buf, LevelToString(level)...)
|
||||
needsSpace = true
|
||||
}
|
||||
|
||||
if trace != "" {
|
||||
if needsSpace {
|
||||
f.buf = append(f.buf, ' ')
|
||||
}
|
||||
// Sanitize trace to prevent terminal control sequence injection
|
||||
traceHandler := sanitizer.NewSerializer("txt", f.sanitizer)
|
||||
tempBuf := make([]byte, 0, len(trace)*2)
|
||||
traceHandler.WriteString(&tempBuf, trace)
|
||||
// Extract content without quotes if added by txt serializer
|
||||
if len(tempBuf) > 2 && tempBuf[0] == '"' && tempBuf[len(tempBuf)-1] == '"' {
|
||||
f.buf = append(f.buf, tempBuf[1:len(tempBuf)-1]...)
|
||||
} else {
|
||||
f.buf = append(f.buf, tempBuf...)
|
||||
}
|
||||
needsSpace = true
|
||||
}
|
||||
|
||||
for _, arg := range args {
|
||||
f.convertValue(&f.buf, arg, serializer, needsSpace)
|
||||
needsSpace = true
|
||||
}
|
||||
|
||||
f.buf = append(f.buf, '\n')
|
||||
return f.buf
|
||||
}
|
||||
143
formatter/formatter_test.go
Normal file
143
formatter/formatter_test.go
Normal file
@ -0,0 +1,143 @@
|
||||
// FILE: lixenwraith/log/formatter/formatter_test.go
|
||||
package formatter
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/lixenwraith/log/sanitizer"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
)
|
||||
|
||||
func TestFormatter(t *testing.T) {
|
||||
timestamp := time.Date(2024, 1, 1, 12, 0, 0, 0, time.UTC)
|
||||
|
||||
t.Run("fluent API", func(t *testing.T) {
|
||||
s := sanitizer.New().Policy(sanitizer.PolicyRaw)
|
||||
f := New(s).
|
||||
Type("json").
|
||||
TimestampFormat(time.RFC3339).
|
||||
ShowLevel(true).
|
||||
ShowTimestamp(true)
|
||||
|
||||
data := f.Format(0, timestamp, 0, "", []any{"test"})
|
||||
assert.Contains(t, string(data), `"level":"INFO"`)
|
||||
assert.Contains(t, string(data), `"time":"2024-01-01T12:00:00Z"`)
|
||||
})
|
||||
|
||||
t.Run("txt format", func(t *testing.T) {
|
||||
s := sanitizer.New().Policy(sanitizer.PolicyRaw)
|
||||
f := New(s).Type("txt")
|
||||
|
||||
data := f.Format(FlagDefault, timestamp, 0, "", []any{"test message", 123})
|
||||
str := string(data)
|
||||
|
||||
assert.Contains(t, str, "2024-01-01")
|
||||
assert.Contains(t, str, "INFO")
|
||||
assert.Contains(t, str, "test message")
|
||||
assert.Contains(t, str, "123")
|
||||
assert.True(t, strings.HasSuffix(str, "\n"))
|
||||
})
|
||||
|
||||
t.Run("json format", func(t *testing.T) {
|
||||
s := sanitizer.New().Policy(sanitizer.PolicyRaw)
|
||||
f := New(s).Type("json")
|
||||
|
||||
data := f.Format(FlagDefault, timestamp, 4, "trace1", []any{"warning", true})
|
||||
|
||||
var result map[string]any
|
||||
err := json.Unmarshal(data[:len(data)-1], &result) // Remove trailing newline
|
||||
require.NoError(t, err)
|
||||
|
||||
assert.Equal(t, "WARN", result["level"])
|
||||
assert.Equal(t, "trace1", result["trace"])
|
||||
fields := result["fields"].([]any)
|
||||
assert.Equal(t, "warning", fields[0])
|
||||
assert.Equal(t, true, fields[1])
|
||||
})
|
||||
|
||||
t.Run("raw format", func(t *testing.T) {
|
||||
s := sanitizer.New().Policy(sanitizer.PolicyRaw)
|
||||
f := New(s).Type("raw")
|
||||
|
||||
data := f.FormatWithOptions("raw", 0, timestamp, 0, "", []any{"raw", "data", 42})
|
||||
str := string(data)
|
||||
|
||||
assert.Equal(t, "raw data 42", str)
|
||||
assert.False(t, strings.HasSuffix(str, "\n"))
|
||||
})
|
||||
|
||||
t.Run("flag override raw", func(t *testing.T) {
|
||||
s := sanitizer.New().Policy(sanitizer.PolicyRaw)
|
||||
f := New(s).Type("json") // Configure as JSON
|
||||
|
||||
data := f.Format(FlagRaw, timestamp, 0, "", []any{"forced", "raw"})
|
||||
str := string(data)
|
||||
|
||||
assert.Equal(t, "forced raw", str)
|
||||
})
|
||||
|
||||
t.Run("structured json", func(t *testing.T) {
|
||||
s := sanitizer.New().Policy(sanitizer.PolicyJSON)
|
||||
f := New(s).Type("json")
|
||||
|
||||
fields := map[string]any{"key1": "value1", "key2": 42}
|
||||
data := f.Format(FlagStructuredJSON|FlagDefault, timestamp, 0, "",
|
||||
[]any{"structured message", fields})
|
||||
|
||||
var result map[string]any
|
||||
err := json.Unmarshal(data[:len(data)-1], &result)
|
||||
require.NoError(t, err)
|
||||
|
||||
assert.Equal(t, "structured message", result["message"])
|
||||
assert.Equal(t, map[string]any{"key1": "value1", "key2": float64(42)}, result["fields"])
|
||||
})
|
||||
|
||||
t.Run("special characters escaping", func(t *testing.T) {
|
||||
s := sanitizer.New().Policy(sanitizer.PolicyJSON)
|
||||
f := New(s).Type("json")
|
||||
|
||||
data := f.Format(FlagDefault, timestamp, 0, "",
|
||||
[]any{"test\n\r\t\"\\message"})
|
||||
|
||||
str := string(data)
|
||||
assert.Contains(t, str, `test\n\r\t\"\\message`)
|
||||
})
|
||||
|
||||
t.Run("error type handling", func(t *testing.T) {
|
||||
s := sanitizer.New().Policy(sanitizer.PolicyRaw)
|
||||
f := New(s).Type("txt")
|
||||
|
||||
err := errors.New("test error")
|
||||
data := f.Format(FlagDefault, timestamp, 8, "", []any{err})
|
||||
|
||||
str := string(data)
|
||||
assert.Contains(t, str, "test error")
|
||||
})
|
||||
}
|
||||
|
||||
func TestLevelToString(t *testing.T) {
|
||||
tests := []struct {
|
||||
level int64
|
||||
expected string
|
||||
}{
|
||||
{-4, "DEBUG"},
|
||||
{0, "INFO"},
|
||||
{4, "WARN"},
|
||||
{8, "ERROR"},
|
||||
{12, "PROC"},
|
||||
{16, "DISK"},
|
||||
{20, "SYS"},
|
||||
{999, "LEVEL(999)"},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.expected, func(t *testing.T) {
|
||||
assert.Equal(t, tt.expected, LevelToString(tt.level))
|
||||
})
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user