typespec-rust-emitter 0.13.1 → 0.14.1

package/example/output-rust/src/generated/server.rs

@@ -12,11 +12,12 @@ use eyre::Result;
 
 /// Pluggable ETag cache backend.
 /// Implement this for Redis, Memcached, in-memory HashMap, or any store.
+#[async_trait]
 pub trait EtagCache {
     /// Return the stored ETag string for `key`, or `None` if not cached.
-    fn get(&self, key: &str) -> Option<String>;
+    async fn get(&self, key: &str) -> Option<String>;
     /// Store `etag` under `key`.
-    fn set(&self, key: &str, etag: &str);
+    async fn set(&self, key: &str, etag: &str);
 }
 
 
@@ -34,6 +35,15 @@ pub trait Server: Send + Sync {
     async fn items_get_item(&self, id: String) -> Result<ItemsGetItemResponse>;
     async fn items_create_item(&mut self, body: Item) -> Result<ItemsCreateItemResponse>;
     async fn items_update_item(&mut self, id: String, body: Item) -> Result<ItemsUpdateItemResponse>;
+    async fn images_list_public<C: EtagCache + Send + Sync>(
+        &self, cache: &C, account_id: uuid::Uuid
+    ) -> Result<ImagesListPublicResponse>;
+    async fn images_list_recent<C: EtagCache + Send + Sync>(
+        &mut self, cache: &C, account_id: uuid::Uuid, user_timezone: String, last_id: Option<uuid::Uuid>, limit: i32
+    ) -> Result<ImagesListRecentResponse>;
+    async fn images_get_image<C: EtagCache + Send + Sync>(
+        &self, cache: &C, account_id: uuid::Uuid, image_id: String
+    ) -> Result<ImagesGetImageResponse>;
     async fn articles_get_article<C: EtagCache + Send + Sync>(
         &self, claims: Self::Claims, cache: &C, id: String
     ) -> Result<ArticlesGetArticleResponse>;
@@ -124,6 +134,54 @@ impl IntoResponse for ItemsUpdateItemResponse {
     }
 }
 
