gofast

package module
v0.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 17, 2021 License: BSD-3-Clause Imports: 23 Imported by: 0

README

gofast GoDoc Go Report Card Travis CI results GitHub Action Test result

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

Contents

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.

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.

You may think of gofast as a "client library" to consume any FastCGI application server.

Why?

Many popular languages (e.g. Python, PHP, nodejs) has FastCGI application server implementations. With gofast, you may mix using the languages in a simple way.

Also, this is fun to do :-)

How to Use?

You basically would use the Handler as http.Handler. You can further mux it with default ServeMux or other compatible routers (e.g. gorilla, pat). You then serve your fastcgi within this golang http server.

Simple Example

Please note that this is only the web server component. You need to start your application component elsewhere.

// this is a very simple fastcgi web server
package main

import (
	"log"
	"net/http"
	"os"

	"github.com/cyber-claws/gofast"
)

func main() {
	// Get fastcgi application server tcp address
	// from env FASTCGI_ADDR. Then configure
	// connection factory for the address.
	address := os.Getenv("FASTCGI_ADDR")
	connFactory := gofast.SimpleConnFactory("tcp", address)

	// route all requests to a single php file
	http.Handle("/", gofast.NewHandler(
		gofast.NewFileEndpoint("/var/www/html/index.php")(gofast.BasicSession),
		gofast.SimpleClientFactory(connFactory),
	))

	// serve at 8080 port
	log.Fatal(http.ListenAndServe(":8080", nil))
}
Advanced Examples
Normal PHP Application

To serve normal PHP application, you'd need to:

  1. Serve the static assets from file system; and
  2. Serve only the path with relevant PHP file.
Code 
package main

import (
	"fmt"
	"net/http"
	"os"

	"github.com/cyber-claws/gofast"
)

func main() {
	// Get fastcgi application server tcp address
	// from env FASTCGI_ADDR. Then configure
	// connection factory for the address.
	address := os.Getenv("FASTCGI_ADDR")
	connFactory := gofast.SimpleConnFactory("tcp", address)

	// handles static assets in the assets folder
	http.Handle("/assets/",
		http.StripPrefix("/assets/",
			http.FileServer(http.FileSystem(http.Dir("/var/www/html/assets")))))

	// route all requests to relevant PHP file
	http.Handle("/", gofast.NewHandler(
		gofast.NewPHPFS("/var/www/html")(gofast.BasicSession),
		gofast.SimpleClientFactory(connFactory),
	))

	// serve at 8080 port
	log.Fatal(http.ListenAndServe(":8080", nil))
}
Customizing Request Session with Middleware

Each web server request will result in a gofast.Request. And each gofast.Request will first run through SessionHandler before handing to the Do() method of gofast.Client.

The default gofast.BasicSession implementation does nothing. The library function like gofast.NewPHPFS, gofast.NewFileEndpoint are gofast.Middleware implementations, which are lower level middleware chains.

So you may customize your own session by implemention gofast.Middleware.

Code 

package main

import (
	"fmt"
	"net/http"
	"os"

	"github.com/cyber-claws/gofast"
)

func main() {
	// Get fastcgi application server tcp address
	// from env FASTCGI_ADDR. Then configure
	// connection factory for the address.
	address := os.Getenv("FASTCGI_ADDR")
	connFactory := gofast.SimpleConnFactory("tcp", address)

	// a custom authentication handler
	customAuth := func(inner gofast.SessionHandler) gofast.SessionHandler {
		return func(client gofast.Client, req *gofast.Request) (*gofast.ResponsePipe, error) {
			user, err := someCustomAuth(
				req.Raw.Header.Get("Authorization"))
			if err != nil {
				// if login not success
				return nil, err
			}
			// set REMOTE_USER accordingly
			req.Params["REMOTE_USER"] = user
			// run inner session handler
			return inner(client, req)
		}
	}

	// session handler
	sess := gofast.Chain(
		customAuth,            // maps REMOTE_USER
		gofast.BasicParamsMap, // maps common CGI parameters
		gofast.MapHeader,      // maps header fields into HTTP_* parameters
		gofast.MapRemoteHost,  // maps REMOTE_HOST
	)(gofast.BasicSession)

	// route all requests to a single php file
	http.Handle("/", gofast.NewHandler(
		gofast.NewFileEndpoint("/var/www/html/index.php")(sess),
		gofast.SimpleClientFactory(connFactory),
	))

	// serve at 8080 port
	log.Fatal(http.ListenAndServe(":8080", nil))
}
FastCGI Authorizer

