The Output Boundary: Rendering, Streaming, and Response State
Gin's output side answers a different question from binding: once an endpoint has an application value, how does it turn that value into an HTTP response, and when does that choice become irreversible? This chapter examines the shared Render seam, the response writer that tracks status and body state, and the different consequences of JSON, templates, files, readers, streams, and negotiated formats. The practical judgment is simple but important: choose an output path by its commitment, resource, and visibility behavior—not only by the convenience of its method name.
Rendering is a contract, not a collection of shortcuts
An endpoint can write directly to Go's http.ResponseWriter, but Gin's rendering layer gives different representations a common contract. A renderer writes content and declares its content type. Context.Render accepts a status code and a renderer, sets the response status, handles cases where an HTTP status must not carry a body, and records a rendering error on the context before aborting if rendering fails.
This shared seam separates two responsibilities. The context owns the HTTP-facing lifecycle: status, headers, the writer, and error attachment. The renderer owns how a value becomes bytes: JSON encoding, template execution, a redirect, a reader copy, or another representation. A JSON renderer and an HTML renderer do different work, but they enter the same status-and-writer path. Middleware can therefore observe a common response lifecycle without knowing every representation the endpoint selected.
The distinction is useful when an endpoint has more than one format. A handler may choose JSON for an API client and HTML for a browser, or use content negotiation to select from formats offered by the server. The rendering seam avoids duplicating all of the surrounding response bookkeeping for each case. It does not erase the differences between representations: a template can expose filesystem and data-model concerns, while a reader or stream can keep resources active after a small value would have been fully serialized.
The renderer also preserves a clear failure path. If serialization or template execution fails, Gin can attach the error to the active context and abort the remaining chain. Whether the client receives a useful error depends on when the failure occurs. If no output has been committed, a later error handler may still control the response. If the renderer has already sent part of the output, the application cannot assume that a new status or body will replace what the client received.
That last condition leads to the most important object on the output side: Gin's wrapped response writer.
The response writer has a one-way lifecycle
Gin's ResponseWriter still implements Go's HTTP writer interfaces, but it adds state that the ordinary interface does not expose directly. It tracks the current status, the number of body bytes written, and whether the response has begun. On a fresh request, the writer has a default status of 200 but has not yet committed anything to the underlying writer.
Calling WriteHeader changes the pending status if the response has not been written. Calling WriteHeaderNow commits the status and headers. A body write commits them automatically first, then sends the body and increments the tracked size. A flush also commits headers before asking the underlying writer to flush. This delayed commitment allows an endpoint to set headers and status before the first body byte, while still ensuring that a normal write produces a valid HTTP response.
Once the writer has committed the response, later status changes are not ordinary assignments. Gin logs a warning when code tries to override a status after headers have already been written and leaves the earlier commitment in place. This behavior explains a common debugging surprise: a handler may call a success renderer, then a later middleware may discover an error and attempt to write a failure status, but the client still sees the first response. The correct repair is to move the decision earlier, not to add another status call after the write.
The writer's body-size counter gives middleware a consistent observation point.