Add cookie documentation to Pavex's guide (LukeMathWalker#236)

Misc: I restructured the guide to use navigation sections since the left
sidebar was getting busy.

.github/workflows/docs.yml

@@ -289,10 +289,10 @@ jobs:
             --exclude-path="site/api_reference/help.html" 
             --exclude-path="site/api_reference/settings.html" 
             --exclude="https://doc.rust-lang.org/*" 
+            --exclude="https://github.com/LukeMathWalker/pavex/edit/main/*"
             --exclude="https://docs.rs/**/*" 
             --exclude-path="site/api_reference/static.files" 
             --exclude="https://fonts.gstatic.com" 
             --require-https 
-            --verbose 
             --no-progress 
             site

doc_examples/.gitignore

@@ -1 +1,2 @@
-!*.snap
+!*.snap
+tutorial_envs

doc_examples/guide/cookies/installation/project-kit.snap

@@ -0,0 +1,10 @@
+```rust title="src/blueprint.rs" hl_lines="6"
+use pavex::blueprint::Blueprint;
+use pavex::cookie::CookieKit;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    CookieKit::new().register(&mut bp);
+    // [...]
+}
+```

doc_examples/guide/cookies/installation/project/.gitignore

@@ -0,0 +1,2 @@
+/target
+Cargo.lock

doc_examples/guide/cookies/installation/project/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "cookie_installation"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { path = "../../../../../libs/pavex" }
+pavex_cli_client = { path = "../../../../../libs/pavex_cli_client" }
+serde = { version = "1", features = ["derive"] }
+cargo_px_env = "0.1"
+tokio = { version = "1.35.1", features = ["time"] }
+
+[workspace]
+members = [".", "server_sdk"]

doc_examples/guide/cookies/installation/project/server_sdk/Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "cookie_installation_server_sdk"
+version = "0.1.0"
+edition = "2021"
+
+[package.metadata.px.generate]
+generator_type = "cargo_workspace_binary"
+generator_name = "cookie_installation"

doc_examples/guide/cookies/installation/project/server_sdk/src/lib.rs

@@ -0,0 +1 @@
+

doc_examples/guide/cookies/installation/project/src/blueprint.rs

@@ -0,0 +1,8 @@
+use pavex::blueprint::Blueprint;
+use pavex::cookie::CookieKit;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    CookieKit::new().register(&mut bp);
+    bp
+}

doc_examples/guide/cookies/installation/project/src/lib.rs

@@ -0,0 +1,5 @@
+#![allow(dead_code)]
+#![allow(unused_variables)]
+pub use blueprint::blueprint;
+
+mod blueprint;

doc_examples/guide/cookies/installation/project/src/main.rs

@@ -0,0 +1,13 @@
+use std::error::Error;
+
+use cargo_px_env::generated_pkg_manifest_path;
+use cookie_installation::blueprint;
+use pavex_cli_client::Client;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let generated_dir = generated_pkg_manifest_path()?.parent().unwrap().into();
+    Client::new()
+        .generate(blueprint(), generated_dir)
+        .execute()?;
+    Ok(())
+}

doc_examples/guide/cookies/installation/tutorial.yml

@@ -0,0 +1,9 @@
+starter_project_folder: "project"
+commands:
+  - command: "cargo px c"
+    expected_outcome: "success"
+snippets:
+  - name: "kit"
+    source_path: "src/blueprint.rs"
+    ranges: [ "0..6", "7..8" ]
+    hl_lines: [ 6 ]

doc_examples/guide/cookies/installation_with_default/project-default.snap

@@ -0,0 +1,12 @@
+```rust title="src/blueprint.rs" hl_lines="7"
+use pavex::blueprint::Blueprint;
+use pavex::cookie::CookieKit;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    CookieKit::new()
+        .with_default_processor_config()
+        .register(&mut bp);
+        // [...]
+}
+```

doc_examples/guide/cookies/installation_with_default/project/.gitignore

@@ -0,0 +1,2 @@
+/target
+Cargo.lock

doc_examples/guide/cookies/installation_with_default/project/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "cookie_installation_with_default"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { path = "../../../../../libs/pavex" }
+pavex_cli_client = { path = "../../../../../libs/pavex_cli_client" }
+serde = { version = "1", features = ["derive"] }
+cargo_px_env = "0.1"
+tokio = { version = "1.35.1", features = ["time"] }
+
+[workspace]
+members = [".", "server_sdk"]

doc_examples/guide/cookies/installation_with_default/project/server_sdk/Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "cookie_installation_with_default_server_sdk"
+version = "0.1.0"
+edition = "2021"
+
+[package.metadata.px.generate]
+generator_type = "cargo_workspace_binary"
+generator_name = "cookie_installation_with_default"

doc_examples/guide/cookies/installation_with_default/project/server_sdk/src/lib.rs

@@ -0,0 +1 @@
+

doc_examples/guide/cookies/installation_with_default/project/src/blueprint.rs

@@ -0,0 +1,10 @@
+use pavex::blueprint::Blueprint;
+use pavex::cookie::CookieKit;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    CookieKit::new()
+        .with_default_processor_config()
+        .register(&mut bp);
+    bp
+}

doc_examples/guide/cookies/installation_with_default/project/src/lib.rs

@@ -0,0 +1,5 @@
+#![allow(dead_code)]
+#![allow(unused_variables)]
+pub use blueprint::blueprint;
+
+mod blueprint;

doc_examples/guide/cookies/installation_with_default/project/src/main.rs

@@ -0,0 +1,13 @@
+use std::error::Error;
+
+use cargo_px_env::generated_pkg_manifest_path;
+use cookie_installation_with_default::blueprint;
+use pavex_cli_client::Client;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let generated_dir = generated_pkg_manifest_path()?.parent().unwrap().into();
+    Client::new()
+        .generate(blueprint(), generated_dir)
+        .execute()?;
+    Ok(())
+}

doc_examples/guide/cookies/installation_with_default/tutorial.yml

@@ -0,0 +1,9 @@
+starter_project_folder: "project"
+commands:
+  - command: "cargo px c"
+    expected_outcome: "success"
+snippets:
+  - name: "default"
+    source_path: "src/blueprint.rs"
+    ranges: [ "0..8", "9.." ]
+    hl_lines: [ 7 ]

doc_examples/guide/cookies/request_cookies/project-inject.snap

@@ -0,0 +1,12 @@
+```rust title="src/core/routes.rs"
+use pavex::cookie::RequestCookies;
+use pavex::response::Response;
+
+pub fn handler(request_cookies: &RequestCookies) -> Response {
+    let Some(session_id) = request_cookies.get("session_id") else {
+        return Response::unauthorized();
+    };
+    // Further processing
+    // [...]
+}
+```

doc_examples/guide/cookies/request_cookies/project-multiple.snap

@@ -0,0 +1,13 @@
+```rust title="src/multiple/routes.rs"
+use pavex::cookie::RequestCookies;
+use pavex::response::Response;
+
+pub fn handler(request_cookies: &RequestCookies) -> Response {
+    let cookies_values: Vec<_> = match request_cookies.get_all("origin") {
+        Some(cookies) => cookies.values().collect(),
+        None => Vec::new(),
+    };
+    // Further processing
+    // [...]
+}
+```

doc_examples/guide/cookies/request_cookies/project/.gitignore

@@ -0,0 +1,2 @@
+/target
+Cargo.lock

doc_examples/guide/cookies/request_cookies/project/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "request_cookies"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { path = "../../../../../libs/pavex" }
+pavex_cli_client = { path = "../../../../../libs/pavex_cli_client" }
+serde = { version = "1", features = ["derive"] }
+cargo_px_env = "0.1"
+tokio = { version = "1.35.1", features = ["time"] }
+
+[workspace]
+members = [".", "server_sdk"]

doc_examples/guide/cookies/request_cookies/project/server_sdk/Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "request_cookies_server_sdk"
+version = "0.1.0"
+edition = "2021"
+
+[package.metadata.px.generate]
+generator_type = "cargo_workspace_binary"
+generator_name = "request_cookies"

doc_examples/guide/cookies/request_cookies/project/server_sdk/src/lib.rs

@@ -0,0 +1 @@
+

doc_examples/guide/cookies/request_cookies/project/src/blueprint.rs

@@ -0,0 +1,12 @@
+use pavex::blueprint::Blueprint;
+use pavex::cookie::CookieKit;
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    CookieKit::new().register(&mut bp);
+    bp.singleton(f!(<pavex::cookie::ProcessorConfig as std::default::Default>::default));
+    bp.nest_at("/core", crate::core::blueprint());
+    bp.nest_at("/multiple", crate::multiple::blueprint());
+    bp
+}

doc_examples/guide/cookies/request_cookies/project/src/core/blueprint.rs

@@ -0,0 +1,9 @@
+use pavex::blueprint::router::GET;
+use pavex::blueprint::Blueprint;
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(GET, "/", f!(super::handler));
+    bp
+}

doc_examples/guide/cookies/request_cookies/project/src/core/mod.rs

