v4.4.2

.changeset/quick-routes-rank.md

@@ -0,0 +1,6 @@
+---
+'@cleverbrush/server': patch
+---
+
+Prefer the most specific matching HTTP or WebSocket route instead of allowing
+an earlier generic dynamic route to shadow a more literal route.

libs/server-integration-tests/tests/integration.test.ts

@@ -903,3 +903,38 @@ describe('withHealthcheck()', () => {
         expect(builder.withHealthcheck()).toBe(builder);
     });
 });
+
+// ===========================================================================
+// Route specificity
+// ===========================================================================
+
+describe('Route specificity', () => {
+    let server: Server;
+
+    afterEach(async () => {
+        await server?.close();
+    });
+
+    it('dispatches to the most specific handler regardless of registration order', async () => {
+        const SessionPath = route({ id: string() })`/${t => t.id}`;
+        const QuestionPath = route({ id: string() })`/${t => t.id}/question`;
+        const session = endpoint.get('/sessions', SessionPath);
+        const question = endpoint.get('/sessions', QuestionPath);
+
+        server = await createServer()
+            .handle(session, ({ params }) => ({
+                handler: 'session',
+                id: params.id
+            }))
+            .handle(question, ({ params }) => ({
+                handler: 'question',
+                id: params.id
+            }))
+            .listen(0);
+
+        const res = await request(server, 'GET', '/sessions/984/question');
+
+        expect(res.status).toBe(200);
+        expect(json(res)).toEqual({ handler: 'question', id: '984' });
+    });
+});

libs/server/README.md

@@ -97,6 +97,12 @@ server.handle(GetUser, ({ params }) => {
 });
 ```
 
+When several route schemas validate the same URL, the server selects the most
+specific route independently of registration order. Exact static routes win,
+followed by routes with more literal path segments and then fewer dynamic
+segments. Registration order only breaks ties between equally specific routes.
+The same precedence applies to WebSocket subscriptions.
+
 ### Authorization
 
 ```ts