mirror of https://github.com/yusing/godoxy.git synced 2026-02-19 17:07:42 +01:00

Files

yusing 6da7227f9b refactor(errs): migrate from gperr.Error to standard Go error interface

This is a large-scale refactoring across the codebase that replaces the custom
`gperr.Error` type with Go's standard `error` interface. The changes include:

- Replacing `gperr.Error` return types with `error` in function signatures
- Using `errors.New()` and `fmt.Errorf()` instead of `gperr.New()` and `gperr.Errorf()`
- Using `%w` format verb for error wrapping instead of `.With()` method
- Replacing `gperr.Subject()` calls with `gperr.PrependSubject()`
- Converting error logging from `gperr.Log*()` functions to zerolog's `.Err().Msg()` pattern
- Update NewLogger to handle multiline error message
- Updating `goutils` submodule to latest commit

This refactoring aligns with Go idioms and removes the dependency on
custom error handling abstractions in favor of standard library patterns.

2026-02-08 12:07:36 +08:00

accesslog

refactor(errs): migrate from gperr.Error to standard Go error interface

2026-02-08 12:07:36 +08:00

memlogger

refactor(memlogger): remove HTTP/WebSocket handler and simplify buffer management

2026-01-22 15:25:50 +08:00

logging.go

refactor(errs): migrate from gperr.Error to standard Go error interface

2026-02-08 12:07:36 +08:00

README.md

docs: add per package README for implementation details (AI generated with human review)

2026-01-08 23:39:19 +08:00

README.md

Logging Package

Structured logging capabilities for GoDoxy, including application logging, HTTP access logging, and in-memory log streaming.

Overview

This package provides structured logging for GoDoxy with three distinct subsystems:

Application Logger: Zerolog-based console logger with level-aware formatting
Access Logger: HTTP request/response logging with configurable formats, filters, and destinations
In-Memory Logger: Circular buffer with WebSocket streaming for real-time log viewing

Primary Consumers

internal/api/ - HTTP request logging
internal/route/ - Route-level access logging
WebUI - Real-time log streaming via WebSocket

Non-goals

Log aggregation across multiple GoDoxy instances
Persistent storage of application logs (access logs only)
Structured logging output to external systems (Datadog, etc.)

Stability

Internal package with stable APIs. Exported interfaces (AccessLogger, MemLogger) are stable.

Packages

`accesslog/`

HTTP request/response logging with configurable formats, filters, and destinations.

See accesslog/README.md for full documentation.

`memlogger/`

In-memory circular buffer with WebSocket streaming for real-time log viewing.

See memlogger/README.md for full documentation.

Architecture

graph TB
    subgraph "Application Logger"
        L[logging.go] --> Z[zerolog.Logger]
        Z --> CW[ConsoleWriter]
    end

    subgraph "Access Log Pipeline"
        R[HTTP Request] --> M[Middleware]
        M --> RR[ResponseRecorder]
        RR --> F[Formatter]
        F --> B[BufferedWriter]
        B --> W[Writer]
        W --> F1[File]
        W --> S[Stdout]
    end

    subgraph "In-Memory Logger"
        WB[Write Buffer]
        WB --> RB[Circular Buffer<br/>16KB max]
        RB --> WS[WebSocket]
        WS --> C[Client]
    end

Configuration Surface

Access Log Configuration

See accesslog/README.md for configuration options.

In-Memory Logger

See memlogger/README.md for configuration options.

Dependency and Integration Map

Internal Dependencies

internal/task/task.go - Lifetime management
internal/maxmind/ - IP geolocation for ACL logging
pkg/gperr - Error handling

External Dependencies

github.com/rs/zerolog - Structured logging
github.com/puzpuzpuz/xsync/v4 - Concurrent maps
golang.org/x/time/rate - Error rate limiting

Observability

Logs

Level	When
`Debug`	Buffer size adjustments, rotation checks
`Info`	Log rotation events, file opens/closes
`Error`	Write failures (rate-limited)

Failure Modes and Recovery

Failure Mode	Impact	Recovery
File write failure	Log entries dropped	Rate-limited error logging; task termination after 5 errors
Disk full	Rotation fails	Continue logging until space available
WebSocket client disconnect	Client misses logs	Client reconnects to receive new logs
Buffer overflow (memlogger)	Oldest entries truncated	Automatic truncation at 50% threshold

Testing Notes

access_logger_test.go - Integration tests with mock file system
file_logger_test.go - Reference counting tests
back_scanner_test.go - Rotation boundary tests