Plugins and Pipeline

## Plugins are the extension model Ktor's core is deliberately small: an engine, a call pipeline, and routing. Compression, CORS, caching headers, content negotiation, call logging, status pages, request validation — all of it is a *plugin* you opt into. Nothing is on by default, which is why a fresh Ktor app does not, for example, negotiate JSON until you install the plugin that does. `install()` is the single verb for that opt-in: ``` fun Application.module() { install(Compression) { gzip() } install(CORS) { allowHost("example.com", schemes = listOf("https")) allowHeader(HttpHeaders.ContentType) } routing { /* ... */ } } ``` The first argument is the plugin object itself; the trailing lambda is a **configuration block** whose receiver is that plugin's own config type. That block runs exactly once, during application startup. This trips people up: code inside `install(X) { ... }` is setup, not per-request logic. If you want per-request behaviour you either configure the plugin to do it or write a custom plugin whose handlers fire per call. ## What installation actually does Installing stores the configured plugin under a key on the pipeline and lets the plugin register its own handlers at points in the call lifecycle. From then on, each incoming call flows through those handlers before or after reaching your route handler. The plugin is a *singleton per scope*, which is why the config block is evaluated once — the resulting configuration is shared by every request. That also explains why installing the same plugin twice in the same scope is rejected rather than silently merged: the pipeline holds one instance per key, and two `install` calls would leave ambiguity about which configuration wins. Consolidate into one call. ## Scopes **Application scope.** `install(...)` on the `Application` receiver inside a module function. Applies to every call the server handles. This is the common case and where most plugins belong. **Route scope.** Plugins built as route-scoped can be installed inside a `route` block: ``` routing { get("/public") { call.respondText("open") } route("/admin") { install(AdminOnlyPlugin) get("/stats") { call.respondText("secret") } } } ``` Only calls that match that subtree see the plugin. This matters when a policy is genuinely local — an audit log for a sensitive subtree, a stricter payload limit for an upload endpoint — and it keeps the cost off the routes that do not need it. The distinction is a property of how the plugin was written, not a flag at the call site: a plugin authored for application scope cannot simply be dropped into a route block. ## Where install calls live Because a module is just `fun Application.module()`, installation is ordinary Kotlin code and can be factored: ``` fun Application.module() { configureMonitoring() configureSerialization() configureRouting() } fun Application.configureMonitoring() { install(CallLogging) } ``` Those helper functions are extension functions on `Application` as well, so each one can install what it owns. This is the layout Ktor's own project generator produces, and it is the reason a Ktor app's setup stays readable as the plugin list grows. ## Common built-in plugins worth naming - **CORS** — browser cross-origin policy: which hosts, methods and headers are allowed. - **Compression** — response encoding, e.g. `gzip()` and `deflate()`, with conditions such as a minimum size. - **CachingHeaders** — attaches `Cache-Control` and related headers to outgoing content. - **CallLogging** — logs each call. - **ContentNegotiation** — request/response body conversion. - **StatusPages** — maps exceptions and status codes to responses. Being able to name a handful, and to say what each *plugs into*, is the tell that you understand the model rather than having copied a template. ## The one-sentence summary for an interview "`install()` attaches a plugin to a pipeline and runs its configuration once at startup; the plugin then hooks into every call flowing through that pipeline. Application scope covers the whole server, route scope narrows it to a subtree, and a plugin only supports route scope if it was written for it."