router

package module
v3.1.3 Latest Latest
Warning

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

Go to latest
Published: Mar 16, 2023 License: GPL-2.0 Imports: 8 Imported by: 5

README

Golang HTTP Router

For people who need simple routing, with a lot of fine grained control
yet still simple enough to not make everything a hassle.

Installation

go get github.com/Nigel2392/router/v3@latest

Usage

Registering routes
func indexFunc(req *request.Request) {
    // Sessions are only available when using a middleware which defines
    // the request.Session variable.
	req.Session.Set("Hello", "World")

    // Write to the response
    req.WriteString("Index!")
}

func variableFunc(req *request.Request) {
    // Get from the session
    // Sessions are only available when using a middleware which defines
    // the request.Session variable.
    fmt.Println(rq.Session.Get("Hello"))
    // Get from the URL parameters, write to the response.
	for k, v := range rq.URLParams {
		rq.WriteString(fmt.Sprintf("%s: %s ", k, v))
	}
}

func defaultJSONFunc(req *request.Request) {
    // Easily render JSON responses!
    req.JSON.Encode(map[string]interface{}{
        "Hello": "World",
    })
}

// Configuration options for the router
var Config = &router.Config{
	// Server options.
	Host: "localhost",
	Port: 8080,
	// Recommended to be true!
	SkipTrailingSlash: true,
	// The server to use,
	// if nil, a new http.Server will be created.
	// Addr will always be overwritten, so will the handler.
	Server: &http.Server{},
	// Default handler to use when no route is found.
	// If nil, http.NotFound will be used.
	NotFoundHandler: nil,
}

func main(){
    // Initialize the router
    var SessionStore = scs.New()
    var r = router.NewRouter(nil)

    // Use middleware
    r.Use(middleware.Printer)

    // Custom remade middleware for alexedwards/scs!
    // The regular loadandsave method does not work.
    r.Use(scsmiddleware.SessionMiddleware(SessionStore))

    // Register URLs
    r.Get("/", indexFunc, "index")
    r.Get("/variable/<<name:string>>/<<id:int>>", variableFunc, "variable")

    // Register groups of URLs
    var group = r.Group("/api", "api")
    group.Get("/json", defaultJSONFunc, "json")
    group.Post("/json2", defaultJSONFunc, "json2")
Getting urls, formatting them
    // Find routess by name with the following syntax:
    var index = r.URL(router.ALL, "index")
    var variableRoute = r.URL(router.ALL, "variable")

    // Format the route urls.
    fmt.Println(index.Format())
    fmt.Println(variableRoute.Format("John-Doe", 123))

    // Extra parameters are ignored!
    fmt.Println(variableRoute.Format("John-Doe", 123, 456, 789))

    // Getting child urls
    var json = r.URL(router.ALL, "api:json")
    var json2 = r.URL(router.POST, "api:json2")
    fmt.Println(json.Format())
    fmt.Println(json2.Format())

    // The router is compliant with the http.Handler interface.
    // This means that you can use it as a handler for your own server, 
    // Or serve from the router itself, using the server in the defined config.
    if err := r.Listen(); err != nil {
        fmt.Println(err)
    }
}
Rendering templates

Firstly, we need to define some variables in the router/ templatespackage like so:

    // Configure default template settings.
    templates.TEMPLATEFS = os.DirFS("templates/")
    templates.BASE_TEMPLATE_SUFFIXES = []string{".tmpl"}
    templates.BASE_TEMPLATE_DIRS = []string{"base"}
    templates.TEMPLATE_DIRS = []string{"templates"}
    templates.USE_TEMPLATE_CACHE = false

As you might see from the above code, this follows your file structure.
We do not have to define the regular template directories, but we do have to define the base template directories.
We define the regular directories when rendering them.

    # The base directory is where the base templates are stored.
    templates/
    ├── base
    │   └── base.tmpl
    └── app
        ├── index.tmpl
        └── user.tmpl

Then, we can render templates like so:

func indexFunc(req *request.Request) {
    // Render the template with the given data.
    var err = req.Render("app/index.tmpl")
	if err != nil {
		req.WriteString(err.Error())
	}
}

Documentation

Index

Constants

View Source
const (
	GET     = "GET"
	POST    = "POST"
	PUT     = "PUT"
	DELETE  = "DELETE"
	PATCH   = "PATCH"
	OPTIONS = "OPTIONS"
	HEAD    = "HEAD"

	// Special method for matching all methods
	ALL = "ALL"
)

