http
HTTP handling framework
Import
_ <- fat.http
Route
A route is a structure used to map HTTP methods to certain path patterns, specifying what code should be executed when a request comes in. Each route can define a different behavior for each HTTP method (POST
, GET
, PUT
, DELETE
).
Constructor
Name | Signature | Brief |
---|---|---|
Route | (path: Text, post: Method, get: Method, put: Method, delete: Method) | Constructs a Route object |
each implemented method receives an HttpRequest as argument and shall return an HttpResponse object
HttpRequest
An HttpRequest
represents an HTTP request message. This is what your server receives from a client when it makes a request to your server.
Constructor
Name | Signature | Brief |
---|---|---|
HttpRequest | (method: Text, path: Text, params: Scope, headers: List/Text, data: Text) | Constructs an HttpRequest object |
HttpResponse
An HttpResponse
represents an HTTP response message. This is what a server sends back to the client in response to an HTTP request.
Constructor
Name | Signature | Brief |
---|---|---|
HttpResponse | (status: Number, headers: List/Text, data: Text) | Constructs an HttpResponse object |
Methods
Name | Signature | Brief |
---|---|---|
setHeaders | (headers: List): Void | Set headers of requests |
post | (url: Text, body, wait): HttpResponse | Create/post body to url |
get | (url: Text, wait): HttpResponse | Read/get from url |
put | (url: Text, body, wait): HttpResponse | Update/put body to url |
delete | (url: Text, wait): HttpResponse | Delete on url |
escape | (url: Text): Text | Encode text to url-safe |
unescape | (url: Text): Text | Decode url-safe text |
setName | (name: Text): Void | Set user agent/server name |
listen | (port: Number, routes: List/Route) | Endpoint provider (server mode) |
body: Text
andwait: Number
are always optional parameters, being thatwait
is the maximum waiting time and must be indicated in milliseconds
Usage Notes
Client mode
For data in HttpResponse
you can decode a JSON response to FatScript scope by using the fromJson
method, or to post
a FatScript scope as JSON you can encode using the toJson
method, both in fat.extra.json library.
The default headers are:
[
"Accept: application/json; charset=UTF-8"
"Content-Type: application/json; charset=UTF-8"
]
You can set custom request headers like so:
http <- fat.http
_ <- fat.extra.json
url = ...
token = ...
data = ...
http.setHeaders([
"Accept: application/json; charset=UTF-8"
"Content-Type: application/json; charset=UTF-8"
"Authorization: Bearer " + token # custom header
])
http.post(url, toJson(data))
setting headers will completely replace previous list with new list
Server mode
Handling HTTP Responses
The FatScript server automatically handles common HTTP status codes such as 200, 400, 404, 405, 500, and 501. Being 200 the default when constructing an HttpResponse
object.
In addition to the common status codes, you can also explicitly return other status codes, such as 201, 202, 203, 204, 205, 206, 301, 401, and 403, by specifying the status code in the HttpResponse
object, for example: HttpResponse(status = 401)
. In all cases, where applicable, the server provides default plain text bodies. However, you have the option to override these defaults and provide your own custom response bodies when necessary.
By automatically handling these status codes and providing default response bodies, the FatScript server simplifies the development process while still allowing you to have control over the response content when needed.
if the status code doesn't belong to any of the above, the server will return a 500 code
See an example of a simple text file HTTP server:
_ <- fat.type.Text
file <- fat.file
http <- fat.http
{ Route, HttpRequest, HttpResponse } = http
# adapt to content location
basePath = '/home/user/contentFolder'
# restrict to text format extensions only
getContentType = (path: Text): Text -> {
ext2 = path(-3..).toLower
ext3 = path(-4..).toLower
ext4 = path(-5..).toLower
ext4 == '.html' => 'Content-Type: text/html'
ext3 == '.htm' => 'Content-Type: text/html'
ext2 == '.js' => 'Content-Type: application/javascript'
ext4 == '.json' => 'Content-Type: application/json'
ext3 == '.css' => 'Content-Type: text/css'
ext2 == '.md' => 'Content-Type: text/markdown'
ext3 == '.xml' => 'Content-Type: application/xml'
ext3 == '.csv' => 'Content-Type: text/csv'
ext3 == '.txt' => 'Content-Type: text/plain'
ext4 == '.svg' => 'Content-Type: image/svg+xml'
ext3 == '.rss' => 'Content-Type: application/rss+xml'
ext4 == '.atom' => 'Content-Type: application/atom+xml'
_ => null
}
charset = '; charset=UTF-8'
routes: List/Route = [
Route(
'*'
get = (request: HttpRequest): HttpResponse -> {
path = basePath + request.path
type = getContentType(path)
!type => HttpResponse(status = 403) # forbidden
file.exists(path) => HttpResponse(data = file.read(path), headers = [type + charset])
_ => HttpResponse(status = 404) # not found
}
)
]
http.listen(8080, routes)
Note that FatScript currently does not support binary data handling, but there is a proposal to add support for it in the future.