falcore: github.com/fitstar/falcore Index | Files | Directories

package falcore

import "github.com/fitstar/falcore"

Falcore is a framework for constructing high performance, modular HTTP servers. For more information, see the project page at http://fitstar.github.io/falcore. Or read the full package documentation at http://godoc.org/github.com/fitstar/falcore.


Package Files

continue.go doc.go filter.go logger.go pipeline.go request.go response.go router.go server.go server_notwindows.go


const (
    FINEST level = iota

Log levels, in order of priority

func ByteResponse Uses

func ByteResponse(req *http.Request, status int, headers http.Header, body []byte) *http.Response

Generate an http.Response using a []byte for the body.

func Critical Uses

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

Log using the packages default logger. You can change the underlying logger using SetLogger

func Debug Uses

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

Log using the packages default logger. You can change the underlying logger using SetLogger

func Error Uses

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

Log using the packages default logger. You can change the underlying logger using SetLogger

func Fine Uses

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

Log using the packages default logger. You can change the underlying logger using SetLogger

func Finest Uses

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

Log using the packages default logger. You can change the underlying logger using SetLogger

func Info Uses

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

Log using the packages default logger. You can change the underlying logger using SetLogger

func PipeResponse Uses

func PipeResponse(req *http.Request, status int, headers http.Header) (io.WriteCloser, *http.Response)

Generate an http.Response using the read half of an io.Pipe as the Body. Returns the write half of an io.Pipe and the response.

Use this to stream a generated body without buffering first. Don't forget to close the writer when finished. Writes are blocking until something Reads so you must use a separate goroutine for writing. Response will be Transfer-Encoding: chunked.

func SetLogger Uses

func SetLogger(newLogger Logger)

Set the packages static logger. This logger is used by falcore can its subpackages. It is also available through the standalone functions that match the logger interface. The default is a StdLibLogger

func SimpleResponse Uses

func SimpleResponse(req *http.Request, status int, headers http.Header, contentLength int64, body io.Reader) *http.Response

Generate an http.Response using the basic fields Use -1 for the contentLength if you don't know the content length in advance.

func StringResponse Uses

func StringResponse(req *http.Request, status int, headers http.Header, body string) *http.Response

Generate an http.Response using a string for the body.

func TimeDiff Uses

func TimeDiff(startTime time.Time, endTime time.Time) float32

Helper for calculating times. return value in Seconds DEPRECATED: Use endTime.Sub(startTime).Seconds()

func Trace Uses

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

Log using the packages default logger. You can change the underlying logger using SetLogger

func Warn Uses

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

Log using the packages default logger. You can change the underlying logger using SetLogger

type Logger Uses

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 Uses

func NewStdLibLogger() Logger

type Pipeline Uses

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 Uses

func NewPipeline() (l *Pipeline)

func (*Pipeline) FilterRequest Uses

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

Pipelines are valid RequestFilters. This makes them nestable.

type PipelineStageStat Uses

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 Uses

func NewPiplineStage(name string) *PipelineStageStat

type PipelineStageType Uses

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 Uses

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 Uses

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

Returns a completed falcore.Request and response after running the single filter stage The PipelineStageStats is completed in the returned Request The falcore.Request.Connection and falcore.Request.RemoteAddr are nil

func (*Request) Signature Uses

func (fReq *Request) Signature() string

This gives a unique signature for each unique path through the pipeline. The Signature will only be complete in the RequestDoneCallback. At any given time, the Signature is a crc32 sum of all the finished pipeline stages combining PipelineStageStat.Name and PipelineStageStat.Status. To modify the signature for your own use, just set the request.CurrentStage.Status in your RequestFilter or ResponseFilter.

func (*Request) Trace Uses

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

Call from RequestDoneCallback. Logs a bunch of information about the request to the falcore logger. This is a pretty big hit to performance so it should only be used for debugging or development. The source is a good example of how to get useful information out of the Request.

type RequestCompletionCallback Uses

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 Uses

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 Uses

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

Helper to create a Filter by just passing in a func

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

type ResponseFilter Uses

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 Uses

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

Helper to create a Filter by just passing in a func

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

type Router Uses

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 Uses

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

Generate a new Router instance using f for SelectPipeline

type Server Uses

type Server struct {
    Addr               string
    Pipeline           *Pipeline
    CompletionCallback RequestCompletionCallback
    ListenerTimeout    time.Duration // used to set deadline on listener (Default: 3s)

    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 Uses

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

func (*Server) FdListen Uses

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

Setup the server to listen using an existing file pointer. If this is set, server will not open a new listening socket.

func (*Server) ListenAndServe Uses

func (srv *Server) ListenAndServe() error

Start the server. This method blocks until the server has stopped completely.

func (*Server) ListenAndServeTLS Uses

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

Start the server using TLS for serving HTTPS.

func (*Server) Port Uses

func (srv *Server) Port() int

The port the server is listening on

func (*Server) ServeHTTP Uses

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

For compatibility with net/http.Server or Google App Engine If you are using falcore.Server as a net/http.Handler, you should not call any of the Listen methods

func (*Server) SocketFd Uses

func (srv *Server) SocketFd() int

Get the file descriptor from the listening socket.

func (*Server) StopAccepting Uses

func (srv *Server) StopAccepting()

Gracefully shutdown the server. Calling this more than once will result in a panic.

type StdLibLogger Uses

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 (StdLibLogger) Critical Uses

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

func (StdLibLogger) Debug Uses

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

func (StdLibLogger) Error Uses

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

func (StdLibLogger) Fine Uses

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

func (StdLibLogger) Finest Uses

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

func (StdLibLogger) Info Uses

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

func (StdLibLogger) Log Uses

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

func (StdLibLogger) Trace Uses

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

func (StdLibLogger) Warn Uses

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


filterA collection of useful RequestFilters and ResponseFilters
responderHelpers for generating common types of responses
routerA collection of useful Routers
utilsUtilities used by falcore and its sub-packages

Package falcore imports 24 packages (graph) and is imported by 8 packages. Updated 2018-03-15. Refresh now. Tools for package owners.