webserver-framework/README.md

72 lines
3.7 KiB
Markdown
Raw Normal View History

2022-11-06 18:36:13 +01:00
# Navy's webserver framework
2022-11-09 13:56:55 +01:00
A template repository for creating Node.js based webservers with sharding.
2022-11-23 23:05:29 +01:00
Main repository: https://git.corgi.wtf/Navy.gif/webserver-framework
Frontend: https://git.corgi.wtf/Navy.gif/webserver-framework-frontend
2022-11-06 18:36:13 +01:00
2022-11-11 20:34:33 +01:00
## Technologies
- Argon2
- Express
2022-11-12 21:19:27 +01:00
- Passport & related strategies (2FA support)
2022-11-11 20:34:33 +01:00
- MongoDB & MariaDB
2022-11-09 20:43:22 +01:00
## 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`.
2022-11-23 23:05:29 +01:00
(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.
2022-11-24 12:20:26 +01:00
Endpoints have a loadOrder property that can be adjusted, lower values are loaded first.
2022-11-09 20:43:22 +01:00
2022-11-26 14:59:05 +01:00
**Serving files**
2023-02-11 17:01:56 +01:00
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`
2022-11-26 14:59:05 +01:00
2023-04-30 01:49:25 +02:00
## Src directory structure
2023-04-30 01:50:22 +02:00
/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
2023-04-30 01:49:25 +02:00
2022-11-29 11:21:55 +01:00
## TODO
- Dependency injection for structures, such as User.
- Some kind of plugin system
2022-11-06 18:36:13 +01:00
## 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`
2022-11-09 13:56:55 +01:00
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`
2023-02-13 01:08:28 +01:00
Takes care of sessions, authentication and authorisation, relies on an implementation of `UserDatabaseInterface.js`.
2022-11-09 13:56:55 +01:00
**UserDatabase:** `/src/server/components/UserDatabase.js`
2023-02-13 01:08:28 +01:00
Implementation of `UserDatabaseInterface.js`, takes care of user management.