feat: Turn configuration into a first-class concept for Pavex

Author: LukeMathWalker

.github/workflows/docs.yml

@@ -977,14 +977,7 @@ jobs:
     - name: Build API reference
       run: |
         cd libs
-        cargo doc \
-            --all-features \
-            --package pavex \
-            --package pavex_cli_client \
-            --package pavex_session \
-            --package pavex_session_sqlx \
-            --package pavex_session_memory_store \
-            --no-deps
+        cargo api_ref
     - name: Copy API reference files
       run: |
         mkdir -p docs/api_reference
@@ -1001,7 +994,7 @@ jobs:
         tags: pavex-docs
     - name: Build docs
       run: |
-        docker run --rm -v ${PWD}:/docs pavex-docs build
+        docker run --rm -v ${PWD}:/docs pavex-docs build --strict
     - uses: actions/upload-artifact@v4
       with:
         name: docs
@@ -1025,6 +1018,7 @@ jobs:
           --exclude-path="site/api_reference/pavex/time"
           --exclude-path="site/api_reference/help.html"
           --exclude-path="site/api_reference/settings.html"
+          --exclude=".*crate#per-style$"
           --exclude="https://doc.rust-lang.org/*"
           --exclude="https://stackoverflow.com/*"
           --exclude="https://github.com/LukeMathWalker/pavex/edit/main/*"

.gitignore

@@ -20,3 +20,4 @@
 trace-*.json
 /docs/api_reference/
 .direnv/
+site

CHANGELOG.md

@@ -12,19 +12,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### ‼️ Breaking changes
 
 - Finalize the API for `pavex_session`, the HTTP session implementation for Pavex.
-  
+
   The previous API gave equal standing to client-side and server-side state manipulation,
   while the latter is to be preferred and likely to be more widely used.
   This change moves all server-related method to appear directly on the `Session`
   type, while client-side method remain on dedicated accessors.
   Capabilities are unchanged, but the user-experience should be more pleasant.
 
 ### 📚 Documentation
+
 - Add [a guide on HTTP sessions](https://pavex.dev/docs/guide/sessions/) to pavex.dev (by @LukeMathWalker) - #463
 
 ### Contributors
 
-* @LukeMathWalker
+- @LukeMathWalker
 
 ## [0.1.77](https://github.com/LukeMathWalker/pavex/compare/0.1.76...0.1.77) - 2025-02-26
 

ci_utils/templates/job_steps/build_docs.jinja

@@ -7,14 +7,7 @@
 - name: Build API reference
   run: |
     cd libs
-    cargo doc \
-        --all-features \
-        --package pavex \
-        --package pavex_cli_client \
-        --package pavex_session \
-        --package pavex_session_sqlx \
-        --package pavex_session_memory_store \
-        --no-deps
+    cargo api_ref
 - name: Copy API reference files
   run: |
     mkdir -p docs/api_reference
@@ -31,7 +24,7 @@
     tags: pavex-docs
 - name: Build docs
   run: |
-    docker run --rm -v ${PWD}:/docs pavex-docs build
+    docker run --rm -v ${PWD}:/docs pavex-docs build --strict
 - uses: actions/upload-artifact@v4
   with:
     name: docs
@@ -55,6 +48,7 @@
       --exclude-path="site/api_reference/pavex/time"
       --exclude-path="site/api_reference/help.html"
       --exclude-path="site/api_reference/settings.html"
+      --exclude=".*crate#per-style$"
       --exclude="https://doc.rust-lang.org/*"
       --exclude="https://stackoverflow.com/*"
       --exclude="https://github.com/LukeMathWalker/pavex/edit/main/*"

doc_examples/guide/configuration/01-build_state.snap

@@ -0,0 +1,7 @@
+```rust title="server_sdk/src/lib.rs"
+// [...]
+pub struct ApplicationConfig {
+    pub database: configuration::base::DatabaseConfig,
+    pub server: configuration::server::ServerConfig,
+}
+```

doc_examples/guide/configuration/01.patch

@@ -0,0 +1,12 @@
+```rust title="src/base/config.rs" hl_lines="3"
+use secrecy::Secret;
+
+#[derive(serde::Deserialize, Debug, Clone)]
+pub struct DatabaseConfig {
+    pub username: String,
+    pub password: Secret<String>,
+    pub host: String,
+    pub database_name: String,
+    pub require_ssl: bool,
+}
+```

doc_examples/guide/configuration/project-derives.snap

@@ -0,0 +1,24 @@
+```rust title="src/postgres.rs"
+use secrecy::Secret;
+
+#[derive(serde::Deserialize, Debug, Clone)]
+pub struct PostgresConfig {
+    pub pool: PoolConfig,
+    pub connection: ConnectionConfig,
+}
+
+#[derive(serde::Deserialize, Debug, Clone)]
+pub struct ConnectionConfig {
+    pub username: String,
+    pub password: Secret<String>,
+    pub host: String,
+    pub database_name: String,
+    pub require_ssl: bool,
+}
+
+#[derive(serde::Deserialize, Debug, Clone)]
+pub struct PoolConfig {
+    pub min_size: u32,
+    pub max_size: u32,
+}
+```

doc_examples/guide/configuration/project-nested_def.snap

@@ -0,0 +1,4 @@
+```rust title="src/postgres.rs"
+    // [...]
+    bp.config("postgres", t!(self::PostgresConfig));
+```

doc_examples/guide/configuration/project-nested_reg.snap

@@ -0,0 +1,11 @@
+```rust title="src/base/profile.rs"
+pub use pavex::config::ConfigProfile;
+
+#[derive(ConfigProfile)] // (1)!
+pub enum Profile {
+    #[pavex(profile = "dev")]
+    Development,
+    #[pavex(profile = "prod")]
+    Production,
+}
+```