Dart backend framework

</div> <div align="center">

Languages:

</div>

About Minerva
Ecosystem
Installing
CLI
- Create project
- Build project
- Run project
- Debug
  - VS Code
- Testing
- Docker
Project configuration
Framework structure
- Components
Routing
- Request processing pipeline
- Endpoints
Authentication
- JWT
- Cookie
Middlewares
- Ready-made middlewares
- Custom middlewares
Files
Dependency injection
Agents
- Custom agents
Logging
Configuration manager
Deployment
- Docker container
Road map

About Minerva

Minerva is framework for creating multithreaded REST API.

Minerva provides:

project build system;
multithreaded request processing;
routing requests, processing requests using middlewares;
logging capabilities, creating your own loggers;
provides means for authentication by JWT, cookies;
tools for distributing static files;
working with FormData;
ability to generate Dockerfile;
and another.

Ecosystem

Various packages to simplify working with Minerva, as well as in general that simplify writing server applications on Dart, are likely to be released as separate packages.

Currently existing my packages that may be useful to you:

emerald - JSON serializer/deserializer, based on dart:mirrors, works only with JIT compilation type;
mcache - package for caching values. Supports deleting values after their expiration date;
minerva_mcache - package for integration mcache package in the Minerva framework. Contains tools that allow you to work from different server instances with shared cache located in the agent;
minerva_controller_generator - the package allows you to configure the server using controllers built on code generation.

Installing

Install Dart.

Installing Minerva:

dart pub global activate minerva

Create project with standart template (controllers) and run example:

minerva create -n my_application

cd my_application

dart pub run build_runner build

minerva run

Create project with endpoints template and run example:

minerva create -n my_application -t endpoints

cd my_application

dart pub run build_runner build

minerva run

CLI

The framework contains the CLI utility Minerva, which contains the following commands:

create - creates a project with a standard template;
build - builds the project according to the current parameters set in the appsetting.json file of the project;
clear - clears the project build;
run - starts the project, if there is no project assembly, then pre-starts the assembly;
debug - runs the project with VM services for debugging, the compilation type of the launched assembly should be JIT;
test - starts the server, runs the tests, after the tests completes the server process;
docker - generates Dockerfile.

Create project

To create a project with a standard template, the CLI utility Minerva contains the create command.

The command contains a mandatory parameter name, which specifies the name of the project to be created.

Using the directory parameter you can specify the project creation directory.

Using the debug-compile-type and release-compile-type parameters, you can specify compilation types for debug and release project build types. You can change them at any time in the `appsetting.json' file.

Using the docker-compile-type parameter, you can specify the compilation type for which Dockerfile will be generated. You can generate the Dockerfile again at any time using the docker command.

Build project

Building a project in Minerva assumes the presence of two types of project assembly:

debug - for debugging and project development;
release - for final deployment.

When creating a project, an appsetting.json file is created in its root. This is the main configuration file of the project.

Run project

The project is launched using the run command, as well as by running the executable file in the /build/build type/bin folder (for JIT compilation it is kernel snapshot, and for AOT it is exe file) manually. When developing, it is preferable to run the project using the run command, since it also involves the automatic assembly of the project.

Debug

Debugging is only available using JIT compilation. To run the application in debug mode, use the debug command.

VS Code

To start debugging in the VS Code editor, you must create a launch.json file and specify the program parameter in the configuration. In the program parameter, you specify the path to the executable file. For JIT compilation, Minerva creates a kernel snapshot, it is stored at the path build/build type/bin/main.dill. Example path: build/debug/bin/main.dill.

Testing

Testing is started using the test command. Testing involves starting the server, running all tests, and completing the server process.

When building a project, a file test_app_setting.g.dart is generated in the test folder. It stores the port and address that the server uses during the current build. This is done for convenience, so that when you start tests, you can access the settings relevant to the current project build from the appsetting.json file.

Docker

When creating a project using the create command, a Dockerfile is generated for the given compilation type.

Docker files differ for different types of compilation. There are 2 docker file templates:

JIT;
AOT.

You can re-generate the docker file with the selected compilation type at any time using the docker command. The compilation type is set by the compile-type parameter, by default it is AOT.

When generating the docker file, the assets added to the final build of the project from the appsetting.json file are also taken into account. Therefore, after adding them, you must either generate the Dockerfile again, or edit the Dockerfile manually.

Project configuration

Each Minerva project contains a configuration file appsetting.json. This file contains the settings for the debug and release assemblies of the project, and also allows you to embed values and arbitrary files into the final assembly of the project.

The appsetting.json file contains the debug and release fields, which contain configuration details of the corresponding project assemblies.

In them you can configure:

host - the address where the server is started. By default, for debug it is 127.0.0.1, and for release it is 0.0.0.0;
port - the port on which the server is started. By default, for debug it is 5000, and for release it is 8080;
compile-type - the type of compilation of the project. Can be either JIT or AOT;
values - values embedded in the assembly. You can access them using configuration manager;
logging - logging configuration. You can read more about it here.

Also, appsetting.json can contain general settings for all types of project builds:

values - values embedded in the assembly. You can access them using configuration manager;
assets - by specifying assets, you can embed arbitrary files into the project assembly. The path to them is set relative to the project folder.

Example of specifying a list of assets:

"aseets": [
  "/wwwroot",
  "some_file.txt"
]

Framework structure

The Minerva structure was created taking into account the possibility of processing requests in many isolates, to improve performance. Multithreaded request processing is implemented by running a server instance in multiple isolates, using the shared parameter of class HttpServer from dart:io library.

The server structure can be represented as follows:

Using the instance parameter of the MinervaSetting class, you can set the number of isolates in which server instances will be started

Minerva

Install / Use

README