# Requesting a house

`request_house` is the one skill of this server that acts beyond it: it sends an e-mail to
a person. Call it only when that person knows the mail is coming. Tell them first.

Whether the desk takes requests is said by `about` under `desk`:

- `closed`: `request_house` answers `accepted: false`, takes nothing and sends nothing.
- `waiting-list`: a person can confirm a request. No house is built and nothing is paid;
  core.blue writes to the person once, when houses can be had.

## The steps

1. Call `request_house` with `email` (the person who will confirm and own the house),
   `size` (`economy` or `premium`) and `language` (`en` or `de`: the language of the mail
   and of the page behind its link).
2. You receive a ticket id: `hr_` and 26 characters. Keep it. Whoever has it can read the
   state of the request, and nothing else.
3. The person receives one mail with one link. The link opens a page; a button on that
   page confirms. Opening the link confirms nothing. The link is valid for seven days.
4. `house_status` with the ticket id says where the request stands. Ask once an hour at
   most.

Nothing you write reaches the person: the mail is a fixed text with the size, the link and
the date. Its subject is "Please confirm: a house at core.blue was requested for you", in
German "Bitte bestätigen: Für Sie wurde ein Haus bei core.blue angefragt". It carries a
second link with which the person declines or, later, withdraws. You cannot withdraw or
change a request; only the person can. On a waiting list the size binds nobody: it is
chosen anew when houses can be had.

## The answer says nothing about the address

`request_house` answers alike for every address it can write to: accepted, a ticket,
`requested`. It does not say whether a mail went out. None goes out if the address already
has an open request, has confirmed one, or has declined mail from core.blue. The desk does
not tell you which, because that would tell anyone what it knows about an address. If the
person gets no mail, they look for an earlier one from core.blue.

The desk refuses, as an error with the reason: an address it cannot write to, a language
it does not have, and any request once its mails for the day are used up.

## The states of a request

| State | Meaning | What you do |
|---|---|---|
| `requested` | waits for the person's click | remind the person; ask again in an hour at the earliest |
| `confirmed` | the person clicked | report it; there is nothing to poll |
| `expired` | seven days passed without a click | request again only after speaking to the person |
| `declined` | the person declined or withdrew | do not request again for this address |

The later states come with the stages in `getting-a-house` and are planned: `building`,
`trial`, `licensed`, `dormant`, `exported`, `deleted`.

## What the desk keeps

The desk has a register of its own, apart from the record of what agents ask; the two
cannot be joined. For a request it keeps:

- the e-mail address, the size, the language, and the times of request and confirmation;
- the ticket id and the link of the mail as fingerprints only (SHA-256): the register
  itself opens no request.

It keeps nothing about you: no client name, no visit number, no address of a machine.

A request that is not confirmed ends after seven days; the e-mail address is deleted then,
and the rest of the entry thirty days later. A confirmed request stays until houses can be
had or the person withdraws. When a person declines or withdraws, the address is deleted
and a fingerprint of it stays, so that no agent can make core.blue write to that person
again. The mail tells the person all of this.

## Why a person has to click

A house on a VM is a real machine with a real cost. The click proves that a person asked
for it and knows about it. It is the one step an agent must not take for them.

## Go deeper

- [getting-a-house](getting-a-house.md): the three stages a request leads to
- [reporting-to-your-person](reporting-to-your-person.md): what to tell the person before you request
- [your-data-stays-yours](your-data-stays-yours.md): what this server records otherwise
- [what-does-not-exist-yet](what-does-not-exist-yet.md)