typespec-rust-emitter 0.12.0 → 0.13.1

package/src/formatter/index.ts

@@ -0,0 +1,2 @@
+export * from "./strings.js";
+export * from "./mappings.js";

package/src/formatter/mappings.ts

@@ -0,0 +1,70 @@
+export const scalarToRust: Record<string, string> = {
+  string: "String",
+  int8: "i8",
+  int16: "i16",
+  int32: "i32",
+  int64: "i64",
+  uint8: "u8",
+  uint16: "u16",
+  uint32: "u32",
+  uint64: "u64",
+  float32: "f32",
+  float64: "f64",
+  boolean: "bool",
+  bytes: "Vec<u8>",
+  plainDate: "chrono::NaiveDate",
+  plainTime: "chrono::NaiveTime",
+  utcDateTime: "chrono::DateTime<chrono::Utc>",
+  offsetDateTime: "chrono::DateTime<chrono::FixedOffset>",
+  plainDateTime: "chrono::NaiveDateTime",
+  duration: "String",
+  numeric: "f64",
+  integer: "i64",
+  float: "f64",
+  safeint: "i64",
+  decimal: "f64",
+  decimal128: "f64",
+  url: "String",
+};
+
+export const formatToRust: Record<string, string> = {
+  uuid: "uuid::Uuid",
+  date: "chrono::NaiveDate",
+  time: "chrono::NaiveTime",
+  dateTime: "chrono::DateTime<chrono::Utc>",
+  "date-time": "chrono::DateTime<chrono::Utc>",
+};
+
+export function getStatusVariantName(code: number): string {
+  const map: Record<number, string> = {
+    200: "Ok",
+    201: "Created",
+    202: "Accepted",
+    204: "NoContent",
+    304: "NotModified",
+    400: "BadRequest",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "NotFound",
+    409: "Conflict",
+    500: "InternalServerError",
+  };
+  return map[code] ?? `Status${code}`;
+}
+
+export function getHttpStatusCode(code: number): string {
+  const map: Record<number, string> = {
+    200: "StatusCode::OK",
+    201: "StatusCode::CREATED",
+    202: "StatusCode::ACCEPTED",
+    204: "StatusCode::NO_CONTENT",
+    304: "StatusCode::NOT_MODIFIED",
+    400: "StatusCode::BAD_REQUEST",
+    401: "StatusCode::UNAUTHORIZED",
+    403: "StatusCode::FORBIDDEN",
+    404: "StatusCode::NOT_FOUND",
+    409: "StatusCode::CONFLICT",
+    500: "StatusCode::INTERNAL_SERVER_ERROR",
+  };
+  return map[code] ?? `StatusCode::from_u16(${code}).unwrap()`;
+}

package/src/formatter/strings.ts

