mainmatter / gerust

Gerust [Gerust] provides an architecture and tooling for [Rust] backend projects. It takes care of the accidental complexity that comes with writing backends with Rust so you can stay focused on the essence of the system you're building: • Separating distinct parts of the system into separate crates • Organizing files into a logical folder structure • Maintaining and running database migrations • Isolating test cases that access the database • Tracing and error handling • and much more For now, Gerust is just a project generator that creates the files and structure to get you started. There is no runtime dependency on Gerust – all the code that goes into your project remains under your control. Gerust projects are based on [axum] and use [SQLx] and [PostgreSQL] for data storage (if data storage is used at all). > [!NOTE] > This project has been created by [Mainmatter]. > > Check out our [landing page][Mainmatter] if you're looking for Rust consulting or training! Installation Gerust can be installed with : Creating a new project A new project is created with the command, e.g.: By default, Gerust will generate an empty project with the complete project structure as described below but without any actual entities, controllers, etc. If you're just getting started looking at Gerust, creating a full project, complete with example implementations of all concepts via might be a better starting point: For projects that do not need database access, there is also the option that will generate a project without any of the concepts and structure related to database access – no [ crate], no dependency. Project Structure Gerust uses [Cargo workspaces] to separate distinct parts of the system into separate crates: Let's see what these crates are resonsible for and how they work in detail: The crate The [ crate] contains the main application, providing the web interface of the system. It contains the controllers with the implementations of the exposed endpoints, as well as any middlewares. The crate also contains the application's main executable, which when starting up, will determine the environment the application runs in, load the configuration, initialize the app state, set up tracing and error handling, and bind the server to the configured interface. The crate uses a simple folder structure: Testing Application tests that cover the entire stack of the system including middlewares, controller, as well as database access are maintained in the crate. Testing backends is typically straight forward: request a particular endpoint with a particular method and potentially query string and/or request body and assert the response is what you expect. However, things become more complicated when the server you're testing uses a database. In your tests, you then need to seed the database with test data to establish a well-defined state for the test. You also need to clean up afterwards or better, use isolated database states for the different tests so they don't interfere with each other. There are several mechanisms for that like transactions, cleanup scripts, etc. Gerust uses an approach for test isolation that allows parallel execution of tests without adding a ton of complexity: every test runs in its own database. These test-specific databases are automatically created as copies of the main test database and destroyed after the test has completed. All that is made easily available via the macro: The concept of changesets as well as the database access utilities like , are explained below. The crate The [ crate] only exists for projects that use a database and contains all functionality related to database access from entity definitions, functions for reading and writing data, as well as migrations. Gerust uses SQLx and PostgreSQL without any additional ORM on top. Instead, it defines entities as simple structs along with functions for retrieving and persisting those entities. Validations are implemented via changesets that can get applied to or be converted to entities if they are valid: Database queries are checked for correctness at compile time using [sqlx's compile-time checked queries][sqlx is not an orm]. The crate's folder structure consists of 3 main folders: Test helpers allow to make specific database access functions available only for application tests but not for actual application code. If e.g. the system does not allow for creating new user accounts but tests need to be able to create users, a function could be defined in in the crate. The crate The [ crate] contains the struct that holds all configuration values at runtime as well as code for parsing the configuration based on a hierarchy of TOML files and environment variables. The struct contains fields for the server and database configuration (if the application uses a database) and can be extended freely: The values for the server and database configuration are read from the , , and environment variables. Any application-specific settings are read from _[app.toml]_ as well as environment-specific file, e.g. _[production.toml]_ such that settings in the environment-specific files override those in _app.toml_. The main files and folders in the crate are: The crate The [ crate] contains the binary for running database operations such as executing migrations (this binary only exists for projects that use a database) as well as the binary for generating project files such as entities, controllers, tests, or middlewares. The workspace is configured so that those binaries can be executed with just and : You would typically not have to make any changes to the crate. The crate The [ crate] contains the implementation of the macro. You would typically not have to make any changes to the crate. Testing & CI Projects generated by Gerust come with a complete CI setup for GitHub Actions that includes: • checking the format of all Rust source files • running Clippy on the entire project • running all tests in al…