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

• 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
  • 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

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.