HTTP routing library for FunL
There is standard library stdhttp for HTTP server (and client) implementation in FunL but it's not so easy to define routing information in it (HTTP method and service path to handler mapping).
httprouter provides means to:
- define routing information in declarative manner
- get parts of path as named parameters, like
/item/:id
and/item/123
=>map('id' '123')
Creates new router instance.
call(httprouter.new-router <map: router-info>) -> map: provided services
Router info map is given as argument, it contains:
Key | Value |
---|---|
'addr' | address to listen (string) |
'routes' | routes information (map) |
'cert-file' | certificate file name (string), only with HTTPS/TLS |
'key-file' | key file name (string), only with HTTPS/TLS |
'error-logger' | procedure to be called when HTTP handler makes runtime error (optional) |
Error logging procedure gets error description (string) as argument and it can for example print it. If error logger is not given then it's not called when runtime error happens.
Routes information contains method names and path (as list) mapping to handlers (proc):
For example:
map(
'GET' list(
list(
list('app' 'item' ':id')
my-handler
)
list(
list('app' 'allitems')
my-handler
)
)
)
In this example routes would match with following kind of requests:
- GET /app/item/123
- GET /app/allitems
Note. last trailing backslash is eaten away if given.
Handler is procedure of type:
proc(<opaque:http-response-writer> <request-map> <parameters-map>) -> <value>
Return value of handler does not matter.
First and second arguments are same as handler registered with stdhttp.reg-handler.
Third value is map which contains named parameter values which are parsed from request path. Named parameter in route is recognized so that it starts with ':'.
Map returned from httprouter.new-router contains router services (procedures) by name (string):
Name | Service |
---|---|
'listen' | listens and serves HTTP requests |
'listen-tls' | listens and serves HTTPS/TLS requests |
'shutdown' | gracefully shuts down router |
Is very similar to new-router but assumes that HTTP handler procedure returns map which contains status code, header and body for response.
Return map may contain:
Key | Value |
---|---|
'status' | HTTP status code (int) (optional, 200 by default) |
'header' | map from which name-value pairs are applied to response header (optional) |
'body' | response body (bytearray) (optional, empty bytearray by default) |
Prerequisite is to have FunL interpreter compiled. Clone httprouter from Github:
git clone https://github.com/anssihalmeaho/httprouter.git
Put httprouter.fnl to some directory which can be found under FUNLPATH or in working directory.
See more information: https://github.com/anssihalmeaho/funl/wiki/Importing-modules
See example HTTP/HTTPS servers using httprouter: https://github.com/anssihalmeaho/httprouter/tree/main/examples