diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 980f5cc..a88f794 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -102,11 +102,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 diff --git a/docs/config.toml b/docs/config.toml index 9d9eb9b..2fb83ae 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -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" diff --git a/docs/content/endpoints/_index.md b/docs/content/endpoints/_index.md new file mode 100644 index 0000000..02fab75 --- /dev/null +++ b/docs/content/endpoints/_index.md @@ -0,0 +1,6 @@ +--- +title: JSON API Endpoints +anchor: endpoints +weight: 10 +--- + diff --git a/docs/content/endpoints/auth.md b/docs/content/endpoints/auth.md new file mode 100644 index 0000000..e40e6d0 --- /dev/null +++ b/docs/content/endpoints/auth.md @@ -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"} +``` diff --git a/docs/content/endpoints/channels.md b/docs/content/endpoints/channels.md new file mode 100644 index 0000000..8ca6553 --- /dev/null +++ b/docs/content/endpoints/channels.md @@ -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\ + +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 + + diff --git a/docs/content/endpoints/invites.md b/docs/content/endpoints/invites.md new file mode 100644 index 0000000..5fc26b9 --- /dev/null +++ b/docs/content/endpoints/invites.md @@ -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 + 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": , + < "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 + < } +``` + diff --git a/docs/content/endpoints/members.md b/docs/content/endpoints/members.md new file mode 100644 index 0000000..3dc8c8d --- /dev/null +++ b/docs/content/endpoints/members.md @@ -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": , + < "permissions": <64-bit-mask> + < } +``` + +### `GET /members/online` + +* Required query string parameters: + + * id: u64 + * jwt: String + * limit: Optional + * Internal default: 100 + +* Returns + * members: Array + * 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 + * Maximum = 1000 + +* Returns + * messages: Array + + +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 + * Maximum = 1000 + +* Returns + * messages: Array + +Example +``` + > GET /message/from_id?id=123&jwt=... + + < { "mesages": [...] } +``` + + diff --git a/docs/content/endpoints/perms.md b/docs/content/endpoints/perms.md new file mode 100644 index 0000000..f5fe8a2 --- /dev/null +++ b/docs/content/endpoints/perms.md @@ -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. + + + diff --git a/docs/content/structures/_index.md b/docs/content/structures/_index.md index f7ad36b..1d39f08 100644 --- a/docs/content/structures/_index.md +++ b/docs/content/structures/_index.md @@ -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=`. The other data is merely for tracking the server's end. - - diff --git a/docs/content/structures/channels.md b/docs/content/structures/channels.md new file mode 100644 index 0000000..3dbeffc --- /dev/null +++ b/docs/content/structures/channels.md @@ -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 + diff --git a/docs/content/structures/messages.md b/docs/content/structures/messages.md new file mode 100644 index 0000000..05a9ea5 --- /dev/null +++ b/docs/content/structures/messages.md @@ -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=`. The other data is merely for tracking the server's end. + + diff --git a/docs/content/structures/users.md b/docs/content/structures/users.md new file mode 100644 index 0000000..405faf5 --- /dev/null +++ b/docs/content/structures/users.md @@ -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. + diff --git a/json-api/src/messages.rs b/json-api/src/messages.rs index 58bd351..e084723 100644 --- a/json-api/src/messages.rs +++ b/json-api/src/messages.rs @@ -18,14 +18,14 @@ pub async fn get_by_time(pool: &Pool, response: &mut Response, 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