httpd

Documentation

Overview

Package httpd implements a simple HTTP router with path parameters support.

Example

package main

import (
	"context"
	"fmt"
	"io"
	"net"
	"net/http"

	"github.com/whoisnian/glb/httpd"
)

func pingHandler(store *httpd.Store) {
	store.Respond200([]byte("pong"))
}

func sayHandler(store *httpd.Store) {
	name := store.RouteParam("name")
	msg := store.RouteParam("msg")
	store.Respond200([]byte(name + " say: " + msg))
}

func anyHandler(store *httpd.Store) {
	// a struct keeps the member order stable, as encoding/json/v2 does not sort map keys
	store.RespondJson(http.StatusOK, struct {
		Method string `json:"method"`
		Path   string `json:"path"`
	}{
		Method: store.R.Method,
		Path:   store.RouteParamAny(),
	})
}

func printResp(resp *http.Response, err error) {
	if err != nil {
		fmt.Println(err)
	} else {
		data, _ := io.ReadAll(resp.Body)
		defer resp.Body.Close()
		fmt.Println(string(data))
	}
}

func main() {
	mux := httpd.NewMux()
	mux.Handle("/test/ping", http.MethodGet, pingHandler)
	mux.Handle("/test/say/:name/:msg", http.MethodPost, sayHandler)
	mux.Handle("/test/any/*", httpd.MethodAll, anyHandler)

	ln, err := net.Listen("tcp", "127.0.0.1:0")
	if err != nil {
		panic(err)
	}
	server := &http.Server{Addr: ln.Addr().String(), Handler: mux}
	go func() {
		if err := server.Serve(ln); err != nil && err != http.ErrServerClosed {
			panic(err)
		}
	}()
	defer server.Shutdown(context.Background())

	printResp(http.Get("http://" + server.Addr + "/test/ping"))
	printResp(http.Post("http://"+server.Addr+"/test/say/cat/meow", "application/octet-stream", nil))
	printResp(http.Get("http://" + server.Addr + "/test/any/hello/world"))

}

Output:
pong
cat say: meow
{"method":"GET","path":"hello/world"}

Index

• Constants
• type HandlerFunc
  • func CreateHandler(httpHandler http.HandlerFunc) HandlerFunc
• type Mux
  • func NewMux() *Mux
  • func (mux *Mux) Handle(path string, method string, handler HandlerFunc)
  • func (mux *Mux) HandleMiddleware(middleware ...HandlerFunc)
  • func (mux *Mux) HandleNoRoute(handler HandlerFunc)
  • func (mux *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Params
  • func (ps *Params) Get(key string) (value string, ok bool)
• type ResponseWriter
  • func (w *ResponseWriter) Flush()
  • func (w *ResponseWriter) FlushError() error
  • func (w *ResponseWriter) Header() http.Header
  • func (w *ResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error)
  • func (w *ResponseWriter) Unwrap() http.ResponseWriter
  • func (w *ResponseWriter) Write(bytes []byte) (int, error)
  • func (w *ResponseWriter) WriteHeader(code int)
• type RouteInfo
• type Store
  • func (store *Store) CookieValue(name string) string
  • func (store *Store) Error404(msg string)
  • func (store *Store) Error500(msg string)
  • func (store *Store) GetClientIP() string
  • func (store *Store) Next()
  • func (store *Store) Redirect(code int, url string)
  • func (store *Store) Respond200(content []byte) error
  • func (store *Store) RespondJson(code int, v any) error
  • func (store *Store) RouteParam(name string) (value string)
  • func (store *Store) RouteParamAny() string

Examples

• Package

Constants

const MethodAll string = "*"

Types

type HandlerFunc

type HandlerFunc func(*Store)

func CreateHandler

func CreateHandler(httpHandler http.HandlerFunc) HandlerFunc

CreateHandler converts 'http.HandlerFunc' to 'httpd.HandlerFunc'.

type Mux

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

func NewMux

func NewMux() *Mux

NewMux allocates and returns a new Mux.

func (*Mux) Handle

func (mux *Mux) Handle(path string, method string, handler HandlerFunc)

Handle registers the handler for the given routePath and method.

func (*Mux) HandleMiddleware

func (mux *Mux) HandleMiddleware(middleware ...HandlerFunc)

func (*Mux) HandleNoRoute

func (mux *Mux) HandleNoRoute(handler HandlerFunc)

func (*Mux) ServeHTTP

func (mux *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP dispatches the request to the matched handler.

type Params

type Params struct {
	K, V []string
}

Params consists of a pair of key-value slice.

func (*Params) Get

func (ps *Params) Get(key string) (value string, ok bool)

Get gets the first param value associated with the given key. The ok result indicates whether param was found.

type ResponseWriter

type ResponseWriter struct {
	Origin http.ResponseWriter
	Status int
}

ResponseWriter records response status with http.ResponseWriter.

func (*ResponseWriter) Flush

func (w *ResponseWriter) Flush()

Flush implements the standard http.Flusher interface.

func (*ResponseWriter) FlushError

func (w *ResponseWriter) FlushError() error

FlushError attempts to invoke FlushError() of the standard http.ResponseWriter.

func (*ResponseWriter) Header

func (w *ResponseWriter) Header() http.Header

func (*ResponseWriter) Hijack

func (w *ResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error)

Hijack implements the standard http.Hijacker interface.

func (*ResponseWriter) Unwrap

func (w *ResponseWriter) Unwrap() http.ResponseWriter

Unwrap returns the original http.ResponseWriter.

func (*ResponseWriter) Write

func (w *ResponseWriter) Write(bytes []byte) (int, error)

func (*ResponseWriter) WriteHeader

func (w *ResponseWriter) WriteHeader(code int)

type RouteInfo

type RouteInfo struct {
	Path        string
	Method      string
	HandlerName string
	HandlerFunc HandlerFunc
	Middlewares *[]HandlerFunc
}

RouteInfo exports route information for logs and metrics.

type Store

type Store struct {
	W *ResponseWriter
	R *http.Request
	P *Params
	I *RouteInfo
	// contains filtered or unexported fields
}

Store consists of responseWriter, request, routeParams and routeInfo.

func (*Store) CookieValue

func (store *Store) CookieValue(name string) string

CookieValue returns the value of specified cookie, or empty string if cookie not found.

func (*Store) Error404

func (store *Store) Error404(msg string)

Error404 is similar to `http.Error()`.

func (*Store) Error500

func (store *Store) Error500(msg string)

Error500 is similar to `http.Error()`.

func (*Store) GetClientIP

func (store *Store) GetClientIP() string

GetClientIP looks for possible client IP by the following order:

• Header["X-Client-IP"]
• Header["X-Forwarded-For"]
• Header["X-Real-IP"]
• Request.RemoteAddr

Warning: Malicious clients may use request header for IP spoofing.

func (*Store) Next

func (store *Store) Next()

Next should be used only in middleware to call the next middleware or handler.

func (*Store) Redirect

func (store *Store) Redirect(code int, url string)

Redirect is similar to `http.Redirect()`.

func (*Store) Respond200

func (store *Store) Respond200(content []byte) error

Respond200 replies 200 to client request with optional body.

func (*Store) RespondJson

func (store *Store) RespondJson(code int, v any) error

RespondJson replies json body to client request. It cannot be called after `store.W.WriteHeader()`.

func (*Store) RouteParam

func (store *Store) RouteParam(name string) (value string)

RouteParam returns the value of specified route param, or empty string if param not found.

func (*Store) RouteParamAny

func (store *Store) RouteParamAny() string

RouteParamAny returns the value of route param "/*".