Fossil SCM
Improvements to Chat documentation. No code changes.
Commit
cedac53a4728c8daa13f93abc54798086a98792f4098e2e32116b979276c88da
Parent
6cdddee2bd1358b…
2 files changed
+14
+48
-16
+14
| --- src/chat.c | ||
| +++ src/chat.c | ||
| @@ -352,10 +352,22 @@ | ||
| 352 | 352 | ** On success it responds with an empty response: the new message |
| 353 | 353 | ** should be fetched via /chat-poll. On error, e.g. login expiry, |
| 354 | 354 | ** it emits a JSON response in the same form as described for |
| 355 | 355 | ** /chat-poll errors, but as a standalone object instead of a |
| 356 | 356 | ** list of objects. |
| 357 | +** | |
| 358 | +** Requests to this page should be POST, not GET. POST parameters | |
| 359 | +** include: | |
| 360 | +** | |
| 361 | +** msg The (Markdown) text of the message to be sent | |
| 362 | +** | |
| 363 | +** file The content of the file attachment | |
| 364 | +** | |
| 365 | +** lmtime ISO-8601 formatted date-time string showing the local time | |
| 366 | +** of the sender. | |
| 367 | +** | |
| 368 | +** At least one of the "msg" or "file" POST parameters must be provided. | |
| 357 | 369 | */ |
| 358 | 370 | void chat_send_webpage(void){ |
| 359 | 371 | int nByte; |
| 360 | 372 | const char *zMsg; |
| 361 | 373 | const char *zUserName; |
| @@ -765,11 +777,13 @@ | ||
| 765 | 777 | ** |
| 766 | 778 | ** This routine both deletes the identified chat entry and also inserts |
| 767 | 779 | ** a new entry with the current timestamp and with: |
| 768 | 780 | ** |
| 769 | 781 | ** * xmsg = NULL |
| 782 | +** | |
| 770 | 783 | ** * file = NULL |
| 784 | +** | |
| 771 | 785 | ** * mdel = The msgid of the row that was deleted |
| 772 | 786 | ** |
| 773 | 787 | ** This new entry will then be propagated to all listeners so that they |
| 774 | 788 | ** will know to delete their copies of the message too. |
| 775 | 789 | */ |
| 776 | 790 |
| --- src/chat.c | |
| +++ src/chat.c | |
| @@ -352,10 +352,22 @@ | |
| 352 | ** On success it responds with an empty response: the new message |
| 353 | ** should be fetched via /chat-poll. On error, e.g. login expiry, |
| 354 | ** it emits a JSON response in the same form as described for |
| 355 | ** /chat-poll errors, but as a standalone object instead of a |
| 356 | ** list of objects. |
| 357 | */ |
| 358 | void chat_send_webpage(void){ |
| 359 | int nByte; |
| 360 | const char *zMsg; |
| 361 | const char *zUserName; |
| @@ -765,11 +777,13 @@ | |
| 765 | ** |
| 766 | ** This routine both deletes the identified chat entry and also inserts |
| 767 | ** a new entry with the current timestamp and with: |
| 768 | ** |
| 769 | ** * xmsg = NULL |
| 770 | ** * file = NULL |
| 771 | ** * mdel = The msgid of the row that was deleted |
| 772 | ** |
| 773 | ** This new entry will then be propagated to all listeners so that they |
| 774 | ** will know to delete their copies of the message too. |
| 775 | */ |
| 776 |
| --- src/chat.c | |
| +++ src/chat.c | |
| @@ -352,10 +352,22 @@ | |
| 352 | ** On success it responds with an empty response: the new message |
| 353 | ** should be fetched via /chat-poll. On error, e.g. login expiry, |
| 354 | ** it emits a JSON response in the same form as described for |
| 355 | ** /chat-poll errors, but as a standalone object instead of a |
| 356 | ** list of objects. |
| 357 | ** |
| 358 | ** Requests to this page should be POST, not GET. POST parameters |
| 359 | ** include: |
| 360 | ** |
| 361 | ** msg The (Markdown) text of the message to be sent |
| 362 | ** |
| 363 | ** file The content of the file attachment |
| 364 | ** |
| 365 | ** lmtime ISO-8601 formatted date-time string showing the local time |
| 366 | ** of the sender. |
| 367 | ** |
| 368 | ** At least one of the "msg" or "file" POST parameters must be provided. |
| 369 | */ |
| 370 | void chat_send_webpage(void){ |
| 371 | int nByte; |
| 372 | const char *zMsg; |
| 373 | const char *zUserName; |
| @@ -765,11 +777,13 @@ | |
| 777 | ** |
| 778 | ** This routine both deletes the identified chat entry and also inserts |
| 779 | ** a new entry with the current timestamp and with: |
| 780 | ** |
| 781 | ** * xmsg = NULL |
| 782 | ** |
| 783 | ** * file = NULL |
| 784 | ** |
| 785 | ** * mdel = The msgid of the row that was deleted |
| 786 | ** |
| 787 | ** This new entry will then be propagated to all listeners so that they |
| 788 | ** will know to delete their copies of the message too. |
| 789 | */ |
| 790 |
+48
-16
| --- www/chat.md | ||
| +++ www/chat.md | ||
| @@ -121,10 +121,42 @@ | ||
| 121 | 121 | shows up in the list but has no messages which are currently visible |
| 122 | 122 | because they were deleted, or an admin user who has not posted |
| 123 | 123 | anything but deleted a message. That is a known minor cosmetic-only |
| 124 | 124 | bug with a resolution of "will not fix." |
| 125 | 125 | |
| 126 | +### <a id="cli"></a> The `fossil chat` Command | |
| 127 | + | |
| 128 | +Type [fossil chat](/help?cmd=chat) from within any open check-out | |
| 129 | +to bring up a chatroom for the project that is in that checkout. | |
| 130 | +The new chat window will attempt to connect to the default sync | |
| 131 | +target for that check-out (the server whose URL is shown by the | |
| 132 | +[fossil remote](/help?cmd=remote) command). | |
| 133 | + | |
| 134 | +### <a id="robots"></a> Chat Messages From Robots | |
| 135 | + | |
| 136 | +The [fossil chat send](/help?cmd=chat) can be used by project-specific | |
| 137 | +robots to send notifications to the chatroom. For example, on the | |
| 138 | +[SQLite project](https://sqlite.org/) (for which the Fossil chatroom | |
| 139 | +feature, and indeed all of Fossil, was invented) there are long-running | |
| 140 | +fuzz servers that sometimes run across obscure problems. Whenever this | |
| 141 | +happens, a message is sent to the SQLite developers chatroom altering | |
| 142 | +them to the problem. | |
| 143 | + | |
| 144 | +The recommended way to allow robots to send chat messages is to create | |
| 145 | +a new user on the server for each robot. Give each such robot account | |
| 146 | +the "C" privilege only. That means that the robot user account will be | |
| 147 | +able to send chat messages, but not do anything else. Then, in the | |
| 148 | +program or script that runs the robot, when it wants to send a chat | |
| 149 | +message, have it run a command like this: | |
| 150 | + | |
| 151 | +> ~~~~ | |
| 152 | +fossil chat send --remote https://robot:[email protected]/fossil \ | |
| 153 | + --message 'MESSAGE TEXT' --file file-to-attach.txt | |
| 154 | +~~~~ | |
| 155 | + | |
| 156 | +Substitute the appropriate project URL, robot account | |
| 157 | +name and password, message text and file attachment, of course. | |
| 126 | 158 | |
| 127 | 159 | ## Implementation Details |
| 128 | 160 | |
| 129 | 161 | *You do not need to understand how Fossil chat works in order to use it. |
| 130 | 162 | But many developers prefer to know how their tools work. |
| @@ -134,22 +166,22 @@ | ||
| 134 | 166 | and a small amount of javascript to run the chat session. The |
| 135 | 167 | javascript uses XMLHttpRequest (XHR) to download chat content, post |
| 136 | 168 | new content, or delete historical messages. The following web |
| 137 | 169 | interfaces are used by the XHR: |
| 138 | 170 | |
| 139 | - * **/chat-poll** → | |
| 171 | + * [/chat-poll](/help?name=/chat-poll) → | |
| 140 | 172 | Downloads chat content as JSON. |
| 141 | 173 | Chat messages are numbered sequentially. |
| 142 | 174 | The client tells the server the largest chat message it currently |
| 143 | 175 | holds, and the server sends back subsequent messages. If there |
| 144 | 176 | are no subsequent messages, the /chat-poll page blocks until new |
| 145 | 177 | messages are available. |
| 146 | 178 | |
| 147 | - * **/chat-send** → | |
| 179 | + * [/chat-send](/help?name=/chat-send) → | |
| 148 | 180 | Sends a new chat message to the server. |
| 149 | 181 | |
| 150 | - * **/chat-delete** → | |
| 182 | + * [/chat-delete](/help?name=/chat-delete) → | |
| 151 | 183 | Deletes a chat message. |
| 152 | 184 | |
| 153 | 185 | Fossil chat uses the venerable "hanging GET" or |
| 154 | 186 | "[long polling](wikipedia:/wiki/Push_technology#Long_polling)" |
| 155 | 187 | technique to recieve asynchronous notification of new messages. |
| @@ -160,30 +192,30 @@ | ||
| 160 | 192 | [WebSockets](wikipedia:/wiki/WebSocket) might seem more appropriate for |
| 161 | 193 | a chat system, but those technologies are not compatible with CGI. |
| 162 | 194 | |
| 163 | 195 | Downloading of posted files and images uses a separate, non-XHR interface: |
| 164 | 196 | |
| 165 | - * **/chat-download** → | |
| 197 | + * [/chat-download](/help?name=/chat-download) → | |
| 166 | 198 | Fetches the file content associated with a post (one file per |
| 167 | 199 | post, maximum). In the UI, this is accessed via links to uploaded |
| 168 | 200 | files and via inlined image tags. |
| 169 | 201 | |
| 170 | 202 | Chat messages are stored on the server-side in the CHAT table of |
| 171 | 203 | the repository. |
| 172 | 204 | |
| 173 | -~~~ | |
| 174 | - CREATE TABLE repository.chat( | |
| 175 | - msgid INTEGER PRIMARY KEY AUTOINCREMENT, | |
| 176 | - mtime JULIANDAY, | |
| 177 | - ltime TEXT, | |
| 178 | - xfrom TEXT, | |
| 179 | - xmsg TEXT, | |
| 180 | - fname TEXT, | |
| 181 | - fmime TEXT, | |
| 182 | - mdel INT, | |
| 183 | - file BLOB) | |
| 184 | - ); | |
| 205 | +> ~~~ | |
| 206 | +CREATE TABLE repository.chat( | |
| 207 | + msgid INTEGER PRIMARY KEY AUTOINCREMENT, | |
| 208 | + mtime JULIANDAY, -- Time for this entry - Julianday Zulu | |
| 209 | + lmtime TEXT, -- Client YYYY-MM-DDZHH:MM:SS when message originally sent | |
| 210 | + xfrom TEXT, -- Login of the sender | |
| 211 | + xmsg TEXT, -- Raw, unformatted text of the message | |
| 212 | + fname TEXT, -- Filename of the uploaded file, or NULL | |
| 213 | + fmime TEXT, -- MIMEType of the upload file, or NULL | |
| 214 | + mdel INT, -- msgid of another message to delete | |
| 215 | + file BLOB -- Text of the uploaded file, or NULL | |
| 216 | +); | |
| 185 | 217 | ~~~ |
| 186 | 218 | |
| 187 | 219 | The CHAT table is not cross-linked with any other tables in the repository |
| 188 | 220 | schema. An administrator can "DROP TABLE chat;" at any time, without |
| 189 | 221 | harm (apart from deleting all chat history, of course). The CHAT table |
| 190 | 222 |
| --- www/chat.md | |
| +++ www/chat.md | |
| @@ -121,10 +121,42 @@ | |
| 121 | shows up in the list but has no messages which are currently visible |
| 122 | because they were deleted, or an admin user who has not posted |
| 123 | anything but deleted a message. That is a known minor cosmetic-only |
| 124 | bug with a resolution of "will not fix." |
| 125 | |
| 126 | |
| 127 | ## Implementation Details |
| 128 | |
| 129 | *You do not need to understand how Fossil chat works in order to use it. |
| 130 | But many developers prefer to know how their tools work. |
| @@ -134,22 +166,22 @@ | |
| 134 | and a small amount of javascript to run the chat session. The |
| 135 | javascript uses XMLHttpRequest (XHR) to download chat content, post |
| 136 | new content, or delete historical messages. The following web |
| 137 | interfaces are used by the XHR: |
| 138 | |
| 139 | * **/chat-poll** → |
| 140 | Downloads chat content as JSON. |
| 141 | Chat messages are numbered sequentially. |
| 142 | The client tells the server the largest chat message it currently |
| 143 | holds, and the server sends back subsequent messages. If there |
| 144 | are no subsequent messages, the /chat-poll page blocks until new |
| 145 | messages are available. |
| 146 | |
| 147 | * **/chat-send** → |
| 148 | Sends a new chat message to the server. |
| 149 | |
| 150 | * **/chat-delete** → |
| 151 | Deletes a chat message. |
| 152 | |
| 153 | Fossil chat uses the venerable "hanging GET" or |
| 154 | "[long polling](wikipedia:/wiki/Push_technology#Long_polling)" |
| 155 | technique to recieve asynchronous notification of new messages. |
| @@ -160,30 +192,30 @@ | |
| 160 | [WebSockets](wikipedia:/wiki/WebSocket) might seem more appropriate for |
| 161 | a chat system, but those technologies are not compatible with CGI. |
| 162 | |
| 163 | Downloading of posted files and images uses a separate, non-XHR interface: |
| 164 | |
| 165 | * **/chat-download** → |
| 166 | Fetches the file content associated with a post (one file per |
| 167 | post, maximum). In the UI, this is accessed via links to uploaded |
| 168 | files and via inlined image tags. |
| 169 | |
| 170 | Chat messages are stored on the server-side in the CHAT table of |
| 171 | the repository. |
| 172 | |
| 173 | ~~~ |
| 174 | CREATE TABLE repository.chat( |
| 175 | msgid INTEGER PRIMARY KEY AUTOINCREMENT, |
| 176 | mtime JULIANDAY, |
| 177 | ltime TEXT, |
| 178 | xfrom TEXT, |
| 179 | xmsg TEXT, |
| 180 | fname TEXT, |
| 181 | fmime TEXT, |
| 182 | mdel INT, |
| 183 | file BLOB) |
| 184 | ); |
| 185 | ~~~ |
| 186 | |
| 187 | The CHAT table is not cross-linked with any other tables in the repository |
| 188 | schema. An administrator can "DROP TABLE chat;" at any time, without |
| 189 | harm (apart from deleting all chat history, of course). The CHAT table |
| 190 |
| --- www/chat.md | |
| +++ www/chat.md | |
| @@ -121,10 +121,42 @@ | |
| 121 | shows up in the list but has no messages which are currently visible |
| 122 | because they were deleted, or an admin user who has not posted |
| 123 | anything but deleted a message. That is a known minor cosmetic-only |
| 124 | bug with a resolution of "will not fix." |
| 125 | |
| 126 | ### <a id="cli"></a> The `fossil chat` Command |
| 127 | |
| 128 | Type [fossil chat](/help?cmd=chat) from within any open check-out |
| 129 | to bring up a chatroom for the project that is in that checkout. |
| 130 | The new chat window will attempt to connect to the default sync |
| 131 | target for that check-out (the server whose URL is shown by the |
| 132 | [fossil remote](/help?cmd=remote) command). |
| 133 | |
| 134 | ### <a id="robots"></a> Chat Messages From Robots |
| 135 | |
| 136 | The [fossil chat send](/help?cmd=chat) can be used by project-specific |
| 137 | robots to send notifications to the chatroom. For example, on the |
| 138 | [SQLite project](https://sqlite.org/) (for which the Fossil chatroom |
| 139 | feature, and indeed all of Fossil, was invented) there are long-running |
| 140 | fuzz servers that sometimes run across obscure problems. Whenever this |
| 141 | happens, a message is sent to the SQLite developers chatroom altering |
| 142 | them to the problem. |
| 143 | |
| 144 | The recommended way to allow robots to send chat messages is to create |
| 145 | a new user on the server for each robot. Give each such robot account |
| 146 | the "C" privilege only. That means that the robot user account will be |
| 147 | able to send chat messages, but not do anything else. Then, in the |
| 148 | program or script that runs the robot, when it wants to send a chat |
| 149 | message, have it run a command like this: |
| 150 | |
| 151 | > ~~~~ |
| 152 | fossil chat send --remote https://robot:[email protected]/fossil \ |
| 153 | --message 'MESSAGE TEXT' --file file-to-attach.txt |
| 154 | ~~~~ |
| 155 | |
| 156 | Substitute the appropriate project URL, robot account |
| 157 | name and password, message text and file attachment, of course. |
| 158 | |
| 159 | ## Implementation Details |
| 160 | |
| 161 | *You do not need to understand how Fossil chat works in order to use it. |
| 162 | But many developers prefer to know how their tools work. |
| @@ -134,22 +166,22 @@ | |
| 166 | and a small amount of javascript to run the chat session. The |
| 167 | javascript uses XMLHttpRequest (XHR) to download chat content, post |
| 168 | new content, or delete historical messages. The following web |
| 169 | interfaces are used by the XHR: |
| 170 | |
| 171 | * [/chat-poll](/help?name=/chat-poll) → |
| 172 | Downloads chat content as JSON. |
| 173 | Chat messages are numbered sequentially. |
| 174 | The client tells the server the largest chat message it currently |
| 175 | holds, and the server sends back subsequent messages. If there |
| 176 | are no subsequent messages, the /chat-poll page blocks until new |
| 177 | messages are available. |
| 178 | |
| 179 | * [/chat-send](/help?name=/chat-send) → |
| 180 | Sends a new chat message to the server. |
| 181 | |
| 182 | * [/chat-delete](/help?name=/chat-delete) → |
| 183 | Deletes a chat message. |
| 184 | |
| 185 | Fossil chat uses the venerable "hanging GET" or |
| 186 | "[long polling](wikipedia:/wiki/Push_technology#Long_polling)" |
| 187 | technique to recieve asynchronous notification of new messages. |
| @@ -160,30 +192,30 @@ | |
| 192 | [WebSockets](wikipedia:/wiki/WebSocket) might seem more appropriate for |
| 193 | a chat system, but those technologies are not compatible with CGI. |
| 194 | |
| 195 | Downloading of posted files and images uses a separate, non-XHR interface: |
| 196 | |
| 197 | * [/chat-download](/help?name=/chat-download) → |
| 198 | Fetches the file content associated with a post (one file per |
| 199 | post, maximum). In the UI, this is accessed via links to uploaded |
| 200 | files and via inlined image tags. |
| 201 | |
| 202 | Chat messages are stored on the server-side in the CHAT table of |
| 203 | the repository. |
| 204 | |
| 205 | > ~~~ |
| 206 | CREATE TABLE repository.chat( |
| 207 | msgid INTEGER PRIMARY KEY AUTOINCREMENT, |
| 208 | mtime JULIANDAY, -- Time for this entry - Julianday Zulu |
| 209 | lmtime TEXT, -- Client YYYY-MM-DDZHH:MM:SS when message originally sent |
| 210 | xfrom TEXT, -- Login of the sender |
| 211 | xmsg TEXT, -- Raw, unformatted text of the message |
| 212 | fname TEXT, -- Filename of the uploaded file, or NULL |
| 213 | fmime TEXT, -- MIMEType of the upload file, or NULL |
| 214 | mdel INT, -- msgid of another message to delete |
| 215 | file BLOB -- Text of the uploaded file, or NULL |
| 216 | ); |
| 217 | ~~~ |
| 218 | |
| 219 | The CHAT table is not cross-linked with any other tables in the repository |
| 220 | schema. An administrator can "DROP TABLE chat;" at any time, without |
| 221 | harm (apart from deleting all chat history, of course). The CHAT table |
| 222 |