HTTP Methods

Variables

This section is empty.

Functions

func RedirectWithNextURL

func RedirectWithNextURL(r *request.Request, nextURL string)

Redirect user to a URL, appending the current URL as a "next" query parameter

func ToHTTPHandler

func ToHTTPHandler(h Handler) http.Handler

Make a new http.Handler from a Handler

func WalkRoutes

func WalkRoutes(route *Route, f func(*Route, int))

Recurse over a routes children, keeping track of depth

Types

type Config

type Config struct {
	// The address to listen on
	Host string
	Port int
	// Wether to skip trailing slashes
	SkipTrailingSlash bool
	// The server to use
	Server *http.Server
	// The handler to use when a route is not found
	NotFoundHandler Handler

	// SSL options
	CertFile string
	KeyFile  string
}

Configuration options for the router, and serving.

type HandleFunc

type HandleFunc func(*request.Request)

HandleFunc is the function that is called when a route is matched

func HTTPWrapper

func HTTPWrapper(handler func(http.ResponseWriter, *http.Request)) HandleFunc

Wrapper function for http.Handler to make it compatible with HandleFunc

func (HandleFunc) ServeHTTP

func (f HandleFunc) ServeHTTP(r *request.Request)

type Handler

type Handler interface {
	ServeHTTP(*request.Request)
}

Handler is the interface that wraps the ServeHTTP method.

func FromHTTPHandler

func FromHTTPHandler(h http.Handler) Handler

Make a new handler from a http.Handler

type Middleware

type Middleware func(Handler) Handler

Middleware is the function that is called when a route is matched

type Registrar

type Registrar interface {
	// Put registers a new route with the given path and method.
	Put(path string, handler HandleFunc, name ...string) Registrar

	// Post registers a new route with the given path and method.
	Post(path string, handler HandleFunc, name ...string) Registrar

	// Get registers a new route with the given path and method.
	Get(path string, handler HandleFunc, name ...string) Registrar

	// Delete registers a new route with the given path and method.
	Delete(path string, handler HandleFunc, name ...string) Registrar

	// Patch registers a new route with the given path and method.
	Patch(path string, handler HandleFunc, name ...string) Registrar

	// Options registers a new route with the given path and method.
	Options(path string, handler HandleFunc, name ...string) Registrar

	// Head registers a new route with the given path and method.
	Head(path string, handler HandleFunc, name ...string) Registrar

	// Register a route for all methods
	Any(path string, handler HandleFunc, name ...string) Registrar

	// HandleFunc registers a new route with the given path and method.
	HandleFunc(method, path string, handler HandleFunc, name ...string) Registrar

	// Handle is a convenience method that wraps the http.Handler in a HandleFunc
	Handle(method, path string, handler http.Handler) Registrar

	// Use adds middleware to the router.
	Use(middlewares ...Middleware)

	// Group creates a new router URL group
	Group(path string, name string, middlewares ...Middleware) Registrar

	// Addgroup adds a group of routes to the router
	AddGroup(group Registrar)

	// URL returns the URL for a named route
	URL(method, name string) routevars.URLFormatter
}

Registrar is the main interface for registering routes

func Group

func Group(path string, name string) Registrar

Group creates a new router URL group

type Route

type Route struct {
	Method      string
	Path        routevars.URLFormatter
	HandlerFunc HandleFunc
	// contains filtered or unexported fields
}

Route is a single route in the router

func (*Route) AddGroup

func (r *Route) AddGroup(group Registrar)

Add a group to the route

func (*Route) Any

func (r *Route) Any(path string, handler HandleFunc, name ...string) Registrar

Register a route for all methods

func (*Route) Delete

func (r *Route) Delete(path string, handler HandleFunc, name ...string) Registrar

Delete registers a new route with the given path and method.

func (*Route) DisableMiddleware

func (r *Route) DisableMiddleware()

Disable the router's middlewares for this route, and all its children It will however still run the route's own middlewares.

func (*Route) Get

func (r *Route) Get(path string, handler HandleFunc, name ...string) Registrar

Get registers a new route with the given path and method.

func (*Route) Group

func (r *Route) Group(path string, name string, middlewares ...Middleware) Registrar

Group creates a new group of routes

func (*Route) Handle

func (r *Route) Handle(method, path string, handler http.Handler) Registrar

