CerberusMVC Documentation


We use the CLI tool (cerberus-cli) to generate a new CerberusMVC project; the CLI creates structure, default files, generates a small example to get you going and allows you to start your API immediately with swagger interactive documentation. Consider using the CerberusCLI to start your new project.

Now Supporting AWS and ExpressJS (with child processes)

CerberusMVC is simply a node MVC stack, that is used to create API's on FaaS backgrounds such as AWS's lambda, Google clouds compute, Azures function services as well as more natural Express JS setups.

Why would it exist? If you have ever worked in serverless or have been involved with large FaaS architectures,you will soon find diversity brings issues. Diversity in developers, coding styles and rules leads to complicated, fragmented and overlapping capabilities, by virtue of the many individual functions generated by all those invloved. This means in simple terms, a mess. the mess is nto intentional, it just happens as naturally as entropy. We end up with many lambdas/computes/functions written all in slightly different ways, some with similar functionality and a loss of abstraction.

Other issues also exist, such as managing a collection of resources on a function based serverless architecture. You gain the strengths of the seperation and modularity but suffer in lost time, developement, repetion and the ability to orchastrate the collection as an entity in itself.

A FaaS serverless MVC stack offers a cure to both. We abstract the modularity with a known methodology, that of a singlualr MVC stack that works in a regimented way. We also solve orchastration through tools to publish the stacks as their tue modular form through the many ways that the providers give us... an example of this would be SAM from AWS and cloudformation.

We simply build as a singluar MVC stack, test, develop, then publish to moduler resources, best of both worlds. Whilst for some providers, we may need to develop as a single function (azure) due to the innability to have a single routing file, all production pushes will generate individual functions and resources form the stack, wiht the MVC framework only pulling in what is needed for that particular route through the stack. AWS, openfass and forked processes all allow for development in as near to production as possible, with seperate endpoint functions, with azure having to develop in a single funciton and build to many on push. As the stack loads controllers on the fly, whilst we may push a full stack to each function, we will only laods the required items for that path through the system due to this on the fly loading. Future release may offer a more streamlined chunking of files to reduce files on each function, this will nto make any difference to memory when in use, just disk space.

CerberusMVC is a FaaS, serverless MVC architecture that is provider agnostic... currently supporting AWS configuration and Express JS forked server configuration for basic VPS's, with the want to open this up to other platforms such as OpenFaaS, Azure. Our aim is to offer a way to build API's and deploy them easily, for many different providers as demand increases.

Want to Know More


Want to know more, see more of CerberusMVC? We are all about MVP, we are happy to expand documentation, add in more support; let us know your thoughts.

Find Me Here

Installation


The recommended method of installation is automated, through use of the cerberus-cli; use the cli to initialise a new project, generate required structure and install cerberus-mvc.

You are however welcome to do this manually, installing cerberus-mvc manually through npm will require the correct folder structure to ensure controllers can be found (see below).

Install the CLI...

npm install -g cerberus-cli

Start a new project at this location...

cerberus-cli init

NPM Script Commands


Several NPM scripts have been pre-set, this allow you to control your stack via the npm run [command] that maps to the script section of package.json. These commands do things like start local servers, run packaging and deployment if required, start document servers and perform tests on your system.

Commands include...

Start server (you can omit run for start command).

npm start

Start server but dont download any images (AWS SAM --skip-pull).

npm run serve

Package your stack for FaaS providers (currently just AWS, requires adjustment).

npm run package

Deploy your stack for FaaS providers (currently just AWS, requires adjustment).

npm run deploy

Start swagger server and return to command promt (uses docker).

npm swagger:up

Stop swagger server and return to command promt (uses docker).

npm swagger:down

Start unit test, uses mocha, supertest to perform endpoint hits (you can omit run for test command).

npm test

Structure


The basic structure is that of MVC, with controllers, models and obviously the views removed (however you could add these for serving things like email templates to email?).

The specific structure is...

  • Controller - The entry point in and the exit path out.
  • Library - Any 3rd party bundled things, or maybe your own stuff.
  • Middleware - Loads in order on in, out or both altering requests or responses.
  • Model - Connection to DB through models, using knexjs.
  • Service - Singleton services isntantiated at creation and accessed throughout.
  • Template - Storage of templates such as emails.

This structure is generated by the cerberus-cli tool when using the init command. in addition a handler template is generated, this is the bridge between your provider and CerberusMVC, the entry point into the stack. As stated above, controllers are lazy loaded, so we only load what we need for that path through the system, othe rcontroller dependencies will not be loaded unles that controller is lazy loaded when routing form your providers routing logic (e.g. AWS API gateway).

The controller start point is furnished with a request property that is passed into the controller. The request is a generic request that is generated form the providers event, that hits function/lambda/compute. the idea here is that we abstract the provider allowing us to write code that is portable to other providers! the exit path out the controller is a geenric response. Once hte repsonse has passed through middleware, the stack will auto convert it back to the required response for the provider. thi sallows us to generate API's we can port to other providers with minimal changes. The idea here is to offer multiplatform FaaS in MVC form to aid development and allow for simple porting.

Inherited Properties


All cerberus-mvc base classes inherit from the Core.js class, which in turn expose 3 properties to help you in your application development; ensure to extend the base classes to inherit this functionality...

  • this.$services - The services loaded into the system as an instantiated singleton.
  • this.$environment - Any environment variables passed into the system (process.env).
  • this.$client - Any client specific information.

In addition to exposed properties, models also gain the raw db object... so it my talk directly to knexjs inside each model

  • this.db - The services loaded into the system as an instantiated singleton.