Ktor Expert

Ktor Expert

Delineate Ktor references, enforce client engine selection guidelines, apply token refresh double-check Mutex structures, mandate client disconnect cancellations, and audit with auditktorcode.py.

Index

Use these references for specific Ktor domains:

• Client architecture, engine selection, connection pool tuning, OAuth2 token refresh, certificate pinning: read [client.md](file:///Users/jsanjaya/.gemini/config/skills/ktor-expert/references/client.md)
• Server setup, Netty tuning, first-party DI, HTMX, typed config mapping, request lifecycle cancellation: read [server.md](file:///Users/jsanjaya/.gemini/config/skills/ktor-expert/references/server.md)
• Testing (MockEngine, testApplication, DI overrides, parallel DB isolation, KMP Bearer Auth pitfalls): read [testing.md](file:///Users/jsanjaya/.gemini/config/skills/ktor-expert/references/testing.md)

Core Guidelines (Terse)

Client Engine Choice

• OkHttp (Android) + Darwin (iOS) for mobile. Handles HTTP/2, system proxy, backgrounding, VPN, ATS.
• CIO for server, CLI, Native (if HTTP/2 not required). Note: CIO client is HTTP/1.x only.

Client Lifecycle

• Create one HttpClient singleton, reuse it, close at app shutdown. Per-request client leaks threads/connections.

Token Refresh

• Use Auth plugin with bearer flow. Single-flight refresh is built-in.
• Wrap refresh calls in a coroutine Mutex with double-check lock. Mark refresh request with markAsRefreshTokenRequest() to prevent infinite loops.
• 401 responses must carry WWW-Authenticate: Bearer to trigger the refresh flow.
• Use a separate HttpClient for the refresh call to avoid nested engine deadlocks.

Server Lifecycle & Cancellation

• Use HttpRequestLifecycle plugin (cancelCallOnClose = true) to propagate cancellation on client disconnect (CIO/Netty).
• Keep route tasks cooperative: use ensureActive() or check isActive.

Configuration

• Use environment.config.getAs() in Ktor 3.5.0+ to deserialize root ApplicationConfig directly into data classes.

Dependency Injection

• Use first-party ktor-server-di via dependencies { provide { ... } } to avoid external DI overhead.

Code Examples

• Client setup: [clientsetup.kt](file:///Users/jsanjaya/.gemini/config/skills/ktor-expert/examples/clientsetup.kt)
• Server setup: [serversetup.kt](file:///Users/jsanjaya/.gemini/config/skills/ktor-expert/examples/serversetup.kt)

Static Code Audits

• Run Python validator to inspect codebase for Ktor anti-patterns:

``bash python3 /Users/jsanjaya/.gemini/config/skills/ktor-expert/scripts/audit_ktor_code.py ``

Always verify Ktor client engine target compatibility and enforce the double-checked lock Mutex pattern for authentication. Never install HttpTimeout in MockEngine-backed test clients — it causes deadlocks on KMP native targets during auth retries. Always include WWW-Authenticate: Bearer in 401 mock responses to trigger the Auth plugin refresh flow. Use url.pathSegments (not encodedPath) in sendWithoutRequest for KMP compatibility.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JosephSanjaya
• Source: JosephSanjaya/skills
• License: MIT

Install and usage instructions live in the source repository linked above.