74 lines
3.7 KiB
Markdown
74 lines
3.7 KiB
Markdown
# 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. |