useful

README

UsefulHandler

UsefulHandler is useful middleware for Go that will both compress

Documentation

Index

• Constants
• Variables
• func NewUsefulHandler(handler http.Handler, opts ...Options) http.Handler
• type ApacheLogRecord
  • func (a *ApacheLogRecord) Hijack() (rwc net.Conn, buf *bufio.ReadWriter, err error)
  • func (r *ApacheLogRecord) Write(p []byte) (int, error)
  • func (r *ApacheLogRecord) WriteHeader(status int)
  • func (r ApacheLogRecord) WriteTo(w io.Writer) (n int64, err error)
• type Handler
  • func (h *Handler) ServeHTTP(rw http.ResponseWriter, r *http.Request)
• type Log
  • func NewLog(opts ...Options) *Log
  • func (l *Log) Close()
  • func (l *Log) Log(r ApacheLogRecord)
  • func (l *Log) Rotate()
  • func (l *Log) SetWriter()
  • func (l *Log) Start()
• type Logger
• type Options
  • func DefaultOptions() Options

Constants

const (
	Byte     = 1
	B        = Byte
	Kilobyte = 1024 * Byte
	KB       = Kilobyte
	Megabyte = 1024 * Kilobyte
	MB       = Megabyte
	Gigabyte = 1024 * Megabyte
	GB       = Gigabyte
	Terabyte = 1024 * Gigabyte
	TB       = Terabyte
)

For ease of use.

const (
	Stdout dest = iota
	Stderr
	File
	Both
	Writer
)

Locations for log writing.

Variables

var (
	// CommonLog is "%h %l %u %t \"%r\" %>s %b"
	CommonLog commonLog = "%s - - [%s] \"%s\" %d %d\n"

	// CommonLogWithVHost is "%v %h %l %u %t \"%r\" %>s %b"
	CommonLogWithVHost commonLogWithVHost = "- %s - - [%s] \"%s\" %d %d\n"

	// NCSALog is
	// "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
	NCSALog ncsaLog = "%s - - [%s] \"%s\" %d %d \"%s\" \"%s\"\n"

	// RefererLog is "%{Referer}i -> %U"
	RefererLog refererLog = "%s -> %s\n"

	// AgentLog is "%{User-agent}i"
	AgentLog agentLog = "%s\n"
)

These format strings correspond with the log formats described in https://httpd.apache.org/docs/2.2/mod/mod_log_config.html

var ErrUnHijackable = errors.New("A(n) underlying ResponseWriter doesn't support the http.Hijacker interface")

ErrUnHijackable indicates an unhijackable connection. I.e., (one of) the underlying http.ResponseWriter(s) doesn't support the http.Hijacker interface.

Functions

func NewUsefulHandler

func NewUsefulHandler(handler http.Handler, opts ...Options) http.Handler

NewUsefulHandler returns a Handler with logging capabilities as well as potentially compressed content.

Types

type ApacheLogRecord

type ApacheLogRecord struct {
	http.ResponseWriter
	Logger
	// contains filtered or unexported fields
}

ApacheLogRecord is a structure containing the necessary information to write a proper log in the ApacheFormatPattern.

func (*ApacheLogRecord) Hijack

func (a *ApacheLogRecord) Hijack() (rwc net.Conn, buf *bufio.ReadWriter, err error)

Hijack implements the http.Hijacker interface to allow connection hijacking.

func (*ApacheLogRecord) Write

func (r *ApacheLogRecord) Write(p []byte) (int, error)

Write fulfills the Write method of the http.ResponseWriter interface.

func (*ApacheLogRecord) WriteHeader

func (r *ApacheLogRecord) WriteHeader(status int)

WriteHeader fulfills the WriteHeader method of the http.ResponseWriter interface.

func (ApacheLogRecord) WriteTo

func (r ApacheLogRecord) WriteTo(w io.Writer) (n int64, err error)

type Handler

type Handler struct {
	*Log
	// contains filtered or unexported fields
}

Handler is a wrapper around http.Handler in order for us to be able to fulfill the http.Handler interface. (The interface requires a ServeHTTP method which we cannot provide without defining our own type.)

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(rw http.ResponseWriter, r *http.Request)

ServeHTTP fulfills the ServeHTTP method of the http.Handler interface.

type Log

type Log struct {
	*sync.Mutex // Guards the following.

	Options // Current log options.
	// contains filtered or unexported fields
}

Log is a structure with our open file we log to, the size of said file (measured by the number of bytes written to it, or it's size on initialization), our current writer (usually Stdout and the aforementioned file), our pool of random names, and a mutex lock to keep race conditions from tripping us up.

func NewLog

func NewLog(opts ...Options) *Log

NewLog returns a new Log initialized to the default values. If no log file exists with the name specified in 'LogName' it'll create a new one, otherwise it opens 'LogName'. If it cannot create or open a file it'll return nil for *Log and the applicable error.

func (*Log) Close

func (l *Log) Close()

Close closes the Log file.

func (*Log) Log

func (l *Log) Log(r ApacheLogRecord)

Log will log an entry to its io.Writer.

func (*Log) Rotate

func (l *Log) Rotate()

Rotate will rotate the logs so that the current (theoretically full) log will be compressed and added to the archive and a new log generated. Will panic if we cannot replace our physical file. (See newFile function for more information.)

func (*Log) SetWriter

func (l *Log) SetWriter()

SetWriter sets Log's writer depending on LogDestination.

func (*Log) Start

func (l *Log) Start()

Start begins the check for 'cur'. TOOD: Implement this better.

type Logger

type Logger interface {
	WriteLog(w io.Writer, r ApacheLogRecord) (n int, err error)
}

Logger is the interface implemented by log types to print an ApacheLogRecord in the desired format.

type Options

type Options struct {
	// Logger determines the format of the log. Most standard
	// formats found in Apache's mod_log_config docs are supported.
	Logger

	// Destination determines where the Handler will write to.
	// By default it writes to Stdout and LogName.
	Destination dest

	// LogName is the name of the log the handler will write to.
	// It defaults to "access.log", but can be set to anything you
	// want.
	LogName string

	// ArchiveDir is the directory where the archives will be stored.
	// If set to "" (empty string) it'll be set to the current directory.
	// It defaults to "archives", so it'll look a little something like
	// this: '/home/user/files/archives/'
	ArchiveDir string

	// MaxFileSize is the maximum size of a log file in bytes.
	// It defaults to 1 Gigabyte (multiple of 1024, not 1000),
	// but can be set to anything you want.
	//
	// Log files larger than this size will be compressed into
	// archive files.
	MaxFileSize int64
}

Options is the structure containing the options for a given Log.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the default configuration for the Options structure.