@@ -0,0 +1,5 @@
+pub use blueprint::blueprint;
+pub use routes::handler;
+
+mod blueprint;
+mod routes;

doc_examples/guide/cookies/request_cookies/project/src/core/routes.rs

@@ -0,0 +1,10 @@
+use pavex::cookie::RequestCookies;
+use pavex::response::Response;
+
+pub fn handler(request_cookies: &RequestCookies) -> Response {
+    let Some(session_id) = request_cookies.get("session_id") else {
+        return Response::unauthorized();
+    };
+    // Further processing
+    Response::ok()
+}

doc_examples/guide/cookies/request_cookies/project/src/lib.rs

@@ -0,0 +1,7 @@
+#![allow(dead_code)]
+#![allow(unused_variables)]
+pub use blueprint::blueprint;
+
+mod blueprint;
+pub mod core;
+pub mod multiple;

doc_examples/guide/cookies/request_cookies/project/src/main.rs

@@ -0,0 +1,13 @@
+use std::error::Error;
+
+use cargo_px_env::generated_pkg_manifest_path;
+use request_cookies::blueprint;
+use pavex_cli_client::Client;
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let generated_dir = generated_pkg_manifest_path()?.parent().unwrap().into();
+    Client::new()
+        .generate(blueprint(), generated_dir)
+        .execute()?;
+    Ok(())
+}

doc_examples/guide/cookies/request_cookies/project/src/multiple/blueprint.rs

@@ -0,0 +1,9 @@
+use pavex::blueprint::router::GET;
+use pavex::blueprint::Blueprint;
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(GET, "/", f!(super::handler));
+    bp
+}

doc_examples/guide/cookies/request_cookies/project/src/multiple/mod.rs

@@ -0,0 +1,5 @@
+pub use blueprint::blueprint;
+pub use routes::handler;
+
+mod blueprint;
+mod routes;

doc_examples/guide/cookies/request_cookies/project/src/multiple/routes.rs

@@ -0,0 +1,11 @@
+use pavex::cookie::RequestCookies;
+use pavex::response::Response;
+
+pub fn handler(request_cookies: &RequestCookies) -> Response {
+    let cookies_values: Vec<_> = match request_cookies.get_all("origin") {
+        Some(cookies) => cookies.values().collect(),
+        None => Vec::new(),
+    };
+    // Further processing
+    Response::ok()
+}

doc_examples/guide/cookies/request_cookies/tutorial.yml

@@ -0,0 +1,11 @@
+starter_project_folder: "project"
+commands:
+  - command: "cargo px c"
+    expected_outcome: "success"
+snippets:
+  - name: "inject"
+    source_path: "src/core/routes.rs"
+    ranges: [ "0..8", "9..10" ]
+  - name: "multiple"
+    source_path: "src/multiple/routes.rs"
+    ranges: [ "0..9", "10.." ]

doc_examples/guide/cookies/response_cookies/project-delete.snap

@@ -0,0 +1,13 @@
+```rust title="src/delete/routes.rs"
+use pavex::cookie::{RemovalCookie, ResponseCookies};
+use pavex::response::Response;
+
+pub fn handler(response_cookies: &mut ResponseCookies) -> Response {
+    let cookie = RemovalCookie::new("last_visited")
+        // We need to match the path of the cookie we want to delete.
+        .set_path("/web");
+    response_cookies.insert(cookie);
+
+    Response::ok()
+}
+```

doc_examples/guide/cookies/response_cookies/project-insert.snap

@@ -0,0 +1,21 @@
+```rust title="src/core/routes.rs"
+use pavex::cookie::{ResponseCookie, ResponseCookies};
+use pavex::response::Response;
+use pavex::time::{format_description::well_known::Iso8601, OffsetDateTime};
+
+pub fn handler(response_cookies: &mut ResponseCookies) -> Response {
+    let now = OffsetDateTime::now_utc().format(&Iso8601::DEFAULT).unwrap();
+    let cookie = ResponseCookie::new("last_visited", now)
+        // We restrict the cookie to a specific path.
+        .set_path("/web");
+
+    // Make sure to insert the cookie into `&mut ResponseCookies`!
+    // Otherwise, the cookie won't be attached to the response.
+    response_cookies.insert(cookie);
+
+    // You don't have to manually attach the cookie to the response!
+    // It'll be done by the injector middleware at the end of the request
+    // processing pipeline.
+    Response::ok()
+}
+```

doc_examples/guide/cookies/response_cookies/project/.gitignore

@@ -0,0 +1,2 @@
+/target
+Cargo.lock