shockrah/freechat
shockrah/freechat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merging new wiki into master

Browse Source
This commit is contained in:
shockrah 2021-02-18 16:30:16 -08:00
commit c4db03f962
13 changed files with 486 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitlab-ci.yml
View File

@ -124,11 +124,9 @@ build-wiki:
- mkdir -p ~/.ssh/
- chmod 700 ~/.ssh/
# sed is required because hugo keep building bad html on the stylesheet line somehow
script:
- cd docs/
- hugo
- sed 's/xyzcss/xyz\/css' -i public/index.html
- ssh $SHOPTS web@shockrah.xyz "rm -rf /var/www/freechat"
- scp $SHOPTS -r public/ web@shockrah.xyz:/var/www/freechat

4
docs/config.toml
View File

@ -1,7 +1,5 @@
baseURL = "https://freechat.shockrah.xyz"
baseURL = "https://freechat.shockrah.xyz/"
languageCode = "en-us"
theme = "kraiklyn"
title = "Freechat Reference"
[params]
externalTitle = "Freechat docs"

6
docs/content/endpoints/_index.md Normal file
View File

@ -0,0 +1,6 @@
---
title: JSON API Endpoints
anchor: endpoints
weight: 10
---

27
docs/content/endpoints/auth.md Normal file
View File

@ -0,0 +1,27 @@
---
title: Authorization
anchor: auth-ep
weight: 11
---
To make things easy: user `id`, `secret`, and `jwt` values are to be put in the query string. Headers are largely ignored as they offer no guarantees in security. The biggest reason for this however is for simplicity of implementation for servers.
### `POST /login`
This route can be used to
* Required query string parameters:
* id: u64
* secret: String
* Returns:
* jwt: String
Example
```
> POST /login?id=123&secret=super-secret-token
< {"jwt": "asdf.asdf.asdf"}
```

94
docs/content/endpoints/channels.md Normal file
View File

@ -0,0 +1,94 @@
---
title: Channels
anchor: channels-ep
weight: 13
---
### `GET /channels/list`
* Required query string parameters:
* id: u64
* jwt: String
* Required Permissions
* None
* Returns:
* channels: Array\<Channel\>
Example
```
> GET /channels/list?id=123&jwt=...
< {
< "channels": [
< {
< "id": 1
< "name": "general",,
< "kind": 2,
< "description": "this could be null"
< },
< ...
< ]
< }
```
### `POST /channels/create`
* Required Permissions:
* CREATE_CHANNEL
* Required query string parameters:
* id: u64
* jwt: String
* name: String
* kind: u32
* Voice channel = 1
* Text channel = 2
* description: String
* Optional field
* Returns
* Channel
* id: u64
* name: String
* description: String | null
* kind: i32
```
> POST /channels/create?id=123&jwt=...
< {
< "id": 3,
< "name": "new-channel",
< "description": null,
< "kind": 2
< }
```
### `DELETE /channels/delete`
* Required permissions:
* DELETE_CHANNEL
* Required query string parameters:
* id: u64
* jwt: String
* channel_id: u64
* Returns:
* None

78
docs/content/endpoints/invites.md Normal file
View File

@ -0,0 +1,78 @@
---
title: Invites
anchor: invites-ep
weight: 15
---
### `POST /invite/create`
* Required permissions:
* CREATE_TMP_INVITES
* Base requirement
* CREATE_PERM_INVITES
* Additional requirement for permanent invite codes
* Required query string parameters:
* id: u64
* jwt: string
* Returns
* id: i64
* uses: Optional<i64>
This field is really meant for servers and really doesn't have much use to users. It just to keep track of whether or not an invite has been used too many times or not.
* expires: boolean
Example
```
> POST /invite/create?id=123&jwt=
< {
< "id": <unix-timestamp>,
< "uses": 3,
< "expires": true
< }
```
### `GET /join`
* Required Permissions
* None
* Required query string parameters:
* code: i64
* Returns a new member account - The account details are not behind a key in the JSON object, so the resulting data is completely flat, for JSON.
* id: u64
* secret: String
* name: String
* joindate: i64
* status: i32
* permissions: u64
* Default values
* status: 0
* permissions: 51
* name: Anonymous
* joindate: Current Unix time since epoch
Example
```
> GET /join?code=123456
< {
< "id": 123,
< "secret": "super secret",
< "name": "Anonymous",
< "joindate": 134256,
< "status": 0,
< "permissions": 51
< }
```

147
docs/content/endpoints/members.md Normal file
View File

@ -0,0 +1,147 @@
---
title: Members
anchor: members-ep
weight: 14
---
### `POST /members/me/nickname`
* Required permissions:
* CHANGE_NICK
* Required query string parameters:
* id: u64
* jwt: String
* name: String
* New nickname to change to(if allowed)
* Returns
* None
### `GET /members/me`
* Required query string parameters:
* id: u64
* jwt: String
* Returns:
* Member
* Contains all public data about your account on the server
Example
```
> GET /members/me?id=123&jwt=...
< {
< "name": "nickname-here",
< "id": 123,
< "joindate": <unix-timestamp>,
< "permissions": <64-bit-mask>
< }
```
### `GET /members/online`
* Required query string parameters:
* id: u64
* jwt: String
* limit: Optional<u64>
* Internal default: 100
* Returns
* members: Array<Members>
* Each member contains: [`name`, `id`, `joindate`, `permissions`]
* count: u64
Example
```
> GET /members/online?id=123&jwt=...
< { "members": [...] }
```
## Messages
### `POST /message/send`
* Required permissions:
* SEND_MESSAGES
* Required query string parameters:
* id: u64
* jwt: String
* channel_id: u64
* type: String
Valid values:
* text
* jpeg
* png
* webm
* mp4
* Required body:
* Content itself should always go in the body
* Empty bodies result in an HTTP 400 response
* Returns:
* None
### `GET /message/get_range`
* Required query string parameters:
* id: u64
* jwt: string
* channel_id: u64
* start_time: i64
* Unix timestamp (seconds)
* end_time: i64
* Unix timestamp (seconds)
* limit: Optional<u64>
* Maximum = 1000
* Returns
* messages: Array<Message>
Example
```
> GET /message/get_range?id=123&jwt=...
< { "mesages": [...] }
```
### `GET /message/from_id`
* Required query string parameters:
* id: u64
* jwt: string
* channel_id: u64
* start: u64
* limit: Optional<u64>
* Maximum = 1000
* Returns
* messages: Array<Message>
Example
```
> GET /message/from_id?id=123&jwt=...
< { "mesages": [...] }
```

32
docs/content/endpoints/perms.md Normal file
View File

@ -0,0 +1,32 @@
---
title: Permissions
anchor: permissions
weight: 12
---
Due to the nature of many endpoints, some endpoints require a user to have certain permissions setup.
User permissions are stored as an `unsigned 64-bit` bit mask alongside other user data. So far the current implemented permissions are listed below as follows.
NOTE: due to the rapid changing of features this list is subject to change until
the protocol reaches `1.0` status.
| Name | Value | Short Description
:------|:-------------:|:----
JOIN_VOICE| 0x01 | Ability to join a voice channel via
SEND_MESSAGES| 0x02 | Ability to send text messages in any text channel
CREATE_TMP_INVITES| 0x04 | Creation of invite codes which expire
CREATE_PERM_INVITES| 0x08 | Create of invite codes which do not expire
CHANGE_NICK | 0x10 | Can change nickname
ALLOW_PFP|0x20 | Allowed to upload their own profile picture to the server
CREATE_CHANNEL| 0x40 | Can create channels
DELETE_CHANNEL| 0x80 | Can delete channels
ADMIN| 0x4000000000000000 | Can modify any permission beneath them, but not other admins
OWNER| 0x8000000000000000 | Can modify anything
Typically Admins and Owners will have every role beneath them alongside their own
admin/owner flag for the sake of implementation simplicity although this is of
no importance to those wanting to write their own client software.

84
docs/content/structures/_index.md
View File

