Architecture Concepts

Request Lifecycle

Introduction#

You can build a Marmeon app without knowing what happens between a browser's request and your controller. Knowing it helps when something does not behave as you expect: why a guest is sent to the sign-in page before a 404, why a form's controller never runs when its input is wrong, or why a page shows its HTML before its data. This page follows a request from the moment the app starts to the moment the browser shows the page.

In short: the app boots once per process. Then each request passes the global middleware, its route's middleware group and its own middleware, its bound parameters, its authorization and its validation, and only then reaches the controller. The controller's answer becomes a whole HTML document on a first visit, and the page's data as JSON when the browser is already running the app:

request → global middleware → group middleware → route middleware → bindings → authorize → validate → controller → response

Starting the app#

Before the first request, marmeon start or marmeon dev prepares the process once:

1. The environment. marmeon decides NODE_ENV: the process's own, else the one in .env, else the command's default. See configuration.
2. The loader hook. It adds the injection lists to your classes as Node loads them. In production it takes them from marmeon build instead of reading every file.
3. The packages. The app reads the list of installed packages, .marmeon/manifest.json, and with it their service providers. The list is written again by itself when the dependencies change.
4. The configuration. Every config definition of the app, its modules and its packages is checked at once. A missing or wrong variable stops the start here.
5. Register. Every service provider binds its services: the packages' first, then the app's, then each module's in the order of modules. The HTTP package loads each module's routes in this phase.
6. Boot. Once every provider has registered, every provider boots, in the same order. The middleware groups are completed here.
7. Listen. The server builds its kernel from the routes and listens. The start line names the environment and the number of routes and modules.

Steps 3 to 6 are createApplication(), the same function every test calls through createTestApp(). The service providers page explains the two phases, and the modules page the definition they read.

A request on the server#

A request then passes these stages, in this order:

An exception thrown at any stage goes to the app's exception handler, which turns it into the right error response: a page for a browser, JSON for everyone else.

The order explains several rules of the framework. Bindings run after the middleware, so a guest is sent to the sign-in page before a 404 could tell them which notes exist. Authorization and validation run before the controller is even built, so a controller never sees input that failed its schema. And because each request has its own scope, a service that holds the signed-in user can never leak into another request.

The web group#

A route of a module's routes file passes the web group. Its middleware runs in a fixed order, whatever order the packages registered it in. Each package adds its part when the app has it installed, and this is the list of a new app:

The api group has no middleware of its own: no cookies and no session. pnpm marmeon route:list shows the exact list of every route. The middleware page explains the groups.

From the controller to the browser#

A controller that answers with a page names a view and hands it its props:

import type { Authenticated } from '@marmeon/auth';
import { Controller, type HttpContext } from '@marmeon/http';

export class ListNotesController extends Controller {
  handle(ctx: HttpContext<Authenticated>) {
    return this.view('notes/ListNotes', { author: ctx.user.name });
  }
}

What the server sends depends on who asks.

The first visit#

When the browser asks for the page itself, the server answers with a whole HTML document:

1. The server renders the page component, modules/notes/views/ListNotes.tsx, with its props into index.html. The page streams: the first part goes out as soon as it is ready, and parts that wait for data follow in the same response.
2. The document carries the page as data next to the markup: the component's name, its props and the URL.
3. In the browser, bootstrap/client.tsx reads that data, loads the page's component and the texts of its language, and hydrates the markup. From now on the browser runs the app.

A search engine or a link preview gets the whole page at once, without streaming.

Every visit after it#

A click on a <Link> or a form sent with <Form> does not load a new document. The browser asks for the same URL with the header x-marmeon: true, and the server answers with the page as JSON: the component's name, its props and the URL. The browser loads the component when it does not have it yet, swaps the page and writes the history entry. The history entry holds the URL and the scroll position, never the page's data: Back and Forward take the page from memory or ask the server again.

When the server runs a newer build than the tab, it answers 409 with the URL instead, and the browser loads that URL as a whole document. A visit never mixes an old browser bundle with a new server.

Parts that load on their own#

A page can hand some of its props over later. Deferred props are computed after the page's first part and streamed into the same response, or fetched by the browser right after the page. An island is a part of the page with a route of its own, and a layer is a page that opens above another one, such as a dialog. Each of them is a request through the same stages as above. The deferred props and dialogs pages explain them.

Requests that only read#

Some requests may read the session but never change it: an island's request, a live check of a form field, a request for an upload's target or bytes, the live stream of a page, the tabs' question for the session's state, a layer's base page loaded for a deep link, and the work that still runs after a streamed page's headers went out. They write no session, set no cookie and defer no work. A write there throws in development and in tests, so the mistake shows where it is made. Everywhere else it is dropped and logged.

Jobs, tasks and commands#

Not every unit of work is a request. A queue worker runs each attempt of a job in a container scope of its own, the scheduler each task, and the marmeon command each command. Each of these processes boots the same app with the same providers. The context page shows how code finds out which unit of work it runs in.

Stopping#

On SIGTERM, the server leaves readiness, answers for SHUTDOWN_DELAY seconds, finishes the requests in flight and the work after them, and then shuts the app down: every provider's shutdown() runs, in reverse order, and closes its pools and connections. The deployment page explains the stages.