@@ -0,0 +1,33 @@
+export function toRustIdent(name: string): string {
+  const snakeCase = name.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+  const result = snakeCase.replace(/[^a-z0-9_]/g, "_");
+  if (/^[0-9]/.test(result)) {
+    return "_" + result;
+  }
+  return result;
+}
+
+export function toPascalCase(name: string): string {
+  if (/^[^a-z]+$/.test(name)) {
+    return name;
+  }
+  if (/[-_]/.test(name)) {
+    return name
+      .split(/[-_]/)
+      .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+      .join("");
+  }
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+export function toRustVariantName(name: string): string {
+  return toPascalCase(name);
+}
+
+export function formatDoc(doc: string | undefined): string {
+  if (!doc) return "";
+  return doc
+    .split("\n")
+    .map((line) => `/// ${line.trim()}`)
+    .join("\n");
+}

package/src/generator/etag_router.ts

@@ -0,0 +1,97 @@
+/**
+ * generateEtagCacheTrait
+ *
+ * Returns the Rust source for the EtagCache trait.
+ * Called once per server.rs when at least one operation uses @etagCache.
+ */
+export function generateEtagCacheTrait(): string {
+  return `/// 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);
+}
+`;
+}
+
+/**
+ * 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 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;
+  extractorLines: string[];
+  serverArgsStr: string;
+  responseName: string;
+  etagKey?: string;
+  cacheControl?: string;
+  serviceBinding?: string;
+}): string {
+  const {
+    handlerFnName,
+    cacheKey,
+    extractorLines,
+    serverArgsStr,
+    etagKey,
+    cacheControl,
+    serviceBinding = "service",
+  } = opts;
+
+  const effectiveCacheKey = etagKey ? `"${etagKey}"` : `format!("${cacheKey}")`;
+  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(),
+                );
+            }
+            ${cacheControl ? `res.headers_mut().insert(axum::http::header::CACHE_CONTROL, axum::http::HeaderValue::from_static("${cacheControl}"));` : ""}
+            res
+        }
+        Err(e) => (
+            axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+            format!("Internal error: {e}"),
+        )
+            .into_response(),
+    }`;
+
+  return `pub async fn ${handlerFnName}_handler<S, C>(
+    axum::extract::State(${serviceBinding}): axum::extract::State<S>,
+    axum::extract::State(cache): axum::extract::State<C>,
+    if_none_match: Option<axum_extra::TypedHeader<axum_extra::headers::IfNoneMatch>>,
+${operationExtractors}) -> 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 = ${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;
+        }
+    }
+    // Forward to business logic
+    let result = ${serviceBinding}.${handlerFnName}(${serverArgsStr}).await;
+${finalResponseLogic}
+}`;
+}

package/src/generator/index.ts

@@ -0,0 +1,5 @@
+export * from "./types_file.js";
+export * from "./server_trait.js";
+export * from "./response_enums.js";
+export * from "./router.js";
+export * from "./etag_router.js";

package/src/generator/response_enums.ts

@@ -0,0 +1,76 @@
+import { Operation, Program, Namespace } from "@typespec/compiler";
+import { AnonymousStringLiteralUnion } from "../models/types.js";
+import { toPascalCase } from "../formatter/strings.js";
+import { emitOperationInfo } from "../parser/operations.js";
+import {
+  getStatusVariantName,
+  getHttpStatusCode,
+} from "../formatter/mappings.js";
+
+export function generateResponseEnums(
+  program: Program,
+  namespaceGroups: { namespace: Namespace; operations: Operation[] }[],
+  anonymousEnums: Map<string, AnonymousStringLiteralUnion>,
+): string {
+  const parts: string[] = [];
+
+  for (const group of namespaceGroups) {
+    const nsName = toPascalCase(
+      group.namespace.name.replace(/[^a-zA-Z0-9_]/g, "_"),
+    );
+
+    for (const op of group.operations) {
+      const opInfo = emitOperationInfo(program, op, "", anonymousEnums);
+      if (!opInfo) continue;
+
+      if (opInfo.responses.length === 0) continue;
+
+      const responseName = `${nsName}${toPascalCase(opInfo.name)}Response`;
+
+      const variants: string[] = [];
+      for (const resp of opInfo.responses) {
+        const variantName = getStatusVariantName(resp.statusCode);
+        if (!resp.bodyType) {
+          variants.push(`    ${variantName},`);
+        } else if (resp.isSse) {
+          variants.push(`    ${variantName}(${resp.bodyType}),`);
+        } else {
+          variants.push(`    ${variantName}(Json<${resp.bodyType}>),`);
+        }
+      }
+      parts.push(`#[allow(clippy::type_complexity)]
+pub enum ${responseName} {
+${variants.join("\n")}
+}
+`);
+
+      parts.push(`impl IntoResponse for ${responseName} {
+    fn into_response(self) -> axum::response::Response {
+        match self {
+`);
+      for (const resp of opInfo.responses) {
+        const variantName = getStatusVariantName(resp.statusCode);
+        const statusCodeStr = getHttpStatusCode(resp.statusCode);
+        if (!resp.bodyType) {
+          parts.push(
+            `            ${responseName}::${variantName} => ${statusCodeStr}.into_response(),`,
+          );
+        } else if (resp.isSse) {
+          parts.push(
+            `            ${responseName}::${variantName}(body) => body.into_response(),`,
+          );
+        } else {
+          parts.push(
+            `            ${responseName}::${variantName}(body) => (${statusCodeStr}, body).into_response(),`,
+          );
+        }
+      }
+      parts.push(`        }
+    }
+}
+`);
+    }
+  }
+
+  return parts.join("\n");
+}

package/src/generator/router.ts

@@ -0,0 +1,284 @@
+import { Operation, Program, Namespace } from "@typespec/compiler";
+import { AnonymousStringLiteralUnion } from "../models/types.js";
+import { toPascalCase, toRustIdent } from "../formatter/strings.js";
+import {
+  emitOperationInfo,
+  hasAuthDecorator,
+  getSelfReceiver,
+  hasEtagCache,
+} from "../parser/operations.js";
+import { getFullRoute } from "../parser/routes.js";
+import { getRustTypeForProperty } from "../parser/types.js";
+import { hasMultipartBody } from "../parser/parameters.js";
+import { generateEtagHandler } from "./etag_router.js";
+
+export function generateRouter(
+  program: Program,
+  namespaceGroups: { namespace: Namespace; operations: Operation[] }[],
+  anonymousEnums: Map<string, AnonymousStringLiteralUnion>,
+): string {
+  const handlers: string[] = [];
+  const queryTypeStructs: string[] = [];
+  const publicRoutes: string[] = [];
+  const protectedRoutes: string[] = [];
+  const usedMethods = new Set<string>();
+
+  const hasEtag = namespaceGroups.some((g) =>
+    g.operations.some((o) => hasEtagCache(program, o)),
+  );
+
+  for (const group of namespaceGroups) {
+    const nsRoute = getFullRoute(program, group.namespace);
+    if (!nsRoute) continue;
+
+    const nsName = toPascalCase(
+      group.namespace.name.replace(/[^a-zA-Z0-9_]/g, "_"),
+    );
+
+    for (const op of group.operations) {
+      const opInfo = emitOperationInfo(program, op, nsRoute, anonymousEnums);
+      if (!opInfo) continue;
+
+      const method = opInfo.method.toLowerCase();
+      usedMethods.add(method);
+
+      const handlerFnName = toRustIdent(`${nsName}_${opInfo.name}`);
+      const traitFnName = handlerFnName;
+      const isProtected = hasAuthDecorator(op);
+      const selfReceiver = getSelfReceiver(op);
+
+      const pathParams = opInfo.parameters.filter((p) => p.location === "path");
+      const hasPathParams = pathParams.length > 0;
+      const queryParams = opInfo.parameters.filter(
+        (p) => p.location === "query",
+      );
+      const hasQueryParams = queryParams.length > 0;
+      const hasBody = !!opInfo.body;
+      const isMultipartBody = hasMultipartBody(op);
+
+      const extractorLines: string[] = [];
+      const serverArgs: string[] = [];
+
+      const serviceBinding =
+        selfReceiver === "&mut self" ? "mut service" : "service";
+
+      if (isProtected) {
+        extractorLines.push(`    Extension(claims): Extension<S::Claims>,`);
+        serverArgs.push(`claims`);
+      }
+
+      if (hasPathParams) {
+        const pathTypes = pathParams.map((p) => p.rustType).join(", ");
+        const pathFields = pathParams.map((p) => p.rustName).join(", ");
+        if (pathParams.length === 1) {
+          extractorLines.push(`    Path(${pathFields}): Path<${pathTypes}>,`);
+        } else {
+          extractorLines.push(
+            `    Path((${pathFields})): Path<(${pathTypes})>,`,
+          );
+        }
+        for (const param of pathParams) {
+          serverArgs.push(param.rustName);
+        }
+      }
+
+      if (hasQueryParams && queryParams.length > 0) {
+        const queryTypeName = `${toPascalCase(handlerFnName)}Query`;
+        const queryFields = queryParams
+          .map(
+            (p) =>
+              `    #[serde(rename = "${p.name}")]\n    pub ${p.rustName}: ${p.rustType}`,
+          )
+          .join(",\n");
+        queryTypeStructs.push(
+          `#[derive(Debug, Clone, serde::Deserialize)]\npub struct ${queryTypeName} {\n${queryFields}\n}`,
+        );
+        extractorLines.push(`    Query(params): Query<${queryTypeName}>,`);
+        for (const param of queryParams) {
+          serverArgs.push(`params.${param.rustName}`);
+        }
+      }
+
+      if (hasBody && opInfo.body) {
+        if (isMultipartBody) {
+          extractorLines.push(`    multipart: axum::extract::Multipart,`);
+          serverArgs.push(`multipart`);
+        } else {
+          const bodyType = getRustTypeForProperty(
+            opInfo.body.type,
+            program,
+            anonymousEnums,
+          );
+          extractorLines.push(`    Json(payload): Json<${bodyType.type}>,`);
+          serverArgs.push(`payload`);
+        }
+      }
+
+      const serverArgsStr = serverArgs.join(", ");
+
+      if (hasEtagCache(program, op)) {
+        const cacheKey = `${handlerFnName}:${pathParams.map((p) => `{${p.rustName}}`).join(":")}`;
+        const cachedServerArgs = isProtected
+          ? [serverArgs[0], "&cache", ...serverArgs.slice(1)]
+          : ["&cache", ...serverArgs];
+        const code = generateEtagHandler({
+          handlerFnName,
+          cacheKey,
+          extractorLines,
+          serverArgsStr: cachedServerArgs.join(", "),
+          responseName: `${nsName}${toPascalCase(opInfo.name)}Response`,
+          etagKey: opInfo.etagKey,
+          cacheControl: opInfo.cacheControl,
+          serviceBinding,
+        });
+        handlers.push(code);
+        const routePath = `"${opInfo.path}"`;
+        const routeStmt = `.route(${routePath}, ${method}(${handlerFnName}_handler::<S, C>))`;
+        if (isProtected) {
+          protectedRoutes.push(routeStmt);
+        } else {
+          publicRoutes.push(routeStmt);
+        }
+        continue;
+      }
+
+      const serverCall = `service.${traitFnName}(${serverArgsStr}).await`;
+
+      let responseHandling = opInfo.cacheControl
+        ? `match result {
+        Ok(response) => {
+            let mut res = response.into_response();
+            res.headers_mut().insert(
+                axum::http::header::CACHE_CONTROL,
+                axum::http::HeaderValue::from_static("${opInfo.cacheControl}"),
+            );
+            res
+        }
+        Err(e) => (
+            axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+            format!("Internal error: {e}"),
+        )
+            .into_response(),
+    }`
+        : `match result {
+        Ok(response) => response.into_response(),
+        Err(e) => (
+            axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+            format!("Internal error: {e}"),
+        )
+            .into_response(),
+    }`;
+
+      const needsClone = selfReceiver !== "self" ? "+ Clone" : "";
+      const handlerCode =
+        selfReceiver === "self"
+          ? `// NOTE: ${handlerFnName} 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 ${handlerFnName}_handler<S>(
+    axum::extract::State(service): axum::extract::State<S>,
+${extractorLines.join("\n")}
+) -> impl axum::response::IntoResponse
+where
+    S: Server + Send + Sync + 'static,
+    S::Claims: Send + Sync + Clone + 'static,
+{
+    let result = service.${traitFnName}(${serverArgsStr}).await;
+    ${responseHandling}
+}`
+          : `pub async fn ${handlerFnName}_handler<S>(
+    axum::extract::State(${serviceBinding}): axum::extract::State<S>,
+${extractorLines.join("\n")}
+) -> impl axum::response::IntoResponse
+where
+    S: Server${needsClone} + Send + Sync + 'static,
+    S::Claims: Send + Sync + Clone + 'static,
+{
+    let result = ${serverCall};
+    ${responseHandling}
+}`;
+
+      handlers.push(handlerCode);
+
+      if (selfReceiver === "self") {
+        continue;
+      }
+
+      const routePath = `"${opInfo.path}"`;
+      let routeStmt = "";
+      if (isProtected) {
+        routeStmt = `.route(${routePath}, ${method}(${handlerFnName}_handler::<S>))`;
+        protectedRoutes.push(routeStmt);
+      } else {
+        routeStmt = `.route(${routePath}, ${method}(${handlerFnName}_handler::<S>))`;
+        publicRoutes.push(routeStmt);
+      }
+    }
+  }
+
+  const methodImports = Array.from(usedMethods).sort().join(", ");
+
+  const routerBody = buildRouterBody(publicRoutes, protectedRoutes);
+
+  const parts: string[] = [];
+  parts.push(`use axum::extract::{Query, Multipart};
+use axum::routing::{${methodImports}};
+use axum::Router;
+
+`);
+  if (queryTypeStructs.length > 0) {
+    parts.push(queryTypeStructs.join("\n\n"));
+    parts.push("\n\n");
+  }
+  parts.push(handlers.join("\n\n"));
+
+  if (hasEtag) {
+    parts.push(`
+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,
+{
+${routerBody.replace("Router::new()", "Router::new().with_state(cache)")}
+}`);
+  } else {
+    parts.push(`
+pub fn create_router<S, M>(service: S, middleware: M) -> Router
+where
+    S: Server + Clone + Send + Sync + 'static,
+    S::Claims: Send + Sync + Clone + 'static,
+    M: FnOnce(Router<S>) -> Router<S> + Clone + Send + Sync + 'static,
+{
+${routerBody}
+}`);
+  }
+
+  return parts.join("\n");
+}
+
+export function buildRouterBody(
+  publicRoutes: string[],
+  protectedRoutes: string[],
+): string {
+  const lines: string[] = [];
+  lines.push("    let mut router = Router::new();");
+  if (publicRoutes.length > 0) {
+    lines.push("    let public = Router::new()");
+    for (const r of publicRoutes) {
+      lines.push(`        ${r.trim()}`);
+    }
+    lines.push("        ;");
+    lines.push("    router = router.merge(public);");
+  }
+  if (protectedRoutes.length > 0) {
+    lines.push("    let protected = Router::new()");
+    for (const r of protectedRoutes) {
+      lines.push(`        ${r.trim()}`);
+    }
+    lines.push("        ;");
+    lines.push("    router = router.merge(middleware(protected));");
+  }
+  lines.push("    router.with_state(service)");
+  return lines.join("\n");
+}