From 55eca196af7e4a6d8870b0df7c006eb5227d3237 Mon Sep 17 00:00:00 2001 From: Sam Scott Date: Mon, 14 Jul 2025 17:29:00 -0500 Subject: [PATCH] Fix various Rust documentation formatting issues --- .../docs/workers/examples/basic-auth.mdx | 39 +++---- .../workers/examples/cors-header-proxy.mdx | 107 +++++++++--------- .../docs/workers/examples/logging-headers.mdx | 11 +- .../workers/examples/security-headers.mdx | 4 +- .../docs/workers/examples/websockets.mdx | 91 ++++++++------- 5 files changed, 132 insertions(+), 120 deletions(-) diff --git a/src/content/docs/workers/examples/basic-auth.mdx b/src/content/docs/workers/examples/basic-auth.mdx index 46105a13575d8a7..74ec57b26f8a871 100644 --- a/src/content/docs/workers/examples/basic-auth.mdx +++ b/src/content/docs/workers/examples/basic-auth.mdx @@ -260,21 +260,22 @@ export default { ``` + ```rs use base64::prelude::*; use worker::*; #[event(fetch)] async fn fetch(req: Request, env: Env, _ctx: Context) -> Result { -let basic_user = "admin"; -// You will need an admin password. This should be -// attached to your Worker as an encrypted secret. -// Refer to https://developers.cloudflare.com/workers/configuration/secrets/ -let basic_pass = match env.secret("PASSWORD") { -Ok(s) => s.to_string(), -Err(_) => "password".to_string(), -}; -let url = req.url()?; + let basic_user = "admin"; + // You will need an admin password. This should be + // attached to your Worker as an encrypted secret. + // Refer to https://developers.cloudflare.com/workers/configuration/secrets/ + let basic_pass = match env.secret("PASSWORD") { + Ok(s) => s.to_string(), + Err(_) => "password".to_string(), + }; + let url = req.url()?; match url.path() { "/" => Response::ok("Anyone can access the homepage."), @@ -328,10 +329,10 @@ let url = req.url()?; } _ => Response::error("Not Found.", 404), } - } -```` +``` + ```ts @@ -346,17 +347,17 @@ import { basicAuth } from "hono/basic-auth"; // Define environment interface interface Env { - Bindings: { + Bindings: { USERNAME: string; - PASSWORD: string; - }; + PASSWORD: string; + }; } const app = new Hono(); // Public homepage - accessible to everyone app.get("/", (c) => { - return c.text("Anyone can access the homepage."); + return c.text("Anyone can access the homepage."); }); // Admin route - protected with Basic Auth @@ -365,8 +366,8 @@ app.get( async (c, next) => { const auth = basicAuth({ username: c.env.USERNAME, - password: c.env.PASSWORD - }) + password: c.env.PASSWORD, + }); return await auth(c, next); }, @@ -374,10 +375,10 @@ app.get( return c.text("🎉 You have private access!", 200, { "Cache-Control": "no-store", }); - } + }, ); export default app; -```` +``` diff --git a/src/content/docs/workers/examples/cors-header-proxy.mdx b/src/content/docs/workers/examples/cors-header-proxy.mdx index 34f467d6e5db1b6..ab87ea853e1151e 100644 --- a/src/content/docs/workers/examples/cors-header-proxy.mdx +++ b/src/content/docs/workers/examples/cors-header-proxy.mdx @@ -583,67 +583,69 @@ async def on_fetch(request): ``` + ```rs use std::{borrow::Cow, collections::HashMap}; use worker::*; -fn raw*html_response(html: &str) -> Result { -Response::from_html(html) +fn raw_html_response(html: &str) -> Result { + Response::from_html(html) } async fn handle_request(req: Request, api_url: &str) -> Result { -let url = req.url().unwrap(); -let mut api_url2 = url -.query_pairs() -.find(|x| x.0 == Cow::Borrowed("apiurl")) -.unwrap() -.1 -.to_string(); -if api_url2 == String::from("") { -api_url2 = api_url.to_string(); -} -let mut request = req.clone_mut()?; -\*request.path_mut()? = api_url2.clone(); -if let url::Origin::Tuple(origin, *, _) = Url::parse(&api_url2)?.origin() { -(\*request.headers_mut()?).set("Origin", &origin)?; -} -let mut response = Fetch::Request(request).send().await?.cloned()?; -let headers = response.headers_mut(); -if let url::Origin::Tuple(origin, _, \_) = url.origin() { -headers.set("Access-Control-Allow-Origin", &origin)?; -headers.set("Vary", "Origin")?; -} + let url = req.url().unwrap(); + let mut api_url2 = url + .query_pairs() + .find(|x| x.0 == Cow::Borrowed("apiurl")) + .unwrap() + .1 + .to_string(); + if api_url2 == String::from("") { + api_url2 = api_url.to_string(); + } + let mut request = req.clone_mut()?; + *request.path_mut()? = api_url2.clone(); + if let url::Origin::Tuple(origin, _, _) = Url::parse(&api_url2)?.origin() { + (*request.headers_mut()?).set("Origin", &origin)?; + } + let mut response = Fetch::Request(request).send().await?.cloned()?; + let headers = response.headers_mut(); + if let url::Origin::Tuple(origin, _, _) = url.origin() { + headers.set("Access-Control-Allow-Origin", &origin)?; + headers.set("Vary", "Origin")?; + } Ok(response) - } -fn handle*options(req: Request, cors_headers: &HashMap<&str, &str>) -> Result { -let headers: Vec<*> = req.headers().keys().collect(); -if [ -"access-control-request-method", -"access-control-request-headers", -"origin", -] -.iter() -.all(|i| headers.contains(&i.to_string())) -{ -let mut headers = Headers::new(); -for (k, v) in cors_headers.iter() { -headers.set(k, v)?; -} -return Ok(Response::empty()?.with_headers(headers)); +fn handle_options(req: Request, cors_headers: &HashMap<&str, &str>) -> Result { + let headers: Vec<_> = req.headers().keys().collect(); + if [ + "access-control-request-method", + "access-control-request-headers", + "origin", + ] + .iter() + .all(|i| headers.contains(&i.to_string())) + { + let mut headers = Headers::new(); + for (k, v) in cors_headers.iter() { + headers.set(k, v)?; + } + return Ok(Response::empty()?.with_headers(headers)); + } + Response::empty() } -Response::empty() -} #[event(fetch)] -async fn fetch(req: Request, \_env: Env, \_ctx: Context) -> Result { -let cors_headers = HashMap::from([ -("Access-Control-Allow-Origin", "*"), -("Access-Control-Allow-Methods", "GET,HEAD,POST,OPTIONS"), -("Access-Control-Max-Age", "86400"), -]); -let api_url = "https://examples.cloudflareworkers.com/demos/demoapi"; -let proxy_endpoint = "/corsproxy/"; -let demo_page = format!( + +#[event(fetch)] +async fn fetch(req: Request, _env: Env, _ctx: Context) -> Result { + let cors_headers = HashMap::from([ + ("Access-Control-Allow-Origin", "*"), + ("Access-Control-Allow-Methods", "GET,HEAD,POST,OPTIONS"), + ("Access-Control-Max-Age", "86400"), + ]); + let api_url = "https://examples.cloudflareworkers.com/demos/demoapi"; + let proxy_endpoint = "/corsproxy/"; + let demo_page = format!( r#" @@ -696,7 +698,7 @@ return response.json() "# -); + ); if req.url()?.path().starts_with(proxy_endpoint) { match req.method() { @@ -708,7 +710,6 @@ return response.json() raw_html_response(&demo_page) } - ``` -``` + diff --git a/src/content/docs/workers/examples/logging-headers.mdx b/src/content/docs/workers/examples/logging-headers.mdx index 787f7f4d99f9287..73cdb899d15aa8e 100644 --- a/src/content/docs/workers/examples/logging-headers.mdx +++ b/src/content/docs/workers/examples/logging-headers.mdx @@ -59,16 +59,17 @@ async def on_fetch(request): ``` + ```rs use worker::*; #[event(fetch)] -async fn fetch(req: HttpRequest, \_env: Env, \_ctx: Context) -> Result { -console_log!("{:?}", req.headers()); -Response::ok("hello world") +async fn fetch(req: HttpRequest, _env: Env, _ctx: Context) -> Result { + console_log!("{:?}", req.headers()); + Response::ok("hello world") } +``` -```` ```ts @@ -98,7 +99,7 @@ app.get('*', (c) => { }); export default app; -```` +``` diff --git a/src/content/docs/workers/examples/security-headers.mdx b/src/content/docs/workers/examples/security-headers.mdx index 2de1b4ece617536..e9f256f79ccd64f 100644 --- a/src/content/docs/workers/examples/security-headers.mdx +++ b/src/content/docs/workers/examples/security-headers.mdx @@ -258,6 +258,7 @@ async def on_fetch(request): ``` + ```rs use std::collections::HashMap; use worker::*; @@ -329,7 +330,8 @@ async fn fetch(req: Request, _env: Env, _ctx: Context) -> Result { } -```` +``` + ```ts diff --git a/src/content/docs/workers/examples/websockets.mdx b/src/content/docs/workers/examples/websockets.mdx index c883e2641e32fbc..0ae0cc6a1380d59 100644 --- a/src/content/docs/workers/examples/websockets.mdx +++ b/src/content/docs/workers/examples/websockets.mdx @@ -53,6 +53,7 @@ For more details about creating and working with WebSockets in the client, refer When an incoming WebSocket request reaches the Workers function, it will contain an `Upgrade` header, set to the string value `websocket`. Check for this header before continuing to instantiate a WebSocket: + ```js async function handleRequest(request) { const upgradeHeader = request.headers.get('Upgrade'); @@ -62,27 +63,28 @@ async function handleRequest(request) { } ``` -```rs -use worker::\*; +```rs +use worker::*; #[event(fetch)] -async fn fetch(req: HttpRequest, \_env: Env, \_ctx: Context) -> Result { -let upgrade_header = match req.headers().get("Upgrade") { -Some(h) => h.to_str().unwrap(), -None => "", -}; -if upgrade_header != "websocket" { -return worker::Response::error("Expected Upgrade: websocket", 426); -} +async fn fetch(req: HttpRequest, _env: Env, _ctx: Context) -> Result { + let upgrade_header = match req.headers().get("Upgrade") { + Some(h) => h.to_str().unwrap(), + None => "", + }; + if upgrade_header != "websocket" { + return worker::Response::error("Expected Upgrade: websocket", 426); + } } +``` -```` After you have appropriately checked for the `Upgrade` header, you can create a new instance of `WebSocketPair`, which contains server and client WebSockets. One of these WebSockets should be handled by the Workers function and the other should be returned as part of a `Response` with the [`101` status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/101), indicating the request is switching protocols: + ```js async function handleRequest(request) { const upgradeHeader = request.headers.get('Upgrade'); @@ -99,21 +101,22 @@ async function handleRequest(request) { webSocket: client, }); } -```` +``` + ```rs use worker::*; #[event(fetch)] -async fn fetch(req: HttpRequest, \_env: Env, \_ctx: Context) -> Result { -let upgrade_header = match req.headers().get("Upgrade") { -Some(h) => h.to_str().unwrap(), -None => "", -}; -if upgrade_header != "websocket" { -return worker::Response::error("Expected Upgrade: websocket", 426); -} +async fn fetch(req: HttpRequest, _env: Env, _ctx: Context) -> Result { + let upgrade_header = match req.headers().get("Upgrade") { + Some(h) => h.to_str().unwrap(), + None => "", + }; + if upgrade_header != "websocket" { + return worker::Response::error("Expected Upgrade: websocket", 426); + } let ws = WebSocketPair::new()?; let client = ws.client; @@ -123,8 +126,8 @@ return worker::Response::error("Expected Upgrade: websocket", 426); worker::Response::from_websocket(client) } +``` -```` The `WebSocketPair` constructor returns an Object, with the `0` and `1` keys each holding a `WebSocket` instance as its value. It is common to grab the two WebSockets from this pair using [`Object.values`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_objects/Object/values) and [ES6 destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment), as seen in the below example. @@ -133,6 +136,7 @@ In order to begin communicating with the `client` WebSocket in your Worker, call + ```js async function handleRequest(request) { const upgradeHeader = request.headers.get('Upgrade'); @@ -150,21 +154,22 @@ async function handleRequest(request) { webSocket: client, }); } -```` +``` + ```rs use worker::*; #[event(fetch)] -async fn fetch(req: HttpRequest, \_env: Env, \_ctx: Context) -> Result { -let upgrade_header = match req.headers().get("Upgrade") { -Some(h) => h.to_str().unwrap(), -None => "", -}; -if upgrade_header != "websocket" { -return worker::Response::error("Expected Upgrade: websocket", 426); -} +async fn fetch(req: HttpRequest, _env: Env, _ctx: Context) -> Result { + let upgrade_header = match req.headers().get("Upgrade") { + Some(h) => h.to_str().unwrap(), + None => "", + }; + if upgrade_header != "websocket" { + return worker::Response::error("Expected Upgrade: websocket", 426); + } let ws = WebSocketPair::new()?; let client = ws.client; @@ -174,13 +179,14 @@ return worker::Response::error("Expected Upgrade: websocket", 426); worker::Response::from_websocket(client) } +``` -```` WebSockets emit a number of [Events](/workers/runtime-apis/websockets/#events) that can be connected to using `addEventListener`. The below example hooks into the `message` event and emits a `console.log` with the data from it: + ```js async function handleRequest(request) { const upgradeHeader = request.headers.get('Upgrade'); @@ -201,22 +207,23 @@ async function handleRequest(request) { webSocket: client, }); } -```` +``` + ```rs use futures::StreamExt; use worker::*; #[event(fetch)] -async fn fetch(req: HttpRequest, \_env: Env, \_ctx: Context) -> Result { -let upgrade_header = match req.headers().get("Upgrade") { -Some(h) => h.to_str().unwrap(), -None => "", -}; -if upgrade_header != "websocket" { -return worker::Response::error("Expected Upgrade: websocket", 426); -} +async fn fetch(req: HttpRequest, _env: Env, _ctx: Context) -> Result { + let upgrade_header = match req.headers().get("Upgrade") { + Some(h) => h.to_str().unwrap(), + None => "", + }; + if upgrade_header != "websocket" { + return worker::Response::error("Expected Upgrade: websocket", 426); + } let ws = WebSocketPair::new()?; let client = ws.client; @@ -235,8 +242,8 @@ return worker::Response::error("Expected Upgrade: websocket", 426); worker::Response::from_websocket(client) } +``` -```` ```ts @@ -264,7 +271,7 @@ app.get( ) export default app; -```` +```