diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/authentication.md | 47 | ||||
| -rw-r--r-- | docs/api/channels-messages.md | 23 | ||||
| -rw-r--r-- | docs/api/events.md | 2 | ||||
| -rw-r--r-- | docs/api/initial-setup.md | 14 | ||||
| -rw-r--r-- | docs/api/invitations.md | 13 | ||||
| -rw-r--r-- | docs/debian-packaging.md | 8 | ||||
| -rw-r--r-- | docs/internal-server-errors.md | 19 |
7 files changed, 104 insertions, 22 deletions
diff --git a/docs/api/authentication.md b/docs/api/authentication.md index 135e91b..93a8e52 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -113,3 +113,50 @@ The request must be an empty JSON object. This endpoint will respond with a status of `204 No Content` when successful. The response will include a `Set-Cookie` header that clears the `identity` cookie. Regardless of whether the client clears the cookie, the service also invalidates the token. + + +## `POST /api/password` + +Changes the current login's password, and invalidate all outstanding identity tokens. + +### Request + +```json +{ + "password": "my-old-password", + "to": "my-new-password" +} +``` + +The request must have the following fields: + +| Field | Type | Description | +|:-----------|:-------|:--| +| `password` | string | The login's _current_ password, in plain text. | +| `to` | string | The login's _new_ password, in plain text. | + +### Success + +This endpoint will respond with a status of `200 Okay` when successful. The body of the response will be a JSON object describing the authenticated login: + +```json +{ + "id": "Labcd1234", + "name": "Andrea" +} +``` + +The response will include the following fields: + +| Field | Type | Description | +|:------------|:-------|:--| +| `id` | string | The authenticated login's ID. | +| `name` | string | The authenticated login's name. | + +The response will include a `Set-Cookie` header for the `identity` cookie, providing the client with a newly-minted identity token associated with the login identified in the request. This token's value must be kept confidential. All previously-created identity cookies will cease to be valid. + +The cookie will expire if it is not used regularly. + +### Authentication failure + +This endpoint will respond with a status of `400 Bad Request` if the `password` does not match the login's current password. diff --git a/docs/api/channels-messages.md b/docs/api/channels-messages.md index 9854d22..2aa8ac5 100644 --- a/docs/api/channels-messages.md +++ b/docs/api/channels-messages.md @@ -64,6 +64,14 @@ The request must have the following fields: |:-------|:-------|:--| | `name` | string | The channel's name. | +The proposed `name` must be valid. The precise definition of valid is still up in the air, but, at minimum: + +* It must be non-empty. +* It must not be "too long." (Currently, 64 characters is too long.) +* It must begin with a printing character. +* It must end with a printing character. +* It must not contain runs of multiple whitespace characters. + ### Success This endpoint will respond with a status of `202 Accepted` when successful. The body of the response will be a JSON object describing the new channel: @@ -86,7 +94,11 @@ The returned name may not be identical to the name requested, as the name will b When completed, the service will emit a [channel created](events.md#channel-created) event with the channel's ID. -### Duplicate channel name +### Name not valid + +This endpoint will respond with a status of `400 Bad Request` if the proposed `name` is not valid. + +### Channel name in use This endpoint will respond with a status of `409 Conflict` if a channel with the requested name already exists. @@ -152,7 +164,7 @@ This endpoint will respond with a status of `404 Not Found` if the channel ID is Deletes a channel. -Deleting a channel prevents it from receiving any further messages, and deletes the messages it contains at that point. +Deleting a channel prevents it from receiving any further messages. The channel must be empty; to delete a channel with messages in it, delete the messages first (or wait for them to expire). This endpoint requires the following path parameter: @@ -178,6 +190,9 @@ The response will have the following fields: When completed, the service will emit a [message deleted](events.md#message-deleted) event for each message in the channel, followed by a [channel deleted](events.md#channel-deleted) event with the channel's ID. +### Channel not empty + +This endpoint will respond with a status of `409 Conflict` if the channel contains messages. ### Invalid channel ID @@ -215,3 +230,7 @@ When completed, the service will emit a [message deleted](events.md#message-dele ### Invalid message ID This endpoint will respond with a status of `404 Not Found` if the message ID is not valid. + +### Not the sender + +This endpoint will respond with a status of `403 Forbidden` if the message was sent by a different login. diff --git a/docs/api/events.md b/docs/api/events.md index b08e971..b23469c 100644 --- a/docs/api/events.md +++ b/docs/api/events.md @@ -46,7 +46,7 @@ This endpoint is designed for use with the [EventSource] DOM API, and supports s ### Query parameters -This endpoint accepts an optional `resume_point` (integer) query parameter. When provided, the event stream will include events published after that point in time; the value must be the value obtained by calling the [`GET /api/boot`](./boot.md) method. If absent, the returned event stream includes all events. +This endpoint requires a `resume_point` (integer) query parameter. The event stream will collect events published after that point in time. The value must be obtained by calling the [`GET /api/boot`](./boot.md) method. ### Request headers diff --git a/docs/api/initial-setup.md b/docs/api/initial-setup.md index 306d798..c2bdaec 100644 --- a/docs/api/initial-setup.md +++ b/docs/api/initial-setup.md @@ -51,6 +51,16 @@ The request must have the following fields: | `name` | string | The initial login's name. | | `password` | string | The initial login's password, in plain text. | +<!-- Reproduced in invitations.md. Edit in both places. --> + +The proposed `name` must be valid. The precise definition of valid is still up in the air, but, at minimum: + +* It must be non-empty. +* It must not be "too long." (Currently, 64 characters is too long.) +* It must begin with a printing character. +* It must end with a printing character. +* It must not contain runs of multiple whitespace characters. + ### Success <!-- This prose is duplicated from authentication.md, with small changes for context. If you edit it here, edit it there, too. --> @@ -79,6 +89,10 @@ The response will include a `Set-Cookie` header for the `identity` cookie, provi The cookie will expire if it is not used regularly. +### Name not valid + +This endpoint will respond with a status of `400 Bad Request` if the proposed `name` is not valid. + ### Setup previously completed Once completed, this operation cannot be performed a second time. Subsequent requests to this endpoint will respond with a status of `409 Conflict`. diff --git a/docs/api/invitations.md b/docs/api/invitations.md index ddbef8a..1839ef5 100644 --- a/docs/api/invitations.md +++ b/docs/api/invitations.md @@ -130,6 +130,15 @@ The request must have the following fields: | `name` | string | The new login's name. | | `password` | string | The new login's password, in plain text. | +<!-- Reproduced in initial-setup.md. Edit in both places. --> +The proposed `name` must be valid. The precise definition of valid is still up in the air, but, at minimum: + +* It must be non-empty. +* It must not be "too long." (Currently, 64 characters is too long.) +* It must begin with a printing character. +* It must end with a printing character. +* It must not contain runs of multiple whitespace characters. + ### Success <!-- This prose is duplicated from authentication.md, with small changes for context. If you edit it here, edit it there, too. --> @@ -162,6 +171,10 @@ The cookie will expire if it is not used regularly. This endpoint will respond with a status of `404 Not Found` when the invitation ID either does not exist, or has already been accepted. +### Name not valid + +This endpoint will respond with a status of `400 Bad Request` if the proposed `name` is not valid. + ### Name in use This endpoint will respond with a status of `409 Conflict` if the requested login name has already been taken. diff --git a/docs/debian-packaging.md b/docs/debian-packaging.md new file mode 100644 index 0000000..f307536 --- /dev/null +++ b/docs/debian-packaging.md @@ -0,0 +1,8 @@ +# Building Debian packages + +You will need `docker` installed, and set up to use the `containerd` storage backend. The builder image is built as a multi-architecture image. + +1. Run `tools/build-builder`. +2. Run `tools/build-debian`. + +Packages will be built in `target/debian`. diff --git a/docs/internal-server-errors.md b/docs/internal-server-errors.md index 4f679b7..16d61a2 100644 --- a/docs/internal-server-errors.md +++ b/docs/internal-server-errors.md @@ -9,22 +9,3 @@ The server attempted two write transactions at the same time, and encountered [s This error will almost always resolve itself if clients re-try their requests; no further action is needed. This is a known issue. If you are encountering this consistently (or if you can trigger it on demand), let us know. We are aware of sqlite's features for mitigating this issue but have been unsuccessful in applying them; we're working on it, but patches _are_ welcome, if you have the opportunity. - -## stored canonical form […] does not match computed canonical form […] for name […] - -When `hi` applies the `migrations/20241019191531_canonical_names.sql` migration (from commit `3f9648eed48cd8b6cd35d0ae2ee5bbe25fa735ac`), this can leave existing names in a state where the stored canonical form is not the correct canonicalization of the stored display names of channels and logins. `hi` will abort requests when it encounters this situation, to avoid incorrect behaviours such as duplicate channels or duplicate logins. - -As channel and login names may be presented during client startup, this can render the service unusable until repaired. Treat this as an immediate outage if you see it. - -You can verify that login names are unique by running the following commands as the user the `hi` server runs as: - -* `sqlite3 .hi 'select display_name from login'` -* `sqlite3 .hi 'select display_name from channel_name'` - -Substitute `.hi` with the path to your `hi` database if it differs from the default. - -If the names are unique, you can repair the database: - -* Stop the `hi` server. -* Run `hi-recanonicalize`, as the same user the `hi` server runs as, with the same database options. -* Start the `hi` server. |