FastCGI specified an authorizer role for authorizing an HTTP request with an "authorizer application". As different from a usual FastCGI application (i.e. responder), it only does authorization check.

Summary of Spec

Before actually serving an HTTP request, a web server can format a normal FastCGI request to the Authorizer application with only FastCGI parameters (FCGI_PARAMS stream). This application is responsible to determine if the request is properly authenticated and authorized for the request.

If valid,

  • The authorizer application should response with HTTP status 200 (OK).

  • It may add additional variables (e.g. SOME-HEADER) to the subsequence request by adding Variable-SOME-HEADER header field to its response to web server.

  • The web server will create a new HTTP request from the old one, appending the additional header variables (e.g. Some-Header), then send the modified request to the subquence application.

If invalid,

  • The authorizer application should response with HTTP status that is NOT 200, and the content to display for failed login.

  • The webserver will skip the responder and directly show the authorizer's response.

Code 

package main

import (
	"net/http"
	"time"

	"github.com/cyber-claws/gofast"
)

func myApp() http.Handler {
  // ... any normal http.Handler, using gofast or not
	return h
}

func main() {
	address := os.Getenv("FASTCGI_ADDR")
	connFactory := gofast.SimpleConnFactory("tcp", address)
	clientFactory := gofast.SimpleClientFactory(connFactory)

	// authorization with php
	authSess := gofast.Chain(
		gofast.NewAuthPrepare(),
		gofast.NewFileEndpoint("/var/www/html/authorization.php"),
	)(gofast.BasicSession)
	authorizer := gofast.NewAuthorizer(
		authSess,
		gofast.SimpleConnFactory(network, address)
	)

	// wrap the actual app
	http.Handle("/", authorizer.Wrap(myApp()))

	// serve at 8080 port
	log.Fatal(http.ListenAndServe(":8080", nil))
}
FastCGI Filter

FastCGI specified a filter role for filtering web server assets before sending out. As different from a usual FastCGI application (i.e. responder), the requested data is on the web server side. So the web server will pass those data to the application when requested.

Code 

package main

import (
	"net/http"
	"time"

	"github.com/cyber-claws/gofast"
)

func main() {
	address := os.Getenv("FASTCGI_ADDR")
	connFactory := gofast.SimpleConnFactory("tcp", address)
	clientFactory := gofast.SimpleClientFactory(connFactory)

	// Note: The local file system "/var/www/html/" only need to be
	// local to web server. No need for the FastCGI application to access
	// it directly.
	connFactory := gofast.SimpleConnFactory(network, address)
	http.Handle("/", gofast.NewHandler(
		gofast.NewFilterLocalFS("/var/www/html/")(gofast.BasicSession),
		clientFactory,
	))

	// serve at 8080 port
	log.Fatal(http.ListenAndServe(":8080", nil))
}
Pooling Clients

To have a better, more controlled, scaling property, you may scale the clients with ClientPool.

Code 
package main

import (
	"fmt"
	"net/http"
	"os"

	"github.com/cyber-claws/gofast"
)

