Merge branch 'main' into wip/path-routing-for-channels

2 files changed, 46 insertions, 41 deletions

diff --git a/docs/api.md b/docs/api.md
index 91485f3..4957666 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -25,23 +25,25 @@ Returns information needed to boot the client. Also the recommended way to check
         "id": "L1234abcd",
     },
     "resume_point": "1312",
+    "logins": [
+        {
+            "id": "L1234abcd",
+            "name": "example username"
+        }
+    ],
     "channels": [
         {
             "name": "nonsense and such",
             "id": "C1234abcd",
-            "messages": [
-                {
-                    "at": "2024-09-27T23:19:10.208147Z",
-                    "sender": {
-                        "id": "L1234abcd",
-                        "name": "example username"
-                    },
-                    "message": {
-                        "id": "M1312acab",
-                        "body": "beep"
-                    }
-                }
-            ]
+        }
+    ],
+    "messages": [
+        {
+            "at": "2024-09-27T23:19:10.208147Z",
+            "channel": "C1234abcd",
+            "sender": "L1234abcd",
+            "id": "M1312acab",
+            "body": "beep"
         }
     ]
 }
@@ -137,7 +139,7 @@ Chat messages expire after 90 days and can no longer be retrieved at that time.
 
 ```json
 {
-    "message": "my amazing thoughts, by bob"
+    "body": "my amazing thoughts, by bob"
 }
 ```
 
@@ -200,50 +202,49 @@ The event IDs `hi` sends in `application/event-stream` encoding are ephemeral, a
 The returned event stream is a sequence of events:
 
 ```json
+id: 1232
+data: {
+data:   "type": "login",
+data:   "event": "created",
+data:   "at": "2024-09-27T23:17:10.208147Z",
+data:   "id": "L1234abcd",
+data:   "name": "example username"
+data: }
+
 id: 1233
 data: {
-data:   "type": "created",
+data:   "type": "channel",
+data:   "event": "created",
 data:   "at": "2024-09-27T23:18:10.208147Z",
-data:   "channel": {
-data:     "id": "C9876cyyz",
-data:     "name": "example channel 2"
-data:   }
+data:   "id": "C9876cyyz",
+data:   "name": "example channel 2"
 data: }
 
 id: 1234
 data: {
 data:   "type": "message",
+data:   "event": "sent",
 data:   "at": "2024-09-27T23:19:10.208147Z",
-data:   "channel": {
-data:     "id": "C9876cyyz",
-data:     "name": "example channel 2"
-data:   },
-data:   "sender": {
-data:     "id": "L1234abcd",
-data:     "name": "example username"
-data:   },
-data:   "message": {
-data:     "id": "M1312acab",
-data:     "body": "beep"
-data:   }
+data:   "channel": "C9876cyyz",
+data:   "sender": "L1234abcd",
+data:   "id": "M1312acab",
+data:   "body": "beep"
 data: }
 
 id: 1235
 data: {
+data:   "type": "message",
+data:   "event": "deleted",
 data:   "at": "2024-09-28T02:44:27.077355Z",
-data:   "channel": {
-data:     "id": "C9876cyyz",
-data:     "name": "example channel 2"
-data:   },
-data:   "type": "message_deleted",
-data:   "message": "M1312acab"
+data:   "id": "M1312acab"
 data: }
 
 id: 1236
 data: {
+data:   "type": "channel",
+data:   "event": "deleted",
 data:   "at": "2024-09-28T03:40:25.384318Z",
-data:   "type": "deleted",
-data:   "channel": "C9876cyyz"
+data:   "id": "C9876cyyz"
 data: }
 
 ```
diff --git a/docs/ops.md b/docs/ops.md
index 8f21c79..02644c2 100644
--- a/docs/ops.md
+++ b/docs/ops.md
@@ -2,6 +2,10 @@
 
 ## Upgrades
 
-`hi` will automatically upgrade its database on startup. Before doing so, it will create a backup of your database (at `.hi.backup`, or controlled by `--backup-database-url`). If the migration process succeeds, this backup will be deleted automatically. If the migration process _fails_, however, the backup will be left in place. In addition, `hi` will attempt to restore your existing database from the backup before exiting.
+`hi` will automatically upgrade its database on startup. Before doing so, it will create a backup of your database (at `.hi.backup`, or controlled by `--backup-database-url`). If the migration process succeeds, this backup will be deleted automatically. If the migration process _fails_, however, `hi` will attempt to restore your existing database from the backup before exiting. If the restore process also fails, then both the backup database and the suspected-broken database will be left in place.
 
-`hi` will not start if the backup database already exists. To restart `hi` after a failure, move the backup database aside. Once you are satisfied that `hi` has recovered successfully, you can delete it. If you need to restore the database manually, you can also copy it overtop of your database using normal filesystem tools (`cp -a .hi.backup. hi`, for example).
+To avoid destroying backups that may still be needed, `hi` will not start if the backup database already exists. **There is no catch-all advice on how to proceed**, but you can try the following:
+
+* Start the server with **a copy** of the backup database, and determine if any data has been lost. If not, shut it down, replace your main database by copying the backup, and carry on.
+
+The `hi` database is an ordinary file. While the server is not running, it can be freely copied or renamed without invalidating the data in it.