KTOR-9085 Infer security schemes from Authentication plugin
#5244
Conversation
WalkthroughAdds optional provider descriptions and description-aware overloads across authentication providers, exposes provider/session keys and provider listings, makes OAuth providerLookup nullable with settings fallback, introduces OpenAPI security-scheme model and registration/inference APIs, and adds related tests and synthetic API entries. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Points to focus on:
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
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. Comment |
zibet27
force-pushed
the
zibet27/open-api-auth
branch
from
c528817 to
e248449
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (11)
ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.kt (1)
13-14: Consider adding KDoc for the newly public API.The
@InternalAPIannotation is correctly applied per coding guidelines. However, since this is now a public API (even if internal), consider adding brief documentation explaining its purpose and warning about stability.+/** + * Attribute key used to store session providers in the application attributes. + * Can be used to retrieve registered session providers for documentation generation. + */ @InternalAPI public val SessionProvidersKey: AttributeKey<List<SessionProvider<*>>> = AttributeKey("SessionProvidersKey")ktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.kt (1)
11-14: LGTM! No-op implementation is appropriate for non-JVM platforms.The implementation correctly returns
nullfor non-JVM platforms where platform-specific metadata isn't available for inferring security schemes from authentication providers. This aligns with the comment and is the expected behavior for platforms without JVM reflection capabilities.Optional improvement: Consider adding KDoc to document this platform-specific behavior, even though it's an internal function. This would help clarify the multiplatform contract, especially since the PR objectives note that "behavior on non-JVM platforms is uncertain."
Example KDoc:
+/** + * Infers a security scheme from the authentication provider using platform-specific metadata. + * @return null on non-JVM platforms as platform-specific metadata is not available. + */ internal actual fun Application.inferPlatformSpecificSecurityScheme(provider: AuthenticationProvider): SecurityScheme? { // No platform-specific metadata for authentication providers on non-JVM platforms. return null }ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/SessionTrackerById.kt (1)
7-10: InternalAPI import is correct; consider aligning with star-import conventionImporting
io.ktor.utils.io.InternalAPIis correct for using the opt‑in annotation. If./gradlew formatKotlindoesn’t already normalize this, consider switching toimport io.ktor.utils.io.*to match the “use star imports forio.ktor.*packages” guideline.ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/SecurityScheme.kt (1)
92-130: Add KDoc for OAuth2SecurityScheme and OpenIdConnectSecuritySchemeUnlike the other new public types,
OAuth2SecuritySchemeandOpenIdConnectSecuritySchemelack KDoc. To comply with the guideline that all public APIs be documented, consider adding brief class-level docs (and, if useful, property tags) mirroring the style used forHttpSecuritySchemeandApiKeySecurityScheme.ktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.api (1)
416-429: Clarify expectations around OAuth static settings and nullability
OAuthAuthenticationProvider.Confignow exposessettingsandOAuthProcedureKt.staticSettings(provider)returns a non-nullOAuthServerSettings, while provider lookup is also still configurable. To avoid surprising runtime behavior:
- Ensure it is clearly documented whether
settingsis required (and whetherstaticSettingsthrows if it’s missing) versus optional.- Consider validating configuration eagerly (e.g., at provider installation) so a misconfigured provider (no
settingsand noproviderLookup, or incompatible type) fails fast rather than leading to silent skips at use sites.
These semantics are important now that OpenAPI inference depends on static settings.Also applies to: 479-486, 505-526
ktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/OAuth.kt (1)
10-17: Handle misconfigured OAuth providers more explicitlyUsing
providerLookup?.invoke(call) ?: settingsmakes sense, but if both arenullor yield a non-OAuth1a settings instance,oauth1awill just return without issuing a challenge, effectively disabling auth on that route. If that scenario is considered misconfiguration rather than “no auth”, consider failing fast (e.g., throwing during provider setup or logging a warning) so it’s detectable instead of silently skipping authentication.ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt (2)
197-258:HttpClientinstances are not closed after use.The
HttpClient()instances created at lines 210 and 225 are never closed, which can cause resource leaks. While this may be acceptable in test code since the JVM terminates, it's a good practice to close clients.Consider closing the clients or using
testApplication's client:- oauth("oauth-no-desc") { - urlProvider = { "http://localhost/callback" } - settings = OAuthServerSettings.OAuth2ServerSettings( - name = "test", - authorizeUrl = "https://auth.example.com/authorize", - accessTokenUrl = "https://auth.example.com/token", - clientId = "client", - clientSecret = "secret", - defaultScopes = listOf("profile", "email") - ) - client = HttpClient() - } + oauth("oauth-no-desc") { + urlProvider = { "http://localhost/callback" } + settings = OAuthServerSettings.OAuth2ServerSettings( + name = "test", + authorizeUrl = "https://auth.example.com/authorize", + accessTokenUrl = "https://auth.example.com/token", + clientId = "client", + clientSecret = "secret", + defaultScopes = listOf("profile", "email") + ) + client = this@testApplication.client + }
109-113: Consider moving test data classes to a shared location or making them private.The
UserSessionandApiSessionclasses are defined inside the test class but are public. If they're only used within this test file, consider making themprivateto reduce unnecessary public API surface in test code.- @Serializable - data class UserSession(val userId: String) - - @Serializable - data class ApiSession(val token: String) + @Serializable + private data class UserSession(val userId: String) + + @Serializable + private data class ApiSession(val token: String)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.kt (1)
212-215: Missing KDoc documentation for newly public API.The
allProviders()function is now public but lacks KDoc documentation. As per coding guidelines, all public APIs should include documentation with parameters, return types, and exceptions.+/** + * Returns all registered authentication providers. + * + * @return A map of provider names to their [AuthenticationProvider] instances, + * where `null` key represents the default provider. + */ @OptIn(InternalAPI::class) public fun AuthenticationConfig.allProviders(): Map<String?, AuthenticationProvider> { return providers }ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (2)
31-38: Variable shadowing reduces clarity.The local
providerNameshadows the parameter with the same name. Consider using a distinct name.public fun Application.registerSecurityScheme( providerName: String?, securityScheme: SecurityScheme ) { - val providerName = providerName ?: AuthenticationRouteSelector.DEFAULT_NAME + val resolvedName = providerName ?: AuthenticationRouteSelector.DEFAULT_NAME val existingSchemes = attributes.getOrNull(AuthenticationSecuritySchemesAttributeKey) ?: emptyMap() - attributes.put(AuthenticationSecuritySchemesAttributeKey, existingSchemes + (providerName to securityScheme)) + attributes.put(AuthenticationSecuritySchemesAttributeKey, existingSchemes + (resolvedName to securityScheme)) }
102-121: Minor code duplication in transport handling.The transport type is checked twice - once for
keyLocationand once forkeyName. Consider consolidating.is SessionAuthenticationProvider<*> -> { val sessionProvider = attributes.getOrNull(SessionProvidersKey)?.firstOrNull { it.type == provider.type } ?: return null - val keyLocation = when (sessionProvider.transport) { - is SessionTransportCookie -> SecuritySchemeIn.COOKIE - is SessionTransportHeader -> SecuritySchemeIn.HEADER - else -> return null - } - val keyName = when (val t = sessionProvider.transport) { - is SessionTransportCookie -> t.name - is SessionTransportHeader -> t.name - else -> return null - } + val (keyLocation, keyName) = when (val t = sessionProvider.transport) { + is SessionTransportCookie -> SecuritySchemeIn.COOKIE to t.name + is SessionTransportHeader -> SecuritySchemeIn.HEADER to t.name + else -> return null + } ApiKeySecurityScheme(
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (33)
ktor-server/ktor-server-plugins/ktor-server-auth-jwt/api/ktor-server-auth-jwt.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.kt(6 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.api(15 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.klib.api(15 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/Authentication.kt(3 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.kt(9 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationProvider.kt(4 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.kt(4 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BearerAuth.kt(4 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/DynamicProviderConfig.kt(2 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/FormAuth.kt(5 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthCommon.kt(5 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt(7 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/SessionAuth.kt(3 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/DigestAuth.kt(6 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/OAuth.kt(2 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api(2 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.klib.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/src/io/ktor/annotate/SecuritySchemeAnnotation.jvm.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-sessions/api/ktor-server-sessions.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-sessions/api/ktor-server-sessions.klib.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/SessionTrackerById.kt(3 hunks)ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.kt(3 hunks)ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api(9 hunks)ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api(7 hunks)ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/JsonSchema.kt(2 hunks)ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.kt(6 hunks)ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/SecurityScheme.kt(1 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
**/*.kt
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.kt: Follow Kotlin official style guide (https://kotlinlang.org/docs/coding-conventions.html)
Use star imports forio.ktor.*packages
Document all public APIs including parameters, return types, and exceptions
Mark internal APIs with@InternalAPIannotation
Run./gradlew lintKotlinand fix all linting issues before giving control back to the user
Use./gradlew formatKotlinto automatically fix formatting issues
Run./gradlew updateLegacyAbiafter making ABI changes to update ABI signature files
Binary compatibility is enforced - all public API changes must be tracked in the/api/directories
Validate ABI with./gradlew checkLegacyAbiand update with./gradlew updateLegacyAbi
API changes must be intentional and well-documented
Error handling follows Kotlin conventions with specific Ktor exceptions
Files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.ktktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/SessionTrackerById.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/DynamicProviderConfig.ktktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/OAuth.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationProvider.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/src/io/ktor/annotate/SecuritySchemeAnnotation.jvm.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/FormAuth.ktktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/SecurityScheme.ktktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.ktktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/DigestAuth.ktktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/JsonSchema.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/SessionAuth.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthCommon.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/Authentication.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BearerAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.kt
**/test/**/*.kt
📄 CodeRabbit inference engine (CLAUDE.md)
Follow test naming pattern:
DescribeWhatIsBeingTested
Files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt
🧠 Learnings (20)
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Mark internal APIs with `InternalAPI` annotation
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/SessionTrackerById.ktktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.ktsktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api
📚 Learning: 2025-05-14T18:05:02.321Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 4855
File: ktor-server/ktor-server-plugins/ktor-server-di/api/ktor-server-di.klib.api:334-336
Timestamp: 2025-05-14T18:05:02.321Z
Learning: Breaking changes in constructor parameter order are acceptable for the ktor-server-di module when the code hasn't been released yet, as confirmed by the development team.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/DynamicProviderConfig.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.ktktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.ktsktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/DigestAuth.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.apiktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthCommon.ktktor-server/ktor-server-plugins/ktor-server-sessions/api/ktor-server-sessions.klib.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-06-23T12:49:56.883Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-06-23T12:49:56.883Z
Learning: Error handling should follow Kotlin conventions and use specific Ktor exceptions.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/DynamicProviderConfig.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationProvider.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/FormAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/DigestAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/SessionAuth.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthCommon.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/Authentication.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BearerAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Error handling follows Kotlin conventions with specific Ktor exceptions
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/DynamicProviderConfig.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationProvider.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/FormAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/DigestAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/SessionAuth.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthCommon.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/Authentication.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BearerAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : API changes must be intentional and well-documented
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/OAuth.ktktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.ktktor-server/ktor-server-plugins/ktor-server-sessions/api/ktor-server-sessions.apiktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.ktsktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/SecurityScheme.ktktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/api/ktor-server-auth-jwt.apiktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/JsonSchema.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.klib.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/test/**/*.kt : Follow test naming pattern: `DescribeWhatIsBeingTested`
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt
📚 Learning: 2025-06-16T17:03:45.729Z
Learnt from: tre3p
Repo: ktorio/ktor PR: 4936
File: ktor-utils/jvm/src/io/ktor/util/ZstdEncoding.kt:28-35
Timestamp: 2025-06-16T17:03:45.729Z
Learning: In the Ktor codebase, encoder implementations consistently use GlobalScope.writer and GlobalScope.reader patterns for compression/decompression operations. This is the established architectural pattern used throughout the codebase for byte channel transformations.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Use star imports for `io.ktor.*` packages
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.ktsktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt
📚 Learning: 2025-05-30T06:45:52.309Z
Learnt from: rururux
Repo: ktorio/ktor PR: 4896
File: ktor-client/ktor-client-core/jvm/test/FileStorageTest.kt:1-12
Timestamp: 2025-05-30T06:45:52.309Z
Learning: The headersOf() function from io.ktor.http package is available through wildcard imports like `import io.ktor.http.*`, so no explicit import statement is needed when using wildcard imports from that package.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.kt
📚 Learning: 2025-05-16T13:11:28.416Z
Learnt from: osipxd
Repo: ktorio/ktor PR: 4860
File: ktor-server/ktor-server-plugins/ktor-server-di/api/ktor-server-di.api:24-26
Timestamp: 2025-05-16T13:11:28.416Z
Learning: Binary incompatible changes (such as constructor signature changes) are acceptable in the ktor-server-di module when the version is not yet released, as confirmed by the development team.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.ktsktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-08-14T15:17:11.466Z
Learnt from: zibet27
Repo: ktorio/ktor PR: 5044
File: ktor-client/ktor-client-webrtc/ktor-client-webrtc-rs/build.gradle.kts:12-12
Timestamp: 2025-08-14T15:17:11.466Z
Learning: The Cargo plugin (dev.gobley.cargo) used in the Ktor WebRTC RS module depends on the kotlin("plugin.atomicfu") plugin, so atomicfu should not be removed even if there are no direct kotlinx.atomicfu imports in the module's source code.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Binary compatibility is enforced - all public API changes must be tracked in the `/api/` directories
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.ktsktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/SecurityScheme.ktktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/api/ktor-server-auth-jwt.apiktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/JsonSchema.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-08-14T15:17:11.466Z
Learnt from: zibet27
Repo: ktorio/ktor PR: 5044
File: ktor-client/ktor-client-webrtc/ktor-client-webrtc-rs/build.gradle.kts:12-12
Timestamp: 2025-08-14T15:17:11.466Z
Learning: The Gobley Cargo plugin (dev.gobley.cargo) used in the Ktor WebRTC RS module requires the kotlin("plugin.atomicfu") plugin as a dependency, so the atomicfu plugin should not be removed even if there are no direct kotlinx.atomicfu imports in the module's source code.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts
📚 Learning: 2025-05-08T09:52:11.723Z
Learnt from: osipxd
Repo: ktorio/ktor PR: 4836
File: build-logic/src/main/kotlin/ktorbuild.project.server-plugin.gradle.kts:12-12
Timestamp: 2025-05-08T09:52:11.723Z
Learning: In the Ktor project's flattened Gradle structure, projects are declared using a custom DSL with the unary plus operator inside specialized blocks. For example, server projects are declared with `+"project-name"` inside a `server {}` block within the main `projects {}` block. When verifying project declarations, search for `+"project-name"` rather than traditional `include(":project-name")` statements.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Document all public APIs including parameters, return types, and exceptions
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.ktsktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/SecurityScheme.ktktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/api/ktor-server-auth-jwt.apiktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/JsonSchema.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.ktktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-05-07T13:42:29.388Z
Learnt from: osipxd
Repo: ktorio/ktor PR: 4822
File: ktor-server/ktor-server-plugins/ktor-server-i18n/build.gradle.kts:13-17
Timestamp: 2025-05-07T13:42:29.388Z
Learning: In Kotlin build scripts (build.gradle.kts), the preferred syntax for declaring dependencies is using the dot notation like `jvmTest.dependencies { ... }` rather than the nested version `jvmTest { dependencies { ... } }` as it reduces the nesting level by one and improves readability.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts
📚 Learning: 2025-10-15T16:47:28.272Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 5125
File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt:442-444
Timestamp: 2025-10-15T16:47:28.272Z
Learning: In the ktor-openapi-schema module, the maintainer prefers to keep certain properties mutable (using `var` instead of `val`) in data classes like Response, even when they are part of the public API, to allow flexibility during construction and modification.
Applied to files:
ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.ktktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/JsonSchema.ktktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-11-26T11:34:00.471Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 5206
File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.kt:150-150
Timestamp: 2025-11-26T11:34:00.471Z
Learning: In OpenAPI 3.1.1 specification, the Components.schemas field is defined as Map[string, Schema Object] and does NOT allow Reference Objects at the top level, unlike other component fields (responses, parameters, examples, requestBodies, headers, links, callbacks) which are defined as Map[string, <Type> | Reference Object].
Applied to files:
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api
📚 Learning: 2025-10-15T16:46:27.493Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 5125
File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt:43-43
Timestamp: 2025-10-15T16:46:27.493Z
Learning: In the ktor-openapi-schema module, Operation objects (and related OpenAPI objects) are designed to be composable and can be combined from multiple sources. Therefore, properties like `responses` should remain nullable to support intermediate states during object composition/merging.
Applied to files:
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-05-13T10:24:59.359Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 4849
File: ktor-server/ktor-server-plugins/ktor-server-di/common/src/io/ktor/server/plugins/di/DependencyRegistry.kt:114-115
Timestamp: 2025-05-13T10:24:59.359Z
Learning: The `provide` function in DependencyRegistry intentionally accepts `DependencyResolver.() -> T?` (nullable return) while passing it to `set` which expects `DependencyResolver.() -> T` (non-nullable return). This is a deliberate design choice to support Java interoperability through Kotlin's flexible types system.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.api
🧬 Code graph analysis (4)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/src/io/ktor/annotate/SecuritySchemeAnnotation.jvm.kt (1)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (1)
registerSecurityScheme(31-38)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt (5)
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.kt (2)
basic(112-117)basic(126-134)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BearerAuth.kt (2)
bearer(120-125)bearer(134-141)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/FormAuth.kt (2)
form(140-145)form(154-161)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt (2)
oauth(110-115)oauth(125-132)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (3)
registerOpenIdConnectSecurityScheme(224-230)registerBearerAuthSecurityScheme(173-182)registerBasicAuthSecurityScheme(159-164)
ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.kt (1)
ktor-utils/common/src/io/ktor/util/Attributes.kt (1)
AttributeKey(19-21)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (3)
ktor-utils/common/src/io/ktor/util/Attributes.kt (1)
AttributeKey(19-21)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/src/io/ktor/annotate/SecuritySchemeAnnotation.jvm.kt (1)
inferPlatformSpecificSecurityScheme(14-27)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.kt (1)
inferPlatformSpecificSecurityScheme(11-14)
🪛 ast-grep (0.40.0)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt
[warning] 20-20: A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive data, can be leaked and used by internal or external malicious actors. It is recommended to rotate the secret and retrieve them from a secure secret vault or Hardware Security Module (HSM), alternatively environment variables can be used if allowed by your company policy.
Context: Algorithm.HMAC256(jwtSecret)
Note: [CWE-798]: Use of Hard-coded Credentials [OWASP A03:2021]: Identification and Authentication Failures [REFERENCES]
- https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures
(jwt-hardcode-kotlin)
ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.kt
Outdated
Show resolved
Hide resolved
...server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt
Show resolved
Hide resolved
...server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api
Outdated
Show resolved
Hide resolved
...plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt
Outdated
Show resolved
Hide resolved
...ins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (5)
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api (1)
1604-1812: Address the Schema vs JsonSchema duplication.The
Schemaclass (lines 1604-1812) appears to be a complete duplicate ofJsonSchemawith identical structure (39 properties, same nested types). This duplication needs clarification:
- If intentional, document the purpose and when to use
SchemavsJsonSchema- If unintended, remove the duplicate from the public API
This is particularly concerning given that
SchemaInferenceKt.buildJsonSchema()at line 1810-1812 returnsSchemainstead ofJsonSchema.ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt (1)
106-124: Align default digest description across tests.
testInferDigestAuthenticationProvider(Line 23) asserts the default digest description as"HTTP Digest Authentication"(Line 52), buttestRegisterDigestAuthSecuritySchemehere expects"Http Digest Authentication"(Line 117). UnlessregisterDigestAuthSecuritySchemeis intentionally using a different default text than the inference path, these two tests cannot both be correct.Recommend asserting against the same default as the inference test, ideally via the shared constant:
- assertEquals("Http Digest Authentication", scheme1.description) + assertEquals(HttpSecurityScheme.DEFAULT_DIGEST_DESCRIPTION, scheme1.description)(or update both tests to a common string) so the contract is consistent between inference and explicit registration.
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (1)
123-129: Form authentication mapped to non-standard HTTP scheme"form".
FormAuthenticationProvideris turned into anHttpSecuritySchemewithscheme = "form". In OpenAPI, fortype: "http"theschemevalue is expected to be an HTTP authentication scheme token (typically an IANA-registered scheme likebasic,bearer,digest), and"form"is not one of them. Using a non-standard scheme here is likely to confuse tooling or violate validators.Given that form auth is body/parameter-based rather than an Authorization header scheme, it may be safer to omit automatic inference for
FormAuthenticationProviderand require users to register an appropriate security scheme manually (e.g., viaregisterApiKeySecuritySchemeor custom docs), rather than emitting a non-standard"form"scheme.ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.kt (1)
102-102: Minor grammatical error in documentation.The doc comment reads "or null it is unavailable" but should be "or null if it is unavailable".
- * @return a claim's value, or null it is unavailable or not a string + * @return a claim's value, or null if it is unavailable or not a stringktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt (1)
67-72: Incorrect KDoc@fqnamereference.The
@fqnamein the "Report a problem" link forsettingsincorrectly referencesproviderLookupinstead ofsettings./** * Static OAuth server settings. Either this or [providerLookup] should be specified. * - * [Report a problem](https://ktor.io/feedback/?fqname=io.ktor.server.auth.OAuthAuthenticationProvider.Config.providerLookup) + * [Report a problem](https://ktor.io/feedback/?fqname=io.ktor.server.auth.OAuthAuthenticationProvider.Config.settings) */ public var settings: OAuthServerSettings? = null
🧹 Nitpick comments (2)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt (1)
16-144: Test naming vs. repository convention.The test methods follow the
testXyz...pattern (e.g.,testInferDigestAuthenticationProvider,testRegisterJWTSecurityScheme), while the stated guideline for tests isDescribeWhatIsBeingTested. This is not a functional issue, but if you want strict consistency with that guideline you might consider renaming to more descriptive phrases (e.g.,inferDigestAuthenticationProviderRegistersHttpDigestScheme).ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt (1)
197-258: OAuth inference test createsHttpClientinstances without cleanup.The
HttpClient()instances created in the OAuth tests are never closed, which could cause resource leaks. While this may be acceptable in test contexts, explicitly closing them would be cleaner.Consider using
useor storing the client to close it:- client = HttpClient() + client = HttpClient().also { /* closed by test framework or use autoCloseable */ }Alternatively, since
testApplicationmay handle cleanup, verify if this is an issue in practice.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (33)
ktor-server/ktor-server-plugins/ktor-server-auth-jwt/api/ktor-server-auth-jwt.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.kt(6 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.api(15 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.klib.api(15 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/Authentication.kt(3 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.kt(9 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationProvider.kt(4 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.kt(4 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BearerAuth.kt(4 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/DynamicProviderConfig.kt(2 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/FormAuth.kt(5 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthCommon.kt(5 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt(7 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/SessionAuth.kt(3 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/DigestAuth.kt(6 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/OAuth.kt(2 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api(2 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.klib.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/src/io/ktor/annotate/SecuritySchemeAnnotation.jvm.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-sessions/api/ktor-server-sessions.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-sessions/api/ktor-server-sessions.klib.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/SessionTrackerById.kt(3 hunks)ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.kt(3 hunks)ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api(9 hunks)ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api(7 hunks)ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/JsonSchema.kt(2 hunks)ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.kt(6 hunks)ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/SecurityScheme.kt(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (10)
- ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.klib.api
- ktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/OAuth.kt
- ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/SecurityScheme.kt
- ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BearerAuth.kt
- ktor-server/ktor-server-plugins/ktor-server-sessions/api/ktor-server-sessions.klib.api
- ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/SessionTrackerById.kt
- ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api
- ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/src/io/ktor/annotate/SecuritySchemeAnnotation.jvm.kt
- ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts
- ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/DynamicProviderConfig.kt
🧰 Additional context used
📓 Path-based instructions (2)
**/*.kt
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.kt: Follow Kotlin official style guide (https://kotlinlang.org/docs/coding-conventions.html)
Use star imports forio.ktor.*packages
Document all public APIs including parameters, return types, and exceptions
Mark internal APIs with@InternalAPIannotation
Run./gradlew lintKotlinand fix all linting issues before giving control back to the user
Use./gradlew formatKotlinto automatically fix formatting issues
Run./gradlew updateLegacyAbiafter making ABI changes to update ABI signature files
Binary compatibility is enforced - all public API changes must be tracked in the/api/directories
Validate ABI with./gradlew checkLegacyAbiand update with./gradlew updateLegacyAbi
API changes must be intentional and well-documented
Error handling follows Kotlin conventions with specific Ktor exceptions
Files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/FormAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationProvider.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthCommon.ktktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/JsonSchema.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/Authentication.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.ktktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.ktktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.ktktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/DigestAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/SessionAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt
**/test/**/*.kt
📄 CodeRabbit inference engine (CLAUDE.md)
Follow test naming pattern:
DescribeWhatIsBeingTested
Files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt
🧠 Learnings (17)
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : API changes must be intentional and well-documented
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/FormAuth.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-sessions/api/ktor-server-sessions.apiktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/JsonSchema.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/api/ktor-server-auth-jwt.apiktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.ktktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.ktktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.klib.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Document all public APIs including parameters, return types, and exceptions
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/FormAuth.ktktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.ktktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-06-23T12:49:56.883Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-06-23T12:49:56.883Z
Learning: Error handling should follow Kotlin conventions and use specific Ktor exceptions.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/FormAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationProvider.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthCommon.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/Authentication.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.ktktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/DigestAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/SessionAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Error handling follows Kotlin conventions with specific Ktor exceptions
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/FormAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationProvider.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthCommon.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/Authentication.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.ktktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/DigestAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/SessionAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.kt
📚 Learning: 2025-06-09T07:09:43.170Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 4916
File: ktor-server/ktor-server-plugins/ktor-server-di/common/src/io/ktor/server/plugins/di/DeferredDependencyMap.kt:16-24
Timestamp: 2025-06-09T07:09:43.170Z
Learning: In the `tryGetCompleted` extension function on `Deferred<T>` in ktor-server/ktor-server-plugins/ktor-server-di/common/src/io/ktor/server/plugins/di/DeferredDependencyMap.kt, exceptions should be thrown if the Deferred completed with an error. The "try" in the function name refers to trying to get a completed value non-blockingly, not to exception handling. The function should return null if not completed, the value if completed successfully, or throw the exception if completed with an error.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.kt
📚 Learning: 2025-05-14T18:05:02.321Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 4855
File: ktor-server/ktor-server-plugins/ktor-server-di/api/ktor-server-di.klib.api:334-336
Timestamp: 2025-05-14T18:05:02.321Z
Learning: Breaking changes in constructor parameter order are acceptable for the ktor-server-di module when the code hasn't been released yet, as confirmed by the development team.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthCommon.ktktor-server/ktor-server-plugins/ktor-server-auth-jwt/api/ktor-server-auth-jwt.apiktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.ktktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.ktktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/DigestAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.ktktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.klib.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-10-15T16:47:28.272Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 5125
File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt:442-444
Timestamp: 2025-10-15T16:47:28.272Z
Learning: In the ktor-openapi-schema module, the maintainer prefers to keep certain properties mutable (using `var` instead of `val`) in data classes like Response, even when they are part of the public API, to allow flexibility during construction and modification.
Applied to files:
ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/JsonSchema.ktktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.ktktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-06-16T17:03:45.729Z
Learnt from: tre3p
Repo: ktorio/ktor PR: 4936
File: ktor-utils/jvm/src/io/ktor/util/ZstdEncoding.kt:28-35
Timestamp: 2025-06-16T17:03:45.729Z
Learning: In the Ktor codebase, encoder implementations consistently use GlobalScope.writer and GlobalScope.reader patterns for compression/decompression operations. This is the established architectural pattern used throughout the codebase for byte channel transformations.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Use star imports for `io.ktor.*` packages
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt
📚 Learning: 2025-05-30T06:45:52.309Z
Learnt from: rururux
Repo: ktorio/ktor PR: 4896
File: ktor-client/ktor-client-core/jvm/test/FileStorageTest.kt:1-12
Timestamp: 2025-05-30T06:45:52.309Z
Learning: The headersOf() function from io.ktor.http package is available through wildcard imports like `import io.ktor.http.*`, so no explicit import statement is needed when using wildcard imports from that package.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Binary compatibility is enforced - all public API changes must be tracked in the `/api/` directories
Applied to files:
ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.ktktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-05-16T13:11:28.416Z
Learnt from: osipxd
Repo: ktorio/ktor PR: 4860
File: ktor-server/ktor-server-plugins/ktor-server-di/api/ktor-server-di.api:24-26
Timestamp: 2025-05-16T13:11:28.416Z
Learning: Binary incompatible changes (such as constructor signature changes) are acceptable in the ktor-server-di module when the version is not yet released, as confirmed by the development team.
Applied to files:
ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.ktktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.ktktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.klib.apiktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.api
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Mark internal APIs with `InternalAPI` annotation
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.ktktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.kt
📚 Learning: 2025-11-26T11:34:00.471Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 5206
File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.kt:150-150
Timestamp: 2025-11-26T11:34:00.471Z
Learning: In OpenAPI 3.1.1 specification, the Components.schemas field is defined as Map[string, Schema Object] and does NOT allow Reference Objects at the top level, unlike other component fields (responses, parameters, examples, requestBodies, headers, links, callbacks) which are defined as Map[string, <Type> | Reference Object].
Applied to files:
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api
📚 Learning: 2025-10-15T16:46:27.493Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 5125
File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt:43-43
Timestamp: 2025-10-15T16:46:27.493Z
Learning: In the ktor-openapi-schema module, Operation objects (and related OpenAPI objects) are designed to be composable and can be combined from multiple sources. Therefore, properties like `responses` should remain nullable to support intermediate states during object composition/merging.
Applied to files:
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api
📚 Learning: 2025-05-13T10:24:59.359Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 4849
File: ktor-server/ktor-server-plugins/ktor-server-di/common/src/io/ktor/server/plugins/di/DependencyRegistry.kt:114-115
Timestamp: 2025-05-13T10:24:59.359Z
Learning: The `provide` function in DependencyRegistry intentionally accepts `DependencyResolver.() -> T?` (nullable return) while passing it to `set` which expects `DependencyResolver.() -> T` (non-nullable return). This is a deliberate design choice to support Java interoperability through Kotlin's flexible types system.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.api
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/test/**/*.kt : Follow test naming pattern: `DescribeWhatIsBeingTested`
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt
🧬 Code graph analysis (1)
ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.kt (1)
ktor-utils/common/src/io/ktor/util/Attributes.kt (1)
AttributeKey(19-21)
🪛 ast-grep (0.40.0)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt
[warning] 20-20: A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive data, can be leaked and used by internal or external malicious actors. It is recommended to rotate the secret and retrieve them from a secure secret vault or Hardware Security Module (HSM), alternatively environment variables can be used if allowed by your company policy.
Context: Algorithm.HMAC256(jwtSecret)
Note: [CWE-798]: Use of Hard-coded Credentials [OWASP A03:2021]: Identification and Authentication Failures [REFERENCES]
- https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures
(jwt-hardcode-kotlin)
🔇 Additional comments (64)
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api (11)
37-72: LGTM! API Key security scheme properly defined.The
ApiKeySecuritySchemepublic API follows Kotlinx.serialization patterns correctly and aligns with the OpenAPI specification for API key authentication. The inclusion ofdefaultDescriptionhelper in the Companion object is a good practice for generating consistent descriptions.
452-490: LGTM! HTTP security scheme correctly defined with predefined descriptions.The
HttpSecuritySchemeprovides predefinedDEFAULT_*description constants for common HTTP authentication schemes (basic, bearer, digest, JWT), which aligns with OpenAPI best practices for HTTP authentication.
107-108: Verify the binary compatibility impact of Components constructor change.The
Componentsclass constructor signature has been extended from 10 to 11 parameters to addsecuritySchemes. This is a binary-breaking change that will require existing code to be recompiled.Ensure that:
- This breaking change is documented in release notes
- Migration guidance is provided for users
- The change is intentional and aligns with the module's versioning strategy
Based on learnings, binary compatibility is enforced and all public API changes must be tracked.
Also applies to: 111-111, 120-121, 133-133
818-851: LGTM! OAuth2 security scheme correctly defined.The
OAuth2SecuritySchemeproperly implements the OAuth2 authentication pattern with support for multiple flows via theOAuthFlowsproperty, aligning with the OpenAPI specification.
853-889: LGTM! OAuth flow definition is complete.The
OAuthFlowclass properly defines all OAuth2 flow parameters (authorization URL, token URL, refresh URL, and scopes), aligning with the OpenAPI specification. TheDEFAULT_SCOPE_DESCRIPTIONconstant is a helpful addition for generating consistent scope documentation.
891-926: LGTM! OAuth flows container properly defined.The
OAuthFlowsclass correctly supports all four OAuth2 flow types (implicit, password, clientCredentials, authorizationCode) as defined in the OpenAPI specification, with proper nullable typing.
1079-1112: LGTM! OpenID Connect security scheme correctly defined.The
OpenIdConnectSecuritySchemeproperly implements the OpenID Connect authentication pattern with the discovery URL, aligning with the OpenAPI specification.
1852-1856: LGTM! Security requirement builder properly defined.The
Security$RequirementBuilderprovides a clean builder API for constructing security requirements with scheme names and scopes, consistent with the existing builder patterns in the module.
1858-1876: LGTM! SecurityScheme interface correctly defines the contract.The
SecuritySchemeinterface provides a proper abstraction for all security scheme types withgetDescription()andgetType()methods. The inclusion of a polymorphic serializer enables correct serialization/deserialization of different security scheme implementations.
1878-1890: LGTM! SecuritySchemeIn enum correctly defined.The
SecuritySchemeInenum properly defines the three valid locations for API key parameters (COOKIE, HEADER, QUERY), exactly matching the OpenAPI specification requirements.
1892-1905: LGTM! SecuritySchemeType enum correctly defined.The
SecuritySchemeTypeenum properly defines all four OpenAPI security scheme types (API_KEY, HTTP, OAUTH2, OPEN_ID_CONNECT), with corresponding implementation classes defined in this file.ktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.kt (1)
11-14: LGTM!The non-JVM actual implementation correctly returns
nullwith a clear comment explaining that no platform-specific metadata is available for authentication providers on non-JVM platforms. This aligns with the expect/actual pattern used elsewhere in the codebase.ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/JsonSchema.kt (1)
62-64: LGTM!The change from
"\$id"to$$"$id"(and similar) is a stylistic improvement using Kotlin's raw string prefix to avoid backslash escaping. Both produce identical serialization output ($id,$anchor,$recursiveAnchor), so this is a readability enhancement with no functional impact.ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.kt (2)
164-164: LGTM!The new
securitySchemesfield correctly follows the OpenAPI Components Object specification and matches the established pattern of other fields in the class (nullableMapwithReferenceOr<T>wrapper). This is an intentional public API addition for the security scheme support feature.
180-191: LGTM!The
isEmpty()method is correctly updated to includesecuritySchemes.isNullOrEmpty()in the check, maintaining consistency with the existing pattern for all other fields.ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/Sessions.kt (1)
13-14: LGTM!Exposing
SessionProvidersKeyas public with@InternalAPIannotation follows the coding guidelines for marking internal APIs. This change enables cross-module access (e.g., for OpenAPI security scheme inference) while clearly signaling that this is not part of the stable public API surface.ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthCommon.kt (2)
80-86: LGTM!The new
refreshUrlanddefaultScopeDescriptionsproperties are well-placed additions for OpenAPI documentation support. The TODO comment appropriately defers the merge ofdefaultScopesanddefaultScopeDescriptionsto a future major release to avoid breaking changes.
100-135: Deprecated constructor correctly maintains backward compatibility.The deprecated constructor properly forwards all existing parameters to the primary constructor while providing sensible defaults (
nullandemptyMap()) for the newrefreshUrlanddefaultScopeDescriptionsparameters. The lambda adaptation at line 129 correctly bridges the oldURLBuilder.() -> Unitsignature to the newURLBuilder.(ApplicationRequest) -> Unitsignature.ktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.klib.api (5)
39-52: API additions for description support look consistent.The
descriptionproperty added toAuthenticationProviderandAuthenticationProvider.Configfollows a clean pattern that's propagated consistently across all provider types. The constructor signature change from(String?)to(String?, String?)is a breaking binary change but is properly tracked in this ABI file.
79-86: NewAuthenticateProvidersRegistrationclass exposes route authentication metadata.This class provides access to authentication provider names and strategy for OpenAPI inference. The design is clean with immutable properties.
521-557: OAuth2ServerSettings extended withrefreshUrlanddefaultScopeDescriptions.The new constructor adds
refreshUrl: String?anddefaultScopeDescriptions: Map<String, String>for richer OpenAPI documentation. The old constructor is preserved for backward compatibility.
626-636: New internal API extensions for accessing authentication configuration.
configuration()andallProviders()extensions enable OpenAPI inference to access registered providers.staticSettings()provides access to OAuth settings without dynamic lookup.
271-276:providerLookupnullability and newsettingsproperty enable flexible OAuth configuration.The changes properly support both dynamic provider lookup and static configuration, with validation ensuring at least one is specified. Existing OAuth configurations using
providerLookupcontinue to work without modification, and the newsettingsproperty provides a convenient path for static configurations needed for documentation generation.ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/FormAuth.kt (3)
22-26: ExposinguserParamNameandpasswordParamNameas@InternalAPI.These properties are correctly marked with
@InternalAPIto indicate they're exposed for internal framework use (OpenAPI inference) rather than general consumption. This aligns with the coding guidelines.
66-69: Config constructor updated to acceptdescriptionparameter.The constructor properly passes both
nameanddescriptionto the parentAuthenticationProvider.Config. This follows the consistent pattern across all authentication providers.
140-161: Form authentication overloads with delegation pattern.The existing
form()function now delegates to the new overload withdescription = null, maintaining backward compatibility. The new overload is properly documented.ktor-server/ktor-server-plugins/ktor-server-auth-jwt/api/ktor-server-auth-jwt.api (1)
1-6: JWT authentication provider gains description parameter overload.The new
jwt(AuthenticationConfig, String, String, Function1)overload follows the same pattern as other authentication providers, adding thedescriptionparameter for OpenAPI documentation. The existing overload is preserved for backward compatibility.ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/Authentication.kt (2)
27-47: Provider registration with description support.The existing
provider()function delegates to the new overload withdescription = null, maintaining backward compatibility. The new overload properly constructsDynamicProviderConfig(name, description)and includes appropriate documentation.
134-135:configuration()extension exposes internal config for OpenAPI inference.The
@InternalAPIannotation correctly marks this as an internal framework API. This enables the OpenAPI module to access registered authentication providers for security scheme inference.ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt (4)
15-32: Comprehensive test for basic authentication inference.The test properly validates that basic authentication providers are inferred with correct type, scheme, description, and bearerFormat. Good coverage of the basic case.
109-113: Test data classes for session authentication.The
@Serializableannotation is appropriate for session data classes used with Ktor Sessions.
382-394: Edge case tests for missing/empty authentication plugin.Good coverage of edge cases where the Authentication plugin is not installed or has no providers. The tests correctly expect
nullschemes in these scenarios.
412-423: Test validates dynamic providers cannot be inferred.This test confirms that custom dynamic providers (created via
provider {}) cannot be automatically inferred for OpenAPI documentation, which is the expected behavior.ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationProvider.kt (2)
36-41: Well-structured addition of thedescriptionproperty.The new
descriptionproperty is properly initialized from the config and documented for API documentation purposes. This aligns with the PR objective of supporting OpenAPI security scheme inference.
69-72: Config constructor signature is correctly updated with proper subclass compatibility.All eight Config subclasses (Basic, Bearer, Digest, Form, JWT, OAuth, Session, and Dynamic) have been updated to pass the new
descriptionparameter to the parent constructor. The binary API signatures have been properly tracked in the.apifiles, confirming that this public API change has been intentionally made and documented.ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.kt (2)
229-232: Config constructor updated correctly for description support.The internal constructor now accepts both
nameanddescriptionparameters, properly delegating to the base class.
401-423: New JWT overloads follow consistent delegation pattern.The existing overload delegates to the new description-aware overload, maintaining backward compatibility while enabling the new functionality.
ktor-server/ktor-server-plugins/ktor-server-auth/jvm/src/io/ktor/server/auth/DigestAuth.kt (2)
96-99: Config constructor properly extended with description.Consistent with the pattern established in the base
AuthenticationProvider.Configclass.
168-188: Digest authentication overloads follow the established pattern.The existing overload delegates to the new description-aware overload, maintaining backward compatibility.
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/SessionAuth.kt (2)
63-67: Config constructor correctly includes description.The
@PublishedApi internalvisibility is preserved, and the description flows through to the base config.
186-210: Session authentication overloads properly extended.The existing overload delegates to the new description-aware inline function, maintaining backward compatibility while enabling description metadata for session authentication.
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.kt (3)
60-63: Config constructor properly extended with description.Consistent with the pattern established across all authentication providers.
112-134: Basic authentication overloads follow the delegation pattern.The existing overload delegates to the new description-aware overload, ensuring backward compatibility.
159-159: Minor improvement usingtake()instead ofsubstring().The change from
substring(0, colonIndex)totake(colonIndex)is a minor readability improvement and functionally equivalent.ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt (3)
90-95: Good validation inbuild()method.The requirement that either
settingsorproviderLookupmust be provided prevents misconfiguration at build time with a clear error message.
99-100:staticSettings()appropriately marked as internal API.The
@InternalAPIannotation correctly indicates this is for internal use (OpenAPI inference), preventing accidental external dependencies. As per coding guidelines, internal APIs should be marked with this annotation.
143-146: Provider resolution correctly implements fallback logic.The
providerLookup?.invoke(call) ?: settingspattern correctly prioritizes dynamic lookup while falling back to static settings, aligning with the documentation that states either can be specified.ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/AuthenticationInterceptors.kt (4)
212-215: NewallProviders()function exposes provider registry.This function is needed for OpenAPI security scheme inference. The
@OptIn(InternalAPI::class)annotation correctly indicates that it accesses internal APIs.
326-331:RouteAuthenticationConfigmade public with appropriate annotations.The combination of
@KtorDsland@InternalAPIannotations correctly indicates this is a DSL configuration class intended for internal/plugin use. As per coding guidelines, internal APIs are marked with@InternalAPIannotation.
347-351:DEFAULT_NAMEconstant provides clearer output.The companion object with
DEFAULT_NAME = "default"improves thetoString()output readability when the authentication provider name is null.
354-361: Public exposure ofAuthenticateProvidersRegistrationandAuthenticateProvidersKeycorrectly tracked in ABI files.Both declarations are properly marked with
@InternalAPIand the ABI files have been updated accordingly. Thektor-server-auth.apifile contains entries forAuthenticateProvidersRegistration(line 1) andAuthenticateProvidersKey(line 84), and the.klib.apifile includes the full API signatures (lines 79-85 and 616-617). The binary compatibility tracking aligns with Ktor's requirements for intentional public API changes.ktor-server/ktor-server-plugins/ktor-server-auth/api/ktor-server-auth.api (13)
1-5: New public API class added for provider registration.This new
AuthenticateProvidersRegistrationclass appropriately encapsulates authentication provider names and strategy for OpenAPI security scheme inference.
29-31: New provider overload with description parameter.This overload appropriately extends the provider configuration API to accept an optional description parameter, supporting the OpenAPI documentation requirements.
117-126: LGTM - Non-breaking API additions.The addition of a
Companionobject andDEFAULT_NAMEconstant toAuthenticationRouteSelectorare non-breaking, additive API changes that appropriately expose default naming conventions.
138-141: Consistent description parameter added across authentication methods.All authentication provider configuration methods (basic, bearer, digest, form) now accept an optional description parameter. The synthetic
$defaultmethods ensure binary compatibility for existing code.Also applies to: 159-162, 195-198, 269-272
170-171: LGTM - Config constructors updated consistently.The
BearerAuthenticationProvider.ConfigandDynamicProviderConfigconstructors are appropriately updated to match the parentAuthenticationProvider.Configsignature changes, with synthetic constructors maintaining compatibility.Also applies to: 250-251
422-427: OAuth settings property added for static configuration.The
settingsproperty provides a static alternative toproviderLookup, enabling OpenAPI documentation generation and potential performance improvements as noted in the PR objectives.
481-485: OAuth overload and static settings accessor added.The new
oauthoverload with description parameter and thestaticSettingsmethod appropriately support OpenAPI security scheme inference from OAuth providers.
276-278: Form authentication parameter names exposed.Exposing
getUserParamNameandgetPasswordParamNameappropriately enables OpenAPI schema generation to document the expected form parameter names.
545-562: Session authentication description support added.The session authentication configuration now accepts an optional description parameter, consistent with other authentication providers. The constructor signature update maintains the established pattern.
103-114: Provider description support added with maintained binary compatibility.The
AuthenticationProviderand itsConfigclass now support a description parameter. The constructor signature shows(String, String), and the synthetic constructor withDefaultConstructorMarkeron line 111 confirms the description parameter has a default value, preserving binary compatibility for existing callers.
90-90: Theconfiguration()method already has the@InternalAPIannotation (line 134-135), correctly marking it as an internal API.
508-509: No breaking change — constructor parameter additions are backward compatible.The new
refreshUrlanddefaultScopeDescriptionsparameters are handled by a deprecated hidden secondary constructor that delegates to the primary constructor with default values (refreshUrl = null,defaultScopeDescriptions = emptyMap()). Existing callers using positional arguments or the old signature will continue to work without modification.
79-84: Add @internalapi annotation toallProviders()function.The
allProviders()function (line 213) exposes internal authentication provider details and should be annotated with@InternalAPIto signal that it is not intended for general use. Currently, it uses@OptIn(InternalAPI::class)internally but lacks the annotation on the function itself. The companionAuthenticateProvidersKeyproperty is correctly annotated with@InternalAPIat line 360.⛔ Skipped due to learnings
Learnt from: CR Repo: ktorio/ktor PR: 0 File: CLAUDE.md:0-0 Timestamp: 2025-11-25T09:38:19.393Z Learning: Applies to **/*.kt : Mark internal APIs with `InternalAPI` annotationLearnt from: CR Repo: ktorio/ktor PR: 0 File: CLAUDE.md:0-0 Timestamp: 2025-11-25T09:38:19.393Z Learning: Applies to **/*.kt : API changes must be intentional and well-documented
...plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt
Show resolved
Hide resolved
ktor-server/ktor-server-plugins/ktor-server-sessions/api/ktor-server-sessions.api
Show resolved
Hide resolved
bjhham
left a comment
bjhham
left a comment
There was a problem hiding this comment.
Looking good! I'll take another gander in the morning 👀
...plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt
Outdated
Show resolved
Hide resolved
|
Seems you've got a test failure...
Very helpful assert message. |
Yeah, it's a last-minute refactor 😅. Also, some tests from |
|
Now that #5243 is merged, could you include the API key support? There seems to be a provision in OpenAPI for it https://swagger.io/docs/specification/v3_0/authentication/api-keys/ |
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.kt (1)
401-406: Fix invalid Kotlin call: named argument followed by positional argument (won’t compile).
Line 405 usesdescription = nulland then passesconfigurepositionally, which Kotlin forbids.public fun AuthenticationConfig.jwt( name: String? = null, configure: JWTAuthenticationProvider.Config.() -> Unit ) { - jwt(name, description = null, configure) + jwt(name = name, description = null, configure = configure) }
♻️ Duplicate comments (3)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (3)
192-200: KDoc fornameparameter does not match function signature.Line 187 states
"@param name The name of the security scheme. Defaults to 'default'."but the signature showsname: String?with no Kotlin default value. The defaulting only occurs whennullis explicitly passed (insideregisterSecurityScheme).For consistency with
registerBasicAuthSecuritySchemeandregisterBearerAuthSecurityScheme(which have= nulldefaults), add a Kotlin default:public fun Application.registerApiKeySecurityScheme( - name: String?, + name: String? = null, keyName: String, location: SecuritySchemeIn, description: String = ApiKeySecurityScheme.defaultDescription(keyName, location.name) )
209-215: KDoc fornameparameter does not match function signature.Line 205 states
"@param name The name of the security scheme. Defaults to 'default'."but the signature showsname: String?with no Kotlin default value.public fun Application.registerOAuth2SecurityScheme( - name: String?, + name: String? = null, flows: OAuthFlows, description: String? = OAuth2SecurityScheme.DEFAULT_DESCRIPTION )
224-230: KDoc fornameparameter does not match function signature.Line 220 states
"@param name The name of the security scheme. Defaults to 'default'."but the signature showsname: String?with no Kotlin default value.public fun Application.registerOpenIdConnectSecurityScheme( - name: String?, + name: String? = null, openIdConnectUrl: String, description: String? = OpenIdConnectSecurityScheme.DEFAULT_DESCRIPTION )
🧹 Nitpick comments (6)
ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.kt (1)
408-423: Public API KDoc: add@paramdocs (and clarify whatdescriptionis used for).
The new overload is public; per guidelines, please document parameters (at leastname,description,configure) and (optionally) mention thatdescriptionis intended for generated API docs / OpenAPI.ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt (1)
99-100: Consider adding KDoc documentation.While the function is correctly marked with
@InternalAPI, adding KDoc documentation would clarify its purpose for OpenAPI security scheme inference and improve maintainability.Example:
+/** + * Returns the static OAuth server settings if configured. + * Used for inferring security schemes in OpenAPI documentation generation. + * + * [Report a problem](https://ktor.io/feedback/?fqname=io.ktor.server.auth.staticSettings) + */ @InternalAPI public fun OAuthAuthenticationProvider.staticSettings(): OAuthServerSettings? = settingsktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt (2)
49-49: Consider using safe casts for clearer test failure messages.The pattern
schemes[...]?.valueOrNull() as HttpSecuritySchemeappears consistently throughout the test methods. While this works, using a non-null castasafter nullable operations can produce less informative error messages if the value is null or of the wrong type.Consider this safer pattern for clearer test failures:
-val scheme1 = schemes["digest-auth"]?.valueOrNull() as HttpSecurityScheme +val scheme1 = assertNotNull(schemes["digest-auth"]?.valueOrNull() as? HttpSecurityScheme)This applies to similar casts on lines 49, 55, 82, 104, 120, 126, 141, and 147.
Also applies to: 82-82, 104-104, 120-120, 141-141
16-150: Consider adding test coverage for error conditions.The tests comprehensively cover happy paths for both inference and explicit registration. According to the PR objectives, "attempting to infer from the auth plugin when it's not installed should produce a runtime error." Consider adding a test case for this scenario to verify the expected error behavior.
Example test case:
@Test fun testInferWithoutAuthenticationPlugin() = testApplication { startApplication() // Should throw or return empty/null when Authentication plugin not installed assertFailsWith<IllegalStateException> { application.findSecuritySchemes(inferFromAuthenticationPlugin = true) } }ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (2)
40-51: Clarify the KDoc forincludeJwtparameter.Line 44 states "Enable only if you have a plugin installed" but doesn't specify which plugin. Consider clarifying that this requires a JWT authentication plugin (e.g.,
ktor-server-auth-jwt) to be installed for JWT scheme inference to work.Apply this diff to improve the documentation:
* @param includeJwt Whether to include JWT security schemes in the result. Enable only if you have a plugin installed. + * @param includeJwt Whether to include JWT security schemes in the result. Enable only if you have a JWT authentication plugin (e.g., ktor-server-auth-jwt) installed.
196-196: Consider using lowercase for location name in default description.Line 196 uses
location.namewhich returns the enum constant name in uppercase (e.g., "HEADER", "COOKIE"). For consistency with line 124 in the session inference logic (which useskeyLocation.name.lowercase()), consider lowercasing the location name in the default description.- description: String = ApiKeySecurityScheme.defaultDescription(keyName, location.name) + description: String = ApiKeySecurityScheme.defaultDescription(keyName, location.name.lowercase()) )
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.kt(6 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt(7 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.kt(2 hunks)ktor-server/ktor-server-plugins/ktor-server-auth/jvm/test/io/ktor/tests/auth/OAuth1aTest.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/src/io/ktor/annotate/SecuritySchemeAnnotation.jvm.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.kt(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/src/io/ktor/annotate/SecuritySchemeAnnotation.jvm.kt
- ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt
🧰 Additional context used
📓 Path-based instructions (2)
**/*.kt
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.kt: Follow Kotlin official style guide (https://kotlinlang.org/docs/coding-conventions.html)
Use star imports forio.ktor.*packages
Document all public APIs including parameters, return types, and exceptions
Mark internal APIs with@InternalAPIannotation
Run./gradlew lintKotlinand fix all linting issues before giving control back to the user
Use./gradlew formatKotlinto automatically fix formatting issues
Run./gradlew updateLegacyAbiafter making ABI changes to update ABI signature files
Binary compatibility is enforced - all public API changes must be tracked in the/api/directories
Validate ABI with./gradlew checkLegacyAbiand update with./gradlew updateLegacyAbi
API changes must be intentional and well-documented
Error handling follows Kotlin conventions with specific Ktor exceptions
Files:
ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.ktktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.ktktor-server/ktor-server-plugins/ktor-server-auth/jvm/test/io/ktor/tests/auth/OAuth1aTest.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt
**/test/**/*.kt
📄 CodeRabbit inference engine (CLAUDE.md)
Follow test naming pattern:
DescribeWhatIsBeingTested
Files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.ktktor-server/ktor-server-plugins/ktor-server-auth/jvm/test/io/ktor/tests/auth/OAuth1aTest.kt
🧠 Learnings (12)
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : API changes must be intentional and well-documented
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.ktktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.kt
📚 Learning: 2025-06-09T07:09:43.170Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 4916
File: ktor-server/ktor-server-plugins/ktor-server-di/common/src/io/ktor/server/plugins/di/DeferredDependencyMap.kt:16-24
Timestamp: 2025-06-09T07:09:43.170Z
Learning: In the `tryGetCompleted` extension function on `Deferred<T>` in ktor-server/ktor-server-plugins/ktor-server-di/common/src/io/ktor/server/plugins/di/DeferredDependencyMap.kt, exceptions should be thrown if the Deferred completed with an error. The "try" in the function name refers to trying to get a completed value non-blockingly, not to exception handling. The function should return null if not completed, the value if completed successfully, or throw the exception if completed with an error.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.kt
📚 Learning: 2025-06-23T12:49:56.883Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-06-23T12:49:56.883Z
Learning: Error handling should follow Kotlin conventions and use specific Ktor exceptions.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Error handling follows Kotlin conventions with specific Ktor exceptions
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.ktktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Document all public APIs including parameters, return types, and exceptions
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Mark internal APIs with `InternalAPI` annotation
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt
📚 Learning: 2025-05-16T13:11:28.416Z
Learnt from: osipxd
Repo: ktorio/ktor PR: 4860
File: ktor-server/ktor-server-plugins/ktor-server-di/api/ktor-server-di.api:24-26
Timestamp: 2025-05-16T13:11:28.416Z
Learning: Binary incompatible changes (such as constructor signature changes) are acceptable in the ktor-server-di module when the version is not yet released, as confirmed by the development team.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.kt
📚 Learning: 2025-05-14T18:05:02.321Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 4855
File: ktor-server/ktor-server-plugins/ktor-server-di/api/ktor-server-di.klib.api:334-336
Timestamp: 2025-05-14T18:05:02.321Z
Learning: Breaking changes in constructor parameter order are acceptable for the ktor-server-di module when the code hasn't been released yet, as confirmed by the development team.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Binary compatibility is enforced - all public API changes must be tracked in the `/api/` directories
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.kt
📚 Learning: 2025-05-30T06:45:52.309Z
Learnt from: rururux
Repo: ktorio/ktor PR: 4896
File: ktor-client/ktor-client-core/jvm/test/FileStorageTest.kt:1-12
Timestamp: 2025-05-30T06:45:52.309Z
Learning: In Ktor test files, particularly in the ktor-client/ktor-client-core/jvm/test/ directory, test files follow the convention of not including explicit package declarations. This is consistent across test files like CachingCacheStorageTest.kt and should be maintained for consistency.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Use star imports for `io.ktor.*` packages
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.ktktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt
📚 Learning: 2025-05-30T06:45:52.309Z
Learnt from: rururux
Repo: ktorio/ktor PR: 4896
File: ktor-client/ktor-client-core/jvm/test/FileStorageTest.kt:1-12
Timestamp: 2025-05-30T06:45:52.309Z
Learning: The headersOf() function from io.ktor.http package is available through wildcard imports like `import io.ktor.http.*`, so no explicit import statement is needed when using wildcard imports from that package.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.kt
🧬 Code graph analysis (2)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (4)
ktor-utils/common/src/io/ktor/util/Attributes.kt (1)
AttributeKey(19-21)ktor-server/ktor-server-core/common/src/io/ktor/server/application/ApplicationPlugin.kt (1)
pluginOrNull(100-102)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/src/io/ktor/annotate/SecuritySchemeAnnotation.jvm.kt (1)
inferPlatformSpecificSecurityScheme(14-27)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.kt (1)
inferPlatformSpecificSecurityScheme(11-18)
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt (2)
ktor-server/ktor-server-plugins/ktor-server-di/common/src/io/ktor/server/plugins/di/DependencyRegistry.kt (1)
require(70-72)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/Authentication.kt (1)
register(56-59)
🪛 ast-grep (0.40.0)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt
[warning] 20-20: A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive data, can be leaked and used by internal or external malicious actors. It is recommended to rotate the secret and retrieve them from a secure secret vault or Hardware Security Module (HSM), alternatively environment variables can be used if allowed by your company policy.
Context: Algorithm.HMAC256(jwtSecret)
Note: [CWE-798]: Use of Hard-coded Credentials [OWASP A03:2021]: Identification and Authentication Failures [REFERENCES]
- https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures
(jwt-hardcode-kotlin)
🔇 Additional comments (17)
ktor-server/ktor-server-plugins/ktor-server-auth/jvm/test/io/ktor/tests/auth/OAuth1aTest.kt (1)
310-325: Good fix: explicit outer-receiver qualification prevents DSL/lambda shadowing.
this@OAuth1aFlowTest.settingsis clearer and more robust than relying on unqualifiedsettingsinside nested DSL scopes.ktor-server/ktor-server-plugins/ktor-server-auth-jwt/jvm/src/io/ktor/server/auth/jwt/JWTAuth.kt (2)
117-140: Verify exception contract vs Auth0 JWT:JWTDecodeExceptionmay not be the only thrown type.
Catching onlyJWTDecodeExceptionmay be fine, but please confirm via tests / current dependency behavior thatClaim.asList(...)/Claim.as(...)won’t throw other runtime exceptions you’d rather map tonull/emptyList.
229-233: ABI + docs follow-up for widened auth provider config surface.
SinceJWTAuthenticationProvider.Confignow routes throughAuthenticationProvider.Config(name, description), please ensure ABI files under/api/are updated and./gradlew checkLegacyAbipasses (and runupdateLegacyAbiif expected).ktor-server/ktor-server-plugins/ktor-server-auth/common/test/io/ktor/tests/auth/AuthBuildersTest.kt (1)
18-18: LGTM! Correct internal API opt-in.The import and opt-in annotation are properly applied to use
AuthenticationInterceptors, which is now marked as internal API per this PR's changes. The opt-in is correctly scoped to the specific usage point.Also applies to: 614-614
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/OAuthProcedure.kt (5)
34-35: LGTM! Dual configuration properties added.The
settingsandproviderLookupproperties appropriately expose configuration values for internal framework use, enabling both static and dynamic OAuth server configuration approaches.
49-72: LGTM! Config class properly extended.The changes correctly implement dual configuration support:
- Constructor now accepts
descriptionparameter for OpenAPI documentation- Both
providerLookupandsettingsare nullable, aligning with the either/or validation- Documentation is comprehensive and correctly references the new
settingsproperty
90-95: LGTM! Appropriate configuration validation.The
build()function correctly validates that at least one configuration method (settingsorproviderLookup) is specified. Usingrequire()with a clear error message follows Kotlin conventions.
110-132: LGTM! OAuth DSL properly extended.The overload pattern correctly maintains backward compatibility while adding description support:
- Original
oauthdelegates to new overload withdescription = null- New overload properly constructs the provider using the validated
build()method- Documentation follows Ktor conventions
145-145: LGTM! Resolution logic correctly implements fallback.The provider resolution
providerLookup?.invoke(call) ?: settingscorrectly:
- Prefers dynamic lookup when available
- Falls back to static settings when lookup is null or returns null
- Aligns with the validation ensuring at least one is configured
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt (1)
18-21: Static analysis warning is a false positive for test code.The hardcoded JWT secret and algorithm setup are appropriate for test fixtures. Test code commonly uses hardcoded credentials, and the values clearly indicate test data (e.g., "test-jwt-secret").
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.kt (1)
11-18: LGTM! Clean non-JVM fallback implementation.The implementation correctly enforces that JWT authentication is not supported on non-JVM platforms and provides a safe fallback by returning
nullfor platform-specific security scheme inference.ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (6)
17-22: LGTM! Well-documented public API.The attribute key is clearly documented and follows Ktor conventions for storing plugin-scoped metadata.
24-38: LGTM! Core registration function is sound.The function correctly accumulates security schemes in application attributes and handles null provider names by defaulting to
AuthenticationRouteSelector.DEFAULT_NAME.
67-84: LGTM! Helper functions implement correct inference logic.The
wrap()function properly converts schemes to OpenAPI references, andinferSecuritySchemesFromAuthenticationcorrectly retrieves providers from the Authentication plugin and delegates to per-provider inference.
86-151: LGTM! Comprehensive provider-to-scheme inference logic.The function correctly infers OpenAPI security schemes from various Ktor authentication providers:
- HTTP schemes for Basic and Bearer authentication
- API Key schemes for Session-based authentication (correctly extracting transport details)
- OAuth2 schemes with proper flow configuration
- Platform-specific delegation for Digest and JWT
The session handling properly extracts transport information, and the OAuth inference correctly uses the newly added
staticSettings()property.
153-164: LGTM! Well-designed helper with proper defaults.The function signature and documentation are consistent, with appropriate Kotlin defaults for optional parameters.
166-182: LGTM! Consistent helper design with proper optional parameters.The function correctly provides defaults for all optional parameters and matches its documentation.
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (4)
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api (2)
164-224:ApiKeySecurityScheme.inand.namebeing nullable risks emitting invalid OpenAPI—ensure validation exists at build/emit time.OpenAPI requires
inandnamefortype=apiKey. If nullability is kept for composability, ensure there’s a validation step (or “finalize/normalize” pass) that either fills defaults or fails fast before serialization.
226-284:Componentsdata-class slot insertion changescomponentN()ordering and destructuring semantics (binary/source behavior break).
securitySchemesis added as the 7th constructor parameter, which shiftscomponent7()from the previous meaning (formerly “links”) to now “securitySchemes”, and shifts subsequent component indices. Any consumer using destructuring declarations or callingcomponentN()will break or silently misbehave.Strongly consider appending
securitySchemesto the end of the constructor (and thus to the end of componentN order), keeping existing component indices stable. Based on learnings, public API changes must be intentional and well-documented, and ABI is enforced via/api/dumps. Based on learnings, API changes must be intentional and well-documented.ktor-server/ktor-server-plugins/ktor-server-auth-api-key/common/src/io/ktor/server/auth/apikey/ApiKeyAuth.kt (2)
14-41: KDoc for the new public overload is incomplete (missing@param description)
AuthenticationConfig.apiKey(name, description, configure)is public, but its KDoc doesn’t documentdescription(and it duplicates the old KDoc without updating params). Based on learnings, public API changes must be intentional and well-documented./** * Installs an API Key authentication mechanism. * * @param name optional name for this authentication provider. If not specified, a default name will be used. - * @param configure configuration block for setting up the API Key authentication provider. + * @param description optional description for this authentication provider (used by API documentation generators). + * @param configure configuration block for setting up the API Key authentication provider. */ public fun AuthenticationConfig.apiKey( name: String? = null, description: String? = null, configure: ApiKeyAuthenticationProvider.Configuration.() -> Unit, ) { val configuration = ApiKeyAuthenticationProvider.Configuration(name, description) val provider = ApiKeyAuthenticationProvider(configuration.apply(configure)) register(provider) }
65-80: PublicheaderNameshould have KDoc (even if@InternalAPI)
This is now a public API surface; please document what it represents and any stability expectations (and/or explicitly note it’s@InternalAPI).public class ApiKeyAuthenticationProvider internal constructor( configuration: Configuration, ) : AuthenticationProvider(configuration) { @InternalAPI + /** + * Header name used to extract the API key for this provider. + * + * This is exposed for internal/advanced integrations (e.g., documentation generators) and may change. + */ public val headerName: String = configuration.headerName
♻️ Duplicate comments (1)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (1)
192-238: Align function signatures with KDoc for optional name parameter.The KDoc for
registerApiKeySecurityScheme,registerOAuth2SecurityScheme, andregisterOpenIdConnectSecuritySchemestates that thenameparameter "Defaults to 'default'", but the function signatures declarename: String?with no Kotlin default value. Either add= nullto match the documented behavior:public fun Application.registerApiKeySecurityScheme( - name: String?, + name: String? = null, keyName: String, location: SecuritySchemeIn, description: String = ApiKeySecurityScheme.DEFAULT_DESCRIPTION ) { ... } public fun Application.registerOAuth2SecurityScheme( - name: String?, + name: String? = null, flows: OAuthFlows, description: String? = OAuth2SecurityScheme.DEFAULT_DESCRIPTION ) { ... } public fun Application.registerOpenIdConnectSecurityScheme( - name: String?, + name: String? = null, openIdConnectUrl: String, description: String? = OpenIdConnectSecurityScheme.DEFAULT_DESCRIPTION ) { ... }or update the KDoc to clarify that
nullmust be explicitly passed to use the default provider name.Based on learnings and coding guidelines: public API docs must align with signatures.
🧹 Nitpick comments (2)
ktor-server/ktor-server-plugins/ktor-server-auth-api-key/common/src/io/ktor/server/auth/apikey/ApiKeyAuth.kt (2)
12-12: Use star import forio.ktor.*here (per repo guidelines)
Switchimport io.ktor.utils.io.InternalAPI→import io.ktor.utils.io.*.-import io.ktor.utils.io.InternalAPI +import io.ktor.utils.io.*
20-25:returnis unnecessary in aUnitfunction
Pure readability nit: the delegating overload can just call the other overload.public fun AuthenticationConfig.apiKey( name: String? = null, configure: ApiKeyAuthenticationProvider.Configuration.() -> Unit, ) { - return apiKey(name, description = null, configure) + apiKey(name, description = null, configure) }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
ktor-server/ktor-server-plugins/ktor-server-auth-api-key/api/ktor-server-auth-api-key.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-auth-api-key/api/ktor-server-auth-api-key.klib.api(2 hunks)ktor-server/ktor-server-plugins/ktor-server-auth-api-key/common/src/io/ktor/server/auth/apikey/ApiKeyAuth.kt(4 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.klib.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt(1 hunks)ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api(8 hunks)ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api(7 hunks)ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/SecurityScheme.kt(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/SecurityScheme.kt
- ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.klib.api
🧰 Additional context used
📓 Path-based instructions (2)
**/*.kt
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.kt: Follow Kotlin official style guide (https://kotlinlang.org/docs/coding-conventions.html)
Use star imports forio.ktor.*packages
Document all public APIs including parameters, return types, and exceptions
Mark internal APIs with@InternalAPIannotation
Run./gradlew lintKotlinand fix all linting issues before giving control back to the user
Use./gradlew formatKotlinto automatically fix formatting issues
Run./gradlew updateLegacyAbiafter making ABI changes to update ABI signature files
Binary compatibility is enforced - all public API changes must be tracked in the/api/directories
Validate ABI with./gradlew checkLegacyAbiand update with./gradlew updateLegacyAbi
API changes must be intentional and well-documented
Error handling follows Kotlin conventions with specific Ktor exceptions
Files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-auth-api-key/common/src/io/ktor/server/auth/apikey/ApiKeyAuth.kt
**/test/**/*.kt
📄 CodeRabbit inference engine (CLAUDE.md)
Follow test naming pattern:
DescribeWhatIsBeingTested
Files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt
🧠 Learnings (16)
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : API changes must be intentional and well-documented
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.ktsktor-server/ktor-server-plugins/ktor-server-auth-api-key/api/ktor-server-auth-api-key.apiktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Binary compatibility is enforced - all public API changes must be tracked in the `/api/` directories
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.ktsktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-08-14T15:17:11.466Z
Learnt from: zibet27
Repo: ktorio/ktor PR: 5044
File: ktor-client/ktor-client-webrtc/ktor-client-webrtc-rs/build.gradle.kts:12-12
Timestamp: 2025-08-14T15:17:11.466Z
Learning: The Cargo plugin (dev.gobley.cargo) used in the Ktor WebRTC RS module depends on the kotlin("plugin.atomicfu") plugin, so atomicfu should not be removed even if there are no direct kotlinx.atomicfu imports in the module's source code.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts
📚 Learning: 2025-05-16T13:11:28.416Z
Learnt from: osipxd
Repo: ktorio/ktor PR: 4860
File: ktor-server/ktor-server-plugins/ktor-server-di/api/ktor-server-di.api:24-26
Timestamp: 2025-05-16T13:11:28.416Z
Learning: Binary incompatible changes (such as constructor signature changes) are acceptable in the ktor-server-di module when the version is not yet released, as confirmed by the development team.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.ktsktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Mark internal APIs with `InternalAPI` annotation
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.ktsktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api
📚 Learning: 2025-05-14T18:05:02.321Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 4855
File: ktor-server/ktor-server-plugins/ktor-server-di/api/ktor-server-di.klib.api:334-336
Timestamp: 2025-05-14T18:05:02.321Z
Learning: Breaking changes in constructor parameter order are acceptable for the ktor-server-di module when the code hasn't been released yet, as confirmed by the development team.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts
📚 Learning: 2025-08-14T15:17:11.466Z
Learnt from: zibet27
Repo: ktorio/ktor PR: 5044
File: ktor-client/ktor-client-webrtc/ktor-client-webrtc-rs/build.gradle.kts:12-12
Timestamp: 2025-08-14T15:17:11.466Z
Learning: The Gobley Cargo plugin (dev.gobley.cargo) used in the Ktor WebRTC RS module requires the kotlin("plugin.atomicfu") plugin as a dependency, so the atomicfu plugin should not be removed even if there are no direct kotlinx.atomicfu imports in the module's source code.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Use star imports for `io.ktor.*` packages
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts
📚 Learning: 2025-05-08T09:52:11.723Z
Learnt from: osipxd
Repo: ktorio/ktor PR: 4836
File: build-logic/src/main/kotlin/ktorbuild.project.server-plugin.gradle.kts:12-12
Timestamp: 2025-05-08T09:52:11.723Z
Learning: In the Ktor project's flattened Gradle structure, projects are declared using a custom DSL with the unary plus operator inside specialized blocks. For example, server projects are declared with `+"project-name"` inside a `server {}` block within the main `projects {}` block. When verifying project declarations, search for `+"project-name"` rather than traditional `include(":project-name")` statements.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Document all public APIs including parameters, return types, and exceptions
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.ktsktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-05-07T13:42:29.388Z
Learnt from: osipxd
Repo: ktorio/ktor PR: 4822
File: ktor-server/ktor-server-plugins/ktor-server-i18n/build.gradle.kts:13-17
Timestamp: 2025-05-07T13:42:29.388Z
Learning: In Kotlin build scripts (build.gradle.kts), the preferred syntax for declaring dependencies is using the dot notation like `jvmTest.dependencies { ... }` rather than the nested version `jvmTest { dependencies { ... } }` as it reduces the nesting level by one and improves readability.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts
📚 Learning: 2025-05-30T06:45:52.309Z
Learnt from: rururux
Repo: ktorio/ktor PR: 4896
File: ktor-client/ktor-client-core/jvm/test/FileStorageTest.kt:1-12
Timestamp: 2025-05-30T06:45:52.309Z
Learning: In Ktor test files, particularly in the ktor-client/ktor-client-core/jvm/test/ directory, test files follow the convention of not including explicit package declarations. This is consistent across test files like CachingCacheStorageTest.kt and should be maintained for consistency.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt
📚 Learning: 2025-11-27T10:07:26.686Z
Learnt from: osipxd
Repo: ktorio/ktor PR: 5205
File: ktor-client/ktor-client-curl/desktop/interop/include/curl/multi.h:410-420
Timestamp: 2025-11-27T10:07:26.686Z
Learning: In the ktorio/ktor repository, do not review files under `ktor-client/ktor-client-curl/desktop/interop/include/curl/*` as these are upstream libcurl header files copied from the curl project and not maintained by the Ktor team.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api
📚 Learning: 2025-10-15T16:47:28.272Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 5125
File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt:442-444
Timestamp: 2025-10-15T16:47:28.272Z
Learning: In the ktor-openapi-schema module, the maintainer prefers to keep certain properties mutable (using `var` instead of `val`) in data classes like Response, even when they are part of the public API, to allow flexibility during construction and modification.
Applied to files:
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-11-26T11:34:00.471Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 5206
File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.kt:150-150
Timestamp: 2025-11-26T11:34:00.471Z
Learning: In OpenAPI 3.1.1 specification, the Components.schemas field is defined as Map[string, Schema Object] and does NOT allow Reference Objects at the top level, unlike other component fields (responses, parameters, examples, requestBodies, headers, links, callbacks) which are defined as Map[string, <Type> | Reference Object].
Applied to files:
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api
📚 Learning: 2025-10-15T16:46:27.493Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 5125
File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt:43-43
Timestamp: 2025-10-15T16:46:27.493Z
Learning: In the ktor-openapi-schema module, Operation objects (and related OpenAPI objects) are designed to be composable and can be combined from multiple sources. Therefore, properties like `responses` should remain nullable to support intermediate states during object composition/merging.
Applied to files:
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api
🧬 Code graph analysis (1)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (4)
ktor-utils/common/src/io/ktor/util/Attributes.kt (1)
AttributeKey(19-21)ktor-server/ktor-server-core/common/src/io/ktor/server/application/ApplicationPlugin.kt (1)
pluginOrNull(100-102)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/src/io/ktor/annotate/SecuritySchemeAnnotation.jvm.kt (1)
inferPlatformSpecificSecurityScheme(14-27)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.kt (1)
inferPlatformSpecificSecurityScheme(11-18)
🔇 Additional comments (10)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/build.gradle.kts (2)
15-16: Dependency strategy aligns well with OpenAPI security scheme inference requirements.The
compileOnlyapproach for auth modules incommonMainis appropriate—it allows compile-time access for inferring security schemes while avoiding a hard runtime dependency, which matches the stated goal of producing a runtime error when the auth plugin is not installed. Test-timeimplementationdependencies correctly enable validation of inference logic.The JVM-specific
compileOnlydependency onauth-jwtand test-time dependencies onauth-jwtandsessionsproperly isolate platform-specific security scheme inference.Also applies to: 20-21, 25-27, 28-31
15-16: Verify API file updates for public API changes in authentication modules.All auth modules have API tracking files, and the
descriptionfield is currently present in the public API signatures. Ensure that any new or modified public APIs inktor-server-auth,ktor-server-auth-api-key, andktor-server-auth-jwtare reflected in their corresponding*.apiand*.klib.apifiles per binary compatibility requirements. If no public API changes were made to these modules in this PR, no action is needed.ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api (3)
27-61: Verify enum serialization matches OpenAPI spec wire values (cookie/header/query, apiKey/http/oauth2/openIdConnect).ABI introduces
SecuritySchemeIn/SecuritySchemeTypewith uppercase enum entries; that’s fine only if the serializers map to the correct OpenAPI strings (likely via@SerialName). Please double-check the serialized JSON output and round-trip parsing for these enums on all targets.
1833-1844:Security.Builderhelpers (apiKey/basic/oauth2/openIdConnect) look good; verify the scheme-name conventions.These helpers are a nice ergonomics win. Please verify that
apiKey(String)(and others) map to the correct security scheme names incomponents.securitySchemes, and that the generated requirement objects match OpenAPI semantics (including empty scope lists where appropriate).
1265-1302: OpenID Connect URL is nullable—consider enforcing non-null whentype=openIdConnect.
openIdConnectUrlis required by spec for OpenID Connect security schemes. If nullability is intentional for composition, ensure there’s a “must be set” validation prior to emitting the final OpenAPI document.⛔ Skipped due to learnings
Learnt from: bjhham Repo: ktorio/ktor PR: 5125 File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt:43-43 Timestamp: 2025-10-15T16:46:27.493Z Learning: In the ktor-openapi-schema module, Operation objects (and related OpenAPI objects) are designed to be composable and can be combined from multiple sources. Therefore, properties like `responses` should remain nullable to support intermediate states during object composition/merging.ktor-server/ktor-server-plugins/ktor-server-auth-api-key/api/ktor-server-auth-api-key.api (2)
6-11: New overload + default stub: please sanity-check Kotlin overload resolution at call sites
This addsapiKey(AuthenticationConfig, String, String, Function1)(plus$default). Since the new params are Strings, it’s worth verifying common usages likeapiKey { ... }andapiKey("name") { ... }don’t become ambiguous after adding a “more-args-with-defaults” overload.
13-16: Public ABI now exposesApiKeyAuthenticationProvider.getHeaderName()—confirm this is intentionally supported
Even if the source annotates it with@InternalAPI, it’s now part of the published JVM ABI; please ensure this is intended and documented as such.ktor-server/ktor-server-plugins/ktor-server-auth-api-key/api/ktor-server-auth-api-key.klib.api (2)
9-12:headerNameis now public in MPP ABI—ensure this is the intended cross-platform contract
This will be visible to JS/Native/Wasm consumers too; please confirm that’s acceptable (even if “internal” by opt-in convention).
33-34: New(name, description, configure)overload in MPP ABI—verify no ambiguity with the existing overload
Please double-check Kotlin call-site resolution forapiKey { ... }/apiKey("name") { ... }in multiplatform builds.ktor-server/ktor-server-plugins/ktor-server-auth-api-key/common/src/io/ktor/server/auth/apikey/ApiKeyAuth.kt (1)
20-41: No action required. The twoapiKeyoverloads do not create ambiguity. Kotlin's overload resolution correctly distinguishes between them based on argument count: calling with one string argument uses the first overload, while calling with two string arguments uses the second. Existing call sites in the test suite confirm both patterns compile cleanly.
| // TODO: merge `defaultScopes` and `defaultScopeDescriptions` in the next major release | ||
| public val defaultScopeDescriptions: Map<String, String> = emptyMap(), |
There was a problem hiding this comment.
Could you log a YT ticket for this and target it for 4.0.0 so we don't forget?
There was a problem hiding this comment.
Sure! I'll create it after the PR is merged.
e5l
left a comment
e5l
left a comment
There was a problem hiding this comment.
lgtm, please consider merging after the release
| } | ||
|
|
||
| @OptIn(InternalAPI::class) | ||
| public fun AuthenticationConfig.allProviders(): Map<String?, AuthenticationProvider> { |
There was a problem hiding this comment.
Could you tell me why it is possible to have a nullable key?
There was a problem hiding this comment.
In ktor-auth, the auth provider name is nullable, null == "default".
In this PR, I just made it publicly available.
Sure, some OpenAPI Security features are still missing. |
…tation OpenAPI Security route annotation
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/RouteAnnotationApi.kt (1)
12-14: LGTM on new authentication imports.The imports correctly bring in the authentication-related types needed for OpenAPI security integration. As per coding guidelines, star imports should be used for
io.ktor.*packages.Consider consolidating to star import:
-import io.ktor.server.auth.AuthenticateProvidersKey -import io.ktor.server.auth.AuthenticationRouteSelector -import io.ktor.server.auth.AuthenticationStrategy +import io.ktor.server.auth.*ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt (2)
224-224: Consider closingHttpClientinstances in tests.The
HttpClient()instances created at lines 224 and 239 are not explicitly closed. While the test framework likely handles cleanup, explicitly closing or usingclient.close()is a best practice to prevent resource leaks.
417-431: Test name may be misleading.The test is named
testDisabledCachingbut it actually tests that caching works (stale cache returns old result, bypassing cache returns fresh result). Consider renaming to something liketestCachingBehaviorortestCacheBypass.ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt (1)
12-20: Use star imports forio.ktor.*packages.Per coding guidelines, star imports should be used for
io.ktor.*packages.-import io.ktor.server.auth.Authentication -import io.ktor.server.auth.AuthenticationStrategy -import io.ktor.server.auth.OAuthServerSettings -import io.ktor.server.auth.UserIdPrincipal -import io.ktor.server.auth.apikey.apiKey -import io.ktor.server.auth.authenticate -import io.ktor.server.auth.basic -import io.ktor.server.auth.bearer -import io.ktor.server.auth.oauth +import io.ktor.server.auth.* +import io.ktor.server.auth.apikey.*ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (1)
32-47: AlignregisterSecuritySchemeergonomics with the other helpers and reset cache on mutation.To match the documented “Defaults to
default” behavior and the other helpers, it would be clearer to makeproviderNameoptional and invalidate the cached schemes when mutating:-public fun Application.registerSecurityScheme( - providerName: String?, - securityScheme: SecurityScheme -) { - val providerName = providerName ?: AuthenticationRouteSelector.DEFAULT_NAME - val existingSchemes = attributes.getOrNull(AuthSecuritySchemesAttributeKey) ?: emptyMap() - attributes.put(AuthSecuritySchemesAttributeKey, existingSchemes + (providerName to securityScheme)) -} +public fun Application.registerSecurityScheme( + providerName: String? = null, + securityScheme: SecurityScheme +) { + val resolvedName = providerName ?: AuthenticationRouteSelector.DEFAULT_NAME + // Ensure subsequent `findSecuritySchemes(useCache = true)` sees the new entry. + attributes.remove(AuthSecuritySchemesCacheAttributeKey) + val existingSchemes = attributes.getOrNull(AuthSecuritySchemesAttributeKey) ?: emptyMap() + attributes.put(AuthSecuritySchemesAttributeKey, existingSchemes + (resolvedName to securityScheme)) +}This keeps the API symmetric with
registerBasicAuthSecurityScheme/friends and avoids stale cache entries if schemes are added after the first lookup.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (14)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.klib.api(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/RouteAnnotationApi.kt(4 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt(4 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/src/io/ktor/annotate/SecuritySchemeAnnotation.jvm.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/RouteAnnotationApiJvmTest.kt(1 hunks)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.kt(1 hunks)ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api(8 hunks)ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api(8 hunks)ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt(4 hunks)ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/SecurityScheme.kt(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/SecurityScheme.kt
- ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/src/io/ktor/annotate/SecuritySchemeAnnotation.jvm.kt
🧰 Additional context used
📓 Path-based instructions (2)
**/*.kt
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.kt: Follow Kotlin official style guide (https://kotlinlang.org/docs/coding-conventions.html)
Use star imports forio.ktor.*packages
Document all public APIs including parameters, return types, and exceptions
Mark internal APIs with@InternalAPIannotation
Run./gradlew lintKotlinand fix all linting issues before giving control back to the user
Use./gradlew formatKotlinto automatically fix formatting issues
Run./gradlew updateLegacyAbiafter making ABI changes to update ABI signature files
Binary compatibility is enforced - all public API changes must be tracked in the/api/directories
Validate ABI with./gradlew checkLegacyAbiand update with./gradlew updateLegacyAbi
API changes must be intentional and well-documented
Error handling follows Kotlin conventions with specific Ktor exceptions
Files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/RouteAnnotationApi.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/RouteAnnotationApiJvmTest.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.ktktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt
**/test/**/*.kt
📄 CodeRabbit inference engine (CLAUDE.md)
Follow test naming pattern:
DescribeWhatIsBeingTested
Files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/RouteAnnotationApiJvmTest.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt
🧠 Learnings (16)
📚 Learning: 2025-05-30T06:45:52.309Z
Learnt from: rururux
Repo: ktorio/ktor PR: 4896
File: ktor-client/ktor-client-core/jvm/test/FileStorageTest.kt:1-12
Timestamp: 2025-05-30T06:45:52.309Z
Learning: In Ktor test files, particularly in the ktor-client/ktor-client-core/jvm/test/ directory, test files follow the convention of not including explicit package declarations. This is consistent across test files like CachingCacheStorageTest.kt and should be maintained for consistency.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : API changes must be intentional and well-documented
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.klib.apiktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.ktktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.apiktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Use star imports for `io.ktor.*` packages
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/RouteAnnotationApi.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Error handling follows Kotlin conventions with specific Ktor exceptions
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/RouteAnnotationApi.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt
📚 Learning: 2025-06-23T12:49:56.883Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-06-23T12:49:56.883Z
Learning: Error handling should follow Kotlin conventions and use specific Ktor exceptions.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/RouteAnnotationApi.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt
📚 Learning: 2025-05-30T06:45:52.309Z
Learnt from: rururux
Repo: ktorio/ktor PR: 4896
File: ktor-client/ktor-client-core/jvm/test/FileStorageTest.kt:1-12
Timestamp: 2025-05-30T06:45:52.309Z
Learning: The headersOf() function from io.ktor.http package is available through wildcard imports like `import io.ktor.http.*`, so no explicit import statement is needed when using wildcard imports from that package.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/RouteAnnotationApi.ktktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Document all public APIs including parameters, return types, and exceptions
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.ktktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Binary compatibility is enforced - all public API changes must be tracked in the `/api/` directories
Applied to files:
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-10-15T16:47:28.272Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 5125
File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt:442-444
Timestamp: 2025-10-15T16:47:28.272Z
Learning: In the ktor-openapi-schema module, the maintainer prefers to keep certain properties mutable (using `var` instead of `val`) in data classes like Response, even when they are part of the public API, to allow flexibility during construction and modification.
Applied to files:
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-10-15T16:46:27.493Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 5125
File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt:43-43
Timestamp: 2025-10-15T16:46:27.493Z
Learning: In the ktor-openapi-schema module, Operation objects (and related OpenAPI objects) are designed to be composable and can be combined from multiple sources. Therefore, properties like `responses` should remain nullable to support intermediate states during object composition/merging.
Applied to files:
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.apiktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api
📚 Learning: 2025-11-26T11:34:00.471Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 5206
File: ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.kt:150-150
Timestamp: 2025-11-26T11:34:00.471Z
Learning: In OpenAPI 3.1.1 specification, the Components.schemas field is defined as Map[string, Schema Object] and does NOT allow Reference Objects at the top level, unlike other component fields (responses, parameters, examples, requestBodies, headers, links, callbacks) which are defined as Map[string, <Type> | Reference Object].
Applied to files:
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/*.kt : Mark internal APIs with `InternalAPI` annotation
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api
📚 Learning: 2025-11-27T10:07:26.686Z
Learnt from: osipxd
Repo: ktorio/ktor PR: 5205
File: ktor-client/ktor-client-curl/desktop/interop/include/curl/multi.h:410-420
Timestamp: 2025-11-27T10:07:26.686Z
Learning: In the ktorio/ktor repository, do not review files under `ktor-client/ktor-client-curl/desktop/interop/include/curl/*` as these are upstream libcurl header files copied from the curl project and not maintained by the Ktor team.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api
📚 Learning: 2025-05-14T18:05:02.321Z
Learnt from: bjhham
Repo: ktorio/ktor PR: 4855
File: ktor-server/ktor-server-plugins/ktor-server-di/api/ktor-server-di.klib.api:334-336
Timestamp: 2025-05-14T18:05:02.321Z
Learning: Breaking changes in constructor parameter order are acceptable for the ktor-server-di module when the code hasn't been released yet, as confirmed by the development team.
Applied to files:
ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt
📚 Learning: 2025-08-14T15:17:11.466Z
Learnt from: zibet27
Repo: ktorio/ktor PR: 5044
File: ktor-client/ktor-client-webrtc/ktor-client-webrtc-rs/build.gradle.kts:12-12
Timestamp: 2025-08-14T15:17:11.466Z
Learning: The Cargo plugin (dev.gobley.cargo) used in the Ktor WebRTC RS module depends on the kotlin("plugin.atomicfu") plugin, so atomicfu should not be removed even if there are no direct kotlinx.atomicfu imports in the module's source code.
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt
📚 Learning: 2025-11-25T09:38:19.393Z
Learnt from: CR
Repo: ktorio/ktor PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T09:38:19.393Z
Learning: Applies to **/test/**/*.kt : Follow test naming pattern: `DescribeWhatIsBeingTested`
Applied to files:
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt
🧬 Code graph analysis (4)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt (5)
ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/Authentication.kt (3)
install(127-130)provider(27-29)provider(38-47)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BasicAuth.kt (3)
basic(112-117)basic(126-134)validate(99-101)ktor-server/ktor-server-plugins/ktor-server-auth-api-key/common/src/io/ktor/server/auth/apikey/ApiKeyAuth.kt (3)
apiKey(20-25)apiKey(33-41)validate(131-133)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (2)
registerBearerAuthSecurityScheme(195-204)registerBasicAuthSecurityScheme(181-186)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/DynamicProviderConfig.kt (1)
authenticate(19-21)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/RouteAnnotationApi.kt (2)
ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.kt (1)
Components(154-197)ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt (4)
security(187-189)requirement(945-947)requirement(956-958)optional(964-966)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt (2)
ktor-server/ktor-server-test-host/common/src/io/ktor/server/testing/TestApplication.kt (1)
startApplication(415-417)ktor-server/ktor-server-plugins/ktor-server-auth/common/src/io/ktor/server/auth/BearerAuth.kt (1)
authSchemes(104-107)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt (3)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/RouteAnnotationApi.kt (1)
generateOpenApiSpec(56-85)ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/OpenApiSpecification.kt (1)
OpenApiInfo(74-130)ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/SecuritySchemeAnnotation.kt (1)
registerApiKeySecurityScheme(214-222)
🪛 ast-grep (0.40.0)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt
[warning] 23-23: A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive data, can be leaked and used by internal or external malicious actors. It is recommended to rotate the secret and retrieve them from a secure secret vault or Hardware Security Module (HSM), alternatively environment variables can be used if allowed by your company policy.
Context: Algorithm.HMAC256(jwtSecret)
Note: [CWE-798]: Use of Hard-coded Credentials [OWASP A03:2021]: Identification and Authentication Failures [REFERENCES]
- https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures
(jwt-hardcode-kotlin)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/RouteAnnotationApiJvmTest.kt
[warning] 29-29: A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive data, can be leaked and used by internal or external malicious actors. It is recommended to rotate the secret and retrieve them from a secure secret vault or Hardware Security Module (HSM), alternatively environment variables can be used if allowed by your company policy.
Context: Algorithm.HMAC256(jwtSecret)
Note: [CWE-798]: Use of Hard-coded Credentials [OWASP A03:2021]: Identification and Authentication Failures [REFERENCES]
- https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures
(jwt-hardcode-kotlin)
🔇 Additional comments (24)
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/nonJvm/src/io/ktor/annotate/SecuritySchemeAnnotation.nonJvm.kt (1)
11-14: LGTM! Non-JVM stub implementation is correct.The platform-specific stub correctly returns null for non-JVM targets with a clear explanatory comment. This aligns with the cross-platform design where JVM provides concrete inference for Digest and JWT providers, while non-JVM platforms have no platform-specific metadata available.
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/src/io/ktor/annotate/RouteAnnotationApi.kt (2)
178-217: Well-structured OpenAPI security generation from authentication routes.The mapping of Ktor's
AuthenticationStrategyto OpenAPI security requirements is correct:
FirstSuccessful→ separate requirements (OR relationship)Required→ combined map (AND relationship)Optional→ includes empty requirement for unauthenticated access
220-235: The destructuring order inRouteAnnotationApi.ktline 223 is correct. TheOAuthFlowsdata class defines fields in this exact order:implicit,password,clientCredentials,authorizationCode. The destructuring matches this order, so there is no risk of silently assigning wrong flow types.Likely an incorrect or invalid review comment.
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/SecuritySchemeInferenceTest.kt (2)
7-7: Unused import.The
HttpClientimport appears to be used only for creating OAuth provider configurations. Consider if this is intentional or if a mock/test client should be used instead.
16-432: Comprehensive test coverage for security scheme inference.The test suite thoroughly covers:
- All supported authentication provider types (basic, bearer, apiKey, session, oauth)
- Edge cases (empty plugin, no plugin, dynamic providers)
- Manual registration overrides
- Caching behavior
- Default provider naming
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/common/test/io/ktor/annotate/RouteAnnotationApiTest.kt (2)
319-431: Thorough test coverage for automatic security annotations.This test validates the correct mapping of Ktor authentication strategies to OpenAPI security requirements:
- Single auth schemes (lines 386-402)
FirstSuccessfulcreating OR relationships (lines 404-413)Requiredcreating AND relationships (lines 415-422)Optionalstrategy (lines 424-430)
478-531: Good OAuth2 security annotation test.The test correctly validates OAuth2 security scheme generation including authorization code flow and scope extraction. Using
this@testApplication.clientfor the OAuth provider configuration is an appropriate approach for testing.ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/Operation.kt (2)
456-459: LGTM - simplified example wrapping.Using
Value(example)directly (via the star import) is cleaner thanReferenceOr.Value(example).
949-966: Well-documented security DSL extensions.The new methods correctly implement OpenAPI security semantics:
requirement(schemes: Map)for AND relationships (all schemes must be satisfied)optional()adds an empty requirement per OpenAPI spec to allow unauthenticated accessThe documentation clearly explains the OR/AND relationship patterns.
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/RouteAnnotationApiJvmTest.kt (3)
27-30: Hardcoded test credentials are acceptable here.The static analysis warning about hardcoded credentials is a false positive for this test file. These are test-only fixtures used to configure JWT verification in a controlled test environment, not production secrets.
39-55: Clean test helper function.The
openApiTestRouteshelper reduces duplication between tests by parameterizing the authentication provider name. This follows good test organization practices.
90-121: Good JVM-specific JWT security test.The test correctly validates that JWT authentication providers are inferred as HTTP bearer schemes with
bearerFormat: "JWT", which is important for API consumers to understand the expected token format.ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.klib.api (1)
20-36: New security-scheme KLIB ABI entries look consistent with common source.
AuthSecuritySchemesAttributeKeyand theApplicationextensions for finding/registering security schemes (including API key/basic/bearer/OAuth2/OpenID Connect) match the intended public API surface and appear ABI‑correct. No changes needed here.ktor-server/ktor-server-plugins/ktor-server-routing-annotate/jvm/test/io/ktor/annotate/JvmSecuritySchemeInferenceTest.kt (1)
1-147: Good JVM coverage for digest/JWT inference and registration.The tests exercise both inferred and explicitly registered schemes (including custom descriptions and custom auth schemes) and validate type/scheme/bearerFormat/description as expected. This should give solid confidence in the JVM‐specific inference helpers.
ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.klib.api (1)
27-42: OpenAPI security-scheme ABI surface is coherent and spec-aligned.The new
SecuritySchemeIn/SecuritySchemeTypeenums,SecuritySchemehierarchy (API key/HTTP/OAuth2/OpenID Connect),Components.securitySchemes, OAuth flow types, andSecurity.Builderhelpers (includingoptional) form a consistent model and match the OpenAPI 3.x structure. From an ABI perspective this looks well‑shaped; no further adjustments needed here.Also applies to: 164-175, 189-229, 231-269, 557-603, 983-1103, 1270-1307, 1826-1867
ktor-server/ktor-server-plugins/ktor-server-routing-annotate/api/ktor-server-routing-annotate.api (1)
29-53: JVM ABI for security-scheme helpers matches the Kotlin declarations.
SecuritySchemeAnnotationKtandSecuritySchemeAnnotation_jvmKtexpose the expectedfind*andregister*SecuritySchememethods (including synthetic default-argument bridges) and correctly surfaceAuthSecuritySchemesAttributeKey. The.apilooks in sync with the source module and ABI tracking requirements.ktor-shared/ktor-openapi-schema/api/ktor-openapi-schema.api (8)
37-72: LGTM: ApiKeySecurityScheme follows OpenAPI spec and project patterns.The structure is complete with proper serialization support, component/copy methods, and interface implementations.
107-111: LGTM: Components expansion maintains binary compatibility.The addition of
securitySchemesfollows the existing pattern for component types. The synthetic constructor withDefaultConstructorMarkerat line 108 indicates default parameters are used, maintaining backward compatibility for existing callers.Based on learnings: Binary compatibility is enforced in this codebase.
Also applies to: 120-121, 133-133
819-852: LGTM: OAuth2SecurityScheme properly structured for OpenAPI OAuth2 flows.The implementation correctly uses
OAuthFlowsto encapsulate the various OAuth2 flow types, consistent with OpenAPI 3.x specification.
854-927: LGTM: OAuth flow types complete per OpenAPI specification.Both
OAuthFlowandOAuthFlowscorrectly model the OAuth2 flow structure per OpenAPI 3.x spec. The inclusion ofrefreshUrl(line 870) aligns with the PR objectives for supporting refresh token flows.
1080-1113: LGTM: OpenIdConnectSecurityScheme properly models OIDC discovery.The structure correctly uses
openIdConnectUrlfor the OpenID Connect discovery endpoint, consistent with OpenAPI 3.x specification.
1647-1684: LGTM: SecurityScheme interface and enums align with OpenAPI specification.The
SecuritySchemeinterface provides a consistent contract for all security scheme implementations. The enums (SecuritySchemeInandSecuritySchemeType) correctly represent the valid values per OpenAPI 3.x spec.
1637-1637: LGTM: Security$Builder enhancements improve API ergonomics.The addition of
optional()and therequirement(Map<String, List>)overload provide more flexible ways to construct security requirements, complementing the existing string-based API.Also applies to: 1639-1639
452-490: No verification needed—DEFAULT_DESCRIPTION constants are correct and consistent.The DEFAULT_*_DESCRIPTION constants in HttpSecurityScheme already use consistent uppercase "HTTP" casing across all schemes (Basic, Bearer, Digest, JWT). Test expectations in SecuritySchemeInferenceTest.kt confirm these values are correct. No changes required.
OpenAPI Security. KTOR-9085 Infer security schemes from the
Authenticationplugin.Subsystem
Server OpeAPI.
Motivation
KTOR-9085 Read OpenAPI security details from authentication plugin
Solution
New API:
securitySchemesas an OpenAPI Spec component. It has all implementations described in the specAuthenticationplugin (we allow combining these approaches, manual has higher priority).:ktor-server-routine-annotatenow depends onktor-server-authviacompileTime. If a developer tries to infer smth from the auth plugin that isn't installed, it should throw a runtime error. It seems to be working, but I'm not sure about non-JVM platforms.Changes to old API:
descriptionfield toAuthenticationProviderand its descendants with new helper functions. Used for API docs only.settingsproperty insideOAuthAuthenticationProvider, which works likeproviderLookupbut static, allows generating OpenAPI docs and should be a bit faster.OAuth2ServerSettings.refreshUrlanddefaultScopeDescriptionsfor docs purposes.@InternalAPIinstead of internal.