Server Auth. Make non-optional principal.

[zibet27]

Subsystem
Server Auth

Motivation
KTOR-8594 Auth: Non-optional principal is of nullable type

Solution
Added dsl

 authenticate<UserPrincipal>("auth") {
   get("/user") { principal ->
      call.respondText("Hello, ${principal.name}")
   }
   post<UserPrincipal, String>("/user") { principal, body ->
      call.respondText("Hello, ${principal.name}, you said $body")
   }
}

Will automatically return HttpStatusCode.Unauthorized if no principal is provided.

[coderabbitai]

Walkthrough

Adds a value-class wrapper AuthenticatedRoute<P : Any> and many Route extension helpers to declare principal-aware routes (authenticate, method/route helpers, HTTP verb variants, typed body overloads). Includes tests and corresponding public API surface expansions for authentication, OpenAPI sources, JSON Schema nullable, and Zstd encoders.

Changes

Cohort / File(s)	Summary
AuthenticatedRoute implementation ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticatedRoute.kt	New value class AuthenticatedRoute<P : Any> plus Route.authenticate(...) and many principal-aware routing helpers (route, method, get/post/put/patch/delete/options/head) including typed body overloads and reified generics. Handlers respond Unauthorized when principal absent.
AuthenticatedRoute tests ktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthenticatedRouteTest.kt	New tests (AuthenticatedRouteTest) and UserPrincipal validating authenticated and unauthorized flows across multiple HTTP methods and nested routes.
Auth public API surface ktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.api, .../ktor-server-auth.klib.api	Adds io.ktor.server.auth.AuthenticatedRoute public class and extensive inline/reified extension signatures for authenticate, principal accessors, and AuthenticatedRoute method overloads; updates AuthenticationFailedCause variants in klib API.
OpenAPI routing sources API ktor-server/ktor-server-plugins/ktor-server-routing-openapi/api/ktor-server-routing-openapi.api	Adds new OpenApiDocSource companion and data-like types (FileSource, OpenApiDocText, RoutingSource) and new getters/options on existing OpenApiDocSource variants.
OpenAPI schema annotations ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api	Adds io.ktor.openapi.JsonSchema$Nullable annotation and synthetic implementation class.
Zstd encoder utilities ktor-utils/api/ktor-utils.api	Adds public io.ktor.util.Zstd and io.ktor.util.ZstdEncoder classes with encode/decode methods and encoder metadata.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested labels

👍 ship!

Suggested reviewers

• osipxd
• e5l
• bjhham

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly references the main change: making principals non-optional in the Server Auth subsystem, which is the core objective of this PR.
Description check	✅ Passed	The description includes all required template sections with detailed information about the subsystem, motivation (with ticket reference), and solution (with concrete code examples).

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In
`@ktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthenticatedRouteTest.kt`:
- Around line 181-183: The two assertions use assertEquals with arguments in the
wrong order; swap the parameters so expected comes first: change
assertEquals(response.status, HttpStatusCode.Unauthorized) to
assertEquals(HttpStatusCode.Unauthorized, response.status) (leave
assertEquals("", response.bodyAsText()) as-is), updating the assertions in the
AuthenticatedRouteTest test where the local variable response is used.

🧹 Nitpick comments (2)

ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticatedRoute.kt (1)

7-11: Consider using star imports for io.ktor.* packages.

Per the coding guidelines, star imports should be used for io.ktor.* packages.

Suggested imports

-import io.ktor.http.*
-import io.ktor.server.request.*
-import io.ktor.server.response.respond
-import io.ktor.server.routing.*
+import io.ktor.http.*
+import io.ktor.server.request.*
+import io.ktor.server.response.*
+import io.ktor.server.routing.*

ktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthenticatedRouteTest.kt (1)

7-23: Consider using star imports for io.ktor.* packages.

Per the coding guidelines, star imports should be used for io.ktor.* packages.

Suggested imports

-import io.ktor.client.request.*
-import io.ktor.client.statement.*
-import io.ktor.http.HttpStatusCode
-import io.ktor.server.auth.Authentication
-import io.ktor.server.auth.authenticate
-import io.ktor.server.auth.basic
-import io.ktor.server.auth.delete
-import io.ktor.server.auth.get
-import io.ktor.server.auth.head
-import io.ktor.server.auth.options
-import io.ktor.server.auth.patch
-import io.ktor.server.auth.post
-import io.ktor.server.auth.put
-import io.ktor.server.auth.route
-import io.ktor.server.response.*
-import io.ktor.server.testing.*
+import io.ktor.client.request.*
+import io.ktor.client.statement.*
+import io.ktor.http.*
+import io.ktor.server.auth.*
+import io.ktor.server.response.*
+import io.ktor.server.testing.*

[bjhham]

I think we could use a little discussion for the design here. Maybe not a full KLIP but a thread in #ktor-team. Introducing a new set of route DSL functions with new lambda arguments seems a little problematic.

[bjhham]

You got some outdated ABI, looks like you need a clean