Query and forms
Bond.query(conn, "q") is the first value of q in the query string, decoded with std/uri: + is a space and %XX is a byte. conn.query stays the raw text after ?.
Bond.query_int(conn, "page") reads a whole number, and Bond.query_all(conn, "tag") gives every value of a name that repeats, in order (an empty list when the name is not there). A piece with no equal sign (?debug) and ?q= have the value "".
Each one is a Result, and a failure is an error that makes a 400, so try answers it. A name that is missing is query parameter q is missing, a number that is not one is page must be an integer, and a query string that does not decode is the query string is not valid.
Read many fields at once #
Each call decodes the whole query string again, so a handler that reads several fields calls Bond.query_params(conn) once: a Map[String, List[String]] with each name’s values in the order sent, the names in the order of their first appearance. Bond.form_params(conn) does the same for a form body.
Invalid is not missing #
A % that is not followed by two hex digits, or bytes that are not UTF-8, anywhere in the string (also in a name or value you do not read) make all of it invalid: a 400, as in Rack. So Bond.query(conn, "q").unwrap_or("") turns an invalid query string into the default, and does not tell it from a missing name. To tell them apart, call query_params first with try, and take the value from the map:
import Bond from "pkg/bond/bond"
import Testing from "pkg/bond/testing"
def search(conn: Bond.Conn) -> Result[Bond.Conn]
fields = try Bond.query_params(conn)
page = fields.get("page", ["1"])[0]
tags = fields.get("tag", [])
q = fields.get("q", [""])[0]
return ok(Bond.text(conn, 200, "q=#{q} page=#{page} tags=#{tags.join(",")}"))
end
def get(app: Bond.App, target: String) -> Void
response = Testing.request(app, "GET", target)
puts("#{response.status} #{Testing.text(response).unwrap!}")
end
def main() -> Void
app = Bond.app() |> Bond.get("/search", &search)
get(app, "/search?q=caf%C3%A9+au+lait&tag=b&tag=a&page=3")
get(app, "/search?q=x")
get(app, "/search?q=x&other=%zz")
end200 q=café au lait page=3 tags=b,a
200 q=x page=1 tags=
400 the query string is not validNumbers #
query_int and form_int accept negative numbers: check the range in the handler. A plain + before the digits is a space, so ?n=+5 is a 400, and ?n=%2B5 is 5. A number outside 64 bits is a 400 too.
Forms #
Bond.form, Bond.form_int, Bond.form_all and Bond.form_params read the body of a form: application/x-www-form-urlencoded. The request must have exactly one Content-Type, and it must be that type, in any case and with any parameters. Another type, or none, is a 400 with content type must be application/x-www-form-urlencoded; with Bond.uploads, the text fields of a multipart/form-data body are read the same way. A field that is missing is form field name is missing, and a body that does not decode is the form is not valid.
The charset parameter is ignored: the body is read as UTF-8. A line break at the end of the body stays in the last value, as in Rack.
import HTTP from "std/http"
import Bond from "pkg/bond/bond"
import Testing from "pkg/bond/testing"
def signup(conn: Bond.Conn) -> Result[Bond.Conn]
name = try Bond.form(conn, "name")
age = try Bond.form_int(conn, "age")
return ok(Bond.text(conn, 201, "welcome #{name}, #{age}"))
end
def post_form(app: Bond.App, body: String) -> Void
headers = [HTTP.Header(name: "Content-Type", value: "application/x-www-form-urlencoded")]
response = Testing.request(app, "POST", "/signup", headers, body)
puts("#{response.status} #{Testing.text(response).unwrap!}")
end
def main() -> Void
app = Bond.app() |> Bond.post("/signup", &signup)
post_form(app, "name=Ana+Mar%C3%ADa&age=30")
post_form(app, "name=Ana&age=old")
post_form(app, "name=Ana")
end201 welcome Ana María, 30
400 age must be an integer
400 form field age is missingThe path is not decoded #
The path of a request is not decoded: a :name param keeps its %XX text. Decode it in the handler with URI.decode_uri_component (a + stays a plus there, as it should in a path):
import URI from "std/uri"
import Bond from "pkg/bond/bond"
import Testing from "pkg/bond/testing"
def show(conn: Bond.Conn) -> Result[Bond.Conn]
raw = try Bond.param(conn, "name")
case URI.decode_uri_component(raw)
ok(name) -> return ok(Bond.text(conn, 200, "file #{name}"))
error(_) -> return Bond.bad_request("the name is not valid")
end
end
def main() -> Void
app = Bond.app() |> Bond.get("/files/:name", &show)
puts(Testing.text(Testing.request(app, "GET", "/files/caf%C3%A9")).unwrap!)
puts(Testing.text(Testing.request(app, "GET", "/files/a+b")).unwrap!)
puts(Testing.request(app, "GET", "/files/%zz").status)
endfile café
file a+b
400