gofast is a FastCGI "client" library written purely in golang.
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.
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 :-)
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.
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))
}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
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))
}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/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 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 addingVariable-SOME-HEADERheader 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/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 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/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))
}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/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))
}Please see the example usages:
This library is written by Koala Yeung.
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 :-)
This library is release under a BSD-like licence. Please find the LICENCE file in this repository
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent