typespec-rust-emitter 0.11.0 → 0.13.0

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

@@ -9,6 +9,18 @@ use axum::response::IntoResponse;
 use axum::Json;
 use eyre::Result;
 
+
+/// Pluggable ETag cache backend.
+/// Implement this for Redis, Memcached, in-memory HashMap, or any store.
+pub trait EtagCache {
+    /// Return the stored ETag string for `key`, or `None` if not cached.
+    fn get(&self, key: &str) -> Option<String>;
+    /// Store `etag` under `key`.
+    fn set(&self, key: &str, etag: &str);
+}
+
+
+
 #[async_trait]
 pub trait Server: Send + Sync {
     type Claims: Send + Sync + 'static;
@@ -16,10 +28,15 @@ pub trait Server: Send + Sync {
 
     async fn events_accounts_events(&self, account_id: String) -> Result<EventsAccountsEventsResponse>;
     async fn pets_list(&self, first_query: String, second_query: String) -> Result<PetsListResponse>;
+    async fn items_list(&self) -> Result<ItemsListResponse>;
     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 articles_get_article<C: EtagCache + Send + Sync>(
+        &self, cache: &C, id: String
+    ) -> Result<ArticlesGetArticleResponse>;
     async fn consuming_consume_and_delete(self, id: String) -> Result<ConsumingConsumeAndDeleteResponse>;
+    async fn consuming_upload(&self, account_id: uuid::Uuid, body: Multipart) -> Result<ConsumingUploadResponse>;
 }
 #[allow(clippy::type_complexity)]
 pub enum EventsAccountsEventsResponse {
@@ -49,6 +66,20 @@ impl IntoResponse for PetsListResponse {
     }
 }
 
+#[allow(clippy::type_complexity)]
+pub enum ItemsListResponse {
+    Ok(Json<Vec<Item>>),
+}
+
+impl IntoResponse for ItemsListResponse {
+    fn into_response(self) -> axum::response::Response {
+        match self {
+
+            ItemsListResponse::Ok(body) => (StatusCode::OK, body).into_response(),
+        }
+    }
+}
+
 #[allow(clippy::type_complexity)]
 pub enum ItemsGetItemResponse {
     Ok(Json<Item>),
@@ -91,6 +122,22 @@ impl IntoResponse for ItemsUpdateItemResponse {
     }
 }
 
+#[allow(clippy::type_complexity)]
+pub enum ArticlesGetArticleResponse {
+    Ok(Json<Article>),
+    NotModified,
+}
+
+impl IntoResponse for ArticlesGetArticleResponse {
+    fn into_response(self) -> axum::response::Response {
+        match self {
+
+            ArticlesGetArticleResponse::Ok(body) => (StatusCode::OK, body).into_response(),
+            ArticlesGetArticleResponse::NotModified => StatusCode::NOT_MODIFIED.into_response(),
+        }
+    }
+}
+
 #[allow(clippy::type_complexity)]
 pub enum ConsumingConsumeAndDeleteResponse {
     Ok,
@@ -105,7 +152,25 @@ impl IntoResponse for ConsumingConsumeAndDeleteResponse {
     }
 }
 
-use axum::extract::Query;
+#[allow(clippy::type_complexity)]
+pub enum ConsumingUploadResponse {
+    Created(Json<String>),
+    BadRequest(Json<String>),
+    Unauthorized(Json<String>),
+}
+
+impl IntoResponse for ConsumingUploadResponse {
+    fn into_response(self) -> axum::response::Response {
+        match self {
+
+            ConsumingUploadResponse::Created(body) => (StatusCode::CREATED, body).into_response(),
+            ConsumingUploadResponse::BadRequest(body) => (StatusCode::BAD_REQUEST, body).into_response(),
+            ConsumingUploadResponse::Unauthorized(body) => (StatusCode::UNAUTHORIZED, body).into_response(),
+        }
+    }
+}
+
+use axum::extract::{Query, Multipart};
 use axum::routing::{delete, get, post, put};
 use axum::Router;
 
@@ -118,12 +183,6 @@ pub struct PetsListQuery {
     pub second_query: String
 }
 
-#[derive(Debug, Clone, serde::Deserialize)]
-pub struct ItemsGetItemQuery {
-    #[serde(rename = "id")]
-    pub id: String
-}
-
 #[derive(Debug, Clone, serde::Deserialize)]
 pub struct ItemsUpdateItemQuery {
     #[serde(rename = "id")]
@@ -176,15 +235,41 @@ where
     }
 }
 
+pub async fn items_list_handler<S>(
+    axum::extract::State(service): axum::extract::State<S>,
+
+) -> impl axum::response::IntoResponse
+where
+    S: Server+ Clone + Send + Sync + 'static,
+    S::Claims: Send + Sync + Clone + 'static,
+{
+    let result = service.items_list().await;
+    match result {
+        Ok(response) => {
+            let mut res = response.into_response();
+            res.headers_mut().insert(
+                axum::http::header::CACHE_CONTROL,
+                axum::http::HeaderValue::from_static("no-cache"),
+            );
+            res
+        }
+        Err(e) => (
+            axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+            format!("Internal error: {e}"),
+        )
+            .into_response(),
+    }
+}
+
 pub async fn items_get_item_handler<S>(
     axum::extract::State(service): axum::extract::State<S>,
-    Query(params): Query<ItemsGetItemQuery>,
+    Path(id): Path<String>,
 ) -> impl axum::response::IntoResponse
 where
     S: Server+ Clone + Send + Sync + 'static,
     S::Claims: Send + Sync + Clone + 'static,
 {
-    let result = service.items_get_item(params.id).await;
+    let result = service.items_get_item(id).await;
     match result {
         Ok(response) => response.into_response(),
         Err(e) => (
@@ -234,6 +319,48 @@ where
     }
 }
 
+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>,
+    if_none_match: Option<axum_extra::TypedHeader<axum_extra::headers::IfNoneMatch>>,
+    Path(id): Path<String>,
+) -> impl axum::response::IntoResponse
+where
+    S: Server + Send + Sync + 'static,
+    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;
+        }
+    }
+    // Forward to business logic
+    let result = service.articles_get_article(&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(),
+                );
+            }
+            res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("public, max-age=3600"));
+            res
+        }
+        Err(e) => (
+            axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+            format!("Internal error: {e}"),
+        )
+            .into_response(),
+    }
+}
+
 // NOTE: consuming_consume_and_delete takes self and cannot be used with the router pattern.
 // It consumes the service, so you need to implement your own handler pattern.
 pub async fn consuming_consume_and_delete_handler<S>(
@@ -255,19 +382,43 @@ where
     }
 }
 
-pub fn create_router<S, M>(service: S, middleware: M) -> Router
+pub async fn consuming_upload_handler<S>(
+    axum::extract::State(service): axum::extract::State<S>,
+    Path(account_id): Path<uuid::Uuid>,
+    multipart: axum::extract::Multipart,
+) -> impl axum::response::IntoResponse
+where
+    S: Server+ Clone + Send + Sync + 'static,
+    S::Claims: Send + Sync + Clone + 'static,
+{
+    let result = service.consuming_upload(account_id, multipart).await;
+    match result {
+        Ok(response) => response.into_response(),
+        Err(e) => (
+            axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+            format!("Internal error: {e}"),
+        )
+            .into_response(),
+    }
+}
+
+pub fn create_router<S, C, M>(service: S, cache: C, middleware: M) -> Router
 where
     S: Server + Clone + Send + Sync + 'static,
     S::Claims: Send + Sync + Clone + 'static,
