# 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](https://www.agentica-lang.com/bond/guide/query/index.md). 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 `:param` at the same place, whatever the order the routes were added in: `/posts/latest` is not taken by `/posts/:id`, even when `/posts/:id` was 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/intro` and `/docs/:page/edit`, the path `/docs/guide/edit` is `/docs/:page/edit` with `page` set to `guide`.
- 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 `Allow` lists the methods of that route only. The methods of `/posts/:id` are not borrowed for `/posts/latest`. This differs from Sinatra, which tries the next route: with `GET /users/me` and `PUT /users/:id`, a `PUT /users/me` is a 405 here, and it would reach `:id` there.
- 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 (`/posts` and `/posts/` are the same pattern), and two names for the param at the same place, whatever the methods (`/users/:id` with `/users/:name/posts`, or with `POST /users/:uid`). Use one name at each place.

```agentica
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")}")
end
```

```output
post 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](https://www.agentica-lang.com/bond/guide/errors/index.md) 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; when an `after` filter answers that 405 with another status, the `Allow` header is dropped.

`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.
