feat(acl): add reason field to ACL logging for decision tracking

Add a reason parameter throughout the ACL system to track and log why
each IP was allowed or denied. This provides better visibility into
ACL decisions by recording specific reasons such as "allowed by
allow_local rule", "blocked by deny rule: [rule]", or "deny by default".

Changes include:
- Add reason field to checkCache and ipLog structs
- Update LogACL interface and implementations to accept reason
- Generate descriptive reasons for all ACL decision paths
- Include reason in console log output

internal/logging/accesslog/console_logger.go

@@ -59,8 +59,8 @@ func (l *ConsoleLogger) LogError(req *http.Request, err error) {
 	l.formatter.LogRequestZeroLog(&log, req, internalErrorResponse)
 }
 
-func (l *ConsoleLogger) LogACL(info *maxmind.IPInfo, blocked bool) {
-	ConsoleACLFormatter{}.LogACLZeroLog(stdoutLogger, info, blocked)
+func (l *ConsoleLogger) LogACL(info *maxmind.IPInfo, blocked bool, reason string) {
+	ConsoleACLFormatter{}.LogACLZeroLog(stdoutLogger, info, blocked, reason)
 }
 
 func (l *ConsoleLogger) Flush() {

internal/logging/accesslog/file_access_logger.go

@@ -131,7 +131,7 @@ func (l *fileAccessLogger) LogError(req *http.Request, err error) {
 	l.LogRequest(req, internalErrorResponse)
 }
 
-func (l *fileAccessLogger) LogACL(info *maxmind.IPInfo, blocked bool) {
+func (l *fileAccessLogger) LogACL(info *maxmind.IPInfo, blocked bool, reason string) {
 	line := bytesPool.GetBuffer()
 	defer bytesPool.PutBuffer(line)
 	l.AppendACLLog(line, info, blocked)

internal/logging/accesslog/formatter.go

@@ -171,7 +171,7 @@ func (f ACLLogFormatter) LogACLZeroLog(logger *zerolog.Logger, info *maxmind.IPI
 	event.Send()
 }
 
-func (f ConsoleACLFormatter) LogACLZeroLog(logger *zerolog.Logger, info *maxmind.IPInfo, blocked bool) {
+func (f ConsoleACLFormatter) LogACLZeroLog(logger *zerolog.Logger, info *maxmind.IPInfo, blocked bool, reason string) {
 	event := logger.Info()
 	if info.City != nil {
 		if isoCode := info.City.Country.IsoCode; isoCode != "" {
@@ -186,6 +186,10 @@ func (f ConsoleACLFormatter) LogACLZeroLog(logger *zerolog.Logger, info *maxmind
 		action = "denied"
 	}
 
+	if reason != "" {
+		event.Str("reason", reason)
+	}
+
 	// NOTE: zerolog will append a newline to the buffer
 	event.Msgf("request %s from %s", action, info.Str)
 }

internal/logging/accesslog/multi_access_logger.go

@@ -50,9 +50,9 @@ func (m *MultiAccessLogger) LogError(req *http.Request, err error) {
 	}
 }
 
-func (m *MultiAccessLogger) LogACL(info *maxmind.IPInfo, blocked bool) {
+func (m *MultiAccessLogger) LogACL(info *maxmind.IPInfo, blocked bool, reason string) {
 	for _, accessLogger := range m.accessLoggers {
-		accessLogger.LogACL(info, blocked)
+		accessLogger.LogACL(info, blocked, reason)
 	}
 }
 

internal/logging/accesslog/multi_access_logger_test.go

@@ -116,7 +116,7 @@ func TestMultiAccessLoggerLogACL(t *testing.T) {
 		Str: "192.168.1.1",
 	}
 
-	logger.LogACL(info, false)
+	logger.LogACL(info, false, "test reason")
 	logger.Flush()
 
 	expect.Equal(t, writer1.NumLines(), 1)
@@ -252,7 +252,7 @@ func TestMultiAccessLoggerMixedOperations(t *testing.T) {
 	cfg2 := DefaultACLLoggerConfig()
 	cfg2.LogAllowed = true
 	aclLogger := NewMultiAccessLogger(testTask, cfg2, writers)
-	aclLogger.LogACL(info, false)
+	aclLogger.LogACL(info, false, "test reason")
 
 	logger.Flush()
 

internal/logging/accesslog/types.go

@@ -13,7 +13,7 @@ type (
 	AccessLogger interface {
 		LogRequest(req *http.Request, res *http.Response)
 		LogError(req *http.Request, err error)
-		LogACL(info *maxmind.IPInfo, blocked bool)
+		LogACL(info *maxmind.IPInfo, blocked bool, reason string)
 
 		Config() *Config
 
@@ -35,9 +35,9 @@ type (
 	}
 	ACLFormatter interface {
 		// AppendACLLog appends a log line to line with or without a trailing newline
-		AppendACLLog(line *bytes.Buffer, info *maxmind.IPInfo, blocked bool)
+		AppendACLLog(line *bytes.Buffer, info *maxmind.IPInfo, blocked bool, reason string)
 		// LogACLZeroLog logs an ACL log to the logger
-		LogACLZeroLog(logger *zerolog.Logger, info *maxmind.IPInfo, blocked bool)
+		LogACLZeroLog(logger *zerolog.Logger, info *maxmind.IPInfo, blocked bool, reason string)
 	}
 )