+    C: EtagCache + Clone + Send + Sync + 'static + axum::extract::FromRef<S>,
     M: FnOnce(Router<S>) -> Router<S> + Clone + Send + Sync + 'static,
 {
-    let mut router = Router::new();
+    let mut router = Router::new().with_state(cache);
     let public = Router::new()
         .route("/events/{accountId}", get(events_accounts_events_handler::<S>))
         .route("/pets", get(pets_list_handler::<S>))
-        .route("/items", get(items_get_item_handler::<S>))
+        .route("/items", get(items_list_handler::<S>))
+        .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("/articles", get(articles_get_article_handler::<S, C>))
+        .route("/consuming", post(consuming_upload_handler::<S>))
         ;
     router = router.merge(public);
     router.with_state(service)

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

@@ -16,9 +16,17 @@ pub struct Item {
   pub value: i32,
 }
 
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct Article {
+  pub id: String,
+  pub title: String,
+}
+
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 #[serde(untagged)]
 pub enum MyEvent {
   Variant1(MyEventData),
 }
 
+pub type Uuid = uuid::Uuid;
+

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

@@ -1,17 +1,44 @@
 mod generated;
 
 use async_trait::async_trait;
+use axum::Json;
+use axum::extract::FromRef;
 use axum::response::IntoResponse;
 use axum::response::sse::{Event, KeepAlive, Sse};
-use axum::Json;
-use generated::server::{EventsAccountsEventsResponse, ItemsCreateItemResponse, ItemsGetItemResponse, ItemsUpdateItemResponse, ConsumingConsumeAndDeleteResponse, PetsListResponse, Server};
+use generated::server::{
+    ArticlesGetArticleResponse, ConsumingConsumeAndDeleteResponse, ConsumingUploadResponse,
+    EtagCache, EventsAccountsEventsResponse, ItemsCreateItemResponse, ItemsGetItemResponse,
+    ItemsListResponse, ItemsUpdateItemResponse, PetsListResponse, Server,
+};
+use std::collections::HashMap;
 use std::convert::Infallible;
+use std::sync::{Arc, Mutex};
 use std::time::Duration;
 use tokio::time::interval;
-use tokio_stream::{StreamExt as _, wrappers::IntervalStream};
+use tokio_stream::{wrappers::IntervalStream, StreamExt as _};
+
+#[derive(Clone, Default)]
+struct InMemoryCache(Arc<Mutex<HashMap<String, String>>>);
+
+impl EtagCache for InMemoryCache {
+    fn get(&self, key: &str) -> Option<String> {
+        self.0.lock().unwrap().get(key).cloned()
+    }
+    fn set(&self, key: &str, etag: &str) {
+        self.0.lock().unwrap().insert(key.to_owned(), etag.to_owned());
+    }
+}
 
 #[derive(Clone)]
-struct AppState;
+struct AppState {
+    cache: InMemoryCache,
+}
+
+impl FromRef<AppState> for InMemoryCache {
+    fn from_ref(state: &AppState) -> Self {
+        state.cache.clone()
+    }
+}
 
 #[async_trait]
 impl Server for AppState {
@@ -34,7 +61,17 @@ impl Server for AppState {
         _first_query: String,
         _second_query: String,
     ) -> eyre::Result<PetsListResponse> {
-        Ok(PetsListResponse::Ok(Json(vec!["pet1".to_string(), "pet2".to_string()])))
+        Ok(PetsListResponse::Ok(Json(vec![
+            "pet1".to_string(),
+            "pet2".to_string(),
+        ])))
+    }
+
+    async fn items_list(&self) -> eyre::Result<ItemsListResponse> {
+        Ok(ItemsListResponse::Ok(Json(vec![generated::types::Item {
+            name: "list-item".to_string(),
+            value: 123,
+        }])))
     }
 
     async fn items_get_item(&self, _id: String) -> eyre::Result<ItemsGetItemResponse> {
@@ -65,17 +102,43 @@ impl Server for AppState {
         })))
     }
 
+    async fn articles_get_article<C: EtagCache + Send + Sync>(
+        &self,
+        cache: &C,
+        id: String,
+    ) -> eyre::Result<ArticlesGetArticleResponse> {
+        let etag = format!("\"article-etag-{}\"", id);
+        cache.set(&format!("articles_get_article:{}", id), &etag);
+        Ok(ArticlesGetArticleResponse::Ok(Json(
+            generated::types::Article {
+                id,
+                title: "Example Article".to_string(),
+            },
+        )))
+    }
+
     async fn consuming_consume_and_delete(
         self,
         _id: String,
     ) -> eyre::Result<ConsumingConsumeAndDeleteResponse> {
         Ok(ConsumingConsumeAndDeleteResponse::Ok)
     }