+#[allow(clippy::type_complexity)]
+pub enum ImagesListPublicResponse {
+    Ok(Json<Vec<Item>>),
+    NotModified,
+}
+
+impl IntoResponse for ImagesListPublicResponse {
+    fn into_response(self) -> axum::response::Response {
+        match self {
+
+            ImagesListPublicResponse::Ok(body) => (StatusCode::OK, body).into_response(),
+            ImagesListPublicResponse::NotModified => StatusCode::NOT_MODIFIED.into_response(),
+        }
+    }
+}
+
+#[allow(clippy::type_complexity)]
+pub enum ImagesListRecentResponse {
+    Ok(Json<Vec<Item>>),
+    NotModified,
+}
+
+impl IntoResponse for ImagesListRecentResponse {
+    fn into_response(self) -> axum::response::Response {
+        match self {
+
+            ImagesListRecentResponse::Ok(body) => (StatusCode::OK, body).into_response(),
+            ImagesListRecentResponse::NotModified => StatusCode::NOT_MODIFIED.into_response(),
+        }
+    }
+}
+
+#[allow(clippy::type_complexity)]
+pub enum ImagesGetImageResponse {
+    Ok(Json<Item>),
+    NotModified,
+}
+
+impl IntoResponse for ImagesGetImageResponse {
+    fn into_response(self) -> axum::response::Response {
+        match self {
+
+            ImagesGetImageResponse::Ok(body) => (StatusCode::OK, body).into_response(),
+            ImagesGetImageResponse::NotModified => StatusCode::NOT_MODIFIED.into_response(),
+        }
+    }
+}
+
 #[allow(clippy::type_complexity)]
 pub enum ArticlesGetArticleResponse {
     Ok(Json<Article>),
@@ -191,6 +249,16 @@ pub struct ItemsUpdateItemQuery {
     pub id: String
 }
 
+#[derive(Debug, Clone, serde::Deserialize)]
+pub struct ImagesListRecentQuery {
+    #[serde(rename = "userTimezone")]
+    pub user_timezone: String,
+    #[serde(rename = "lastId")]
+    pub last_id: Option<uuid::Uuid>,
+    #[serde(rename = "limit")]
+    pub limit: i32
+}
+
 #[derive(Debug, Clone, serde::Deserialize)]
 pub struct ConsumingConsumeAndDeleteQuery {
     #[serde(rename = "id")]
@@ -249,24 +317,24 @@ where
 {
     // Check If-None-Match against the cache
     let cache_key = "article-list";
-    if let (Some(stored_etag), Some(axum_extra::TypedHeader(inm))) = (cache.get(cache_key.as_ref()), if_none_match) {
-        // If the client's ETag matches, respond 304 immediately
-        if stored_etag == format!("{:?}", inm).trim_matches('"') {
-            let mut res = axum::http::StatusCode::NOT_MODIFIED.into_response();
-            res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("public, max-age=3600"));
-            return res;
-        }
+    if let (Some(stored_etag), Some(axum_extra::TypedHeader(inm))) =
+        (cache.get(cache_key.as_ref()).await, if_none_match)
+        && let Ok(etag) = stored_etag.parse::<axum_extra::headers::ETag>()
+        && !inm.precondition_passes(&etag)
+    {
+        let mut res = axum::http::StatusCode::NOT_MODIFIED.into_response();
+        res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("public, max-age=3600"));
+        return res;
     }
     // Forward to business logic
     let result = service.items_list(&cache).await;
     match result {
         Ok(response) => {
             let mut res = response.into_response();
-            if let Some(stored_etag) = cache.get(cache_key.as_ref()) {
-                res.headers_mut().insert(
-                    axum::http::header::ETAG,
-                    axum::http::HeaderValue::from_str(&stored_etag).unwrap(),
-                );
+            if let Some(stored_etag) = cache.get(cache_key.as_ref()).await
+                && let Ok(etag) = axum::http::HeaderValue::from_str(&stored_etag)
+            {
+                res.headers_mut().insert(axum::http::header::ETAG, etag);
             }
             res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("public, max-age=3600"));
             res
@@ -344,6 +412,136 @@ where
     }
 }
 
+pub async fn images_list_public_handler<S, C>(
+    axum::extract::State(service): axum::extract::State<S>,
+    axum::extract::State(cache): axum::extract::State<C>,
+    if_none_match: Option<axum_extra::TypedHeader<axum_extra::headers::IfNoneMatch>>,
+    Path(account_id): Path<uuid::Uuid>,
+) -> impl axum::response::IntoResponse
+where
+    S: Server + Send + Sync + 'static,
+    S::Claims: Send + Sync + Clone + 'static,
+    C: EtagCache + Clone + Send + Sync + 'static,
+{
+    // Check If-None-Match against the cache
+    let cache_key = format!("img:list:pub:{account_id}");
+    if let (Some(stored_etag), Some(axum_extra::TypedHeader(inm))) =
+        (cache.get(cache_key.as_ref()).await, if_none_match)
+        && let Ok(etag) = stored_etag.parse::<axum_extra::headers::ETag>()
+        && !inm.precondition_passes(&etag)
+    {
+        let mut res = axum::http::StatusCode::NOT_MODIFIED.into_response();
+        res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("no-cache, max-age=2592000"));
+        return res;
+    }
+    // Forward to business logic
+    let result = service.images_list_public(&cache, account_id).await;
+    match result {
+        Ok(response) => {
+            let mut res = response.into_response();
+            if let Some(stored_etag) = cache.get(cache_key.as_ref()).await
+                && let Ok(etag) = axum::http::HeaderValue::from_str(&stored_etag)
+            {
+                res.headers_mut().insert(axum::http::header::ETAG, etag);
+            }
+            res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("no-cache, max-age=2592000"));
+            res
+        }
+        Err(e) => (
+            axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+            format!("Internal error: {e}"),
+        )
+            .into_response(),
+    }
+}
+
+pub async fn images_list_recent_handler<S, C>(
+    axum::extract::State(mut service): axum::extract::State<S>,
+    axum::extract::State(cache): axum::extract::State<C>,
+    if_none_match: Option<axum_extra::TypedHeader<axum_extra::headers::IfNoneMatch>>,
+    Path(account_id): Path<uuid::Uuid>,
+    Query(params): Query<ImagesListRecentQuery>,
+) -> impl axum::response::IntoResponse
+where
+    S: Server + Send + Sync + 'static,
+    S::Claims: Send + Sync + Clone + 'static,
+    C: EtagCache + Clone + Send + Sync + 'static,
+{
+    // Check If-None-Match against the cache
+    let cache_key = format!("img:recent:{account_id}:tz:{}:after:{:?}:limit:{}", params.user_timezone, params.last_id, params.limit);
+    if let (Some(stored_etag), Some(axum_extra::TypedHeader(inm))) =
+        (cache.get(cache_key.as_ref()).await, if_none_match)
+        && let Ok(etag) = stored_etag.parse::<axum_extra::headers::ETag>()
+        && !inm.precondition_passes(&etag)
+    {
+        let mut res = axum::http::StatusCode::NOT_MODIFIED.into_response();
+        res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("no-cache, max-age=2592000"));
+        return res;
+    }
+    // Forward to business logic
+    let result = service.images_list_recent(&cache, account_id, params.user_timezone, params.last_id, params.limit).await;
+    match result {
+        Ok(response) => {
+            let mut res = response.into_response();
+            if let Some(stored_etag) = cache.get(cache_key.as_ref()).await
+                && let Ok(etag) = axum::http::HeaderValue::from_str(&stored_etag)
+            {
+                res.headers_mut().insert(axum::http::header::ETAG, etag);
+            }
+            res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("no-cache, max-age=2592000"));
+            res
+        }
+        Err(e) => (
+            axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+            format!("Internal error: {e}"),
+        )
+            .into_response(),
+    }
+}
+
+pub async fn images_get_image_handler<S, C>(
+    axum::extract::State(service): axum::extract::State<S>,
+    axum::extract::State(cache): axum::extract::State<C>,
+    if_none_match: Option<axum_extra::TypedHeader<axum_extra::headers::IfNoneMatch>>,
+    Path((account_id, image_id)): Path<(uuid::Uuid, String)>,
+) -> impl axum::response::IntoResponse
+where
+    S: Server + Send + Sync + 'static,
+    S::Claims: Send + Sync + Clone + 'static,
+    C: EtagCache + Clone + Send + Sync + 'static,
+{
+    // Check If-None-Match against the cache
+    let cache_key = format!("img:detail:pub:{account_id}:{image_id}");
+    if let (Some(stored_etag), Some(axum_extra::TypedHeader(inm))) =
+        (cache.get(cache_key.as_ref()).await, if_none_match)
+        && let Ok(etag) = stored_etag.parse::<axum_extra::headers::ETag>()
+        && !inm.precondition_passes(&etag)
+    {
+        let mut res = axum::http::StatusCode::NOT_MODIFIED.into_response();
+        res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("public, max-age=60"));
+        return res;
+    }
+    // Forward to business logic
+    let result = service.images_get_image(&cache, account_id, image_id).await;
+    match result {
+        Ok(response) => {
+            let mut res = response.into_response();
+            if let Some(stored_etag) = cache.get(cache_key.as_ref()).await
+                && let Ok(etag) = axum::http::HeaderValue::from_str(&stored_etag)
+            {
+                res.headers_mut().insert(axum::http::header::ETAG, etag);
+            }
+            res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("public, max-age=60"));
+            res
+        }
+        Err(e) => (
+            axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+            format!("Internal error: {e}"),
+        )
+            .into_response(),
+    }
+}
+
 pub async fn articles_get_article_handler<S, C>(
     axum::extract::State(service): axum::extract::State<S>,
     axum::extract::State(cache): axum::extract::State<C>,
@@ -357,25 +555,25 @@ where
     C: EtagCache + Clone + Send + Sync + 'static,
 {
     // Check If-None-Match against the cache
-    let cache_key = "article-list";
-    if let (Some(stored_etag), Some(axum_extra::TypedHeader(inm))) = (cache.get(cache_key.as_ref()), if_none_match) {
-        // If the client's ETag matches, respond 304 immediately
-        if stored_etag == format!("{:?}", inm).trim_matches('"') {
-            let mut res = axum::http::StatusCode::NOT_MODIFIED.into_response();
-            res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("public, max-age=3600"));
-            return res;
-        }
+    let cache_key = format!("article-list:{id}");
+    if let (Some(stored_etag), Some(axum_extra::TypedHeader(inm))) =
+        (cache.get(cache_key.as_ref()).await, if_none_match)
+        && let Ok(etag) = stored_etag.parse::<axum_extra::headers::ETag>()
+        && !inm.precondition_passes(&etag)
+    {
+        let mut res = axum::http::StatusCode::NOT_MODIFIED.into_response();
+        res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("public, max-age=3600"));
+        return res;
     }
     // Forward to business logic
     let result = service.articles_get_article(claims, &cache, id).await;
     match result {
         Ok(response) => {
             let mut res = response.into_response();
-            if let Some(stored_etag) = cache.get(cache_key.as_ref()) {
-                res.headers_mut().insert(
-                    axum::http::header::ETAG,
-                    axum::http::HeaderValue::from_str(&stored_etag).unwrap(),
-                );
+            if let Some(stored_etag) = cache.get(cache_key.as_ref()).await
+                && let Ok(etag) = axum::http::HeaderValue::from_str(&stored_etag)
+            {
+                res.headers_mut().insert(axum::http::header::ETAG, etag);
             }
             res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("public, max-age=3600"));
             res
@@ -444,6 +642,9 @@ where
         .route("/items/{id}", get(items_get_item_handler::<S>))
         .route("/items", post(items_create_item_handler::<S>))
         .route("/items", put(items_update_item_handler::<S>))
+        .route("/accounts/{accountId}/images", get(images_list_public_handler::<S, C>))
+        .route("/accounts/{accountId}/images/recent", get(images_list_recent_handler::<S, C>))
+        .route("/accounts/{accountId}/images/{imageId}", get(images_get_image_handler::<S, C>))
         .route("/consuming", post(consuming_upload_handler::<S>))
         ;
     router = router.merge(public);

package/example/output-rust/src/main.rs

@@ -7,8 +7,9 @@ use axum::response::IntoResponse;
 use axum::response::sse::{Event, KeepAlive, Sse};
 use generated::server::{
     ArticlesGetArticleResponse, ConsumingConsumeAndDeleteResponse, ConsumingUploadResponse,
-    EtagCache, EventsAccountsEventsResponse, ItemsCreateItemResponse, ItemsGetItemResponse,
-    ItemsListResponse, ItemsUpdateItemResponse, PetsListResponse, Server,
+    EtagCache, EventsAccountsEventsResponse, ImagesGetImageResponse, ImagesListPublicResponse,
+    ImagesListRecentResponse, ItemsCreateItemResponse, ItemsGetItemResponse, ItemsListResponse,
+    ItemsUpdateItemResponse, PetsListResponse, Server,
 };
 use std::collections::HashMap;
 use std::convert::Infallible;
@@ -20,11 +21,12 @@ use tokio_stream::{wrappers::IntervalStream, StreamExt as _};
 #[derive(Clone, Default)]
 struct InMemoryCache(Arc<Mutex<HashMap<String, String>>>);
 
+#[async_trait]
 impl EtagCache for InMemoryCache {
-    fn get(&self, key: &str) -> Option<String> {
+    async fn get(&self, key: &str) -> Option<String> {
         self.0.lock().unwrap().get(key).cloned()
     }
-    fn set(&self, key: &str, etag: &str) {
+    async fn set(&self, key: &str, etag: &str) {
         self.0.lock().unwrap().insert(key.to_owned(), etag.to_owned());
     }
 }
@@ -71,7 +73,7 @@ impl Server for AppState {
         &self,
         cache: &C,
     ) -> eyre::Result<ItemsListResponse> {
-        cache.set("article-list", "\"items-etag\"");
+        cache.set("article-list", "\"items-etag\"").await;
         Ok(ItemsListResponse::Ok(Json(vec![generated::types::Item {
             name: "list-item".to_string(),
             value: 123,
@@ -106,6 +108,72 @@ impl Server for AppState {
         })))
     }
 
+    async fn images_list_public<C: EtagCache + Send + Sync>(
+        &self,
+        cache: &C,
+        account_id: uuid::Uuid,
+    ) -> eyre::Result<ImagesListPublicResponse> {
+        cache
+            .set(
+                &format!("img:list:pub:{}", account_id),
+                "\"images-list-etag\"",
+            )
+            .await;
+        Ok(ImagesListPublicResponse::Ok(Json(vec![
+            generated::types::Item {
+                name: "public-image-1".to_string(),
+                value: 200,
+            },
+            generated::types::Item {
+                name: "public-image-2".to_string(),
+                value: 201,
+            },
+        ])))
+    }
+
+    async fn images_list_recent<C: EtagCache + Send + Sync>(
+        &mut self,
+        cache: &C,
+        account_id: uuid::Uuid,
+        user_timezone: String,
+        last_id: Option<uuid::Uuid>,
+        limit: i32,
+    ) -> eyre::Result<ImagesListRecentResponse> {
+        cache
+            .set(
+                &format!(
+                    "img:recent:{}:tz:{}:after:{:?}:limit:{}",
+                    account_id, user_timezone, last_id, limit
+                ),
+                "\"recent-images-etag\"",
+            )
+            .await;
+        Ok(ImagesListRecentResponse::Ok(Json(vec![
+            generated::types::Item {
+                name: "recent-image-1".to_string(),
+                value: limit,
+            },
+        ])))
+    }
+
+    async fn images_get_image<C: EtagCache + Send + Sync>(
+        &self,
+        cache: &C,
+        account_id: uuid::Uuid,
+        image_id: String,
+    ) -> eyre::Result<ImagesGetImageResponse> {
+        cache
+            .set(
+                &format!("img:detail:pub:{}:{}", account_id, image_id),
+                "\"image-detail-etag\"",
+            )
+            .await;
+        Ok(ImagesGetImageResponse::Ok(Json(generated::types::Item {
+            name: format!("image-{}", image_id),
+            value: 300,
+        })))
+    }
+
     async fn articles_get_article<C: EtagCache + Send + Sync>(
         &self,
         _claims: Self::Claims,
@@ -113,7 +181,7 @@ impl Server for AppState {
         id: String,
     ) -> eyre::Result<ArticlesGetArticleResponse> {
         let etag = format!("\"article-etag-{}\"", id);
-        cache.set(&format!("articles_get_article:{}", id), &etag);
+        cache.set(&format!("article-list:{}", id), &etag).await;
         Ok(ArticlesGetArticleResponse::Ok(Json(
             generated::types::Article {
                 id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-rust-emitter",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "TypeSpec emitter that generates idiomatic Rust types and structs",
   "keywords": [
     "typespec",

package/scripts/update-golden.js

@@ -1,36 +1,36 @@
-import { readFileSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { emit } from '../dist/test/test-host.js';
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { emit } from "../dist/test/test-host.js";
 
 async function main() {
   const feature = process.argv[2];
   if (!feature) {
-    console.error('Usage: node scripts/update-golden.js <feature>');
+    console.error("Usage: node scripts/update-golden.js <feature>");
     process.exit(1);
   }
 
   const specPath = resolve(process.cwd(), `test/golden/${feature}/spec.tsp`);
-  const spec = readFileSync(specPath, 'utf8');
-  
+  const spec = readFileSync(specPath, "utf8");
+
   console.log(`Emitting spec for ${feature}...`);
   const out = await emit(spec);
 
-  if (out['types.rs']) {
+  if (out["types.rs"]) {
     const p = resolve(process.cwd(), `test/golden/${feature}/types.rs`);
-    writeFileSync(p, out['types.rs']);
+    writeFileSync(p, out["types.rs"]);
     console.log(`Updated types.rs`);
   }
-  
-  if (out['server.rs']) {
+
+  if (out["server.rs"]) {
     const p = resolve(process.cwd(), `test/golden/${feature}/server.rs`);
-    writeFileSync(p, out['server.rs']);
+    writeFileSync(p, out["server.rs"]);
     console.log(`Updated server.rs`);
   }
 
   console.log(`Golden files updated for: ${feature}`);
 }
 
-main().catch(err => {
+main().catch((err) => {
   console.error(err);
   process.exit(1);
 });

package/src/generator/etag_router.ts

@@ -1,3 +1,5 @@
+import type { ParameterInfo } from "../models/types.js";
+
 /**
  * generateEtagCacheTrait
  *
@@ -7,29 +9,90 @@
 export function generateEtagCacheTrait(): string {
   return `/// Pluggable ETag cache backend.
 /// Implement this for Redis, Memcached, in-memory HashMap, or any store.
+#[async_trait]
 pub trait EtagCache {
     /// Return the stored ETag string for \`key\`, or \`None\` if not cached.
-    fn get(&self, key: &str) -> Option<String>;
+    async fn get(&self, key: &str) -> Option<String>;
     /// Store \`etag\` under \`key\`.
-    fn set(&self, key: &str, etag: &str);
+    async fn set(&self, key: &str, etag: &str);
 }
 `;
 }
 
+function rustStringLiteral(value: string): string {
+  return `"${value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t")}"`;
+}
+
+function buildCacheKeyExpression(opts: {
+  handlerFnName: string;
+  etagKey?: string;
+  pathParams: ParameterInfo[];
+  queryParams?: ParameterInfo[];
+}): string {
+  const { handlerFnName, etagKey, pathParams, queryParams = [] } = opts;
+  const pathSuffix = pathParams.map((p) => `{${p.rustName}}`).join(":");
+  const paramNames = new Map<string, string>();
+  for (const param of pathParams) {
+    paramNames.set(param.name, param.rustName);
+    paramNames.set(param.rustName, param.rustName);
+  }
+  const queryParamNames = new Map<string, ParameterInfo>();
+  for (const param of queryParams) {
+    queryParamNames.set(param.name, param);
+    queryParamNames.set(param.rustName, param);
+  }
+
+  let template = etagKey ?? handlerFnName;
+  const formatArgs: string[] = [];
+  template = template.replace(/\{([^}]+)\}/g, (match, name: string) => {
+    const rustName = paramNames.get(name);
+    if (rustName) {
+      return `{${rustName}}`;
+    }
+    const queryParam = queryParamNames.get(name);
+    if (queryParam) {
+      formatArgs.push(`params.${queryParam.rustName}`);
+      return queryParam.rustType.startsWith("Option<") ? "{:?}" : "{}";
+    }
+    return match;
+  });
+
+  const hasExplicitPathParam = pathParams.some(
+    (param) =>
+      template.includes(`{${param.name}}`) ||
+      template.includes(`{${param.rustName}}`),
+  );
+  if (pathSuffix && !hasExplicitPathParam) {
+    template = `${template}:${pathSuffix}`;
+  }
+
+  if (!template.includes("{")) {
+    return rustStringLiteral(template);
+  }
+  const args = formatArgs.length > 0 ? `, ${formatArgs.join(", ")}` : "";
+  return `format!(${rustStringLiteral(template)}${args})`;
+}
+
 /**
  * generateEtagHandler
  *
  * Returns the Rust source for a single ETag-aware axum handler.
  *
  * @param handlerFnName  snake_case name, e.g. "articles_get_article"
- * @param cacheKey       format string for the cache key, e.g. "articles_get_article:{id}"
+ * @param pathParams     route path parameters used for cache key scoping
  * @param extractorLines axum extractors needed by the operation
  * @param serverArgsStr  comma-separated args forwarded to the trait method
  * @param responseName   PascalCase name of the response enum, e.g. "ArticlesGetArticleResponse"
  */
 export function generateEtagHandler(opts: {
   handlerFnName: string;
-  cacheKey: string;
+  pathParams: ParameterInfo[];
+  queryParams?: ParameterInfo[];
   extractorLines: string[];
   serverArgsStr: string;
   responseName: string;
@@ -39,7 +102,8 @@ export function generateEtagHandler(opts: {
 }): string {
   const {
     handlerFnName,
-    cacheKey,
+    pathParams,
+    queryParams = [],
     extractorLines,
     serverArgsStr,
     etagKey,
@@ -47,18 +111,23 @@ export function generateEtagHandler(opts: {
     serviceBinding = "service",
   } = opts;
 
-  const effectiveCacheKey = etagKey ? `"${etagKey}"` : `format!("${cacheKey}")`;
+  const effectiveCacheKey = buildCacheKeyExpression({
+    handlerFnName,
+    etagKey,
+    pathParams,
+    queryParams,
+  });
+  const serviceReceiver = serviceBinding.replace(/^mut\s+/, "");
   const operationExtractors =
     extractorLines.length > 0 ? `${extractorLines.join("\n")}\n` : "";
 
   const finalResponseLogic = `    match result {
         Ok(response) => {
             let mut res = response.into_response();
-            if let Some(stored_etag) = cache.get(cache_key.as_ref()) {
-                res.headers_mut().insert(
-                    axum::http::header::ETAG,
-                    axum::http::HeaderValue::from_str(&stored_etag).unwrap(),
-                );
+            if let Some(stored_etag) = cache.get(cache_key.as_ref()).await
+                && let Ok(etag) = axum::http::HeaderValue::from_str(&stored_etag)
+            {
+                res.headers_mut().insert(axum::http::header::ETAG, etag);
             }
             ${cacheControl ? `res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("${cacheControl}"));` : ""}
             res
@@ -82,16 +151,17 @@ where
 {
     // Check If-None-Match against the cache
     let cache_key = ${effectiveCacheKey};
-    if let (Some(stored_etag), Some(axum_extra::TypedHeader(inm))) = (cache.get(cache_key.as_ref()), if_none_match) {
-        // If the client's ETag matches, respond 304 immediately
-        if stored_etag == format!("{:?}", inm).trim_matches('"') {
-            let mut res = axum::http::StatusCode::NOT_MODIFIED.into_response();
-            ${cacheControl ? `res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("${cacheControl}"));` : ""}
-            return res;
-        }
+    if let (Some(stored_etag), Some(axum_extra::TypedHeader(inm))) =
+        (cache.get(cache_key.as_ref()).await, if_none_match)
+        && let Ok(etag) = stored_etag.parse::<axum_extra::headers::ETag>()
+        && !inm.precondition_passes(&etag)
+    {
+        let mut res = axum::http::StatusCode::NOT_MODIFIED.into_response();
+        ${cacheControl ? `res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("${cacheControl}"));` : ""}
+        return res;
     }
     // Forward to business logic
-    let result = ${serviceBinding}.${handlerFnName}(${serverArgsStr}).await;
+    let result = ${serviceReceiver}.${handlerFnName}(${serverArgsStr}).await;
 ${finalResponseLogic}
 }`;
 }