Standard library · Network

net/router

Routing HTTP requests, with parameters, groups and static files.

import net.router

On this page

Types
Functions

The router keeps one handler function per method and path. In a pattern, a segment that starts with : is a parameter; /books/:id matches /books/42 with id set to 42. A * at the end of a pattern matches any continuation, without making a parameter.

Usually you hand the router to the net/http server and it calls Dispatch itself; the handlers take the context id of the request.

Types

`Param`

struct Param

One path parameter.

Name	Type	Description
`key`	`str = ""`	The name, without the `:`.
`value`	`str = ""`	The value from the request path.

net-router-Dispatch.salam

import net.router

mut count := 0

func list(_ctx: i64):
    count += 1
end

func show(_ctx: i64):
    count += 1
end

func create(_ctx: i64):
    count += 1
end

func main:
    mut r := router.NewRouter()
    router.Get(r, "/books", list)
    router.Get(r, "/books/:id", show)
    router.Post(r, "/books", create)
    router.Put(r, "/books/:id", create)
    router.Delete(r, "/books/:id", create)
    router.Patch(r, "/books/:id", create)
    router.Head(r, "/books", list)
    router.Options(r, "/books", list)
    router.Method(r, "PURGE", "/cache", create)
    router.Method(r, "GET", "/files/*", show)
    router.Group(r, "/api/v1", "GET", "/users/:uid/books/:id", show)
    router.Static(r, "/static", "public")
    router.EnableListing(r)
    println r.routes.len(), r.has_static, r.static_prefix, r.static_listing
    mut m := router.Dispatch(r, "GET", "/books/42")
    println m.matched, m.fn == show, router.ParamGet(m, "id")
    router.FreeMatch(m)
    mut m2 := router.Dispatch(r, "GET", "/api/v1/users/7/books/3")
    println m2.matched, m2.params.items.len(), m2.params.items[0].key, m2.params.items[0].value
    router.FreeMatch(m2)
    mut m3 := router.Dispatch(r, "GET", "/files/a/b.txt")
    println m3.matched, m3.params.items.len()
    router.FreeMatch(m3)
    mut m4 := router.Dispatch(r, "DELETE", "/books")
    println m4.matched, r.routes[0].method, r.routes[0].pattern
    router.FreeMatch(m4)
end

Output11 true /static true true true 42 true 2 uid 7 true 0 false GET /books

`ParamList`

struct ParamList

A list of parameters.

Name	Type	Description
`items`	`Vector`	The parameters.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Route`

struct Route

One registered route.

Name	Type	Description
`method`	`str = ""`	The HTTP method.
`pattern`	`str = ""`	The path pattern.
`fn`	`i64 = 0`	The handler function.
`mid`	`int = 0`	The method id.
`spec`	`int = 0`	The kind of pattern: zero literal, 1 with parameters, 2 with a `*`.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Router`

struct Router

The router: it sends requests to the right function by method and path.

Name	Type	Description
`routes`	`Vector`	The registered routes.
`static_prefix`	`str = ""`	The path prefix of the static files.
`static_dir`	`str = ""`	The directory of the static files.
`has_static`	`bool = false`	Static files are enabled.
`static_listing`	`bool = false`	Show the contents of directories.
`idx`	`Vector`	The hash table of the literal routes.
`idx_mask`	`int = 0`	The table size minus one.
`n_literal`	`int = 0`	The number of literal routes.
`n_dynamic`	`int = 0`	The number of routes with parameters.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Match`

struct Match

The result of finding a route.

Name	Type	Description
`matched`	`bool = false`	A route was found.
`fn`	`i64 = 0`	The handler function of the route.
`params`	`ParamList`	The path parameters.

The example for this item is shown with the ones above: net-router-Dispatch.salam

Functions

`NewRouter`

func NewRouter(): Router

An empty router.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Get`

func Get(r &: Router, path: str, fn: i64)

Registers the handler for GET requests to a path.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Post`

func Post(r &: Router, path: str, fn: i64)

For POST.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Put`

func Put(r &: Router, path: str, fn: i64)

For PUT.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Delete`

func Delete(r &: Router, path: str, fn: i64)

For DELETE.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Patch`

func Patch(r &: Router, path: str, fn: i64)

For PATCH.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Head`

func Head(r &: Router, path: str, fn: i64)

For HEAD.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Options`

func Options(r &: Router, path: str, fn: i64)

For OPTIONS.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Method`

func Method(r &: Router, method: str, path: str, fn: i64)

Registers the handler for any method you name.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Group`

func Group(r &: Router, prefix: str, method: str, path: str, fn: i64)

Registers the path under a group prefix; for versioning an API, such as /api/v1.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Static`

func Static(r &: Router, prefix: str, dir: str)

Serves the files of the given directory under a path prefix.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`EnableListing`

func EnableListing(r &: Router)

For directories with no index.html, shows the list of files.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`ParamGet`

func ParamGet(m: Match, key: str): str

The value of one path parameter; an empty string when there is none.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`Dispatch`

func Dispatch(r: Router, method: str, path: str): Match

Finds the right route for the method and path of the request. Literal routes win over routes with parameters, and a HEAD request falls back to the GET route when it has none of its own.

The example for this item is shown with the ones above: net-router-Dispatch.salam

`FreeMatch`

func FreeMatch(m &: Match)

Frees the memory of the result.

The example for this item is shown with the ones above: net-router-Dispatch.salam