func main() {
	// Get fastcgi application server tcp address
	// from env FASTCGI_ADDR. Then configure
	// connection factory for the address.
	address := os.Getenv("FASTCGI_ADDR")
	connFactory := gofast.SimpleConnFactory("tcp", address)

	// handles static assets in the assets folder
	http.Handle("/assets/",
		http.StripPrefix("/assets/",
			http.FileSystem(http.Dir("/var/www/html/assets"))))

	// handle all scripts in document root
	// extra pooling layer
	pool := gofast.NewClientPool(
		gofast.SimpleClientFactory(connFactory),
		10, // buffer size for pre-created client-connection
		30*time.Second, // life span of a client before expire
	)
	http.Handle("/", gofast.NewHandler(
		gofast.NewPHPFS("/var/www/html")(gofast.BasicSession),
		pool.CreateClient,
	))

	// serve at 8080 port
	log.Fatal(http.ListenAndServe(":8080", nil))
}
Full Examples

Please see the example usages:

Author

This library is written by Koala Yeung.

Contributing

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.mit.edu/~yandros/doc/specs/fcgi-spec.html

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Authorizer 

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

Authorizer guard a given http.Handler

Since this is implemented as a generic http.Handler middleware, you may use this with other non-gofast library components as long as they implements the http.Handler interface.

func NewAuthorizer 

func NewAuthorizer(clientFactory ClientFactory, sessionHandler SessionHandler) *Authorizer

NewAuthorizer creates an authorizer

func (Authorizer) Wrap 

func (ar Authorizer) Wrap(inner http.Handler) http.Handler

Wrap method is a generic http.Handler middleware. Requests to wrapped hander would go through the fastcgi authorizer first. If not authorized, the request will not reach wrapped hander.

type Client 

type Client interface {

	// Do  a proper FastCGI request.
	// Returns the response streams (stdout and stderr)
	// and the request validation error.
	//
	// Note: protocol error will be written to the stderr
	// stream in the ResponsePipe.
	Do(req *Request) (resp *ResponsePipe, err error)

	// Close the underlying connection
	Close() error
}

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

type ClientFactory 

type ClientFactory func() (Client, error)

ClientFactory creates new FPM client with proper connection to the FPM application.

func SimpleClientFactory 

func SimpleClientFactory(connFactory ConnFactory) ClientFactory

SimpleClientFactory returns a ClientFactory implementation with the given ConnFactory.

type ClientFunc 

type ClientFunc func(req *Request) (resp *ResponsePipe, err error)

ClientFunc is a function wrapper of a Client interface shortcut implementation. Mainly for testing and development purpose.

func (ClientFunc) Close 

func (c ClientFunc) Close() error

Close implements Client.Close

func (ClientFunc) Do 

func (c ClientFunc) Do(req *Request) (resp *ResponsePipe, err error)

Do implements Client.Do

type ClientPool 

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

ClientPool pools client created from a given ClientFactory.

func NewClientPool 

func NewClientPool(
	clientFactory ClientFactory,
	scale uint,
	expires time.Duration,
) *ClientPool

NewClientPool creates a *ClientPool from the given ClientFactory and pool it to scale with expiration.

func (*ClientPool) CreateClient 

func (p *ClientPool) CreateClient() (c Client, err error)

CreateClient implements ClientFactory

type ConnFactory 

type ConnFactory func() (net.Conn, error)

ConnFactory creates new network connections to the FPM application

func SimpleConnFactory 

func SimpleConnFactory(network, address string) ConnFactory

SimpleConnFactory creates the simplest ConnFactory implementation.

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 helps to produce Middleware implementation for mapping path related fastcgi parameters. See method Router for usage.

func (*FileSystemRouter) Router 

func (fs *FileSystemRouter) Router() Middleware

Router returns a Middleware that prepare session parameters that are path related. With information provided in the FileSystemRouter, it will route request to script files which path matches the http request path.

i.e. classic PHP hosting environment like Apache + mod_php

Parameters included: 

PATH_INFO
PATH_TRANSLATED
SCRIPT_NAME
SCRIPT_FILENAME
DOCUMENT_URI
DOCUMENT_ROOT

type Handler 

type Handler interface {
	http.Handler
	SetLogger(logger *log.Logger)
}

Handler is implements http.Handler and provide logger changing method.

func NewHandler 

func NewHandler(sessionHandler SessionHandler, clientFactory ClientFactory) Handler

NewHandler returns the default Handler implementation. This default Handler act as the "web server" component in fastcgi specification, which connects fastcgi "application" through the network/address and passthrough I/O as specified.

type Middleware 

type Middleware func(SessionHandler) SessionHandler

Middleware transform a SessionHandler as another SessionHandler. The middlewares provided by this library helps to map fastcgi parameters according to the need of different application.

You may also implement your own Middleware can be provided to modify the *Request, add extra business logic in between, rewrite the response stream from *ResponsePipe. or better handle errors

Ordinary fastcgi parameters on nginx (for PHP at least): 

fastcgi_split_path_info ^(.+\.php)(/?.+)$;
fastcgi_param  SCRIPT_FILENAME    $document_root$fastcgi_script_name;
fastcgi_param  PATH_INFO          $fastcgi_path_info;
fastcgi_param  PATH_TRANSLATED    $document_root$fastcgi_path_info;
fastcgi_param  QUERY_STRING       $query_string;
fastcgi_param  REQUEST_METHOD     $request_method;
fastcgi_param  CONTENT_TYPE       $content_type;
fastcgi_param  CONTENT_LENGTH     $content_length;
fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;
fastcgi_param  REQUEST_URI        $request_uri;
fastcgi_param  DOCUMENT_URI       $document_uri;
fastcgi_param  DOCUMENT_ROOT      $document_root;
fastcgi_param  SERVER_PROTOCOL    $server_protocol;
fastcgi_param  HTTPS              $https if_not_empty;
fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;
fastcgi_param  REMOTE_ADDR        $remote_addr;
fastcgi_param  REMOTE_PORT        $remote_port;
fastcgi_param  SERVER_ADDR        $server_addr;
fastcgi_param  SERVER_PORT        $server_port;
fastcgi_param  SERVER_NAME        $server_name;
# PHP only, required if PHP was built with --enable-force-cgi-redirect
fastcgi_param  REDIRECT_STATUS    200;

func Chain 

func Chain(middlewares ...Middleware) Middleware

Chain chains middlewares into a single middleware.

The middlewares will be chained from outer to inner. The first middleware will be the first to handle Client and Request. It is also the last to handle ResponsePipe and error.

func MapEndpoint 

func MapEndpoint(endpointFile string) Middleware

MapEndpoint returns a Middleware implementation that prepare session for application with only 1 file as endpoint (i.e. it will handle script routing on its own). Suitable for web.py based application.

Parameters included: 

PATH_INFO
PATH_TRANSLATED
SCRIPT_NAME
SCRIPT_FILENAME
DOCUMENT_URI
DOCUMENT_ROOT

func MapFilterRequest 

func MapFilterRequest(fs http.FileSystem) Middleware

MapFilterRequest changes the request role to RoleFilter and add the Data stream from the given file system, if file exists. Also set the required params to request.

If the file do not exists or cannot be opened, the middleware will return empty response pipe and the error.

TODO: provide way to inject authorization check

func MapFilterRequestTemp added in v0.6.1 

func MapFilterRequestTemp(fs embed.FS) Middleware

MapFilterRequestTemp changes the request role to RoleFilter and add the Data stream from the given file system, if file exists. Also set the required params to request.

If the file do not exists or cannot be opened, the middleware will return empty response pipe and the error.

TODO: merge this functionality with the above.

func NewAuthPrepare 

func NewAuthPrepare() Middleware

NewAuthPrepare chains BasicParamsMap, MapHeader, FilterAuthReqParams to implement Middleware that prepares a authorizer request

func NewFileEndpoint 

func NewFileEndpoint(endpointFile string) Middleware

