gofast

README

gofast

gofast is a FastCGI "client" library written purely in go.

What does it do, really?

In FastCGI specification, a FastCGI system has 2 components: (a) web server; and (b) application server. A web server should hand over request information to the application server through socket. The application server always listens to the socket and response to socket request accordingly.

visitor → web server → application server → web server → visitor

gofast help you to write the code on the web server part of this picture. It helps you to pass the request to application server and receive response from it.

Why?

Many popular languages (e.g. Python, PHP, Ruby) has FastCGI server implementations. With gofast, you may mix the languages without too much complication.

Also, this is fun to do :-)

Author

This library is written by Koala Yeung.

Contirbuting

Your are welcome to contribute to this library.

To report bug, please use the issue tracker.

To fix an existing bug or implement a new feature, please:

1. Check the issue tracker and pull requests for existing discussion.
2. If not, please open a new issue for discussion.
3. Write tests.
4. Open a pull request referencing the issue.
5. Have fun :-)

Licence

This library is release under a BSD-like licence. Please find the LICENCE file in this repository

Documentation

Overview

Package gofast implements the FastCGI protocol. Currently only the responder role is supported. The protocol is defined at http://www.fastcgi.com/drupal/node/22

Index

• type Client
  • func NewClient(conn net.Conn, limit uint32) Client
• type FileSystemRouter
  • func (fs *FileSystemRouter) Router() Middleware
• type Handler
  • func NewHandler(sessionHandler SessionHandler, network, address string) Handler
• type Middleware
  • func Chain(middlewares ...Middleware) Middleware
• type Request
• type ResponsePipe
  • func BasicSession(client Client, req *Request) (*ResponsePipe, error)
  • func NewResponsePipe() (p *ResponsePipe)
  • func (pipes *ResponsePipe) Close()
  • func (pipes *ResponsePipe) WriteTo(rw http.ResponseWriter, ew io.Writer) (err error)
• type SessionHandler
  • func MapHeader(inner SessionHandler) SessionHandler
  • func NewPHPFS(root string) SessionHandler
  • func (handler SessionHandler) Handle(client Client, req *Request) (*ResponsePipe, error)

Types

type Client

type Client interface {

	// Do takes care of a proper FastCGI request
	Do(req *Request) (resp *ResponsePipe, err error)

	// NewRequest returns a standard FastCGI request
	// with a unique request ID allocted by the client
	NewRequest(*http.Request) *Request

	// AllocID allocates a new reqID.
	// It blocks if all possible uint16 IDs are allocated.
	AllocID() uint16

	// ReleaseID releases a reqID.
	// It never blocks.
	ReleaseID(uint16)
}

Client is a client interface of FastCGI application process through given connection (net.Conn)

func NewClient

func NewClient(conn net.Conn, limit uint32) Client

NewClient returns a Client of the given connection (net.Conn).

limit is the maximum number of request that the applcation support. 0 means the maximum number available for 16bit request id (65536). Default 0.

type FileSystemRouter

type FileSystemRouter struct {

	// DocRoot stores the ordinary Apache DocumentRoot parameter
	DocRoot string

	// Exts stores accepted extensions
	Exts []string

	// DirIndex stores ordinary Apache DirectoryIndex parameter
	// for to identify file to show in directory
	DirIndex []string
}

FileSystemRouter handles ordinary filesystem based router like an old fashion PHP hosting environment

func (*FileSystemRouter) Router

func (fs *FileSystemRouter) Router() Middleware

Router returns Middleware

type Handler

type Handler interface {
	SetLogger(logger *log.Logger)
	ServeHTTP(w http.ResponseWriter, r *http.Request)
}

Handler is the interface for a FastCGI web server, which proxy request to FastCGI application through network port or socket

func NewHandler

func NewHandler(sessionHandler SessionHandler, network, address string) Handler

NewHandler returns a new Handler interface

type Middleware

type Middleware func(SessionHandler) SessionHandler

Middleware transform a SessionHandler as another SessionHandler

func Chain

func Chain(middlewares ...Middleware) Middleware

Chain chains middlewares into a single middleware

type Request

type Request struct {
	Raw      *http.Request
	ID       uint16
	Params   map[string]string
	Stdin    io.ReadCloser
	KeepConn bool
}

Request hold information of a standard FastCGI request

type ResponsePipe

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

ResponsePipe contains readers and writers that handles all FastCGI output streams

func BasicSession

func BasicSession(client Client, req *Request) (*ResponsePipe, error)

BasicSession implements SessionHandlerFunc

func NewResponsePipe

func NewResponsePipe() (p *ResponsePipe)

NewResponsePipe returns an initialized new ResponsePipe struct

func (*ResponsePipe) Close

func (pipes *ResponsePipe) Close()

Close close all writers

func (*ResponsePipe) WriteTo

func (pipes *ResponsePipe) WriteTo(rw http.ResponseWriter, ew io.Writer) (err error)

WriteTo writes the given output into http.ResponseWriter

type SessionHandler

type SessionHandler func(client Client, req *Request) (resp *ResponsePipe, err error)

SessionHandler handles the gofast *Reqeust with the provided given Client. The Client should properly handle the transport to the fastcgi application. Should do proper routing or other parameter mapping here.

func MapHeader

func MapHeader(inner SessionHandler) SessionHandler

MapHeader implement Middleware to map header field SomeRandomField to HTTP_SOME_RANDOM_FIELD

func NewPHPFS

func NewPHPFS(root string) SessionHandler

NewPHPFS returns a SessionHandler provides a classic PHP hosting environment for a HTTP session

func (SessionHandler) Handle

func (handler SessionHandler) Handle(client Client, req *Request) (*ResponsePipe, error)

Handle implements SessionHandler