|
1
|
# Fossil Chat |
|
2
|
|
|
3
|
## Introduction |
|
4
|
|
|
5
|
Fossil’s developer chatroom feature provides an |
|
6
|
ephemeral discussion venue for insiders. Design goals include: |
|
7
|
|
|
8
|
* **Simple but functional** → |
|
9
|
Fossil chat is designed to provide a convenient real-time |
|
10
|
communication mechanism for geographically dispersed developers. |
|
11
|
Fossil chat is *not* intended as a replacement or competitor for |
|
12
|
IRC, Slack, Discord, Telegram, Google Hangouts, etc. |
|
13
|
|
|
14
|
* **Low administration** → |
|
15
|
You can activate the chatroom in seconds without having to |
|
16
|
mess with configuration files or install new software. |
|
17
|
In an existing [server setup](./server/), |
|
18
|
simply enable the [C capability](/setup_ucap_list) for users |
|
19
|
whom you want to give access to the chatroom. |
|
20
|
|
|
21
|
* **Ephemeral** → |
|
22
|
Chat messages do not sync to peer repositories, and they are |
|
23
|
automatically deleted after a configurable delay (default: 7 days). |
|
24
|
Individual messages or the entire conversation |
|
25
|
can be deleted at any time without impacting any other part |
|
26
|
of the system. |
|
27
|
|
|
28
|
Fossil chat is designed for use by insiders - people with check-in |
|
29
|
privileges or higher. It is not intended as a general-purpose gathering |
|
30
|
place for random passers-by on the internet. |
|
31
|
Fossil chat seeks to provide a communication venue for discussion |
|
32
|
that does *not* become part of the permanent record for the project. |
|
33
|
For persistent and durable discussion, use the [Forum](./forum.wiki). |
|
34
|
Because the conversation is intended to be ephemeral, the chat messages |
|
35
|
are local to a single repository. Chat content does not sync. |
|
36
|
|
|
37
|
|
|
38
|
## Setup |
|
39
|
|
|
40
|
A Fossil repository must be functioning as a [server](./server/) in order |
|
41
|
for chat to work. |
|
42
|
To activate chat, simply add the [C capability](/setup_ucap_list) |
|
43
|
to every user who is authorized to participate. Anyone who can read chat |
|
44
|
can also post to chat. |
|
45
|
|
|
46
|
Setup ("s") and Admin ("a") users always have access to chat, without needing |
|
47
|
the "C" capability. A common configuration is to add the "C" capability |
|
48
|
to "Developer" so that any individual user who has the "v" capability will |
|
49
|
also have access to chat. |
|
50
|
|
|
51
|
There are also some settings under /Admin/Chat that control the |
|
52
|
behavior of chat, though the default settings are reasonable so in most |
|
53
|
cases those settings can be ignored. The settings control things like |
|
54
|
the amount of time that chat messages are retained before being purged |
|
55
|
from the repository database. |
|
56
|
|
|
57
|
## <a id="usage"></a>Usage |
|
58
|
|
|
59
|
For users with appropriate permissions, simply browse to the |
|
60
|
[/chat](/help/www/chat) to start up a chat session. The default |
|
61
|
skin includes a "Chat" entry on the menu bar on wide screens for |
|
62
|
people with chat privilege. There is also a "Chat" option on |
|
63
|
the [Sitemap page](/sitemap), which means that chat will appear |
|
64
|
as an option under the hamburger menu for many [skins](./customskin.md). |
|
65
|
|
|
66
|
Chat messages are subject to [Fossil's |
|
67
|
full range of Markdown processing](/md_rules). Because chat messages are |
|
68
|
stored as-is when they arrive from a client, this change applies |
|
69
|
retroactively to messages stored by previous fossil versions. |
|
70
|
|
|
71
|
Files may be sent via chat using the file selection element at the |
|
72
|
bottom of the page. If the desktop environment system supports it, |
|
73
|
files may be dragged and dropped onto that element. Files are not |
|
74
|
automatically sent - selection of a file can be cancelled using the |
|
75
|
Cancel button which appears only when a file is selected. When the |
|
76
|
Send button is pressed, any pending text is submitted along with the |
|
77
|
selected file. Image files sent this way will, by default, appear |
|
78
|
inline in messages, but each user may toggle that via the settings |
|
79
|
popup menu, such that images instead appear as downloadable links. |
|
80
|
Non-image files always appear in messages as download links. |
|
81
|
|
|
82
|
### Deletion of Messages |
|
83
|
|
|
84
|
<div class="sidebar">Message deletion is itself a type of message, which |
|
85
|
is why deletions count towards updates in the recent activity list. (It |
|
86
|
is counted for the person who performed the deletion, not the author of |
|
87
|
the deleted comment.) That can potentially lead to odd corner cases |
|
88
|
where a user shows up in the list but has no messages which are |
|
89
|
currently visible because they were deleted, or an admin user who has |
|
90
|
not posted anything but deleted a message. That is a known minor |
|
91
|
cosmetic-only bug with a resolution of "will not fix."</div> |
|
92
|
|
|
93
|
Any user may *locally* delete a given message by clicking on the "tab" |
|
94
|
at the top of the message and clicking the button which appears. Such |
|
95
|
deletions are local-only, and the messages will reappear if the page |
|
96
|
is reloaded. The user who posted a given message, or any Admin users, |
|
97
|
may additionally choose to globally delete a message from the chat |
|
98
|
record, which deletes it not only from their own browser but also |
|
99
|
propagates the removal to all connected clients the next time they |
|
100
|
poll for new messages. |
|
101
|
|
|
102
|
### <a id='notifications'></a>Customizing New-message Notification Sounds |
|
103
|
|
|
104
|
By default, the list of new-message notification sounds is limited to |
|
105
|
a few built in to the fossil binary. In addition, any |
|
106
|
[unversioned files](./unvers.wiki) named `alert-sounds/*.{mp3,wav,ogg}` |
|
107
|
will be included in that list. To switch sounds, tap the "settings" |
|
108
|
button. |
|
109
|
|
|
110
|
### <a id='connection'></a> Who's Online? |
|
111
|
|
|
112
|
Because the chat app has to be able to work over transient CGI-based |
|
113
|
connections, as opposed to a stable socket connection to the server, |
|
114
|
real-time tracking of "who's online" is not feasible. |
|
115
|
Chat offers an optional feature, toggleable in the settings, |
|
116
|
which can list users who have posted messages in the client's current |
|
117
|
list of loaded messages. This is not the same thing as tracking who's |
|
118
|
online, but it gives an overview of which users have been active most |
|
119
|
recently, noting that "lurkers" (people who post no messages) will not |
|
120
|
show up in that list, nor does the chat infrastructure have a way to |
|
121
|
track and present those. That list can be used to filter messages on a |
|
122
|
specific user by tapping on that user's name, tapping a second time to |
|
123
|
remove the filter. |
|
124
|
|
|
125
|
### <a id="cli"></a> The `fossil chat` Command |
|
126
|
|
|
127
|
Type [fossil chat](/help/chat) from within any open check-out |
|
128
|
to bring up a chatroom for the project that is in that checkout. |
|
129
|
The new chat window will attempt to connect to the default sync |
|
130
|
target for that check-out (the server whose URL is shown by the |
|
131
|
[fossil remote](/help/remote) command). |
|
132
|
|
|
133
|
### <a id="robots"></a> Chat Messages From Robots |
|
134
|
|
|
135
|
The [fossil chat send](/help/chat) can be used by project-specific |
|
136
|
robots to send notifications to the chatroom. For example, on the |
|
137
|
[SQLite project](https://sqlite.org/) (for which the Fossil chatroom |
|
138
|
feature, and indeed all of Fossil, was invented) there are long-running |
|
139
|
fuzz servers that sometimes run across obscure problems. Whenever this |
|
140
|
happens, a message is sent to the SQLite developers chatroom alerting |
|
141
|
them to the problem. |
|
142
|
|
|
143
|
The recommended way to allow robots to send chat messages is to create |
|
144
|
a new user on the server for each robot. Give each such robot account |
|
145
|
the "C" privilege only. That means that the robot user account will be |
|
146
|
able to send chat messages, but not do anything else. Then, in the |
|
147
|
program or script that runs the robot, when it wants to send a chat |
|
148
|
message, have it run a command like this: |
|
149
|
|
|
150
|
~~~~ |
|
151
|
fossil chat send --remote https://robot:[email protected]/fossil \ |
|
152
|
--message 'MESSAGE TEXT' --file file-to-attach.txt |
|
153
|
~~~~ |
|
154
|
|
|
155
|
Substitute the appropriate project URL, robot account |
|
156
|
name and password, message text and file attachment, of course. |
|
157
|
|
|
158
|
### <a id="chat-robot"></a> Chat Messages For Timeline Events |
|
159
|
|
|
160
|
If the [chat-timeline-user setting](/help/chat-timeline-user) is not an |
|
161
|
empty string, then any change to the repository that would normally result |
|
162
|
in a new timeline entry is announced in the chatroom. The announcement |
|
163
|
appears to come from a user whose name is given by the chat-timeline-user |
|
164
|
setting. |
|
165
|
|
|
166
|
This mechanism is similar to [email notification](./alerts.md) except that |
|
167
|
the notification is sent via chat instead of via email. |
|
168
|
|
|
169
|
## Quirks |
|
170
|
|
|
171
|
- There is no message-editing capability. This is by design and |
|
172
|
desire of `/chat`'s developers. |
|
173
|
|
|
174
|
- When `/chat` has problems connecting to the message poller (see |
|
175
|
the next section) it will provide a subtle visual indicator of the |
|
176
|
connection problem - a dotted line along the top of the input |
|
177
|
field. If the connection recovers within a short time, that |
|
178
|
indicator will go away, otherwise it will pop up a loud message |
|
179
|
signifying that the connection to the poller is down and how long |
|
180
|
it will wait to retry (progressively longer, up to some |
|
181
|
maximum). `/chat` will recover automatically when the server is |
|
182
|
reachable. Trying to send messages while the poller connection is |
|
183
|
down is permitted, and the poller will attempt to recover |
|
184
|
immediately if sending of a message succeeds. That applies to any |
|
185
|
operations which send traffic, e.g. if the per-message "toggle |
|
186
|
text mode" button is activated or a message is globally deleted. |
|
187
|
|
|
188
|
## Implementation Details |
|
189
|
|
|
190
|
*You do not need to understand how Fossil chat works in order to use it. |
|
191
|
But many developers prefer to know how their tools work. |
|
192
|
This section is provided for the benefit of those curious developers.* |
|
193
|
|
|
194
|
The [/chat](/help/www/chat) webpage downloads a small amount of HTML |
|
195
|
and a small amount of javascript to run the chat session. The |
|
196
|
javascript uses XMLHttpRequest (XHR) to download chat content, post |
|
197
|
new content, or delete historical messages. The following web |
|
198
|
interfaces are used by the XHR: |
|
199
|
|
|
200
|
* [/chat-poll](/help?name=/chat-poll) → |
|
201
|
Downloads chat content as JSON. |
|
202
|
Chat messages are numbered sequentially. |
|
203
|
The client tells the server the latest chat message ID it currently |
|
204
|
holds, and the server sends back subsequent messages. If there |
|
205
|
are no subsequent messages, the /chat-poll page blocks until new |
|
206
|
messages are available. |
|
207
|
|
|
208
|
* [/chat-send](/help?name=/chat-send) → |
|
209
|
Sends a new chat message to the server. |
|
210
|
|
|
211
|
* [/chat-delete](/help?name=/chat-delete) → |
|
212
|
Deletes a chat message. |
|
213
|
|
|
214
|
Fossil chat uses the venerable "hanging GET" or |
|
215
|
"[long polling](wikipedia:/wiki/Push_technology#Long_polling)" |
|
216
|
technique to receive asynchronous notification of new messages. |
|
217
|
This is done because long polling works well with CGI and SCGI, |
|
218
|
which are the usual mechanisms for setting up a Fossil server. |
|
219
|
More advanced notification techniques such as |
|
220
|
[Server-sent events](wikipedia:/wiki/Server-sent_events) and especially |
|
221
|
[WebSockets](wikipedia:/wiki/WebSocket) might seem more appropriate for |
|
222
|
a chat system, but those technologies are not compatible with CGI. |
|
223
|
|
|
224
|
Downloading of posted files and images uses a separate, non-XHR interface: |
|
225
|
|
|
226
|
* [/chat-download](/help?name=/chat-download) → |
|
227
|
Fetches the file content associated with a post (one file per |
|
228
|
post, maximum). In the UI, this is accessed via links to uploaded |
|
229
|
files and via inlined image tags. |
|
230
|
|
|
231
|
Chat messages are stored on the server-side in the CHAT table of |
|
232
|
the repository. |
|
233
|
|
|
234
|
~~~ |
|
235
|
CREATE TABLE repository.chat( |
|
236
|
msgid INTEGER PRIMARY KEY AUTOINCREMENT, |
|
237
|
mtime JULIANDAY, -- Time for this entry - Julianday Zulu |
|
238
|
lmtime TEXT, -- Client YYYY-MM-DDZHH:MM:SS when message originally sent |
|
239
|
xfrom TEXT, -- Login of the sender |
|
240
|
xmsg TEXT, -- Raw, unformatted text of the message |
|
241
|
fname TEXT, -- Filename of the uploaded file, or NULL |
|
242
|
fmime TEXT, -- MIMEType of the upload file, or NULL |
|
243
|
mdel INT, -- msgid of another message to delete |
|
244
|
file BLOB -- Text of the uploaded file, or NULL |
|
245
|
); |
|
246
|
~~~ |
|
247
|
|
|
248
|
The CHAT table is not cross-linked with any other tables in the repository |
|
249
|
schema. An administrator can "DROP TABLE chat;" at any time, without |
|
250
|
harm (apart from deleting all chat history, of course). The CHAT table |
|
251
|
is dropped when running [fossil scrub --verily](/help/scrub). |
|
252
|
|
|
253
|
On the server-side, message text is stored exactly as entered by the |
|
254
|
users. The /chat-poll page queries the CHAT table and constructs a |
|
255
|
JSON reply described in the [/chat-poll |
|
256
|
documentation](/help/www/chat-poll). The message text is translated |
|
257
|
into HTML before being converted to JSON so that the text can be |
|
258
|
safely added to the display using assignment to `innerHTML`. Though |
|
259
|
`innerHTML` assignment is generally considered unsafe, it is only so |
|
260
|
with untrusted content from untrusted sources. The chat content goes |
|
261
|
through sanitization steps which eliminate any potential security |
|
262
|
vulnerabilities of assigning that content to `innerHTML`. |
|
263
|
|