rotate

Documentation

Overview

Package rotate provides a symlink-safe, permission-enforcing file writer with size-based rotation, backup retention, age-based cleanup, and optional gzip compression.

Index

• type Config
• type Writer
  • func New(filename string, cfg Config) (*Writer, error)
  • func (w *Writer) Close() error
  • func (w *Writer) Sync() error
  • func (w *Writer) Write(p []byte) (n int, err error)

Types

type Config

type Config struct {
	// OnRotate is called from the Write goroutine immediately after a
	// successful rotation. The path argument is the absolute path of
	// the file that was rotated. It must not block. If nil, rotation
	// events are silently discarded.
	OnRotate func(path string)

	// OnError is called sequentially from a single background goroutine
	// whenever a background operation (compression, backup removal,
	// age-based cleanup) fails. It must not block. If nil, errors are
	// silently discarded.
	OnError func(error)

	// MaxSize is the maximum size in bytes of the active log file before
	// rotation is triggered. Required; must be > 0.
	MaxSize int64

	// MaxAge is the maximum age of backup files. Backups older than this
	// duration are removed during cleanup. Zero means no age limit.
	MaxAge time.Duration

	// MaxBackups is the maximum number of backup files to retain. Zero
	// means unlimited.
	MaxBackups int

	// Mode is the file permission bits applied to every file the writer
	// creates or opens — active, backup, and compressed. Required; must
	// be non-zero.
	Mode os.FileMode

	// Compress enables gzip compression of rotated backup files.
	Compress bool
}

Config controls the rotation behaviour of a Writer.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer is a concurrency-safe file writer with automatic size-based rotation. It protects against symlink attacks on every open and enforces configured permissions on all files it creates.

Writer is lazy — New validates the configuration but does not create or open the file. The file is opened on the first Writer.Write.

func New

func New(filename string, cfg Config) (*Writer, error)

New creates a Writer that will write to filename with the given rotation configuration. New validates the configuration and checks that the parent directory exists, but does not create or open the file.

func (*Writer) Close

func (w *Writer) Close() error

Close closes the active file and waits for any in-progress compression to finish. Close is idempotent.

func (*Writer) Sync

func (w *Writer) Sync() error

Sync flushes the buffered writer and the file's in-memory state to stable storage.

func (*Writer) Write

func (w *Writer) Write(p []byte) (n int, err error)

Write writes p to the active log file, rotating if the write would cause the file to exceed [Config.MaxSize]. A single write that exceeds MaxSize is accepted (written then rotated) to avoid silently dropping audit events.

Write returns an error wrapping os.ErrClosed if the writer has been closed.