DOCSEARCHbyAlgolia
Submit Docs

mORMot2 Framework Documentation

repository·master·Indexed 20 days ago

https://github.com/synopse/mormot2

Reference implementation and Software Architecture Design (SAD) guide for the mORMot2 framework. It demonstrates recommended patterns including CQRS (Command Query Responsibility Segregation), DDD (Domain-Driven Design), and SOA (Service Oriented Architecture). The documentation covers architecture principles, implementation patterns, and a variety of samples ranging from high-performance HTTP benchmarking and TechEmpower benchmarks to Clean Architecture (Onion Architecture) and TDD-driven services.

Tokens
311.9K
Snippets
760
Records
1.2K
Agent score
71%

What's inside mORMot2

  1. Overview of mORMot 2 Recommended Patterns

    master

    mORMot 2 is a highly flexible framework. To avoid decision fatigue, developers should follow the 'Default Toolbox' patterns. These patterns provide a set of recommended types, classes, and configurations that serve as firm defaults for almost any project.

    The documentation is structured into two main approaches:

    1. Part A — The Default Toolbox: Framework-universal recommendations. These are the types and configurations you should reach for by default unless you have a specific reason to deviate.
    2. Part B — A Possible Application Blueprint: A specific, proven way to structure a service. This is a coherent starting point for new services rather than a strict framework rule.

    For quick reference, developers should prioritize the cheat-sheet tables found in sections A.1 (The one-screen cheat sheet) and A.2 (Recommended type at each layer).

  2. Overview of the File Upload Sample

    master

    The 18-file_upload sample is a functional demonstration of file upload capabilities ported from the DMVCFramework to mORMot2. It serves as a reference for implementing custom HTTP request handling, multipart form data parsing, and file I/O with validation.

    Key capabilities demonstrated include:

    • Multipart Form Data Parsing: Handling complex HTTP requests containing files.
    • REST API Services: Programmatic access to file operations via REST.
    • Static File Serving: Serving files back to the client.
    • Dynamic HTML Generation: Creating web interfaces on the fly.
    • Security: Basic protections for file uploads.
    • Logging: Integration with mORMot2 logging systems.

  3. Overview of mORMot 2 features and architecture

    master

    mORMot 2 is an Open Source Client-Server framework for Delphi and Free Pascal. It provides a complete suite for building modern software using ORM (Object-Relational Mapping), SOA (Service-Oriented Architecture), and Web MVC patterns.

    Core Capabilities

    • ORM/ODM: Object persistence for SQL (SQLite3, PostgreSQL, MySQL, MS SQL, Oracle, etc.) and NoSQL (MongoDB, In-Memory, Files) databases.
    • SOA: Organize business logic into RESTful JSON services using method-based or interface-based designs.
    • Web MVC: Build responsive web applications using Controller classes and Mustache templates.
    • Clients: Consume services via ORM classes, SOA interfaces, or standard HTTP/AJAX clients.

    Architecture Model

    The framework supports both Client-Server (remote access via JSON/REST over HTTP/HTTPS) and Stand-Alone (direct in-process access) modes. Switching between these modes is determined by how mORMot classes are initialized at runtime.

  4. Overview of mORMot Scripting Units

    master

    mORMot Scripting Units provide a modern way to embed scripting capabilities into your applications, allowing for user-defined workflows in both the client and server layers. The framework is designed to be engine-agnostic, allowing you to choose the appropriate interpreter for your specific needs (e.g., lightweight client-side execution vs. high-performance server-side JIT).

    Supported or planned engines include:

    • QuickJS: A small, standalone, and complete JavaScript interpreter, ideal for client-side execution.
    • SpiderMonkey: (Planned) A high-performance JavaScript interpreter and JIT, suitable for high-end production services.

  5. Overview of mORMot SOA Units

    master

    The mormot.soa.* units are organized into four functional areas:

    • mormot.soa.core: Contains the shared SOA process logic, including service logging (TOrmServiceLog), notifications (TOrmServiceNotifications), service factories (TServiceFactory), and the services catalog (TServicesPublishedInterfacesList).
    • mormot.soa.client: Provides client-side implementation tools such as TServiceFactoryClient and TServiceContainerClient to consume services.
    • mormot.soa.server: Provides server-side implementation tools including the base class for service implementations (TInjectableObjectRest), service providers (TServiceFactoryServer), and asynchronous REST synchronization classes.
    • mormot.soa.codegen: Tools for generating API code and documentation. It uses RTTI to extract ORM and SOA logic and can generate code/docs via command-line or server-side wrappers.

  6. Overview of libdeflate

    master

    libdeflate is a highly optimized library for fast, whole-buffer DEFLATE-based compression and decompression. It is designed to be significantly faster than zlib, especially on x86 processors, and offers high compression modes that exceed zlib's level 9 ratio.

    Supported formats:

    • DEFLATE (raw): Raw compressed stream without wrappers.
    • zlib: DEFLATE with a zlib wrapper (includes checksums).
    • gzip: DEFLATE with a gzip wrapper (includes checksums and optional metadata like filenames).

    Note on Streaming: libdeflate does not support streaming. It is designed for chunk-based compression (e.g., data chunks < 1 MB). It is not suitable for compressing large files as a single continuous stream.

  7. Overview of Angelize (agl) Cross-Platform Services Manager

    master

    Angelize (also known as agl) is a cross-platform service manager designed to manage one or several services, whether they are hosted as Windows Services or POSIX Daemons. It functions similarly to NSSM but provides a wider feature set for managing microservices and sub-processes across different operating systems.

    Key capabilities include:

    • Process Monitoring: Automatically restarts managed sub-processes upon failure with increasing pauses (exponential backoff).
    • Dependency Management: Starts sub-processes in levels (rings of dependencies).
    • Cross-Platform: Supports Windows and POSIX (Linux/Unix) environments.
    • Flexible Sub-processes: Can manage other Windows Services, regular executables, or unmanaged executables.
    • Configuration: Uses JSON UTF-8 files for all settings, avoiding reliance on the Windows registry.
    • Observability: Provides status via command-line /list or a locally generated static HTML file, and maintains detailed text logs for forensics.

  8. Overview of mORMot Network Communication Layer

    master
    The mORMot Network Communication Layer provides a comprehensive suite of units for client/server communication. It supports various protocols including Sockets, HTTP/HTTPS, WebSockets, and specialized protocols like SMTP, LDAP, DNS, and TFTP. The layer is designed to be cross-platform and includes support for high-performance, event-driven asynchronous processing.

  9. Overview of mORMot Core Units

    master

    The mORMot Core Units provide the foundational, uncoupled, and reusable building blocks for the mORMot framework. These units implement low-level shared functionality that higher-level features (such as ORM, SOA, or database access) are built upon.

    Key characteristics include:

    • Reusable Bricks: Specialized units for processing files, text, JSON, compression, encryption, networking, and RTTI (often with optimized assembly).
    • Cross-Platform & Cross-Compiler: Designed to ensure identical behavior when compiled on both Free Pascal Compiler (FPC) and Delphi across any supported platform, regardless of the underlying RTL, Operating System, or CPU.

  10. Understand the mORMot 2 source code structure

    master

    The mORMot 2 source code is organized into specialized sub-folders based on functionality. Use these directories to locate the specific components you need for your application:

    • core: Low-level shared components (text, RTTI, JSON, compression).
    • lib: External third-party libraries (e.g., zlib, openssl).
    • crypt: Symmetric and asymmetric cryptography.
    • net: Client/server communication layer.
    • db: SQLite3 kernel and SQL/NoSQL direct access.
    • rest: RESTful client/server processing.
    • orm: High-level Object-Relational Mapping (ORM) features.
    • soa: High-level Service-Oriented Architecture (SOA) features.
    • app: Hosting for (micro)services, daemons, and applications.
    • ui: VCL/LCL User Interface components.
    • script: Supported (java)script engines.
    • ddd: Domain-Driven-Design related code.
    • misc: Miscellaneous reusable units.
    • tools: Framework-specific utility tools.

  11. mORMot2 DMVC Sample Collection Overview

    master

    This collection provides 20 functional samples ported from DelphiMVCFramework to mORMot2. It is designed to demonstrate REST API development patterns, framework equivalence, and advanced features like security, middleware, and real-time communication.

    Core Capabilities Demonstrated:

    • REST APIs: Routing, CRUD, and basic endpoints.
    • Rendering: JSON, HTML, binary, and dataset serialization.
    • Security: HTTP Basic Auth, Custom Auth, and JWT Tokens.
    • Advanced: SSL/TLS (HTTPS), Middleware (CORS, compression, rate limiting), Real-time (SSE, WebSockets), and File Handling (Multipart forms).
    • Error Handling: Custom exceptions and global handlers.

  12. Explore mORMot2 DMVC Samples

    master
    The ex/ThirdPartyDemos/dmvc-ai/ directory contains a catalog of 22 samples demonstrating how to use mORMot2 with DMVC (Delphi MVC Framework) patterns. These samples range from beginner-level basic REST servers to advanced master-detail ORM implementations. They are categorized into Core Features, Security, Advanced Features, and VCL Clients.