@ -36,7 +36,7 @@ You can also run the program using Cargo, that is handy for development: `cargo
3. **Make sure you auth as the correct user!**
4. Paste the Oauth2 token you got into the terminal, hit enter.
The program now ends. The credentials are saved in a file `groups.json`.
The program now ends. The credentials are saved in the directory `groups.d/account@server/`, which is created if missing.
You can repeat this for any number of groups.
@ -44,53 +44,82 @@ In case you need to re-authenticate an existing group, do the same but use `-A`
### Editing config
**Do not edit the config while the group service is running, it will overwrite your changes!**
**Do not edit the config while the group service is running, it may overwrite your changes!**
Each group is stored as a sub-directory in `groups.d`. The sub-directories are normally named after their accounts,
but this is not required.
The group's config and state is split into three files:
- `config.json` - immutable config, never changed beside when you run the -A command to reauth the group.
This is where the auth token and the `enabled` flag are stored.
- `control.json` - settings and state that changes at runtime or can be set using slash commands.
This file is overwritten by the group service when needed.
- `state.json` - frequently changing state data. The last-seen status/notification timestamps are kept here.
State is split from Control to reduce the risk of damaging the control file. Timestamps can be updated multiple times
per minute.
The JSON files are easily editable, you can e.g. add yourself as an admin (use the e-mail format, e.g. `piggo@piggo.space`).
When adding hashtags, note that *they must be entered as lowercase*!
The JSON file is easily editable, you can e.g. add yourself as an admin (use the e-mail format, e.g. `piggo@piggo.space`).
The file format is quite self-explanatory.
#### config.json
```json
{
"groups": {
"group@myserver.xyz": {
"enabled": true,
"acct": "group@myserver.xyz",
"appdata": {
"base": "https://myserver.xyz",
"client_id": "...",
"client_secret": "...",
"redirect": "urn:ietf:wg:oauth:2.0:oob",
"token": "..."
},
"group_tags": [
"grouptest"
],
"admin_users": [
"admin@myserver.xyz"
],
"member_only": false,
"member_users": [],
"banned_users": [],
"banned_servers": [
"bad-stuff-here.cc"
],
"last_notif_ts": 1630011219000,
"last_status_ts": 1630011362000
}
"enabled": true,
"acct": "group@myserver.xyz",
"appdata": {
"base": "https://myserver.xyz",
"client_id": "...",
"client_secret": "...",
"redirect": "urn:ietf:wg:oauth:2.0:oob",
"token": "..."
}
}
```
- `group_tags` - group hashtags (without the `#`). The group reblogs anything with these hashtags if the author is a member.
#### control.json
```json
{
"group_tags": [
"grouptest"
],
"admin_users": [
"admin@myserver.xyz"
],
"member_only": false,
"member_users": [],
"banned_users": [],
"banned_servers": [
"bad-stuff-here.cc"
]
}
```
- `group_tags` - group hashtags (without the `#`), lowercase! The group reblogs anything with these hashtags if the author is a member.
- `member_users` - group members, used to track whose hashtags should be reblogged; in member-only groups, this is also a user whitelist.
- `banned_users` - can't post or interact with the group service
- `banned_servers` - work like an instance block
#### state.json
```json
{
"last_notif_ts": 1630011219000,
"last_status_ts": 1630011362000
}
```
### Running
To run the group service, simply run it with no arguments. It will read what to do from `groups.json`.
To run the group service, simply run it with no arguments. It will find groups in `groups.d` and start the service threads for you.
Note that the file must be writable, it is updated at run-time.
Note that the control and status files must be writable, they are updated at run-time. Config files can have restricted permissions
to avoid accidental overwrite.
An example systemd service file is included in the repository as well. Make sure to set up the system user/group and file permissions according to your needs. You can use targets in the included `Makefile` to manage the systemd service and look at logs.
@ -116,7 +145,7 @@ These won't be shared:
- `ducks suck`
- `@group #ducks /i` (anything with the "ignore" command is ignored)
- `@group /remove #ducks` (admin command, even if it includes a group hashtag)
- `@otheruser tell me about ducks` (in a thread)
- `@otheruser tell me about #ducks` (in a thread)
- `@otheruser @group tell me about ducks` (in a thread)