mirror of
https://github.com/spacebarchat/docs.git
synced 2024-09-19 15:11:44 +02:00
Finalize the work!
This commit is contained in:
parent
4417a3a0c2
commit
571c7baedd
@ -5,7 +5,4 @@ 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).
|
||||
The API is not yet finished.
|
@ -9,21 +9,27 @@ You should be familiar with:
|
||||
and the technologies we use for the API.
|
||||
|
||||
## Getting Started
|
||||
Clone the Repository:
|
||||
### Step 1
|
||||
Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/fosscord/fosscord-api
|
||||
cd fosscord-api
|
||||
```
|
||||
### Install (dev) dependencies
|
||||
### Step 2
|
||||
Install (dev) dependencies:
|
||||
```bash
|
||||
npm install
|
||||
npm install --only=dev
|
||||
```
|
||||
### Starting
|
||||
### Step 3
|
||||
Start:
|
||||
```
|
||||
npm start
|
||||
```
|
||||
### Debugging
|
||||
#### VS Code
|
||||
### Step 4
|
||||
Navigate to `localhost:3001`. You will see the API in action.
|
||||
|
||||
## Debugging
|
||||
### VS Code
|
||||
The Launch file configuration is in ``./vscode/launch.json``,
|
||||
so you can just debug the server by pressing ``F5`` or the ``> Launch Server`` button
|
@ -1,22 +0,0 @@
|
||||
## Testing the api manually
|
||||
### Step 1
|
||||
Follow the setup instructions [here](../../installation).
|
||||
|
||||
### Step 2
|
||||
Navigate to the Gateway, install packages and start:
|
||||
```
|
||||
cd fosscord/gateway
|
||||
npm i
|
||||
npm start
|
||||
```
|
||||
|
||||
### Step 3
|
||||
Navigate to the API, install packages and start:
|
||||
```
|
||||
cd fosscord/api
|
||||
npm i
|
||||
npm start
|
||||
```
|
||||
|
||||
### Step 4
|
||||
Navigate to `localhost:3001`. You will see the API in action.
|
6
docs/UI/index.md
Normal file
6
docs/UI/index.md
Normal file
@ -0,0 +1,6 @@
|
||||
[Status overview](https://github.com/fosscord/fosscord-ui/projects/2)
|
||||
|
||||
This UI Framework includes all _static_ Fosscord CSS Components.
|
||||
|
||||
## Usage:
|
||||
View the [demo](https://ui.fosscord.com/test) and make use of its [source code](https://github.com/fosscord/fosscord-ui).
|
34
docs/UI/installation.md
Normal file
34
docs/UI/installation.md
Normal file
@ -0,0 +1,34 @@
|
||||
## Requirements
|
||||
You should be familiar with:
|
||||
|
||||
* [Git](https://git-scm.com/)
|
||||
* [NodeJS](https://nodejs.org/)
|
||||
* [SCSS](https://sass-lang.com/) _You could also just write plain CSS. (SCSS just adds some nice features)_
|
||||
|
||||
and the technologies we use for the UI.
|
||||
|
||||
## Getting Started
|
||||
### Step 1
|
||||
Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/fosscord/fosscord-api
|
||||
cd fosscord-api
|
||||
```
|
||||
### Step 2
|
||||
Install (dev) dependencies:
|
||||
```bash
|
||||
npm install
|
||||
npm install --only=dev
|
||||
```
|
||||
### Step 3
|
||||
Compile the SCSS:
|
||||
```
|
||||
npm run scss
|
||||
```
|
||||
### Step 4
|
||||
Open `./test/index.html` for see the test page.
|
||||
|
||||
## Debugging
|
||||
### VS Code
|
||||
The Launch file configuration is in ``./vscode/launch.json``,
|
||||
so you can just debug the server by pressing ``F5`` or the ``> Launch Server`` button
|
19
docs/UI/write_a_component.md
Normal file
19
docs/UI/write_a_component.md
Normal file
@ -0,0 +1,19 @@
|
||||
Every Component should have a demo/test page to see how the Component looks like.
|
||||
|
||||
To create a test page in ``/test/`` copy ``template.html``, save it as a new file ``yourComponentName.html`` and open it in your browser.
|
||||
|
||||
Now create a new file in ``/scss/`` e.g. ``yourComponentName.scss`` and write some (S)CSS.
|
||||
|
||||
To import your scss file edit ``/scss/index.scss`` and add this line:
|
||||
```css
|
||||
@import "yourComponentName.scss";
|
||||
```
|
||||
|
||||
Now start the scss bundler with
|
||||
```
|
||||
npm run scss
|
||||
```
|
||||
|
||||
Also make sure create all sort of various states of your component to see how it looks.
|
||||
|
||||
If you are finished commit and push your changes. _For non-maintainers, create a Pull Request ;)_
|
@ -1,35 +1,19 @@
|
||||
## Issues
|
||||
### Naming convention
|
||||
The issue name must have the main label as a prefix in brackets: e.g. ``[Feature] Test`` or ``[Bug] Test``.
|
||||
## Install the workspace
|
||||
### 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`.
|
||||
|
||||
The first letter of the prefix and the title must be uppercase.
|
||||
#### 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`.
|
||||
|
||||
You are not allowed to use CAPS.
|
||||
### 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`.
|
||||
|
||||
|
||||
## 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/css-mediaquery
|
||||
|
||||
### Setup
|
||||
To setup all repositories clone this repo with submodules enabled:
|
||||
```
|
||||
git clone --recurse-submodules -j8 https://github.com/DiegoMagdaleno/fosscord.git
|
||||
```
|
||||
#### 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`.
|
6
docs/gateway/index.md
Normal file
6
docs/gateway/index.md
Normal file
@ -0,0 +1,6 @@
|
||||
[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.
|
31
docs/gateway/installation.md
Normal file
31
docs/gateway/installation.md
Normal file
@ -0,0 +1,31 @@
|
||||
## Requirements
|
||||
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
|
||||
### Step 1
|
||||
Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/fosscord/fosscord-gateway
|
||||
cd fosscord-gateway
|
||||
```
|
||||
### Step 2
|
||||
Install (dev) dependencies:
|
||||
```bash
|
||||
npm install
|
||||
npm install --only=dev
|
||||
```
|
||||
### Step 3
|
||||
Start:
|
||||
```
|
||||
npm start
|
||||
```
|
||||
## Debugging
|
||||
### VS Code
|
||||
The Launch file configuration is in ``./vscode/launch.json``,
|
||||
so you can just debug the server by pressing ``F5`` or the ``> Launch Server`` button
|
1
docs/gateway/structure.md
Normal file
1
docs/gateway/structure.md
Normal file
@ -0,0 +1 @@
|
||||
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.
|
19
docs/plugins.md
Normal file
19
docs/plugins.md
Normal file
@ -0,0 +1,19 @@
|
||||
## Philosophy
|
||||
- Plugins are executed in their environment to prevent security issues
|
||||
- Plugins can create their own UI and loaded in a separate view _(similar to vscode extensions)_
|
||||
- Plugins can access the component Api and therefore extend the client UI
|
||||
- Plugins can access the WebSocket Connection/Rest API and intercept/transform events
|
||||
- Plugins are restricted and can only do actions with the corresponding permission
|
||||
- Plugins should be accessible through a store that needs to verify the plugins (with dev options to sideload plugins/add other stores)
|
||||
|
||||
## Permissions
|
||||
- Can't access the user's token (token plugins should rather be directly integrated into the client (e.g. account switcher))
|
||||
- All permissions must meet the purpose of the plugin and must justify why they need the certain permission to be approved
|
||||
- Shouldn't be able to make any request, except if it:
|
||||
- Requests permission to access the api of the network
|
||||
- Requests permission to access a specific domain (e.g. plugins backend)
|
||||
- Requests permission to access all domains
|
||||
- Shouldn't be able to intercept events, except if it:
|
||||
- Requests permission to a specific event(s)
|
||||
- Requests permission to all events
|
||||
- Needs to request permission to be able to extend extend the client's UI
|
96
docs/server_util/database.md
Normal file
96
docs/server_util/database.md
Normal file
@ -0,0 +1,96 @@
|
||||
## 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/
|
||||
|
||||
or watch this tutorial: https://youtu.be/WDrU305J1yw
|
||||
|
||||
## Getting Started
|
||||
```ts
|
||||
import mongoose from "mongoose";
|
||||
```
|
||||
and now you can query the database, here are some examples:
|
||||
```ts
|
||||
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:
|
||||
```ts
|
||||
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``
|
||||
```ts
|
||||
import { emitEvent } from "./../../../util/Event";
|
||||
```
|
||||
this will take a the following parameters:
|
||||
```ts
|
||||
{
|
||||
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``:
|
||||
```ts
|
||||
import { GuildDeleteEvent } from "fosscord-server-util";
|
||||
|
||||
emitEvent({...} as GuildDeleteEvent);
|
||||
// or with <> brackets:
|
||||
emitEvent(<GuildDeleteEvent>{...});
|
||||
```
|
||||
|
||||
### Example
|
||||
Putting it all together:
|
||||
```ts
|
||||
await emitEvent({
|
||||
event: "GUILD_DELETE",
|
||||
data: {
|
||||
id: guildID,
|
||||
},
|
||||
guild_id: guildID,
|
||||
} as GuildDeleteEvent);
|
||||
```
|
0
docs/server_util/index.md
Normal file
0
docs/server_util/index.md
Normal file
17
docs/server_util/permissions.md
Normal file
17
docs/server_util/permissions.md
Normal file
@ -0,0 +1,17 @@
|
||||
To get the permission for a guild member import the ``getPermission`` from ``fosscord-server-util``.
|
||||
```ts
|
||||
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.
|
||||
```ts
|
||||
getPermission(user_id: string, guild_id: string, channel_id?: string): Promise<Permissions>;
|
||||
```
|
||||
### Example
|
||||
```ts
|
||||
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")) {
|
||||
...
|
||||
}
|
||||
```
|
28
docs/structure.md
Normal file
28
docs/structure.md
Normal file
@ -0,0 +1,28 @@
|
||||
## 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) 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
|
||||
- [react-native-withcss](https://github.com/fosscord/react-native-withcss)
|
||||
- [css-mediaquery](https://github.com/fosscord/css-mediaquery)
|
Loading…
Reference in New Issue
Block a user