How do you write a custom Ktor plugin, and when should it be route-scoped instead of application-scoped?

## The modern plugin API Before Ktor 2.0 a custom plugin meant implementing a companion object against a framework interface, wiring an `AttributeKey`, and interacting with the pipeline directly. Ktor 2.0 introduced a much smaller API: you call a factory function and describe the behaviour with handlers. ``` val RequestId = createApplicationPlugin(name = "RequestId") { onCall { call -> val id = call.request.headers["X-Request-Id"] ?: UUID.randomUUID().toString() call.response.headers.append("X-Request-Id", id) } } ``` Install it exactly like a built-in plugin: `install(RequestId)`. ## The handlers - **`onCall { call -> ... }`** — invoked for every call. The place for inspecting or annotating the request and setting response headers. - **`onCallReceive { call -> ... }`** — wraps the point where the request body is converted into an object, so you can observe or influence deserialization. - **`onCallRespond { call, body -> ... }`** — wraps the point where a response is being sent, giving access to the object being responded with. There are also lifecycle hooks registered with `on(...)`, which is how a plugin reacts to events rather than to the plain call flow — for instance responding to an application-lifecycle event, or to a call failing. Using a hook rather than raw pipeline interception is what keeps a plugin readable: you say *when* you want to run, not *which phase index* you want to sit at. ## Configuration A plugin that needs settings declares a config class and passes its constructor: ``` class AuditConfig { var headerName: String = "X-Actor" var includeBody: Boolean = false } val Audit = createApplicationPlugin(name = "Audit", createConfiguration = ::AuditConfig) { val headerName = pluginConfig.headerName require(headerName.isNotBlank()) { "Audit headerName must not be blank" } onCall { call -> val actor = call.request.headers[headerName] ?: "anonymous" call.application.log.info("audit {} {}", actor, call.request.uri) } } ``` Users then write `install(Audit) { headerName = "X-User" }`. Two things to notice. First, `pluginConfig` gives typed access to the values the user set. Second, the `require` runs **once at install time**, so a misconfiguration fails at startup rather than per request. Reading configuration into a local `val` outside the handler is also a small but real optimisation: it happens once instead of on every call. ## Install-time versus per-call code This is the distinction interviewers probe. The factory body executes once when the plugin is installed. Only the code inside `onCall`, `onCallReceive`, `onCallRespond` and the hooks runs per request. So shared state — a metric registry, a compiled pattern, a validated setting — belongs in the body; anything touching the specific call belongs in a handler. Putting per-call logic in the body silently runs it once with no call at all. Because the body's locals are captured by the handlers and shared across all concurrent requests, mutable state there must be safe for concurrent access. A counter must be an atomic type, not a plain `var`. ## Application scope versus route scope `createRouteScopedPlugin` is the same API with a narrower installation target: ``` val AdminAudit = createRouteScopedPlugin(name = "AdminAudit") { onCall { call -> call.application.log.info("admin access {}", call.request.uri) } } routing { route("/admin") { install(AdminAudit) get("/stats") { call.respondText("...") } } } ``` Only calls matching `/admin` pass through it. The decision rule: - **Application scope** when the behaviour is an invariant of the service — request ids, uniform logging, a security header on every response. Something that must not be forgotten on a new route belongs globally, because global installation cannot be forgotten. - **Route scope** when the behaviour is a property of a subtree — heavier auditing for sensitive endpoints, a different policy for an upload path. Local installation both avoids paying the cost everywhere and documents itself: the route block states what applies to it. A useful sanity check: if you would be uncomfortable with a new endpoint *not* having the behaviour, it is application scope. ## When to drop to raw interception The handler-based API covers most needs. Direct `intercept(phase)` remains available and is the tool when you need control the handlers do not express — a very specific position relative to other plugins, or work in a phase the handlers do not surface. Reaching for it first, though, produces plugins that are harder to read and more coupled to install order than they need to be.