1
0
mirror of https://github.com/spacebarchat/spacebarchat.git synced 2024-11-09 12:12:34 +01:00

GitBook: [master] 18 pages and one asset modified

This commit is contained in:
Fosscord Dev 2021-05-03 20:11:38 +00:00 committed by gitbook-bot
parent 10ee592254
commit ee173224c9
No known key found for this signature in database
GPG Key ID: 07D2180C7B12D0FF
19 changed files with 655 additions and 43 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 62 KiB

View File

@ -1,62 +1,50 @@
<p align="center">
<img width="100" src="/assets/logo_big_transparent.png" />
</p>
<h1 align="center">Fosscord</h1>
# Fosscord
<p>
<a href="https://discord.gg/ZrnGQP6p3d">
<img src="https://img.shields.io/discord/806142446094385153?color=7489d5&logo=discord&logoColor=ffffff" />
</a>
<img src="https://img.shields.io/static/v1?label=Status&message=Development&color=blue">
<a href="https://crowdin.com/project/fosscord">
<img src="https://badges.crowdin.net/fosscord/localized.svg" alt="Crowdin" />
</a>
</p>
[![](https://img.shields.io/discord/806142446094385153?color=7489d5&logo=discord&logoColor=ffffff)](https://discord.gg/ZrnGQP6p3d) ![](https://img.shields.io/static/v1?label=Status&message=Development&color=blue) [![Crowdin](https://badges.crowdin.net/fosscord/localized.svg)](https://crowdin.com/project/fosscord)
## [About](https://github.com/fosscord/fosscord/wiki)
### [About](https://github.com/fosscord/fosscord/wiki)
Fosscord is **f**ree **o**pen **s**ource **s**oftware compatible to dis**cord**. It is a selfhostable Chat, Voice and
Video platform similar to Slack, Rocket.chat and Discord-compatible.
Fosscord is **f**ree **o**pen **s**ource **s**oftware compatible to dis**cord**. It is a selfhostable Chat, Voice and Video platform similar to Slack, Rocket.chat and Discord-compatible.
- Discord-compatible
- Selfhostable
- Open Source
- Configurable
- Secure
- Decentralized
- Extendable
- Themeable
* Discord-compatible
* Selfhostable
* Open Source
* Configurable
* Secure
* Decentralized
* Extendable
* Themeable
logo by [@nwlandas](https://twitter.com/nwlandas)
## Installation
### Installation
_it is in development and not yet finished_
## Support
### Support
https://discord.gg/ZrnGQP6p3d
[https://discord.gg/ZrnGQP6p3d](https://discord.gg/ZrnGQP6p3d)
if we are finished we'll host our own support server.
## Repositories
### Repositories
| Repo name | Brief description |
| :----------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| [UI](https://github.com/fosscord/fosscord-ui) | Open Source CSS framework in the style of Discord. |
| [API](https://github.com/fosscord/fosscord-API) | Fosscord HTTP API Server for fosscord-client |
| [Gateway](https://github.com/fosscord/fosscord-gateway) | Fosscord WebSocket Gateway Server for fosscord-client |
| [Voice/Video](https://github.com/fosscord/fosscord-voice) | Fosscord voice and video server |
| [Server-Util](https://github.com/fosscord/fosscord-server-util) | Utility functions for the all server repositories |
| [Dashboard](https://github.com/fosscord/fosscord-dashboard) | An admin dashboard for fosscord-server (analytics, settings, administration, trust & safety) |
| [Client](https://github.com/fosscord/fosscord-client) | Fosscord Client compatible with fosscord-server and discord.com |
| [CDN](https://github.com/fosscord/fosscord-cdn) | [Content-delivery-network](https://www.cloudflare.com/learning/cdn/what-is-a-cdn/) for the server, used to store images and assets |
| [~~React Native CSS~~](https://github.com/fosscord/react-native-withcss) (archived) | ~~Library to enable css support for the client especially for themes~~ |
| [~~React Native Mediaquery~~](https://github.com/fosscord/css-mediaquery) (archived) | ~~Use CSS media queries with react native~~ |
| Repo name | Brief description |
| :--- | :--- |
| [UI](https://github.com/fosscord/fosscord-ui) | Open Source CSS framework in the style of Discord. |
| [API](https://github.com/fosscord/fosscord-API) | Fosscord HTTP API Server for fosscord-client |
| [Gateway](https://github.com/fosscord/fosscord-gateway) | Fosscord WebSocket Gateway Server for fosscord-client |
| [Voice/Video](https://github.com/fosscord/fosscord-voice) | Fosscord voice and video server |
| [Server-Util](https://github.com/fosscord/fosscord-server-util) | Utility functions for the all server repositories |
| [Dashboard](https://github.com/fosscord/fosscord-dashboard) | An admin dashboard for fosscord-server \(analytics, settings, administration, trust & safety\) |
| [Client](https://github.com/fosscord/fosscord-client) | Fosscord Client compatible with fosscord-server and discord.com |
| [CDN](https://github.com/fosscord/fosscord-cdn) | [Content-delivery-network](https://www.cloudflare.com/learning/cdn/what-is-a-cdn/) for the server, used to store images and assets |
| [~~React Native CSS~~](https://github.com/fosscord/react-native-withcss) \(archived\) | ~~Library to enable css support for the client especially for themes~~ |
| [~~React Native Mediaquery~~](https://github.com/fosscord/css-mediaquery) \(archived\) | ~~Use CSS media queries with react native~~ |
## Contribute
### Contribute
This project is only possible by volunteers like you and me, your contribution is very much appreciated 🥺.
If you want to make this project reality and and you would like to contribute then
[read this issue](https://github.com/fosscord/fosscord/issues/10) first.
If you want to make this project reality and and you would like to contribute then [read this issue](https://github.com/fosscord/fosscord/issues/10) first.

20
SUMMARY.md Normal file
View File

@ -0,0 +1,20 @@
# Table of contents
* [Fosscord](README.md)
* [General](general/README.md)
* [Getting Started](general/setup.md)
* [Contribution](general/contribution.md)
* [API](untitled-1/README.md)
* [Config](untitled-1/config.md)
* [Contributing](untitled-1/contributing.md)
* [Project-Structure](untitled-1/project-structure.md)
* [Route](untitled-1/route.md)
* [Testing](untitled-1/testing.md)
* [Gateway](untitled-2/README.md)
* [Contribution](untitled-2/contribution.md)
* [Project-Structure](untitled-2/project-structure.md)
* [Server-Util](untitled-3/README.md)
* [Database](untitled-3/database.md)
* [Permission](untitled-3/permission.md)
* [Client](untitled-4.md)

39
general/README.md Normal file
View File

@ -0,0 +1,39 @@
# General
### Why the name Fosscord?
Fosscord is a combination of the abbreviation FOSS \(~Free~/**F**air **O**pen **S**ource **S**oftware\) and the name Dis**cord**
## Philosophy
Fosscord aims to be a full one-on-one clone of Discord, adding more features that can be used as a replacement for the official client and still connect to discord.com and host private Fosscord server instances.
Fosscord aims to give the best possible user experience, while being backwards compatible to Discord's features and adding new ones/improving old ones.
The client can connect to multiple server instances without the need to open it multiple times.
The client should be extensible through a secure Plugin and Theme System with own store.
The server should be extensible through bots, just like discord without the need to change anything except the api endpoint.
The project is open source so everyone can have a look what's going on under the hood and can be maintained and expanded by the community.
Everything is configurable in the server config and everyone can add their own features, so that it is not opinionated.
### Concept
![architecture](https://github.com/fosscord/fosscord/blob/master/assets/architecture.png?raw=true)
### Why backwards compatible to Discord?
* Benefit from the large user base of discord -&gt; make a better client
* No disadvantage for the users who use fosscord, so that they can still communicate with all friends who use discord
* Discord has already built a great and stable protocol _\(don't reinvent the wheel\)_
* _\(We can still add additional features\)_
## Support
[https://discord.gg/ZrnGQP6p3d](https://discord.gg/ZrnGQP6p3d)
if we are finished we'll host our own support server.

45
general/contribution.md Normal file
View File

@ -0,0 +1,45 @@
# Contribution
Please read the [concept page](Home/) first
## Issues
### Naming convention
The issue name must have the main label as a prefix in brackets: e.g. `[Feature] Test` or `[Bug] Test`.
The first letter of the prefix and the title must be uppercase.
You are not allowed to use CAPS.
## Project structure
Fosscord consists of many repositories, which together make up the client and the server:
### Server-side
* [Fosscord-server-util](https://github.com/fosscord/fosscord-server-util) contains all shared logic like Database Models, Utility functions
* [Fosscord-api](https://github.com/fosscord/fosscord-api) is the REST HTTP API server
* [Fosscord-gateway](https://github.com/fosscord/fosscord-gateway) is the WebSocket Gateway server
* [Fosscord-media](https://github.com/fosscord/fosscord-media) will be the media server for voice and video sharing
* [Fosscord-cdn](https://github.com/fosscord/fosscord-cdn) is the content-delivery-content \(CDN\) that stores user uploaded images
### Client-side
* [Fosscord-UI](https://github.com/fosscord/fosscord-ui/wiki) is a user interface framework in the style of discord
* [Fosscord-Themes](https://github.com/fosscord/fosscord-themes) contains all the official themes for the client
* [Fosscord-Plugins](https://github.com/fosscord/fosscord-plugins) contains all the official plugins for the client
* [Fosscord-Landingpage](https://github.com/fosscord/fosscord-landingpage) represents and explains the project
* [Fosscord-Client](https://github.com/fosscord/fosscord-client) is the official Fosscord client
#### Discontinued
* [https://github.com/fosscord/react-native-withcss](https://github.com/fosscord/react-native-withcss)
* [https://github.com/fosscord/css-mediaquery](https://github.com/fosscord/css-mediaquery)
### Setup
To setup all repositories use this [setup script](https://github.com/fosscord/fosscord/tree/master/scripts/setup).
If you only want to work on a specific repository follow their setup guide.

28
general/setup.md Normal file
View File

@ -0,0 +1,28 @@
# Getting Started
## Without automated scripts
### Windows
1. Open up a Terminal.
2. Type this command: `curl https://raw.githubusercontent.com/fosscord/fosscord/main/scripts/setup/setup.bat --output setup.bat && setup.bat`.
### Posix systems \(MacOS, Linux...\)
1. Open up a Terminal.
2. Type this command: `curl https://raw.githubusercontent.com/fosscord/fosscord/main/scripts/setup/setup.sh --output setup.sh && sh setup.sh`.
## With automated scripts
This method need to have [Git](https://git-scm.com) installed.
### Windows
1. Open up a Terminal.
2. Type this command: `git clone https://github.com/fosscord/fosscord && .\fosscord\scripts\setup\setup.bat`.
### Posix systems \(MacOS, Linux...\)
1. Open up a Terminal.
2. Type this command: `git clone https://github.com/fosscord/fosscord && sh ./fosscord/scripts/setup/setup.sh`.

18
untitled-1/README.md Normal file
View File

@ -0,0 +1,18 @@
# API
Welcome to the Fosscord API Server wiki!
[Status Overview](https://github.com/discord-open-source/discord-api/projects/2)
This is a complete one-on-on clone of the discord api written in TypeScript.
For documentation head over to the discord [docs](https://discord.dev).
## Installation
The API is not yet finished
## Contribution
If want to help developing go ahead and read the [Contribution Guide](Contribution/)

46
untitled-1/config.md Normal file
View File

@ -0,0 +1,46 @@
# Config
## Philosophy
Every fosscord server instance should be completely configurable in every way, without the need to change the source code.
The config should have reasonable defaults similar to discord.
Only in special cases it should require a third party config value.
The config should be changeable over the admin fosscord-dashboard and update in realtime without the need to restart the servers
The very first time the server starts, it saves to default config in the database. The next start it will load the config from the database.
## Getting Started
You **should not** `get()` the Config in the root of your file and it instead load the config every time you access a value
Import the file:
```javascript
// at the top of the file import the Config file from /src/util/Config.ts
import Config from "/../util/Config";
```
Access the Config in your route:
```javascript
router.get("/", (req: Request, res: Response) => {
// call Config.get() to get the whole config object and then just access the property you want
const { REGISTRATION_DISABLED } = Config.get().register
});
```
`Config.get()` returns the current config object and is not expensive at all
## Add own values to the Config
The default Config is located in `/src/util/Config.ts` and exports a `interface DefaultOptions` and a `const DefaultOptions` object with reasonable default values.
To add your own values to the config, add the properties to the `interface` with corresponding types and add default values to `const DefaultOptions`.
Also you don't need to worry about updating "old config versions", because new values will automatically be synced with the database.
Note, however, that if the database already has a default value it won't update it.

View File

@ -0,0 +1,37 @@
# Contributing
You should be familiar with:
* [Git](https://git-scm.com/)
* [NodeJS](https://nodejs.org/)
* [TypeScript](https://www.typescriptlang.org/)
* [Mongoose](https://mongoosejs.com/)
and the technologies we use for the API.
## Getting Started
Clone the Repository:
```bash
git clone https://github.com/fosscord/fosscord-api
cd fosscord-api
```
### Install \(dev\)dependencies:
```bash
npm install
npm install --only=dev
```
### Starting:
```text
npm start
```
### Debugging:
**Vscode:** The Launch file configuration is in `./vscode/launch.json`, so you can just debug the server by pressing `F5` or the `> Launch Server` button

View File

@ -0,0 +1,30 @@
# Project-Structure
This repository currently contains the HTTP API Server
## Translation
Additionally we use [i18next](https://www.i18next.com/) to manage translation/localization in _some_ API Responses.
The `.json` language files are located in `/locales` and are separated by namespaces.
## Source code
We use [TypeScript](https://www.typescriptlang.org/) \(JavaScript with types\). The `.ts` source files are located in `/src/` and will be compiled to `.js` in the `/dist/` directory.
### Middlewares
All Express [Middlewares](http://expressjs.com/en/guide/writing-middleware.html) are in the directory `/src/middlewares/` and need to be manually loaded in `/src/Server.ts`.
### Routes
All Express [Router](http://expressjs.com/en/4x/api.html#router) Routes are in the directory `/src/routes/` and are automatically registered.
### Models
All Database Typescript interface models are in the directory `/src/models/`
### Util
All Utility functions are in the directory `/src/util/`.

134
untitled-1/route.md Normal file
View File

@ -0,0 +1,134 @@
# Route
## General
All routes are located in the directory `/src/routes/` and are loaded on start by a the [lambert-server](https://www.npmjs.com/package/lambert-server) package.
The HTTP API path is generated automatically based on the folder structure, so it is important that you name your files accordingly.
If you want to use URL Params like `:id` in e.g. `/users/:id` you need to use `#` instead of `:` for the folder/filename, because of file naming issues on windows.
`index.ts` files **won't** serve `/api/index` and instead alias the parent folder e.g. `/api/`
Your file needs to default export a [express.Router\(\)](https://expressjs.com/de/4x/api.html#router):
```typescript
import { Router } from express
const router = Router();
export default router;
```
Now you can just use any regular express function on the router variable e.g:
```typescript
router.get("/", (req, res) => {});
router.post("/", (req, res) => {});
router.get("/members", (req, res) => {});
```
## Authentication
Every request must contain the authorization header except the `/login` and `/register` route.
To access the user id for the token of the request use `req.user_id`
## Body Validation
We use a custom body validation logic from lambert-server to check if the JSON body is valid.
To import the function from `/src/util/instanceOf.ts` use:
```typescript
import { check } from "/src/util/instanceOf";
```
Now you can use the [middleware](http://expressjs.com/en/guide/using-middleware.html) `check` for your routes by calling check with your Body Schema.
```typescript
router.post("/", check(...), (req,res) => {});
```
### Schema
A Schema is a Object Structure with key-value objects that checks if the supplied body is an instance of the specified class.
```typescript
{ id: String, roles: [String] }
```
_Notice if you use e.g. BigInt even if you can't supply it with JSON, it will automatically convert the supplied JSON number/string to a BigInt._
_Also if you want to check for an array of, just put the type inside `[]`_
#### Optional Parameter
You can specify optional parameters if you prefix the key with a `$` \(dollar sign\) e.g.: `{ $captcha: String }`, this will make the captcha property in the body optional.
#### Limit String length
Additionally import the class `Length` from instanceOf and specify the type by making a new `Length` Object taking following parameters:
```typescript
import { Length } from "/src/util/instanceOf";
const min = 2;
const max = 32;
const type = String;
{ username: new Length(min: number, max: number, type) }
```
this will limit the maximum string length to the `min` and `max` value.
### Example:
```typescript
import { check, Length } from "/src/util/instanceOf";
const SCHEMA = { username: new Length(2, 32, String), age: Number, $posts: [{ title: String }] }
app.post("/", check(SCHEMA), (req, res) => {});
```
## Throw Errors
If the body validation fails it will automatically throw an error.
The `errors` structure is a key-value Object describing what field contained the error:
```javascript
{
"code": 50035,
"message": "Invalid Form Body",
"errors": {
"email": {
"_errors": [
{
"message": "Email is already registered",
"code": "EMAIL_ALREADY_REGISTERED"
}
]
},
"username": {
"_errors": [
{
"message": "Must be between 2 - 32 in length",
"code": "BASE_TYPE_BAD_LENGTH"
}
]
}
}
}
```
To manually throw a `FieldError` import `FieldErrors`
```typescript
import { FieldErrors } from /src/util/instanceOf
```
To make sure your errors are understood in all languages translate it with [i18next](https://www.i18next.com/translation-function/essentials) and `req.t`
So after you have checked the field is invalid throw the `FieldErrors`
```typescript
throw FieldErrors(( login: { message: req.t("auth:login.INVALID_LOGIN"), code: "INVALID_LOGIN" }});
```

28
untitled-1/testing.md Normal file
View File

@ -0,0 +1,28 @@
# Testing
## Testing the api manually
### 1.: Follow the setup instructions [here](https://github.com/fosscord/fosscord/tree/main/scripts/setup)
### 2.: Navigate to the Gateway; install packages and run npm start
```text
cd fosscord/gateway
npm i
npm start
```
### 3.: Navigate to the API; install packages and run npm start
```text
cd fosscord/api
npm i
npm start
```
### 4.:
navigate to `localhost:3001`
test your changes manually on localhost

14
untitled-2/README.md Normal file
View File

@ -0,0 +1,14 @@
# Gateway
Welcome to the Fosscord Gateway Server wiki! [Status Overview](https://github.com/fosscord/fosscord-gateway/projects/3)
This is a complete one-on-on clone of the discord gateway written in TypeScript.
## Installation
The Gateway is not yet finished
## Contribution
If want to help developing go ahead and read the [Contribution Guide](Contribution/)

View File

@ -0,0 +1,36 @@
# Contribution
You should be familiar with:
* [Git](https://git-scm.com/)
* [NodeJS](https://nodejs.org/)
* [TypeScript](https://www.typescriptlang.org/)
and the technologies we use for the Gateway.
## Getting Started
Clone the Repository:
```bash
git clone https://github.com/fosscord/fosscord-gateway
cd discord-gateway
```
### Install \(dev\)dependencies:
```bash
npm install
npm install --only=dev
```
### Starting:
```text
npm start
```
### Debugging:
**Vscode:** The Launch file configuration is in `./vscode/launch.json`, so you can just debug the server by pressing `F5` or the `> Launch Server` button

View File

@ -0,0 +1,4 @@
# Project-Structure
For the WebSocket we use [ws](https://www.npmjs.com/package/ws) and we'll write our own packet handler for the individual opcodes and events.

4
untitled-3/README.md Normal file
View File

@ -0,0 +1,4 @@
# Server-Util
Welcome to the fosscord-server-util wiki!

112
untitled-3/database.md Normal file
View File

@ -0,0 +1,112 @@
# Database
## Philosophy
We create [mongoose](http://mongoosejs.com/) models and typescript interfaces for every data structure in the database.
We use BigInt's for ids instead of strings because of a better performance. _Note that they will get encoded if you send them_
## Documentation
Have a look at the mongoose documentation to get familiar with it: [https://mongoosejs.com/docs/](https://mongoosejs.com/docs/)
or watch this tutorial: [https://youtu.be/WDrU305J1yw](https://youtu.be/WDrU305J1yw)
## Getting Started
```typescript
import mongoose from "mongoose";
```
and now you can query the database, here are some examples:
```typescript
import { GuildModel} from "fosscord-server-util";
await new GuildModel({ ... }).save();
const guild = await GuildModel.findOne({id: ...}).exec();
```
## Models
We have mongoose Database Models and additionally [TypeScript Interfaces](https://www.typescriptlang.org/docs/handbook/interfaces.html).
They are located in the repo `fosscord-server-util` under `/src/models/`.
To add your own Database Model, create a new file and export the model and the interface.
Example:
```typescript
export interface Event extends Document {
guild_id?: bigint;
user_id?: bigint;
channel_id?: bigint;
created_at?: number;
event: EVENT;
data?: any;
}
export const EventSchema = new Schema({
guild_id: Types.Long,
user_id: Types.Long,
channel_id: Types.Long,
created_at: { type: Number, required: true },
event: { type: String, required: true },
data: Object,
});
export const EventModel = model<Event>("Event", EventSchema, "events");
```
## Emit events
Most Routes modify the database and therefore need to inform the clients with events for data changes.
_\(Events are stored in a MongoDB Event Store collection and distributed to the individual gateway servers\)_
You can find all events on the [discord docs page](https://discord.com/developers/docs/topics/gateway#commands-and-events)
To emit an event import the `emitEvent` function from `/src/util/Event.ts`
```typescript
import { emitEvent } from "./../../../util/Event";
```
this will take a the following parameters:
```typescript
{
guild_id?: bigint; // specify this if this event should be sent to all guild members
channel_id?: bigint; // specify this if this event should be sent to all channel members (e.g. group dm)
user_id?: bigint; // specify this if this event should be sent to the specific user
event: string; // the EVENTNAME, you can find all gateway event names in the fosscord-server-util Events file
data?: any; // event payload data
}
```
For easy intellisense, annotate the parameter with the corresponding Event interface from `fosscord-server-util`:
```typescript
import { GuildDeleteEvent } from "fosscord-server-util";
emitEvent({...} as GuildDeleteEvent);
// or with <> brackets:
emitEvent(<GuildDeleteEvent>{...});
```
### Example
Putting it all together:
```typescript
await emitEvent({
event: "GUILD_DELETE",
data: {
id: guildID,
},
guild_id: guildID,
} as GuildDeleteEvent);
```

25
untitled-3/permission.md Normal file
View File

@ -0,0 +1,25 @@
# Permission
To get the permission for a guild member import the `getPermission` from `fosscord-server-util`.
```typescript
import { getPermission } from "fosscord-server-util"
```
The first argument is the userid the second the guildid and the third channelid if you want to receive the permission for a certain channel.
```typescript
getPermission(user_id: string, guild_id: string, channel_id?: string): Promise<Permissions>;
```
## Example
```typescript
const perms = await getPermission(req.userid, guild_id);
perms.hasThrow("MANAGE_GUILD") // will throw an error if the users lacks the permission
if (perms.has("MANAGE_GUILD")) {
...
}
```

4
untitled-4.md Normal file
View File

@ -0,0 +1,4 @@
# Client
Welcome to the fosscord-client wiki!