webserver-framework/README.md

# Navy's webserver framework
A template repository for creating Node.js based webservers with sharding.  
Main repository: https://git.corgi.wtf/Navy.gif/webserver-framework  
Frontend: https://git.corgi.wtf/Navy.gif/webserver-framework-frontend  

## Technologies
- Argon2
- Express
- Passport & related strategies (2FA support)
- MongoDB & MariaDB

## How to
Using the template
- Clone the repository `git clone https://git.corgi.wtf/Navy.gif/webserver-framework <project name>`  
- Change the original remote name to `git remote rename origin upstream`.  
- Disable pushing to the upstream remote `git remote set-url --push upstream no_push`.  
- Add your own remote `git remote add <remote name> <repository url>`

Fetching the upstream changes
- Fetch the the remotes `git fetch`.  
- Preview the changes `git log -p HEAD..upstream/master`
- Merge changes to the current branch `git merge upstream/master`.  
(Use `git remote -v` to list remotes)  

**OAuth callbacks**  
By default any OAuth callbacks are expected at `/api/login/<methodname>`, where methodname is the name of the OAuth strategy. E.g. by default this framework has a discord strategy defined in Server.addAuthStrategies which expects a callback to `/api/login/discord`.  

**Endpoints**  
Any all endpoints should go in the `/endpoints` directory and are expected to inherit from the Endpoint superclass.  
Endpoints have a loadOrder property that can be adjusted, lower values are loaded first.  

**Serving files**
By default the framework looks for files to serve under the `/files` directory, it also tries to satisfy requests to `/` with an `index.html` from `/files/build`. This is with the frontend in mind.  

To easily serve a frontend I typically use a symbolic link between the built frontend files and the `files/build` directory.  
E.g.  
Linux: `ln -s /path/to/frontend/build /path/to/backend/files/build`  
Windows (admin cmd) `mklink /D C:\Path\To\Backend\files\build C:\Path\To\Frontend\build`  

## Src directory structure  
<pre>
/controller: Main controller, takes care of sharding and the shard life-cycles. Also instantiates the master process  
    /commands: Commands you can issue to the controller  
/server: Code running on the shards, most of the functionality lives here  
    /components: Base components the server uses  
    /database: Various database extensions, database interactions are primarily handled by [these wrappers](https://git.corgi.wtf/Navy.gif/wrappers)  
    /endpoints: Endpoint functionality, can be organised into subfolders, or not  
    /interfaces: Various interfaces and parent classes  
    /middleware: Middleware functions and classes for express  
    /structures: Abstractions for various API entities, e.g. user & role  
/util: Shared utility functionality & misc stuff  
    /errors: Error classes  
</pre>

## TODO  
- Dependency injection for structures, such as User.
- Some kind of plugin system

## Main components
**Controller:** `/src/controller/Controller.js`  
Master process, orchestrates the whole program. Takes care of starting up the shards and communication with them.  

**Shard.js:** `/src/controller/Shard.js`  
Manages the forked processes. Essentially a wrapper for ChildProcess.

**Server.js:** `/src/server/Server.js`  
Main component that runs on the forked processes. Expects a message with a `_start` property with the startup options to be sent.

## "Lesser" components
**Authenticator:** `/src/server/middleware/Authenticator.js`  
Takes care of sessions, authentication and authorisation, relies on an implementation of `UserDatabaseInterface.js`.  

**UserDatabase:** `/src/server/components/UserDatabase.js`  
Implementation of `UserDatabaseInterface.js`, takes care of user management.