Fluxx is a lightweight, opinionated HTTP library for Go. It provides a thin abstraction over the Go net/http package, with utilities for request reading, response sending, and graceful server lifecycle management.
Designed to stay close to the Go standard library, but with just enough ergonomics to make your web server development simpler!
This guide will follow you through your first steps to use this package.
go get -u github.com/romssc/fluxxGetting started with Fluxx is easy. Here's a basic example to create a simple web server that responds with "hello!" on the root path. This example demonstrates initializing a new Fluxx App, setting up a route, and starting the server.
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", fluxx.HandlerFuncAdapter(func(c *fluxx.Ctx) {
c.Send().JSON(http.StatusOK, "hello!")
}))
app := fluxx.New(fluxx.Config{
Address: ":8080", // or "localhost:8080" just like in the standart net/http
ReadTimeout: 5 * time.Second,
WriteTimeout: 10 * time.Second,
Mux: http.NewServeMux(), // in this example it's the standart mux, might as well be chi or any other.
})
if err := app.Listen(); err != nil {
panic(err)
}
}go run main.goThis message will also contain some of your Config settings, just for convenience.
Here is a list of middleware that are included within the Fluxx.
| Title | Description |
|---|---|
| rid | Allow to track Request ID, creates one if there's none. |
| timeout | Sets a time to handle the request. |
| key | Simple API Key validator. |
ErrListening = errors.New("[ERROR] fluxx: FAILED WHILE LISTENING")
ErrShuttingDown = errors.New("[ERROR] fluxx: FAILED WHILE SHUTTING DOWN")Error values returned by server lifecycle operations.
func New(c Config) *Appfunc HandlerFuncAdapter(h FluxxHandlerFunc) http.HandlerFuncHandlerFuncAdapter adapts a FluxxHandlerFunc into a standard http.HandlerFunc.
type App struct {
// contains filtered or unexported fields
}App represents the Fluxx HTTP application. It manages server configuration and lifecycle.
func (a *App) Listen() errorListen starts the HTTP server. It blocks until the server shuts down or fails.
func (a *App) ListenTLS(certificate, key string) errorListenTLS starts the server with TLS enabled.
func (a *App) GracefulShutdown(timeout time.Duration) errorGracefulShutdown attempts to shut down the server gracefully within the given timeout.
type Config struct {
Address string
ReadTimeout time.Duration
WriteTimeout time.Duration
TLS *tls.Config
Mux http.Handler
}Config holds the configuration options for creating a new App.
type Ctx struct {
// contains filtered or unexported fields
}Ctx wraps the HTTP request and response, providing ergonomic helpers for reading inputs and sending outputs.
func (c *Ctx) Read() *ReaderRead returns the request reader.
func (c *Ctx) Send() *SenderSend returns the response sender.
type Reader struct {
Request *http.Request
}Reader provides methods for accessing request data.
func (r *Reader) QueryParam(key string, defaultValue ...string) (string, bool)QueryParam returns the query parameter by key. If not present, an optional default value may be used. The second return value indicates whether a value was found or defaulted.
type Sender struct {
Writer http.ResponseWriter
// contains filtered or unexported fields
}Sender provides methods for writing responses.
func (s *Sender) Error(status int, message string)Error sends an HTTP error response with the given status code and message.
func (s *Sender) JSON(status int, data any, customHeaders ...map[string]string) errorJSON sends a JSON response with the given status code, data, and optional headers.
func (s *Sender) File(content, filename, path string, customHeaders ...map[string]string)File serves a file response with content type and disposition headers.
type FluxxHandlerFunc func(c *Ctx)FluxxHandlerFunc defines a handler that operates on a Fluxx context.