barrel

README

barrel

barrel provides a rolling writer which can be used as an io.Writer when the underlying writer may change.

Documentation

Index

• Constants
• type Clock
• type FileGzipTransformer
  • func (t FileGzipTransformer) Transform(path string) (string, error)
• type FileRenameTransformer
  • func (t FileRenameTransformer) Transform(path string) (string, error)
• type FileRotator
• type FileSizeBasedTrigger
  • func (t FileSizeBasedTrigger) Trigger(file *os.File, p []byte) (bool, error)
• type FileTimeBasedTrigger
  • func (t *FileTimeBasedTrigger) Trigger(file *os.File, _ []byte) (bool, error)
• type FileTimestampNameGenerator
  • func (g FileTimestampNameGenerator) Name(current string) (string, error)
• type FileTransformer
• type FileTransformingRotator
  • func (r FileTransformingRotator) Rotate(file *os.File) (*os.File, error)
• type FileTrigger
• type NameGenerator
• type RollingWriter
  • func (w *RollingWriter) Close() error
  • func (w *RollingWriter) Write(p []byte) (int, error)
• type Rotator
  • func AdaptFileRotator(fr FileRotator) Rotator
• type Trigger
  • func AdaptFileTrigger(ft FileTrigger) Trigger

Examples

• RollingWriter

Constants

const (
	// ErrClosed is returned when the operations are performed on an already
	// closed item.
	ErrClosed = barrelError("closed writer")
)

Types

type Clock

type Clock interface {
	Now() time.Time
}

Clock wraps stdlib time functions, for alternate timing functions.

type FileGzipTransformer

type FileGzipTransformer struct {
	// Describes gzip compression level.
	GzipLevel int
}

FileGzipTransformer converts file to gzip format.

func (FileGzipTransformer) Transform

func (t FileGzipTransformer) Transform(path string) (string, error)

Transform transforms the file at the provided path to a gzip file in the same directory. It add .gz extension to the file. The original file is not retained. The mod time and access time of the new gzip file is same as mod time of the original file.

type FileRenameTransformer

type FileRenameTransformer struct {
	// Generator to be used for generating new name of the file.
	NameGenerator NameGenerator

	// Force physical move of the file.
	ForceMove bool
}

FileRenameTransformer renames a file.

func (FileRenameTransformer) Transform

func (t FileRenameTransformer) Transform(path string) (string, error)

Transform transforms the file at provided path, to a path generated by the NameGenerator. It returns the generated path.

type FileRotator

type FileRotator interface {
	Rotate(file *os.File) (*os.File, error)
}

Rotator changes the file. If there is an error while rotating then a non-nil error is returned.

type FileSizeBasedTrigger

type FileSizeBasedTrigger struct {
	// Max size of file.
	Size int64
}

FileSizeBasedTrigger describes a trigger which works on size of the file.

func (FileSizeBasedTrigger) Trigger

func (t FileSizeBasedTrigger) Trigger(file *os.File, p []byte) (bool, error)

Trigger returns true if size of file plus size of bytes to be written exceeds the max size provided, otherwise it returns false.

If size of bytes to be written is greater than max size provided then a non-nil error is returned.

type FileTimeBasedTrigger

type FileTimeBasedTrigger struct {
	// Describes the rotation schedule.
	CronExpression string

	// Clock to wrap stdblib timing functions for testing.
	Clock Clock
	// contains filtered or unexported fields
}

FileTimeBasedTrigger describes a trigger which works on mod time of the file.

func (*FileTimeBasedTrigger) Trigger

func (t *FileTimeBasedTrigger) Trigger(file *os.File, _ []byte) (bool, error)

Trigger returns true when current time (as given by the Clock) exceeds the time of next schedule, as described by the provided CronExpression, otherwise it returns false.

type FileTimestampNameGenerator

type FileTimestampNameGenerator struct {
	// Format of timestamp to use.
	Format string
}

FileTimestampNameGenerator is a NameGenerator which generates timestamp suffixed name for the file with current name.

func (FileTimestampNameGenerator) Name

func (g FileTimestampNameGenerator) Name(current string) (string, error)

Name generates a new timestamp suffixed name for file at current path.

current = application.log, out = application_2020-01-02.log

If the directory of the file already has file with same name and suffixed timestamp with indexes, then it returns the file with next available index.

dir
 |- application_2020-01-02.0.log
 |- application_2020-01-02.1.log
 |- application_2020-01-02.2.log