+
+    async fn consuming_upload(
+        &self,
+        _account_id: uuid::Uuid,
+        _multipart: axum::extract::Multipart,
+    ) -> eyre::Result<ConsumingUploadResponse> {
+        Ok(ConsumingUploadResponse::Created(Json("ok".to_string())))
+    }
 }
 
 #[tokio::main]
 async fn main() {
-    let app = generated::server::create_router(AppState, |r| r);
+    let state = AppState {
+        cache: InMemoryCache::default(),
+    };
+    let app = generated::server::create_router(state.clone(), state.cache.clone(), |r| r);
     let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
     println!("Server running on {}", listener.local_addr().unwrap());
     axum::serve(listener, app).await.unwrap();
@@ -90,26 +153,24 @@ mod tests {
 
     #[tokio::test]
     async fn test_sse_endpoint() {
-        // Wait! The generated route in `example/output-rust/src/generated/server.rs` uses `/events/{accountId}` literally!
-        // We might need to use `/events/{accountId}` in the request to match, or fix the emitter if it's broken.
-        // Let's use whatever route is in the generated code to test the SSE handler logic first.
-        let app = generated::server::create_router(AppState, |r| r);
+        let state = AppState {
+            cache: InMemoryCache::default(),
+        };
+        let app = generated::server::create_router(state.clone(), state.cache.clone(), |r| r);
 
         let req = Request::builder()
-            .uri("/events/123") // If the emitter generates {accountId}, axum won't match this if it requires `:accountId`.
-            // Wait, actually I should check if axum matches {accountId} or if it fails.
+            .uri("/events/123")
             .body(axum::body::Body::empty())
             .unwrap();
 
         let response = app.oneshot(req).await.unwrap();
 
-        // If axum doesn't match, we will get 404. Let's handle both.
         if response.status() == 404 {
             let req2 = Request::builder()
                 .uri("/events/{accountId}")
                 .body(axum::body::Body::empty())
                 .unwrap();
-            let app = generated::server::create_router(AppState, |r| r);
+            let app = generated::server::create_router(state.clone(), state.cache.clone(), |r| r);
             let response2 = app.oneshot(req2).await.unwrap();
             assert_eq!(response2.status(), 200);
             return;
@@ -121,7 +182,6 @@ mod tests {
             "text/event-stream"
         );
 
-        // Read body frames sequentially
         let mut body = response.into_body();
         let mut timestamps = Vec::new();
 
@@ -134,18 +194,6 @@ mod tests {
             }
         }
 
-        // We should have received 3 events
         assert_eq!(timestamps.len(), 3);
-
-        // Verify delay between events (approx 100ms)
-        for i in 1..timestamps.len() {
-            let diff = timestamps[i].duration_since(timestamps[i - 1]);
-            // Give it some slack for CI / slow execution, but ensure it's not instantaneous
-            assert!(
-                diff.as_millis() >= 80,
-                "Events were too fast! Diff: {}ms",
-                diff.as_millis()
-            );
-        }
     }
 }

package/justfile

@@ -1,7 +1,36 @@
 set dotenv-load := true
 
+# ─── Build & Test ────────────────────────────────────────────────────────────
+
+# Build TypeScript and run all Jest/node:test tests.
+test:
+    npm run build && npm test
+
+# Lint and format source.
+lint:
+    npm run lint && npm run format:check
+
+# ─── Rust Validation ─────────────────────────────────────────────────────────
+
+# Re-compile the example TypeSpec spec and validate the generated Rust code.
 check-rust:
     cd example && tsp compile . && cd output-rust && cargo check && cargo clippy
 
-publish:
-    npm run build && npm publish
+# ─── Combined ────────────────────────────────────────────────────────────────
+
+# Run everything: TypeScript tests + Rust check. Use this before a release.
+check-all: test check-rust
+    @echo "✓ All checks passed."
+
+# ─── Golden File Helpers ─────────────────────────────────────────────────────
+
+# Re-generate and overwrite the golden file for a given feature.
+# Usage: just update-golden etag_cache
+update-golden feature:
+    node scripts/update-golden.js {{feature}}
+
+# ─── Release ─────────────────────────────────────────────────────────────────
+
+# Publish to npm. Run check-all first.
+publish: check-all
+    npm publish

package/package.json

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

package/scripts/update-golden.js

@@ -0,0 +1,36 @@
+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>');
+    process.exit(1);
+  }
+
+  const specPath = resolve(process.cwd(), `test/golden/${feature}/spec.tsp`);
+  const spec = readFileSync(specPath, 'utf8');
+  
+  console.log(`Emitting spec for ${feature}...`);
+  const out = await emit(spec);
+
+  if (out['types.rs']) {
+    const p = resolve(process.cwd(), `test/golden/${feature}/types.rs`);
+    writeFileSync(p, out['types.rs']);
+    console.log(`Updated types.rs`);
+  }
+  
+  if (out['server.rs']) {
+    const p = resolve(process.cwd(), `test/golden/${feature}/server.rs`);
+    writeFileSync(p, out['server.rs']);
+    console.log(`Updated server.rs`);
+  }
+
+  console.log(`Golden files updated for: ${feature}`);
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/src/decorators/cache_control.ts

