Routing
Bond.get, Bond.post, Bond.put, Bond.patch and Bond.delete take the app, a pattern and a handler, and return the app. The app is a Bond.App, and a handler is a Bond.Handler, which is a Fn[Bond.Conn, Result[Bond.Conn]]: write &name for a function that has only the Conn, and a block for one that needs more.
Params #
A segment that starts with a colon, as in /users/:id/posts/:post_id, matches one segment. Read it with Bond.param(conn, "id"), which is a Result[String], or Bond.param_int(conn, "id"). Text that is not a number is a 400.
The path is decoded before the routes are tried, so the params, conn.path and the literal segments are text, not escapes: %20 is a space, and a /café route matches /caf%C3%A9. A slash, a backslash, a colon, a percent sign and a control character stay escaped (in capitals: %2F), so %2F never splits a segment and %2541 is the text %41. The query string is decoded too: see Query and forms. A param can be . or .. (%2e%2e is ..), so a handler that joins a param into a file path refuses those first.
How routes match #
A trailing or a double slash does not matter: /posts/ and //posts are /posts, also in conn.path; every other escape is decoded there too (/%73 is /s), so a filter that tests the path sees the same text as the router and Bond.static.
- A literal segment wins over a
:paramat the same place, whatever the order the routes were added in:/posts/latestis not taken by/posts/:id, even when/posts/:idwas added first. - When the literal branch has no route to the end of the path, the walk goes back to the param: with
/docs/guide/introand/docs/:page/edit, the path/docs/guide/editis/docs/:page/editwithpageset toguide. - The path is chosen first, then the method. If the route that the path reaches has no handler for the method, the answer is a 405 and
Allowlists the methods of that route only. The methods of/posts/:idare not borrowed for/posts/latest. This differs from Sinatra, which tries the next route: withGET /users/meandPUT /users/:id, aPUT /users/meis a 405 here, and it would reach:idthere. - These mistakes stop the program when the route is added: a pattern that does not start with
/or names a param twice, the same method and pattern twice (/postsand/posts/are the same pattern), and two names for the param at the same place, whatever the methods (/users/:idwith/users/:name/posts, or withPOST /users/:uid). Use one name at each place.
import HTTP from "std/http"
import Bond from "pkg/bond/bond"
import Testing from "pkg/bond/testing"
def show_post(conn: Bond.Conn) -> Result[Bond.Conn]
id = try Bond.param_int(conn, "id")
return ok(Bond.text(conn, 200, "post #{id}"))
end
def latest(conn: Bond.Conn) -> Result[Bond.Conn]
return ok(Bond.text(conn, 200, "the latest post"))
end
def intro(conn: Bond.Conn) -> Result[Bond.Conn]
return ok(Bond.text(conn, 200, "the intro"))
end
def edit(conn: Bond.Conn) -> Result[Bond.Conn]
return ok(Bond.text(conn, 200, "edit #{try Bond.param(conn, "page")}"))
end
def main() -> Void
app = (
Bond.app()
|> Bond.get("/posts/:id", &show_post)
|> Bond.get("/posts/latest", &latest)
|> Bond.get("/docs/guide/intro", &intro)
|> Bond.get("/docs/:page/edit", &edit)
)
puts(Testing.text(Testing.request(app, "GET", "/posts/42")).unwrap!)
puts(Testing.text(Testing.request(app, "GET", "/posts/latest/")).unwrap!)
puts(Testing.text(Testing.request(app, "GET", "/docs/guide/edit")).unwrap!)
response = Testing.request(app, "POST", "/posts/latest")
puts("#{response.status} #{HTTP.header_values(response.headers, "allow")}")
endpost 42
the latest post
edit guide
405 ["GET, HEAD"]No route #
A path with no route is a 404 with the body not found; Errors shows how to answer it with your own page. A path with a route for other methods only is a 405 with an Allow header that lists the methods.
HEAD uses the route of GET (the server drops the body), and Allow lists HEAD where it lists GET. OPTIONS is not answered by Bond: it is a 405 unless you add the route.