current = application.log, out = application_2020-01-02.3.log

If the directory of file contains file with same name and and suffixed timestamp without indexes, then it moves the file to correct index, and returns the file with next index.

dir
 |- application_2020-01-02.log

current = application.log, out application_2020-01-02.1.log

Afterwards,

dir
 |- application_2020-01-02.0.log

If there are any, errors while reading the directories, then non-nil error is returned.

type FileTransformer

type FileTransformer interface {
	Transform(path string) (string, error)
}

FileTransformer takes a file path, transforms the file and returns the path of resulting file. If any error occurs non-nil error is returned.

type FileTransformingRotator

type FileTransformingRotator struct {
	// Flag to be used to Open the the new file, os.O_CREATE is added
	// automatically.
	OpenFlag int

	// Transformers to to transform the file.
	Transformers []FileTransformer
}

FileTransformingRotator describes a Rotator, which works by rotating files.

func (FileTransformingRotator) Rotate

func (r FileTransformingRotator) Rotate(file *os.File) (*os.File, error)

Rotate closes the current file, runs all the provided transformers in order, and returns a reference to a new file, which is created with same name and permissions (os.FileMode) as the original file.

It uses OpenFlag while opening the file.

If there is any error in any of the transformers, then no further transformers are applied and non-nil error is returned.

type FileTrigger

type FileTrigger interface {
	Trigger(file *os.File, p []byte) (bool, error)
}

FileTrigger tells whether the given file should be rotated or not. If it returns true then rotation is preformed, otherwise not. If there are any errors while determining the trigger then a non-nil error is returned.

type NameGenerator

type NameGenerator interface {
	Name(current string) (string, error)
}

NameGenerator generates a new name with the provided current name.

type RollingWriter

type RollingWriter struct {
	// Writer which is wrapped.
	io.Writer

	// Trigger used to check whether to rotate or not.
	Trigger

	// Rotator used to change the Writer.
	Rotator
	// contains filtered or unexported fields
}

RollingWriter wraps an io.Writer, providing mechanisms to check and perform rotation on each write.

Example

package main

import (
	"os"

	"github.com/hemantjadon/barrel"
)

func main() {
	file, _ := os.OpenFile("/path/to/file", os.O_CREATE|os.O_WRONLY|os.O_CREATE, 0644)
	writer := barrel.RollingWriter{
		Writer:  file,
		Trigger: barrel.AdaptFileTrigger(barrel.FileSizeBasedTrigger{Size: 100 * 1000 * 1000}),
		Rotator: barrel.AdaptFileRotator(barrel.FileTransformingRotator{
			OpenFlag: os.O_CREATE | os.O_WRONLY | os.O_CREATE,
			Transformers: []barrel.FileTransformer{
				barrel.FileRenameTransformer{
					NameGenerator: barrel.FileTimestampNameGenerator{},
				},
			},
		}),
	}
	_, _ = writer.Write([]byte(`hello world`))
}

func (*RollingWriter) Close

func (w *RollingWriter) Close() error

Close closes the RollingWriter.

func (*RollingWriter) Write

func (w *RollingWriter) Write(p []byte) (int, error)

Write writes the given bytes to the underlying Writer.

Before writing, it calls Trigger.Trigger, to check whether to rotate or not, if it returns true then, Rotator.Rotate is called and the underlying writer is changed to the new writer. And bytes are written to the new Writer.

If Trigger.Trigger returns false the bytes are immediately written to current Writer.

type Rotator

type Rotator interface {
	Rotate(w io.Writer) (io.Writer, error)
}

Rotator changes the writer. If there is an error while rotating then a non-nil error is returned.

func AdaptFileRotator

func AdaptFileRotator(fr FileRotator) Rotator

AdaptFileRotator converts a FileRotator into a generic Rotator, which can be used with RollingWriter.

The Rotator returned will return a non-nil error if the writer provided is not a reference of os.File.

type Trigger

type Trigger interface {
	Trigger(w io.Writer, p []byte) (bool, error)
}

Trigger tells whether rotation should be done or not. If it returns true then rotation is preformed, otherwise not. If there are any errors while determining the trigger then a non-nil error is returned.

func AdaptFileTrigger

func AdaptFileTrigger(ft FileTrigger) Trigger

AdaptFileTrigger converts a FileTrigger into a generic Trigger, which can be used with RollingWriter.

The Trigger returned will return a non-nil error if the writer provided is not a reference of os.File.