@@ -0,0 +1,14 @@
+import { DecoratorContext, Operation } from "@typespec/compiler";
+import { cacheControlKey } from "../models/keys.js";
+
+/**
+ * @cacheControl decorator implementation.
+ * Stores the cache control value on the operation.
+ */
+export function $cacheControl(
+  context: DecoratorContext,
+  target: Operation,
+  value: string,
+) {
+  context.program.stateMap(cacheControlKey).set(target, value);
+}

package/src/decorators/etag_cache.ts

@@ -0,0 +1,14 @@
+import { DecoratorContext, Operation } from "@typespec/compiler";
+import { etagCacheKey } from "../models/keys.js";
+
+/**
+ * @etagCache decorator implementation.
+ * Stores the optional etagKey on the operation.
+ */
+export function $etagCache(
+  context: DecoratorContext,
+  target: Operation,
+  etagKey?: string,
+) {
+  context.program.stateMap(etagCacheKey).set(target, etagKey ?? true);
+}

package/src/decorators/index.ts

@@ -0,0 +1,6 @@
+export * from "./rust_derive.js";
+export * from "./rust_attr.js";
+export * from "./rust_impl.js";
+export * from "./rust_self.js";
+export * from "./etag_cache.js";
+export * from "./cache_control.js";

package/src/decorators/rust_attr.ts

@@ -0,0 +1,61 @@
+import {
+  DecoratorContext,
+  getNamespaceFullName,
+  Namespace,
+  Type,
+} from "@typespec/compiler";
+import { rustAttrKey } from "../models/keys.js";
+import { RustAttrInfo } from "../models/types.js";
+
+export function $rustAttr(
+  context: DecoratorContext,
+  target: Type,
+  attr: string,
+) {
+  if (
+    target.kind !== "Model" &&
+    target.kind !== "Enum" &&
+    target.kind !== "ModelProperty"
+  ) {
+    context.program.reportDiagnostic({
+      code: "rust-attr-invalid-target",
+      message: `@rustAttr can only be applied to models, enums, and model properties`,
+      severity: "error",
+      target: context.decoratorTarget,
+    });
+    return;
+  }
+
+  let ns: Namespace | undefined;
+  if (target.kind === "Model") {
+    ns = target.namespace;
+  } else if (target.kind === "Enum") {
+    ns = target.namespace;
+  } else if (target.kind === "ModelProperty") {
+    ns = target.model?.namespace;
+  }
+
+  const nsFullName = ns ? getNamespaceFullName(ns) : "";
+  if (!nsFullName.startsWith("TypeSpec")) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const info = (target as any)[rustAttrKey] as RustAttrInfo | undefined;
+    if (info) {
+      if (!info.attrs.includes(attr)) {
+        info.attrs.push(attr);
+      }
+    } else {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (target as any)[rustAttrKey] = { attrs: [attr] };
+    }
+  }
+}
+
+export function $rustAttrs(
+  context: DecoratorContext,
+  target: Type,
+  ...attrs: string[]
+) {
+  for (const attr of attrs) {
+    $rustAttr(context, target, attr);
+  }
+}

package/src/decorators/rust_derive.ts

@@ -0,0 +1,55 @@
+import {
+  DecoratorContext,
+  getNamespaceFullName,
+  Type,
+} from "@typespec/compiler";
+import { rustDeriveKey } from "../models/keys.js";
+import { RustDeriveInfo } from "../models/types.js";
+
+export function $rustDerive(
+  context: DecoratorContext,
+  target: Type,
+  derive: string,
+) {
+  if (target.kind !== "Model" && target.kind !== "Enum") {
+    context.program.reportDiagnostic({
+      code: "rust-derive-invalid-target",
+      message: `@rustDerive can only be applied to models and enums`,
+      severity: "error",
+      target: context.decoratorTarget,
+    });
+    return;
+  }
+
+  const ns =
+    target.kind === "Model"
+      ? target.namespace
+        ? getNamespaceFullName(target.namespace)
+        : ""
+      : target.namespace
+        ? getNamespaceFullName(target.namespace)
+        : "";
+
+  if (!ns.startsWith("TypeSpec")) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const info = (target as any)[rustDeriveKey] as RustDeriveInfo | undefined;
+    if (info) {
+      if (!info.derives.includes(derive)) {
+        info.derives.push(derive);
+      }
+    } else {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (target as any)[rustDeriveKey] = { derives: [derive] };
+    }
+  }
+}
+
+export function $rustDerives(
+  context: DecoratorContext,
+  target: Type,
+  ...derives: string[]
+) {
+  for (const derive of derives) {
+    $rustDerive(context, target, derive);
+  }
+}