@typespec/http-specs 0.1.0-alpha.0

package/specs/routes/main.tsp

@@ -0,0 +1,477 @@
+import "@typespec/http";
+import "@typespec/spector";
+
+using Http;
+using Spector;
+
+/**
+ * Define scenario in building the http route/uri
+ */
+@scenarioService("/routes")
+namespace Routes;
+
+@scenario
+@scenarioDoc("""
+  Simple operation at a fixed in an interface
+    Expected path: /routes/fixed
+  """)
+@route("fixed")
+op fixed(): void;
+
+@scenario
+@scenarioDoc("""
+  Simple operation at a fixed in an interface
+    Expected path: /routes/in-interface/fixed
+  """)
+@route("in-interface")
+interface InInterface {
+  @route("fixed")
+  fixed(): void;
+}
+
+@route("path")
+namespace PathParameters {
+  @scenario
+  @scenarioDoc("""
+    Path parameter defined implicitly
+      Value: "a"
+      Expected path: /routes/path/template-only/a
+    """)
+  @route("template-only/{param}")
+  op templateOnly(param: string): void;
+
+  @scenario
+  @scenarioDoc("""
+    Path parameter defined explicitly
+      Value: "a"
+      Expected path: /routes/path/explicit/a
+    """)
+  @route("explicit/{param}")
+  op explicit(@path param: string): void;
+
+  @scenario
+  @scenarioDoc("""
+    Path parameter annotated with @path but not defined explicitly in the route
+      Value: "a"
+      Expected path: /routes/path/annotation-only/a
+    """)
+  @route("annotation-only")
+  op annotationOnly(@path param: string): void;
+
+  @route("reserved-expansion")
+  namespace ReservedExpansion {
+    @scenario
+    @scenarioDoc("""
+      Defines a path parameter that shouldn't encode reserved characters. It should however still encode the other url characters.
+        Param value: "foo/bar baz"
+        Expected path: "/routes/path/reserved-expansion/template/foo/bar%20baz"
+      """)
+    @route("template/{+param}")
+    op template(param: string): void;
+
+    @scenario
+    @scenarioDoc("""
+      Defines a path parameter that shouldn't encode reserved characters. It should however still encode the other url characters.
+        Param value: "foo/bar baz"
+        Expected path: "/routes/path/reserved-expansion/annotation/foo/bar%20baz"
+      """)
+    @route("annotation")
+    op annotation(@path(#{ allowReserved: true }) param: string): void;
+  }
+
+  @route("simple")
+  namespace SimpleExpansion {
+    @route("standard")
+    namespace Standard {
+      @scenario
+      @scenarioDoc("""
+        Test simple expansion with explode: false when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/simple/standard/primitivea
+        """)
+      @route("primitive{param}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test simple expansion with explode: false when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/simple/standard/arraya,b
+        """)
+      @route("array{param}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test simple expansion with explode: false when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/simple/standard/recorda,1,b,2
+        """)
+      @route("record{param}")
+      op record(param: Record<int32>): void;
+    }
+
+    @route("explode")
+    namespace Explode {
+      @scenario
+      @scenarioDoc("""
+        Test simple expansion with explode: true when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/simple/explode/primitivea
+        """)
+      @route("primitive{param*}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test simple expansion with explode: true when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/simple/explode/arraya.b
+        """)
+      @route("array{param*}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test simple expansion with explode: true when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/simple/explode/recorda=1,b=2
+        """)
+      @route("record{param*}")
+      op record(param: Record<int32>): void;
+    }
+  }
+
+  @route("path")
+  namespace PathExpansion {
+    @route("standard")
+    namespace Standard {
+      @scenario
+      @scenarioDoc("""
+        Test path expansion with explode: false when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/path/standard/primitive/a
+        """)
+      @route("primitive{/param}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test path expansion with explode: false when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/path/standard/array/a,b
+        """)
+      @route("array{/param}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test path expansion with explode: false when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/path/standard/record/a,1,b,2
+        """)
+      @route("record{/param}")
+      op record(param: Record<int32>): void;
+    }
+
+    @route("explode")
+    namespace Explode {
+      @scenario
+      @scenarioDoc("""
+        Test path expansion with explode: true when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/path/explode/primitive/a
+        """)
+      @route("primitive{/param*}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test path expansion with explode: true when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/path/explode/array/a/b
+        """)
+      @route("array{/param*}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test path expansion with explode: true when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/path/explode/record/a=1/b=2
+        """)
+      @route("record{/param*}")
+      op record(param: Record<int32>): void;
+    }
+  }
+
+  @route("label")
+  namespace LabelExpansion {
+    @route("standard")
+    namespace Standard {
+      @scenario
+      @scenarioDoc("""
+        Test label expansion with explode: false when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/label/standard/primitive.a
+        """)
+      @route("primitive{.param}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test label expansion with explode: false when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/label/standard/array.a,b
+        """)
+      @route("array{.param}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test label expansion with explode: false when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/label/standard/record.a,1,b,2
+        """)
+      @route("record{.param}")
+      op record(param: Record<int32>): void;
+    }
+
+    @route("explode")
+    namespace Explode {
+      @scenario
+      @scenarioDoc("""
+        Test label expansion with explode: true when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/label/explode/primitive.a
+        """)
+      @route("primitive{.param*}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test label expansion with explode: true when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/label/explode/array.a.b
+        """)
+      @route("array{.param*}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test label expansion with explode: true when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/label/explode/record.a=1.b=2
+        """)
+      @route("record{.param*}")
+      op record(param: Record<int32>): void;
+    }
+  }
+
+  @route("matrix")
+  namespace MatrixExpansion {
+    @route("standard")
+    namespace Standard {
+      @scenario
+      @scenarioDoc("""
+        Test matrix expansion with explode: false when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/matrix/standard/primitive;a
+        """)
+      @route("primitive{;param}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test matrix expansion with explode: false when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/matrix/standard/array;a,b
+        """)
+      @route("array{;param}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test matrix expansion with explode: false when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/matrix/standard/record;a,1,b,2
+        """)
+      @route("record{;param}")
+      op record(param: Record<int32>): void;
+    }
+
+    @route("explode")
+    namespace Explode {
+      @scenario
+      @scenarioDoc("""
+        Test matrix expansion with explode: true when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/matrix/explode/primitive;a
+        """)
+      @route("primitive{;param*}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test matrix expansion with explode: true when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/matrix/explode/array;a.b
+        """)
+      @route("array{;param*}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test matrix expansion with explode: true when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/matrix/explode/record;a=1;b=2
+        """)
+      @route("record{;param*}")
+      op record(param: Record<int32>): void;
+    }
+  }
+}
+
+@route("query")
+namespace QueryParameters {
+  @scenario
+  @scenarioDoc("Query parameter defined implicitly")
+  @route("template-only{?param}")
+  op templateOnly(param: string): void;
+
+  @scenario
+  @scenarioDoc("Query parameter marked with explicit @query")
+  @route("explicit{?param}")
+  op explicit(@query param: string): void;
+
+  @scenario
+  @scenarioDoc("Query parameter annotated with @query but not defined explicitly in the route")
+  @route("annotation-only")
+  op annotationOnly(@query param: string): void;
+
+  @route("query-expansion")
+  namespace QueryExpansion {
+    @route("standard")
+    namespace Standard {
+      @scenario
+      @scenarioDoc("""
+        Test query expansion with explode: false when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/query/query-expansion/standard/primitive?param=a
+        """)
+      @route("primitive{?param}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query expansion with explode: false when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/query/query-expansion/standard/array?param=a,b
+        """)
+      @route("array{?param}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query expansion with explode: false when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/query/query-expansion/standard/record?param=a,1,b,2
+        """)
+      @route("record{?param}")
+      op record(param: Record<int32>): void;
+    }
+
+    @route("explode")
+    namespace Explode {
+      @scenario
+      @scenarioDoc("""
+        Test query expansion with explode: true when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/query/query-expansion/explode/primitive?param=a
+        """)
+      @route("primitive{?param*}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query expansion with explode: true when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/query/query-expansion/explode/array?param=a&param=b
+        """)
+      @route("array{?param*}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query expansion with explode: true when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/query/query-expansion/explode/record?a=1&b=2
+        """)
+      @route("record{?param*}")
+      op record(param: Record<int32>): void;
+    }
+  }
+
+  @route("query-continuation")
+  namespace QueryContinuation {
+    @route("standard")
+    namespace Standard {
+      @scenario
+      @scenarioDoc("""
+        Test query continuation expansion with explode: false when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/query/query-continuation/standard/primitive?fixed=true&param=a
+        """)
+      @route("primitive?fixed=true{&param}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query continuation expansion with explode: false when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/query/query-continuation/standard/array?fixed=true&param=a,b
+        """)
+      @route("array?fixed=true{&param}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query continuation expansion with explode: false when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/query/query-continuation/standard/record?fixed=true&param=a,1,b,2
+        """)
+      @route("record?fixed=true{&param}")
+      op record(param: Record<int32>): void;
+    }
+
+    @route("explode")
+    namespace Explode {
+      @scenario
+      @scenarioDoc("""
+        Test query continuation expansion with explode: true when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/query/query-continuation/explode/primitive?fixed=true&param=a
+        """)
+      @route("primitive?fixed=true{&param*}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query continuation expansion with explode: true when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/query/query-continuation/explode/array?fixed=true&param=a&param=b
+        """)
+      @route("array?fixed=true{&param*}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query continuation expansion with explode: true when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/query/query-continuation/explode/record?fixed=true&a=1&b=2
+        """)
+      @route("record?fixed=true{&param*}")
+      op record(param: Record<int32>): void;
+    }
+  }
+}

package/specs/routes/mockapi.ts

@@ -0,0 +1,175 @@
+import { MockRequest, passOnSuccess, ScenarioMockApi, ValidationError } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+function createTests(uri: string) {
+  const url = new URL("http://example.com" + uri);
+  const queryMap = new Map<string, string | string[]>();
+  for (const [key, value] of url.searchParams.entries()) {
+    if (queryMap.has(key)) {
+      const existing = queryMap.get(key)!;
+      if (Array.isArray(existing)) {
+        existing.push(value);
+      } else {
+        queryMap.set(key, [existing, value]);
+      }
+    } else {
+      queryMap.set(key, value);
+    }
+  }
+  return passOnSuccess({
+    uri: url.pathname,
+    method: "get",
+    request: {
+      params: Object.fromEntries(queryMap),
+    },
+    response: {
+      status: 204,
+    },
+    handler: (req: MockRequest) => {
+      for (const [key, value] of queryMap.entries()) {
+        if (Array.isArray(value)) {
+          req.expect.containsQueryParam(key, value, "multi");
+        } else {
+          req.expect.containsQueryParam(key, value);
+        }
+      }
+      for (const param of Object.keys(req.query)) {
+        if (!url.searchParams.has(param)) {
+          throw new ValidationError(
+            `Unexpected query parameter ${param}`,
+            undefined,
+            req.query[param],
+          );
+        }
+      }
+      return { status: 204 };
+    },
+    kind: "MockApiDefinition",
+  });
+}
+
+Scenarios.Routes_InInterface = createTests("/routes/fixed");
+Scenarios.Routes_fixed = createTests("/routes/in-interface/fixed");
+Scenarios.Routes_PathParameters_templateOnly = createTests("/routes/path/template-only/a");
+Scenarios.Routes_PathParameters_explicit = createTests("/routes/path/explicit/a");
+Scenarios.Routes_PathParameters_annotationOnly = createTests("/routes/path/annotation-only/a");
+Scenarios.Routes_PathParameters_ReservedExpansion_template = createTests(
+  "/routes/path/reserved-expansion/template/foo/bar%20baz",
+);
+Scenarios.Routes_PathParameters_ReservedExpansion_annotation = createTests(
+  "/routes/path/reserved-expansion/annotation/foo/bar%20baz",
+);
+Scenarios.Routes_PathParameters_SimpleExpansion_Standard_primitive = createTests(
+  "/routes/simple/standard/primitivea",
+);
+Scenarios.Routes_PathParameters_SimpleExpansion_Standard_array = createTests(
+  "/routes/simple/standard/arraya,b",
+);
+Scenarios.Routes_PathParameters_SimpleExpansion_Standard_record = createTests(
+  "/routes/simple/standard/recorda,1,b,2",
+);
+Scenarios.Routes_PathParameters_SimpleExpansion_Explode_primitive = createTests(
+  "/routes/simple/standard/primitivea",
+);
+Scenarios.Routes_PathParameters_SimpleExpansion_Explode_array = createTests(
+  "/routes/simple/standard/arraya,b",
+);
+Scenarios.Routes_PathParameters_SimpleExpansion_Explode_record = createTests(
+  "/routes/simple/standard/recorda=1,b=2",
+);
+Scenarios.Routes_PathParameters_PathExpansion_Standard_primitive = createTests(
+  "/routes/path/standard/primitive/a",
+);
+Scenarios.Routes_PathParameters_PathExpansion_Standard_array = createTests(
+  "/routes/path/standard/array/a,b",
+);
+Scenarios.Routes_PathParameters_PathExpansion_Standard_record = createTests(
+  "/routes/path/standard/record/a,1,b,2",
+);
+Scenarios.Routes_PathParameters_PathExpansion_Explode_primitive = createTests(
+  "/routes/path/standard/primitive/a",
+);
+Scenarios.Routes_PathParameters_PathExpansion_Explode_array = createTests(
+  "/routes/path/standard/array/a/b",
+);
+Scenarios.Routes_PathParameters_PathExpansion_Explode_record = createTests(
+  "/routes/path/standard/record/a=1/b=2",
+);
+Scenarios.Routes_PathParameters_LabelExpansion_Standard_primitive = createTests(
+  "/routes/label/standard/primitive.a",
+);
+Scenarios.Routes_PathParameters_LabelExpansion_Standard_array = createTests(
+  "/routes/label/standard/array.a,b",
+);
+Scenarios.Routes_PathParameters_LabelExpansion_Standard_record = createTests(
+  "/routes/label/standard/record.a,1,b,2",
+);
+Scenarios.Routes_PathParameters_LabelExpansion_Explode_primitive = createTests(
+  "/routes/label/standard/primitive.a",
+);
+Scenarios.Routes_PathParameters_LabelExpansion_Explode_array = createTests(
+  "/routes/label/standard/array.a.b",
+);
+Scenarios.Routes_PathParameters_LabelExpansion_Explode_record = createTests(
+  "/routes/label/standard/record.a=1.b=2",
+);
+Scenarios.Routes_PathParameters_MatrixExpansion_Standard_primitive = createTests(
+  "/routes/matrix/standard/primitive;a",
+);
+Scenarios.Routes_PathParameters_MatrixExpansion_Standard_array = createTests(
+  "/routes/matrix/standard/array;a,b",
+);
+Scenarios.Routes_PathParameters_MatrixExpansion_Standard_record = createTests(
+  "/routes/matrix/standard/record;a,1,b,2",
+);
+Scenarios.Routes_PathParameters_MatrixExpansion_Explode_primitive = createTests(
+  "/routes/matrix/standard/primitive;a",
+);
+Scenarios.Routes_PathParameters_MatrixExpansion_Explode_array = createTests(
+  "/routes/matrix/standard/array;a;b",
+);
+Scenarios.Routes_PathParameters_MatrixExpansion_Explode_record = createTests(
+  "/routes/matrix/standard/record;a=1;b=2",
+);
+Scenarios.Routes_QueryParameters_templateOnly = createTests("/routes/query/template-only?param=a");
+Scenarios.Routes_QueryParameters_explicit = createTests("/routes/query/explicit?param=a");
+Scenarios.Routes_QueryParameters_annotationOnly = createTests(
+  "/routes/query/annotation-only?param=a",
+);
+Scenarios.Routes_QueryParameters_QueryExpansion_Standard_primitive = createTests(
+  "/routes/query/query-expansion/standard/primitive?param=a",
+);
+Scenarios.Routes_QueryParameters_QueryExpansion_Standard_array = createTests(
+  "/routes/query/query-expansion/standard/array?param=a,b",
+);
+Scenarios.Routes_QueryParameters_QueryExpansion_Standard_record = createTests(
+  "/routes/query/query-expansion/standard/record?param=a,1,b,2",
+);
+Scenarios.Routes_QueryParameters_QueryExpansion_Explode_primitive = createTests(
+  "/routes/query/query-expansion/explode/primitive?param=a",
+);
+Scenarios.Routes_QueryParameters_QueryExpansion_Explode_array = createTests(
+  "/routes/query/query-expansion/explode/array?param=a&param=b",
+);
+Scenarios.Routes_QueryParameters_QueryExpansion_Explode_record = createTests(
+  "/routes/query/query-expansion/explode/record?a=1&b=2",
+);
+Scenarios.Routes_QueryParameters_QueryContinuation_Standard_primitive = createTests(
+  "/routes/query/query-continuation/standard/primitive?fixed=true&param=a",
+);
+Scenarios.Routes_QueryParameters_QueryContinuation_Standard_array = createTests(
+  "/routes/query/query-continuation/standard/array?fixed=true&param=a,b",
+);
+Scenarios.Routes_QueryParameters_QueryContinuation_Standard_record = createTests(
+  "/routes/query/query-continuation/standard/record?fixed=true&param=a,1,b,2",
+);
+Scenarios.Routes_QueryParameters_QueryContinuation_Explode_primitive = createTests(
+  "/routes/query/query-continuation/explode/primitive?fixed=true&param=a",
+);
+Scenarios.Routes_QueryParameters_QueryContinuation_Explode_array = createTests(
+  "/routes/query/query-continuation/explode/array?fixed=true&param=a&param=b",
+);
+Scenarios.Routes_QueryParameters_QueryContinuation_Explode_record = createTests(
+  "/routes/query/query-continuation/explode/record?fixed=true&a=1&b=2",
+);

package/specs/scratch/.gitignore

@@ -0,0 +1,3 @@
+# This directory reserved for creating scratch *.tsp for testing/experimentation
+**/*
+!.gitignore