gofast 
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/yookoala/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:
- Serve the static assets from file system; and
- Serve only the path with relevant PHP file.
Code
```go
package main
import (
"fmt"
"net/http"
"os"
"github.com/yookoala/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
```go
package main
import (
"fmt"
"net/http"
"os"
"github.com/yookoala/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
```go
package main
import (
"net/http"
"time"
"github.com/yookoala/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
```go
package main
import (
"net/http"
"time"
"github.com/yookoala/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
```go
package main
import (
"fmt"
"net/http"
"os"
"github.com/yookoala/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:
- Check the issue tracker and pull requests for existing discussion.
- If not, please open a new issue for discussion.
- Write tests.
- Open a pull request referencing the issue.
- Have fun :-)
Licence
This library is release under a BSD-like licence. Please find the
LICENCE file in this repository