Handle is a convenience method that wraps the http.Handler in a HandleFunc

func (*Route) HandleFunc

func (r *Route) HandleFunc(method, path string, handler HandleFunc, name ...string) Registrar

HandleFunc registers a new route with the given path and method.

func (*Route) Head

func (r *Route) Head(path string, handler HandleFunc, name ...string) Registrar

Head registers a new route with the given path and method.

func (*Route) Match

func (r *Route) Match(method, path string) (bool, *Route, request.URLParams)

Match checks if the given path matches the route

func (*Route) Name

func (r *Route) Name() string

Return the name of the route

func (*Route) Options

func (r *Route) Options(path string, handler HandleFunc, name ...string) Registrar

Options registers a new route with the given path and method.

func (*Route) Patch

func (r *Route) Patch(path string, handler HandleFunc, name ...string) Registrar

Patch registers a new route with the given path and method.

func (*Route) Post

func (r *Route) Post(path string, handler HandleFunc, name ...string) Registrar

Post registers a new route with the given path and method.

func (*Route) Put

func (r *Route) Put(path string, handler HandleFunc, name ...string) Registrar

Put registers a new route with the given path and method.

func (*Route) URL added in v3.0.5

func (r *Route) URL(method, name string) routevars.URLFormatter

URL matches a URL for the given names delimited by a colon.

func (*Route) Use

func (r *Route) Use(middlewares ...Middleware)

Use adds middleware to the route

type Router

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

Router is the main router struct It takes care of dispatching requests to the correct route

func NewRouter

func NewRouter(config *Config) *Router

NewRouter creates a new router

func (*Router) AddGroup

func (r *Router) AddGroup(group Registrar)

Addgroup adds a group of routes to the router

func (*Router) Any

func (r *Router) Any(path string, handler HandleFunc, name ...string) Registrar

Register a route for all methods

func (*Router) Delete

func (r *Router) Delete(path string, handler HandleFunc, name ...string) Registrar

Delete registers a new route with the given path and method.

func (*Router) Get

func (r *Router) Get(path string, handler HandleFunc, name ...string) Registrar

Get registers a new route with the given path and method.

func (*Router) Group

func (r *Router) Group(path string, name string, middlewares ...Middleware) Registrar

Group creates a new router URL group

func (*Router) Handle

func (r *Router) Handle(method, path string, handler http.Handler) Registrar

Handle is a convenience method that wraps the http.Handler in a HandleFunc

func (*Router) HandleFunc

func (r *Router) HandleFunc(method, path string, handler HandleFunc, name ...string) Registrar

HandleFunc registers a new route with the given path and method.

func (*Router) Head

func (r *Router) Head(path string, handler HandleFunc, name ...string) Registrar

Head registers a new route with the given path and method.

func (*Router) Listen

func (r *Router) Listen() error

func (*Router) ListenTLS

func (r *Router) ListenTLS() error

func (*Router) Match

func (r *Router) Match(method, path string) (bool, *Route, request.URLParams)

Match returns the route that matches the given method and path.

func (*Router) Options

func (r *Router) Options(path string, handler HandleFunc, name ...string) Registrar

Options registers a new route with the given path and method.

func (*Router) Patch

func (r *Router) Patch(path string, handler HandleFunc, name ...string) Registrar

Patch registers a new route with the given path and method.

func (*Router) Post

func (r *Router) Post(path string, handler HandleFunc, name ...string) Registrar

Post registers a new route with the given path and method.

func (*Router) Put

func (r *Router) Put(path string, handler HandleFunc, name ...string) Registrar

Put registers a new route with the given path and method.

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP dispatches the request to the handler whose pattern matches the request URL.

func (*Router) SiteMap

func (r *Router) SiteMap() []byte

SiteMap returns a ready to use XML sitemap

func (*Router) URL

func (r *Router) URL(method, name string) routevars.URLFormatter

Get a route by name. Route names are optional, when used a route's child can be access like so: router.Route("routeName") router.Route("parentName:childName")

func (*Router) URLFormat

func (r *Router) URLFormat(name string, args ...interface{}) string

Basically the URL func, but for easy use in templates. It returns the URL, formatted based on the arguments.

func (*Router) Use

func (r *Router) Use(middlewares ...Middleware)

Use adds middleware to the router.

type Vars

type Vars map[string]string

Variable map passed to the route.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL