Built-in Web Server

The first thing we must be aware is that Kalgan is not only a web framework but also incorporates a multithreaded web server which can handle concurrent connections simultaneously. The number of threads (workers) that the server contains defines the number of requests that our server can handle in parallel.

Server Internals

The server is based on the Multithreaded Web Server fully documented in Rust Book.

The server is made up by the following components, which for security reasons are private and won't be accessible from the app:

The flowchart below represents the startup sequence of the server:

After the startup the std::net::TcpListener keeps open waiting for the requests that come from the internet, which are finally passed to kalgan/src/handler/resolver.rs.

Server Configuration

As we have just seeen, there are a few settings parameters we must set to make the server works.

Our file settings.yaml should look at follows:

server:
    address: 127.0.0.1
    port: 7878
    number_of_workers: 10
...

Notice that these parameters are read by the server for the startup. Therefore, these are the only settings parameters which are not reload with every request while developing.

Request / Response

It is responsibility of the framework to manage the request which comes from the server and the response back to it. For this purpose it parses the request and creates the struct kalgan::http::request::Request which is passed to the application. In a reverse way, it transforms the struct kalgan::http::response::Response which comes from the application and pass a response to the server.

The below flowchart pictures this behaviour and shows how the server, the framework and the app communicate with each other:

Struct Request

As we said before, it is the kalgan/src/handler/resolver.rs who receives the request ( std::net::TcpStream ) from the server. It creates the kalgan::http::request::Request and sends it to the application handler.

Find the definition of the struct in the code below:

...
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct Request<'a> {
    method: String,
    uri: String,
    protocol: String,
    cookies: HashMap<String, String>,
    host: String,
    user_agent: String,
    input: HashMap<String, String>,
    referer: String,
    #[serde(borrow)]
    files: HashMap<String, File<'a>>,
    raw: String,
    pub middleware: HashMap<String, String>,
    pub route: Option<Route>,
}
...

Notice that all the fields are private but Request.middleware and Request.route. This is because both fields are not part of the request, as they depend on the app route configuration, and are defined after the struct is created.

For more information regarding routing system go to Routing / URLs.

From a logical point of view, Request.middleware and Request.route shouldn't be included in the Request but we'll find they are extremely useful and save a lot of boilerplate. Regarding the private fields, these cannot not be altered and we'll have to use the methods commonly known as getters to get their value (for example Request.get_uri() ) .

Let take a look at these fields:

Struct Response

The kalgan/src/handler/resolver.rs is responsible as well of giving back a response to the server. It receives the kalgan::http::response::Response from the application handler, converts it into a Vec<u8> and finally sends it to the server.

Find the definition of the struct in the code below:

...
#[derive(Debug, Clone)]
pub struct Response {
    status: String,
    content_type: String,
    location: String,
    cookies: Vec,
    content: String,
    content_length: String,
}
...

Notice that all fields are private, we don't need to access to their value as this is information is just for the server. However we are responsible of setting these values, for which we'll have to use the methods commonly known as setters (for example Response.set_status() ).

Let take a look at these fields:

Regarding the status code, these are the only codes which are currently supported:

MVC Pattern

Kalgan is an MVC framework, which means it's divided in 3 main logical layers: model, view and controller. This is probably one of the most common design patterns (architectural pattern) when building user interfaces. MVC separates the business logic (model) and presentation layer (view) from each other.

The below flowchart represents this design:

Let's take just a brief look at these layers. So much has been written about MVC pattern and a deeper approach is out of the scope of this documentation.

Model Layer

The model component stores the application data and related business logic. It only communicates with the controller or other model components. It's commonly related to the database entities but not necessarily as not all entitites can (or need) be mapped to a database.

For more information regarding models and database management go to Database / SQLx in the docs.

View Layer

This is the component that renders the UI using the data passed from the controller. In web applications this is mainly reated to HTML views but this is not the only option (think in a JSON response for a web service or XML for feeds, for example).

For more information regarding view templates go to Templates / Tera in the docs.

Controller Layer

The controller is the only layer which communicates with the other two. First it receives the request from the server (user). Then it calls the model to retrieve the data and the view to retrieve the data representation. Finally it gives back the response to the user.

For more information regarding controllers go to Handlers in the docs.

Services

Kalgan comes with a few built-in services which might help with some of most common tasks in web development. These services are located under kalgan/src/service/.

Features

Kalgan offers some feature flags to reduce the amount of compiled code. Somehow Kalgan could be considered as a microframework out of the box as most of its components are optional. We must be aware that Kalgan doesn't enable any of them by default.

Find below the list of the available feature flags:

Notice that the only component that is not optional is the Routing System.

Kalgan Crates

Kalgan depends on several external crates. It also depends on a few internal crates, which were created specifically for the framework. However this crates are decoupled from the framework and can be used outside Kalgan.

These crates are: