journal

Documentation

Overview

Package journal provides an implementation of cromon's Journaler interface to write to a file. It also provides a file locking abstraction so that only one cronmon instance can run with the same journal file.

Index

• Variables
• func MultiReadWriter(r cronmon.JournalReadWriter, ws ...cronmon.Journaler) cronmon.JournalReadWriter
• func MultiWriter(ws ...cronmon.Journaler) cronmon.Journaler
• func ReadPreviousState(r io.ReadSeeker) (*cronmon.PreviousState, error)
• func ReadPreviousStateFromFile(path string) (*cronmon.PreviousState, error)
• type Event
• type FileLockJournaler
  • func NewFileLockJournaler(path string) (*FileLockJournaler, error)
  • func NewFileLockJournalerWait(ctx context.Context, path string) (*FileLockJournaler, error)
  • func (f *FileLockJournaler) Close() error
• type HumanWriter
  • func NewHumanWriter(id string, w io.Writer) *HumanWriter
  • func WrapHumanWriter(id string, logger *log.Logger) *HumanWriter
  • func (w *HumanWriter) ID() string
  • func (w *HumanWriter) Write(ev cronmon.Event) error
• type Reader
  • func NewReader(r io.ReadSeeker) *Reader
  • func (r *Reader) Read() (cronmon.Event, time.Time, error)
• type Writer
  • func NewWriter(id string, w io.Writer) *Writer
  • func (w *Writer) ID() string
  • func (w *Writer) Write(ev cronmon.Event) error

Variables

var ErrLockedElsewhere = errors.New("file already locked elsewhere")

ErrLockedElsewhere is returned if NewFileLockJournaler can't acquire the file lock.

Functions

func MultiReadWriter

func MultiReadWriter(
	r cronmon.JournalReadWriter, ws ...cronmon.Journaler) cronmon.JournalReadWriter

MultiReadWriter creates a journaler that writes to multiple other journalers but reads from a single journaler. The new journaler makes no guarantee that the reader will read only once all writers are done, so caller should not assume that.

func MultiWriter

func MultiWriter(ws ...cronmon.Journaler) cronmon.Journaler

MultiWriter creates a journaler that writes to multiple other journalers. The passed in ID is the one used for the new journaler.

func ReadPreviousState

func ReadPreviousState(r io.ReadSeeker) (*cronmon.PreviousState, error)

ReadPreviousState reads backwards the given reader to return the PreviousState.

func ReadPreviousStateFromFile

func ReadPreviousStateFromFile(path string) (*cronmon.PreviousState, error)

ReadPreviousStateFromFile reads the PreviousState from the given file path.

Types

type Event

type Event struct {
	Time time.Time     `json:"time"`
	Type string        `json:"type"`
	Data cronmon.Event `json:"data"`
}

Event describes the JSON structure of an event to be written.

type FileLockJournaler

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

FileLockJournaler is a journaler that uses a file lock (flock) to lock the given file and writes to it. The FileLockJournaler instance must be closed by the caller or by the operating system when the application exits.

Reading the Journal

The caller does not need to acquire a file lock in order to read the written journal, as each Write operation performed on the file is guaranteed to always be valid and atomic.

To read the log, simply use Reader, which is implemented with a line reader and a known index to point to the last known length of the file.

func NewFileLockJournaler

func NewFileLockJournaler(path string) (*FileLockJournaler, error)

NewFileLockJournaler creates a new file journaler if it can acquire a flock on the path. It returns an error if it fails to acquire the lock.

func NewFileLockJournalerWait

func NewFileLockJournalerWait(ctx context.Context, path string) (*FileLockJournaler, error)

NewFileLockJournalerWait creates a new file journaler but waits until the lock can be acquired or until the context times out.

func (*FileLockJournaler) Close

func (f *FileLockJournaler) Close() error

Close closes the file and releases the flock.

type HumanWriter

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

HumanWriter writes the journal in a human-friendly format. The format cannot be parsed; use a regular Writer for this.

func NewHumanWriter

func NewHumanWriter(id string, w io.Writer) *HumanWriter

NewHumanWriter creates a new HumanWriter that writes to the given writer.

func WrapHumanWriter

func WrapHumanWriter(id string, logger *log.Logger) *HumanWriter

WrapHumanWriter wraps the given logger to return a HumanWriter.

func (*HumanWriter) ID

func (w *HumanWriter) ID() string

func (*HumanWriter) Write

func (w *HumanWriter) Write(ev cronmon.Event) error

Write writes the given event into the writer.

type Reader

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

Reader implements a primitive reader that can parse journals written by Writer from top to bottom.

func NewReader

func NewReader(r io.ReadSeeker) *Reader

NewReader creates a new journal reader.

func (*Reader) Read

func (r *Reader) Read() (cronmon.Event, time.Time, error)

Read reads a single entry, starting from the top file. An EOF error is returned if the file has been fully consumed.

type Writer

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

Writer is a simple journaler that writes line-delimited JSON events into the writer.

func NewWriter

func NewWriter(id string, w io.Writer) *Writer

NewWriter creates a new journal writer.

func (*Writer) ID

func (w *Writer) ID() string

ID returns the ID of the writer.

func (*Writer) Write

func (w *Writer) Write(ev cronmon.Event) error

Write writes the given event into the writer. Writes are concurrently safe and are atomic.