falcore

type Logger ¶

type Logger interface {
	// Matches the log4go interface
	Finest(arg0 interface{}, args ...interface{})
	Fine(arg0 interface{}, args ...interface{})
	Debug(arg0 interface{}, args ...interface{})
	Trace(arg0 interface{}, args ...interface{})
	Info(arg0 interface{}, args ...interface{})
	Warn(arg0 interface{}, args ...interface{}) error
	Error(arg0 interface{}, args ...interface{}) error
	Critical(arg0 interface{}, args ...interface{}) error
}

Interface for logging from within falcore. You can use your own logger as long as it follows this interface by calling SetLogger.

func NewStdLibLogger() Logger

type Pipeline ¶

type Pipeline struct {
	Upstream   *list.List
	Downstream *list.List
}

Pipelines have an Upstream and Downstream list of filters. FilterRequest is called with the Request for all the items in the Upstream list in order UNTIL a Response is returned. Once a Response is returned iteration through the Upstream list is ended, and FilterResponse is called for ALL ResponseFilters in the Downstream list, in order.

If no Response is returned from any of the Upstream filters, then execution of the Downstream is skipped and the server will return a default 404 response.

The Upstream list may also contain instances of Router.

func NewPipeline() (l *Pipeline)

func (p *Pipeline) FilterRequest(req *Request) *http.Response

type PipelineStageStat ¶

type PipelineStageStat struct {
	Name      string
	Type      PipelineStageType
	Status    byte
	StartTime time.Time
	EndTime   time.Time
}

Container for keeping stats per pipeline stage Name for filter stages is reflect.TypeOf(filter).String()[1:] and the Status is 0 unless it is changed explicitly in the Filter or Router.

For the Status, the falcore library will not apply any specific meaning to the status codes but the following are suggested conventional usages that we have found useful

  type PipelineStatus byte
  const (
	    Success PipelineStatus = iota   // General Run successfully
	    Skip                            // Skipped (all or most of the work of this stage)
	    Fail                            // General Fail
	    // All others may be used as custom status codes
  )

func NewPiplineStage(name string) *PipelineStageStat

type PipelineStageType ¶

type PipelineStageType string

The type of pipeline stage for a stat object. These are included in the (*Request)Trace output.

const (
	PipelineStageTypeOther      PipelineStageType = "OT"
	PipelineStageTypeUpstream   PipelineStageType = "UP"
	PipelineStageTypeDownstream PipelineStageType = "DN"
	PipelineStageTypeRouter     PipelineStageType = "RT"
	PipelineStageTypeOverhead   PipelineStageType = "OH"
)

type Request ¶

type Request struct {
	ID                 string
	StartTime          time.Time
	EndTime            time.Time
	Overhead           time.Duration
	PipelineStageStats *list.List
	CurrentStage       *PipelineStageStat

	RemoteAddr  *net.TCPAddr
	HttpRequest *http.Request
	Context     map[string]interface{}
	// contains filtered or unexported fields
}

Request wrapper

The request is wrapped so that useful information can be kept with the request as it moves through the pipeline.

A pointer is kept to the originating Connection.

Context is provided to allow for passing data between stages. For example, you may have an authentication filter that sets the auth information in Context for use at a later stage.

There is a unique ID assigned to each request. This ID is not globally unique to keep it shorter for logging purposes. It is possible to have duplicates though very unlikely over the period of a day or so. It is a good idea to log the ID in any custom log statements so that individual requests can easily be grepped from busy log files.

Falcore collects performance statistics on every stage of the pipeline. The stats for the request are kept in PipelineStageStats. This structure will only be complete in the Request passed to the pipeline RequestDoneCallback. Overhead will only be available in the RequestDoneCallback and it's the difference between the total request time and the sums of the stage times. It will include things like pipeline iteration and the stat collection itself.

See falcore.PipelineStageStat docs for more info.

func TestWithRequest(request *http.Request, filter RequestFilter, context map[string]interface{}) (*Request, *http.Response)

func (fReq *Request) Signature() string

func (fReq *Request) Trace(res *http.Response)

type RequestCompletionCallback ¶

type RequestCompletionCallback func(req *Request, res *http.Response)

An optional callback called after each request is fully processed and delivered to the client. At this point, it's too late to alter the response. For that, use a ResponseFilter. This is a great place to do things like logging/reporting.

type RequestFilter ¶

type RequestFilter interface {
	FilterRequest(req *Request) *http.Response
}

Filter incomming requests and return a response or nil. Filters are chained together into a flow (the Pipeline) which will terminate if the Filter returns a response.

func NewRequestFilter(f func(req *Request) *http.Response) RequestFilter

   filter = NewRequestFilter(func(req *Request) *http.Response {
			req.Headers.Add("X-Falcore", "is_cool")
			return
		})

type ResponseFilter ¶

type ResponseFilter interface {
	FilterResponse(req *Request, res *http.Response)
}

Filter outgoing responses. This can be used to modify the response before it is sent. Modifying the request at this point will have no effect.

func NewResponseFilter(f func(req *Request, res *http.Response)) ResponseFilter

   filter = NewResponseFilter(func(req *Request, res *http.Response) {
			// some crazy response magic
			return
		})

type Router ¶

type Router interface {
	// Returns a Filter to be executed or nil if one can't be found.
	SelectPipeline(req *Request) (pipe RequestFilter)
}

Interface for defining Routers. Routers may be added to the Pipeline.Upstream, This interface may be used to choose between many mutually exclusive Filters. The Router's SelectPipeline method will be called and if it returns a Filter, the Filter's FilterRequest method will be called. If SelectPipeline returns nil, the next stage in the Pipeline will be executed.

In addition, a Pipeline is itself a RequestFilter so SelectPipeline may return a Pipeline as well. This allows branching of the Pipeline flow.

func NewRouter(f func(req *Request) (pipe RequestFilter)) Router

type Server ¶

type Server struct {
	Addr               string
	Pipeline           *Pipeline
	CompletionCallback RequestCompletionCallback

	AcceptReady <-chan struct{}

	PanicHandler func(conn net.Conn, err interface{})
	// contains filtered or unexported fields
}

A falcore server. This is the thing that actually does the socket stuff and processes requests.

func NewServer(port int, pipeline *Pipeline) *Server

func (srv *Server) FdListen(fd int) error

func (srv *Server) ListenAndServe() error

func (srv *Server) ListenAndServeTLS(certFile, keyFile string) error

func (srv *Server) Port() int

func (srv *Server) ServeHTTP(wr http.ResponseWriter, req *http.Request)

func (srv *Server) SocketFd() int

func (srv *Server) StopAccepting()

type StdLibLogger ¶

type StdLibLogger struct{}

This is a simple Logger implementation that uses the go log package for output. It's not really meant for production use since it isn't very configurable. It is a sane default alternative that allows us to not have any external dependencies. Use timber or log4go as a real alternative.

func (fl StdLibLogger) Critical(arg0 interface{}, args ...interface{}) error

func (fl StdLibLogger) Debug(arg0 interface{}, args ...interface{})

func (fl StdLibLogger) Error(arg0 interface{}, args ...interface{}) error

func (fl StdLibLogger) Fine(arg0 interface{}, args ...interface{})

func (fl StdLibLogger) Finest(arg0 interface{}, args ...interface{})

func (fl StdLibLogger) Info(arg0 interface{}, args ...interface{})

func (fl StdLibLogger) Log(lvl level, arg0 interface{}, args ...interface{}) (e error)

func (fl StdLibLogger) Trace(arg0 interface{}, args ...interface{})

func (fl StdLibLogger) Warn(arg0 interface{}, args ...interface{}) error