@ -1,4 +1,8 @@
# Structures
---
title: Structures
anchor: structures
weight: 30
---
This section details what kind of data structures are returned by the json-api.
@ -16,82 +20,4 @@ This section details what kind of data structures are returned by the json-api.
* String
## Channels
Channels are made up of the following components
Name | Type
:------:|:--------:
id | `u64`
name | `String`
kind | `i32`
Channels have two valid types or (more semantically) `kind` values:
* Voice Channel = 1
* Text Channel = 2
## Users
### Personal User
If you need to get your own user data, with `/users/me` then the data received on success has the following fields:
Name | Type
:------:|:-----:
id | `u64`
secret | `String`
joindate| `i64`
status | `i32`
permissions| `u64`
### JWT
This data is retrieved after a sucessful `/login` hit.
Name | Type
:-----:|:------:
jwt | `String`
### Full Public User
Name | Type
:-----:|:-----:
id | `u64`
name | `String`
joindate| `i64`
status | `i32`
permissions| `u64`
For users _without_ the `USER_FETCH` permission the only two fields with actual data is `id` and `name`. The other fields will be set to 0.
## Messages
Name | Type
:-----:|:-----:
id | `u64`
time | `i64`
content | `String`
type | `String`
author_id | `u64`
channel_id | `u64`
Acceptable values
## Invites
When requesting a code from `/invite/create` successful data contains:
Name | Type
:-----:|:-----:
id | `i64`
uses | `null|i64`
expires| `bool`
Most clients should format this code for usage as `https://domain.net:port/join?code=<id>`. The other data is merely for tracking the server's end.

23
docs/content/structures/channels.md Normal file
View File

@ -0,0 +1,23 @@
---
title: Channels
anchor: channels
weight: 35
---
Channels are made up of the following components
Name | Type
:------:|:--------:
id | `u64`
name | `String`
kind | `i32`
description| `String`
Channels have two valid types or (more semantically) `kind` values:
* Voice Channel = 1
* Text Channel = 2

31
docs/content/structures/messages.md Normal file
View File

@ -0,0 +1,31 @@
---
title: Messages
anchor: messages
weight: 40
---
Name | Type
:-----:|:-----:
id | `u64`
time | `i64`
content | `String`
type | `String`
author_id | `u64`
channel_id | `u64`
Acceptable values
## Invites
When requesting a code from `/invite/create` successful data contains:
Name | Type
:-----:|:-----:
id | `i64`
uses | `null|i64`
expires| `bool`
Most clients should format this code for usage as `https://domain.net:port/join?code=<id>`. The other data is merely for tracking the server's end.

38
docs/content/structures/users.md Normal file
View File

@ -0,0 +1,38 @@
---
title: Users
anchor: users
weight: 50
---
### Personal User
If you need to get your own user data, with `/users/me` then the data received on success has the following fields:
Name | Type
:------:|:-----:
id | `u64`
secret | `String`
joindate| `i64`
status | `i32`
permissions| `u64`
### JWT
This data is retrieved after a sucessful `/login` hit.
Name | Type
:-----:|:------:
jwt | `String`
### Full Public User
Name | Type
:-----:|:-----:
id | `u64`
name | `String`
joindate| `i64`
status | `i32`
permissions| `u64`
For users _without_ the `USER_FETCH` permission the only two fields with actual data is `id` and `name`. The other fields will be set to 0.

8
json-api/src/messages.rs
View File

@ -18,14 +18,14 @@ pub async fn get_by_time(pool: &Pool, response: &mut Response<Body>, params: Has
* @end-time: how long ago do we stop searching
* {
* "channel_id": 1,
* "start-time": unix_now - 24 hours
* "end-time": unix_now - 23 hours
* "start_time": unix_now - 24 hours
* "end_time": unix_now - 23 hours
* }
*
*/
let channel_id = qs_param!(params, "channel_id", u64);
let start_time = qs_param!(params, "start-time", i64);
let end_time = qs_param!(params, "end-time", i64);
let start_time = qs_param!(params, "start_time", i64);
let end_time = qs_param!(params, "end_time", i64);
let limit = qs_param!(params, "limit", u64);
// TODO: flatten me mommy