NewFileEndpoint chains BasicParamsMap, MapHeader and MapEndpoint to implement Middleware that prepares an ordinary web.py hosting session environment

func NewFilterFS 

func NewFilterFS(fs http.FileSystem) Middleware

NewFilterFS chains BasicParamsMap, MapHeader and MapFilterRequest to implement Middleware that prepares a fastcgi Filter session environment.

func NewFilterFSTemp added in v0.6.1 

func NewFilterFSTemp(fs embed.FS) Middleware

NewFilterFS chains BasicParamsMap, MapHeader and MapFilterRequest to implement Middleware that prepares a fastcgi Filter session environment.

func NewFilterLocalFS 

func NewFilterLocalFS(root string) Middleware

NewFilterLocalFS is a shortcut to use NewFilterFS with a http.FileSystem created for the given local folder.

func NewPHPFS 

func NewPHPFS(root string) Middleware

NewPHPFS chains BasicParamsMap, MapHeader and FileSystemRouter to implement Middleware that prepares an ordinary PHP hosting session environment.

type PoolClient 

type PoolClient struct {
	Client
	Err error
	// contains filtered or unexported fields
}

PoolClient wraps a client and alter the Close method for pool return / destroy.

func (*PoolClient) Close 

func (pc *PoolClient) Close() error

Close close the inner client only if it is expired. Otherwise it will return itself to the pool.

func (*PoolClient) Expired 

func (pc *PoolClient) Expired() bool

Expired check if the client expired

type Request 

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

Request hold information of a standard FastCGI request

func NewAuthRequest 

func NewAuthRequest(orgl *http.Request) (r *http.Request, req *Request, err error)

NewAuthRequest returns a new *http.Request and a *Request with the body buffered into new NopReader.

func NewRequest 

func NewRequest(r *http.Request) (req *Request)

NewRequest returns a standard FastCGI request with a unique request ID allocted by the client

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 is the default SessionHandler used in the default Handler

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 Role 

type Role uint16

Role for fastcgi application in spec 

const (
	RoleResponder Role = iota + 1
	RoleAuthorizer
	RoleFilter

	MaxRequestID = ^uint16(0)
)

Roles specified in the fastcgi spec

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 BasicParamsMap 

func BasicParamsMap(inner SessionHandler) SessionHandler

BasicParamsMap implements Middleware. It maps basic parameters to the req.Params.

Parameters included: 

CONTENT_TYPE
CONTENT_LENGTH
HTTPS
GATEWAY_INTERFACE
REMOTE_ADDR
REMOTE_PORT
SERVER_PORT
SERVER_NAME
SERVER_PROTOCOL
SERVER_SOFTWARE
REDIRECT_STATUS
REQUEST_METHOD
REQUEST_SCHEME
REQUEST_URI
QUERY_STRING

func FilterAuthReqParams 

func FilterAuthReqParams(inner SessionHandler) SessionHandler

FilterAuthReqParams filter out FCGI_PARAMS key-value that is explicitly forbidden to passed on in factcgi specification, include: 

CONTENT_LENGTH;
PATH_INFO;
PATH_TRANSLATED; and
SCRIPT_NAME

func MapHeader 

func MapHeader(inner SessionHandler) SessionHandler

MapHeader implement Middleware to map header field HTTP_*

It is a convention to map header field SomeRandomField to HTTP_SOME_RANDOM_FIELD. For example, if a header field "X-Hello-World" is in the header, it will be mapped as "HTTP_X_HELLO_WORLD" in the fastcgi parameter field.

Note: HTTP_CONTENT_TYPE and HTTP_CONTENT_LENGTH cannot be overridden.

func MapRemoteHost 

func MapRemoteHost(inner SessionHandler) SessionHandler

MapRemoteHost does reverse DNS lookup on the r.RemoteAddr IP address.

Source Files

View all Source files

Directories

Path Synopsis
example
nodejs
php
python3
tools
phpfpm

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.