In a web framework, what does it mean for a request handler to return a future, promise or coroutine instead of a finished response?

## Two shapes a handler can have A handler is the function a framework calls once routing has picked it. On most server-side frameworks it can be written in one of two shapes. - **Value-returning.** The handler computes everything it needs and returns the response itself — a body model, a status, or a response object. The framework converts that return into bytes as soon as the call returns. - **Awaitable-returning.** The handler starts the work and returns a *handle* to a result that does not exist yet: a **future**, a **promise**, or a coroutine that will suspend at its first wait point. The handle is a subscription, not a body. | | value-returning handler | awaitable-returning handler | |---|---|---| | what the return value is | the response, or the model for it | a handle to a future response | | when the response is written | when the handler returns | when the handle completes | | while the work is outstanding | control is still inside the handler | the handler has already returned | | where a failure surfaces | thrown out of the call | a failed completion of the handle | | what ends the exchange | the return | the completion callback | ## What the framework does with the handle 1. Routing picks the handler and the framework calls it. 2. The handler starts its work and returns a handle, usually within microseconds. 3. The framework recognises the return as awaitable — from the declared return type, from the registration style used to install the handler, or because every handler on that surface is awaitable — and does **not** try to serialize the handle itself as a body. 4. It attaches a completion callback and leaves the exchange open. Nothing has gone to the socket yet, so status, headers and body are all still changeable. 5. On successful completion it takes the completed value and runs it through the same return-mapping a synchronous return would get: content negotiation, serialization, a default status when none was set. 6. On failed completion it hands the failure to the error stage rather than the serializer. ## Completion carries a value or a failure An awaitable settles exactly once, in one of two ways. A **success** carries the value the handler would otherwise have returned, and the framework converts it normally. A **failure** carries an error, and the framework's error mapping — the same stage that turns a thrown error into a status and a body — gets it instead. Both paths end with the framework, not the handler, writing the response; the handler's job finished the moment it returned the handle. A third outcome is possible and is the dangerous one: the handle **never settles**. There is then no completion callback to fire, so the framework has nothing to write and the exchange simply stays open, holding whatever per-request state it allocated, until some unrelated mechanism tears it down. ## What returning a handle does not change - It does **not** make a blocking call non-blocking. Blocking work inside the handler still occupies whatever thread is running it; wrapping it in a handle only changes the shape of the return. - It does **not** change what the client sees. The protocol carries a status line, headers and a body; it has no notion of how the server produced them. - It does **not**, by itself, speed up a single request. The latency of one request is still dominated by its slowest dependency; what changes is how many requests the process can hold in flight while waiting. - It does **not** exempt the result from validation, negotiation or serialization — the completed value meets the same rules as any return. ## Frameworks differ in how they recognise it Frameworks differ here, and it is worth knowing which style you are in: some inspect the handler's declared return type and adapt whatever awaitable shape they find; some require the handler to be installed through a separate registration so the framework knows in advance; and some make every handler awaitable so the question never arises. The observable behaviour — response written on completion, failure routed to the error stage — is broadly the same across all three. ## Symptoms that you got the shape wrong - The client gets an immediate empty success while log lines from the handler keep arriving afterwards: the handle was created but not returned, so the framework thought the handler was done. - Failures show up as unhandled-error log entries instead of error responses: the failure settled a handle nobody was subscribed to. - Throughput does not improve after a conversion: something on the path still blocks while the handle is outstanding.