Update HttpApi to remove wildcard support for better OpenAPI compat… (

#4245)

.changeset/fifty-pears-occur.md

@@ -0,0 +1,21 @@
+---
+"@effect/platform": minor
+---
+
+Update `HttpApi` to remove wildcard support for better OpenAPI compatibility.
+
+The `HttpApi*` modules previously reused the following type from `HttpRouter`:
+
+```ts
+type PathInput = `/${string}` | "*"
+```
+
+However, the `"*"` wildcard value was not handled correctly, as OpenAPI does not support wildcards.
+
+This has been updated to use a more specific type:
+
+```ts
+type PathSegment = `/${string}`
+```
+
+This change ensures better alignment with OpenAPI specifications and eliminates potential issues related to unsupported wildcard paths.

packages/platform/src/HttpApi.ts

@@ -15,7 +15,6 @@ import type * as HttpApiGroup from "./HttpApiGroup.js"
 import type * as HttpApiMiddleware from "./HttpApiMiddleware.js"
 import * as HttpApiSchema from "./HttpApiSchema.js"
 import type { HttpMethod } from "./HttpMethod.js"
-import type { PathInput } from "./HttpRouter.js"
 
 /**
  * @since 1.0.0
@@ -85,7 +84,7 @@ export interface HttpApi<
   /**
    * Prefix all endpoints in the `HttpApi`.
    */
-  prefix(prefix: PathInput): HttpApi<Id, Groups, E, R>
+  prefix(prefix: HttpApiEndpoint.PathSegment): HttpApi<Id, Groups, E, R>
   /**
    * Add a middleware to a `HttpApi`. It will be applied to all endpoints in the
    * `HttpApi`.
@@ -194,7 +193,7 @@ const Proto = {
       middlewares: this.middlewares
     })
   },
-  prefix(this: HttpApi.AnyWithProps, prefix: PathInput) {
+  prefix(this: HttpApi.AnyWithProps, prefix: HttpApiEndpoint.PathSegment) {
     return makeProto({
       identifier: this.identifier,
       groups: Record.map(this.groups, (group) => group.prefix(prefix)),

packages/platform/src/HttpApiBuilder.ts

@@ -945,7 +945,7 @@ export const middlewareCors = (
  */
 export const middlewareOpenApi = (
   options?: {
-    readonly path?: HttpRouter.PathInput | undefined
+    readonly path?: HttpApiEndpoint.PathSegment | undefined
   } | undefined
 ): Layer.Layer<never, never, HttpApi.Api> =>
   Router.use((router) =>

packages/platform/src/HttpApiEndpoint.ts

@@ -33,6 +33,15 @@ export type TypeId = typeof TypeId
  */
 export const isHttpApiEndpoint = (u: unknown): u is HttpApiEndpoint<any, any, any> => Predicate.hasProperty(u, TypeId)
 
+/**
+ * Represents a path segment. A path segment is a string that represents a
+ * segment of a URL path.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export type PathSegment = `/${string}`
+
 /**
  * Represents an API endpoint. An API endpoint is mapped to a single route on
  * the underlying `HttpRouter`.
@@ -54,7 +63,7 @@ export interface HttpApiEndpoint<
 > extends Pipeable {
   readonly [TypeId]: TypeId
   readonly name: Name
-  readonly path: HttpRouter.PathInput
+  readonly path: PathSegment
   readonly method: Method
   readonly pathSchema: Option.Option<Schema.Schema<Path, unknown, R>>
   readonly urlParamsSchema: Option.Option<Schema.Schema<UrlParams, unknown, R>>
@@ -194,7 +203,7 @@ export interface HttpApiEndpoint<
    * Add a prefix to the path of the endpoint.
    */
   prefix(
-    prefix: HttpRouter.PathInput
+    prefix: PathSegment
   ): HttpApiEndpoint<Name, Method, Path, UrlParams, Payload, Headers, Success, Error, R, RE>
 
   /**
@@ -743,10 +752,10 @@ const Proto = {
       headersSchema: Option.some(schema)
     })
   },
-  prefix(this: HttpApiEndpoint.AnyWithProps, prefix: HttpRouter.PathInput) {
+  prefix(this: HttpApiEndpoint.AnyWithProps, prefix: PathSegment) {
     return makeProto({
       ...this,
-      path: HttpRouter.prefixPath(this.path, prefix) as HttpRouter.PathInput
+      path: HttpRouter.prefixPath(this.path, prefix) as PathSegment
     })
   },
   middleware(this: HttpApiEndpoint.AnyWithProps, middleware: HttpApiMiddleware.TagClassAny) {
@@ -783,7 +792,7 @@ const makeProto = <
   RE
 >(options: {
   readonly name: Name
-  readonly path: HttpRouter.PathInput
+  readonly path: PathSegment
   readonly method: Method
   readonly pathSchema: Option.Option<Schema.Schema<Path, unknown, R>>
   readonly urlParamsSchema: Option.Option<Schema.Schema<UrlParams, unknown, R>>
@@ -802,9 +811,9 @@ const makeProto = <
  */
 export const make = <Method extends HttpMethod>(method: Method): {
   <const Name extends string>(name: Name): HttpApiEndpoint.Constructor<Name, Method>
-  <const Name extends string>(name: Name, path: HttpRouter.PathInput): HttpApiEndpoint<Name, Method>
+  <const Name extends string>(name: Name, path: PathSegment): HttpApiEndpoint<Name, Method>
 } =>
-  ((name: string, ...args: [HttpRouter.PathInput]) => {
+  ((name: string, ...args: [PathSegment]) => {
     if (args.length === 1) {
       return makeProto({
         name,
@@ -821,7 +830,7 @@ export const make = <Method extends HttpMethod>(method: Method): {
       })
     }
     return (segments: TemplateStringsArray, ...schemas: ReadonlyArray<HttpApiSchema.AnyString>) => {
-      let path = segments[0] as HttpRouter.PathInput
+      let path = segments[0] as PathSegment
       let pathSchema = Option.none<Schema.Schema.Any>()
       if (schemas.length > 0) {
         const obj: Record<string, Schema.Schema.Any> = {}
@@ -857,7 +866,7 @@ export const get: {
   <const Name extends string>(name: Name): HttpApiEndpoint.Constructor<Name, "GET">
   <const Name extends string>(
     name: Name,
-    path: HttpRouter.PathInput
+    path: PathSegment
   ): HttpApiEndpoint<Name, "GET">
 } = make("GET")
 
@@ -869,7 +878,7 @@ export const post: {
   <const Name extends string>(name: Name): HttpApiEndpoint.Constructor<Name, "POST">
   <const Name extends string>(
     name: Name,
-    path: HttpRouter.PathInput
+    path: PathSegment
   ): HttpApiEndpoint<Name, "POST">
 } = make("POST")
 
@@ -881,7 +890,7 @@ export const put: {
   <const Name extends string>(name: Name): HttpApiEndpoint.Constructor<Name, "PUT">
   <const Name extends string>(
     name: Name,
-    path: HttpRouter.PathInput
+    path: PathSegment
   ): HttpApiEndpoint<Name, "PUT">
 } = make("PUT")
 
@@ -893,7 +902,7 @@ export const patch: {
   <const Name extends string>(name: Name): HttpApiEndpoint.Constructor<Name, "PATCH">
   <const Name extends string>(
     name: Name,
-    path: HttpRouter.PathInput
+    path: PathSegment
   ): HttpApiEndpoint<Name, "PATCH">
 } = make(
   "PATCH"
@@ -907,7 +916,7 @@ export const del: {
   <const Name extends string>(name: Name): HttpApiEndpoint.Constructor<Name, "DELETE">
   <const Name extends string>(
     name: Name,
-    path: HttpRouter.PathInput
+    path: PathSegment
   ): HttpApiEndpoint<Name, "DELETE">
 } = make(
   "DELETE"

packages/platform/src/HttpApiGroup.ts

@@ -10,7 +10,6 @@ import type * as HttpApiEndpoint from "./HttpApiEndpoint.js"
 import type { HttpApiDecodeError } from "./HttpApiError.js"
 import type * as HttpApiMiddleware from "./HttpApiMiddleware.js"
 import * as HttpApiSchema from "./HttpApiSchema.js"
-import type { PathInput } from "./HttpRouter.js"
 
 /**
  * @since 1.0.0
@@ -77,7 +76,7 @@ export interface HttpApiGroup<
    * Add a path prefix to all endpoints in an `HttpApiGroup`. Note that this will only
    * add the prefix to the endpoints before this api is called.
    */
-  prefix(prefix: PathInput): HttpApiGroup<Id, Endpoints, Error, R, TopLevel>
+  prefix(prefix: HttpApiEndpoint.PathSegment): HttpApiGroup<Id, Endpoints, Error, R, TopLevel>
 
   /**
    * Add an `HttpApiMiddleware` to the `HttpApiGroup`.
@@ -315,7 +314,7 @@ const Proto = {
       middlewares: this.middlewares
     })
   },
-  prefix(this: HttpApiGroup.AnyWithProps, prefix: PathInput) {
+  prefix(this: HttpApiGroup.AnyWithProps, prefix: HttpApiEndpoint.PathSegment) {
     return makeProto({
       identifier: this.identifier,
       topLevel: this.topLevel,

packages/platform/test/OpenApi.test.ts

@@ -734,37 +734,6 @@ describe("OpenApi", () => {
         )
         expectPaths(api, ["/prefix1", "/prefix2/a"])
       })
-
-      it("wildcard: *", () => {
-        const api = HttpApi.make("api").add(
-          HttpApiGroup.make("group").add(
-            HttpApiEndpoint.get("get", "*")
-              .addSuccess(Schema.String)
-          )
-        )
-        // TODO: better handle wildcard paths
-        expectSpecPaths(api, {
-          "*": {
-            "get": {
-              "tags": ["group"],
-              "operationId": "group.get",
-              "parameters": [],
-              "security": [],
-              "responses": {
-                "200": {
-                  "description": "a string",
-                  "content": {
-                    "application/json": {
-                      "schema": { "type": "string" }
-                    }
-                  }
-                },
-                "400": HttpApiDecodeError
-              }
-            }
-          }
-        })
-      })
     })
 
     describe("HttpApiEndpoint.get", () => {