DOCSEARCHbyAlgolia
Submit Docs

Pavex Documentation

repository·main·Indexed 24 days ago

https://github.com/lukemathwalker/pavex

A high-performance, ergonomic backend framework for building APIs in Rust. Pavex bridges the gap between developer productivity and runtime speed using code generation. The framework requires the cargo-px wrapper to automatically regenerate the server_sdk crate when application blueprints change. Documentation includes guides on using cargo-px for building, running, and testing, as well as tools like pxh for extracting source code snippets and md-slash for Markdown processing.

Tokens
108.4K
Snippets
363
Records
737
Agent score
81%

What's inside Pavex

  1. What is Pavex?

    main
    Pavex is a Rust framework designed for building APIs. It aims to combine the high productivity and ergonomics found in frameworks like Ruby on Rails, Spring, or ASP.NET Core with the high performance of a handwritten, low-abstraction Rust solution. For a thorough introduction to the framework and its design philosophy, refer to the official Pavex documentation.

  5. Core value propositions of Pavex

    main

    Pavex is designed to be a production-ready API framework for Rust that balances ease of use with high safety and flexibility. Its core design principles include:

    • Batteries included: Provides first-class solutions for common API tasks like authentication, background jobs, and telemetry, or offers opinionated recommendations for high-quality third-party libraries with smooth integration.
    • Productive: Lowers the barrier to entry by requiring only a basic understanding of Rust core concepts. It uses a transpiler to provide detailed, actionable error messages when configuration or dependency issues arise.
    • Safe: Performs domain-specific static analysis on top of standard Rust compiler checks. The Pavex transpiler catches errors at compile-time to ensure runtime behavior matches expectations without increasing type complexity.
    • Flexible: While opinionated, the framework allows you to swap out any component with your own implementation or a third-party library to meet specific environment or enterprise requirements.

  6. Identify sources of injectable dependencies

    main

    Pavex dependencies can originate from four primary sources. Depending on your needs, you should use one of the following:

    1. Framework primitives: Core types provided by the Pavex framework itself.
    2. Constructors: Logic used to extract or compute specific data (often used for request data).
    3. Configuration: Values and objects provided via the application's configuration.
    4. Prebuilt types: Standard types provided by Pavex for common use cases.

  8. What is an error handler and how does it work?

    main

    An error handler is a function responsible for converting a reference to an error type into a Response.

    Error handlers provide a decoupling mechanism:

    • Constructors only need to signal that an error occurred by returning a Result.
    • Error Handlers determine how that error is represented on the wire (e.g., HTTP status codes, JSON error bodies).

    This allows you to change the API's error representation without modifying the business logic in your constructors. Error handlers can also leverage Pavex's dependency injection system, allowing them to inspect request headers (like Accept) to decide how to format the error response.

  9. Understand the limitations of framework primitives

    main

    While convenient, framework primitives are inflexible. Because they are managed internally by the framework, you cannot customize how they are constructed.

    If you need to change the construction logic for a specific type (for example, changing the JSON deserializer used to produce a JsonBody<T> instance), you should not rely on a framework primitive. Instead, you should define and register your own component to provide that type, ensuring you maintain control over its implementation.

  10. How `pxh` embedded snippets work

    main

    The pxh tool ensures documentation code snippets remain accurate by extracting them directly from source code.

    Workflow:

    1. Create an example project by placing an example.yml file in a folder.
    2. pxh scans the folder for embedded code snippets defined via special comments.
    3. Snippets are extracted and stored in .snap files named after the snippet, located next to the example.yml file.
    4. The documentation (e.g., on pavex.dev) imports these .snap files using the pymdown.snippets plugin.

  11. How dependency injection works in Pavex

    main

    In Pavex, you do not manually wire components together. Instead, components like request handlers, middlewares, and error handlers declare their requirements via their input parameters. These input parameters are called dependencies.

    Pavex's dependency injection framework automatically handles the building and injecting of these dependencies at the appropriate time and location. This allows you to decouple the logic of how data is computed from the logic of how that data is used.

  12. Use Pavex framework primitives in components

    main

    Pavex provides several framework primitives that are automatically available as input parameters to your components. You do not need to register a constructor for these types or mark them as prebuilt; the framework handles their injection automatically.

    Available framework primitives:

    • RequestHead: The incoming request data, excluding the body.
    • RawIncomingBody: The raw body of the incoming request.
    • RawPathParams: The raw path parameters extracted from the incoming request.
    • AllowedMethods: The HTTP methods allowed for the current request path.
    • ConnectionInfo: The peer address for the current connection.