2023-07-15 14:17:27 (UTC-03:00)

Marcel Rodrigues <marcelgmr@gmail.com>

docs: add explanation about request and response API

diff --git a/README.md b/README.md
index 333e666..1c50a73 100644
--- a/README.md
+++ b/README.md
@@ -21,11 +21,64 @@ lud.app.new_app{
 
 = request object
 
-TODO
+The first argument passed to the route callbacks is a request object
+which looks like this:
+
+```
+{
+    method="GET",
+    -- consider a request to "/foo/bar?key=val#potato":
+    path="/foo/bar", query={key="val"}, fragment="potato",
+    headers={["user-agent"]="Mozilla/5.0"},
+    -- for convenience, headers.cookie is parsed when present:
+    cookies={my_key=my_val},
+    -- the remaining fields are typically used in POST requests
+    payload="some data sent by client",
+    -- when a web form is submitted, form data is parsed from payload:
+    form={email="hi@there.com"}
+}
+```
 
 = responses
 
-TODO
+As can be seen in the hello world example above, most callbacks will return just
+one value: the payload string, which typically contains some HTML in web apps or
+some JSON in APIs. However, callbacks can return up to four values:
+
+```
+local function my_callback(req)
+    local payload = "Uh-oh, we can't find the page you're after.\n"
+    local status = 404
+    local reason = "Not Found"  -- for the first line in HTTP response
+    -- cookies can be used e.g. to store session IDs
+    local cookie = {key="sid", val="abce6c3...", path="/", age=2*60*60}
+    local cookies = {cookie}
+    return payload, status, reason, cookies
+end
+```
+
+A few return values have special meaning:
+  * if payload is nil then the server is stopped (i.e. the :run() method returns)
+  * if status is nil, the default values of status=200 and reason="OK" are used
+  * if status is 303, payload will be used as redirection destination (see below)
+
+The special 303 response is used to redirect the client to another address.
+If this status is used, the default value of reason will be "See Other".
+The target address must be given in the payload without any other data.
+Here's a typical example:
+
+```
+local function private_page(req)
+    -- check which user is logged in on this session, if any
+    local user = get_user(req.cookies)
+    -- if there's no login information, redirect to login page
+    if user == nil then
+        return "/login", 303
+    end
+    -- otherwise proceed to show private page
+    return "some private data only accessible to authenticated users"
+end
+```
 
 = templates