# 🤖 The bakeoff contract

Every app in the bakeoff answers the same requests the same way, so one
test suite and one measurement harness can drive all of them. This file
is binding. If something here seems wrong, say so in your `STATUS.md`
rather than deviating.

## Pages

| Request | Response |
|---|---|
| `GET /` | The whole list |
| `GET /active` | Only items not completed |
| `GET /completed` | Only completed items |
| `GET /<filter>?edit=<id>` | The same page, with that item's `li` given the class `editing` and its `input.edit` inside a form that posts to `/todos/<id>/edit` |
| `GET /static/base.css`, `GET /static/index.css` | `shared/base.css` and `shared/index.css`, byte for byte |
| `GET /healthz` | 200 |
| `GET /api/version` | 200, the body is the build version |

The filter links are `href="/"`, `href="/active"` and `href="/completed"`,
and the current one has the class `selected`. `#/` routes aren't used.

## Actions

Every action is an HTML form POST (`application/x-www-form-urlencoded`).
Without any special request headers, each one answers **303 See Other**
back to the current filter.

| Request | Fields | Effect |
|---|---|---|
| `POST /todos` | `title`, `filter` | Adds an item. The title is trimmed; if nothing is left, nothing is added |
| `POST /todos/<id>/toggle` | `filter` | Flips that item between active and completed |
| `POST /todos/<id>/edit` | `title`, `filter` | Renames it. The title is trimmed; if nothing is left, the item is deleted |
| `POST /todos/<id>/destroy` | `filter` | Deletes it |
| `POST /todos/toggle-all` | `filter` | Marks every item completed. If every item already was, marks them all active |
| `POST /todos/clear-completed` | `filter` | Deletes every completed item |

- `filter` is `all`, `active` or `completed`. The 303 goes to `/`,
  `/active` or `/completed` to match. A missing or unknown value goes
  to `/`.
- A POST naming an `<id>` that isn't in the caller's own list answers
  **404**. Nothing changes, in that list or anyone else's.
- A POST with an `Origin` header that isn't this app's own origin
  answers **403**. The app's own origin is `https://$CARLOS_HOST` on
  Carloku, and `http://<listen address>` when run with `--listen`. A
  POST with no `Origin` header is allowed. There's no CSRF token.
- Your JavaScript may call these same endpoints with a request header of
  your choosing (for example `Accept: application/json` or a custom
  header) and get HTML fragments or JSON back. Without that header, the
  behaviour above must not change.

## Markup

Start from `shared/reference.html`, which is TodoMVC's own template.
With JavaScript on, your page must look like it. The suite compares
screenshots, masking only `footer.info`.

- Every `li` in `ul.todo-list` carries `data-id="<id>"`, has the class
  `completed` when completed, and has `editing` while being edited.
- `section.main` and `footer.footer` are hidden when the list is empty
  (all filters considered). `button.clear-completed` is hidden when
  nothing is completed.
- The counter reads `<strong>N</strong> item left` or
  `<strong>N</strong> items left`.
- The footer line "Created by …" reads
  `Created by <a href="https://bakeoff.bfj.oncarlos.com">the CARLOS bakeoff</a> · <LANGUAGE>`,
  where `<LANGUAGE>` is your setup's name, e.g. `Rust` or
  `Go + Rastrillo`.

### Controls that must work without JavaScript

The suite drives a page with JavaScript off through exactly these:

| Action | Control |
|---|---|
| Add | `input.new-todo` in a form posting to `/todos`. Pressing Enter submits it |
| Toggle one | A submit control matching `[data-action="toggle"]` inside that item's `li`, in a form posting to `/todos/<id>/toggle` |
| Edit | A link `a[data-action="edit"]` inside that item's `li`, going to `?edit=<id>` on the current filter. The edit view's `input.edit` submits on Enter |
| Delete | `button.destroy`, a submit button in a form posting to `/todos/<id>/destroy` |
| Toggle all | A submit control matching `[data-action="toggle-all"]`, in a form posting to `/todos/toggle-all` |
| Clear completed | `button.clear-completed`, a submit button in a form posting to `/todos/clear-completed` |

These extra controls may be visible when JavaScript is off, styled to
fit. When JavaScript is on, the page must match the reference, so hide
or replace them.

### With JavaScript on

The page behaves like TodoMVC's own apps. Double-click a label to edit.
Enter or blur saves, and Escape cancels. An empty title deletes. Clicking
`input.toggle` or `input.toggle-all` takes effect without a full page
load, and the counter, filters, "Clear completed" button and toggle-all
state stay correct. `input.new-todo` is cleared after adding.

## Lists

- The whole app is one instance. Each visitor gets their own list through
  a cookie set on their first visit. The cookie holds a random value with
  at least 128 bits of randomness and is `HttpOnly; SameSite=Lax;
  Path=/`, plus `Secure` when served over https.
- A cookie value the app doesn't recognise, garbled or not, gets a fresh
  empty list, never an error.
- Titles are shown as text, never as HTML. Any Unicode is kept exactly as
  typed, and titles up to at least 10,000 characters work.
- `Content-Length`, when sent, is the number of bytes in the body.