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)
  • func (w *Writer) Writev(bufs [][]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

	// SyncOnWrite controls whether [Writer.Write] flushes the
	// bufio buffer to the OS page cache after every call. When
	// true (the previous default), every event is immediately
	// visible to readers at the cost of one syscall per call.
	// When false (the new default), bytes accumulate in the
	// bufio buffer and are flushed by the background timer
	// (see [Config.FlushInterval]), when the buffer fills, on
	// rotation, on Sync, and on Close — trading a bounded
	// data-at-risk window for measurably higher throughput on
	// the singular [Writer.Write] path.
	//
	// SyncOnWrite does NOT affect the batched [Writer.Writev]
	// path. Batched writes always commit in full to the page
	// cache as one syscall; there is no buffer between them
	// and the kernel.
	SyncOnWrite bool

	// FlushInterval is the cadence at which the background
	// flush goroutine drains the bufio buffer to the page
	// cache when [Config.SyncOnWrite] is false. Zero defaults
	// to 100 ms. Values below 1 ms are clamped to 1 ms.
	// Ignored when SyncOnWrite is true.
	FlushInterval time.Duration
}

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.

func (*Writer) Writev

func (w *Writer) Writev(bufs [][]byte) (n int, err error)

Writev writes bufs to the active log file as a single batched operation, rotating if the total size would cause the file to exceed [Config.MaxSize]. A single batch that itself exceeds MaxSize is accepted (written then rotated on the next call) — this mirrors the oversize-write semantics of Writer.Write.

On Linux 5.5+ with io_uring-capable kernels, Writev uses io_uring for the kernel-side write; on other Unix platforms it falls back to writev(2). The selection is handled entirely by iouring.Writev. Unlike Writer.Write, the batched path does NOT go through bufio.Writer: the batch itself is the buffer, so the #450 "flush after every write" contract becomes "flush after every batch" — crashes lose at most one in-flight batch.

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