Skip to content

feat(handler): send response cookies returned by a handler - #139

Merged
zmstone merged 1 commit into
emqx:masterfrom
zmstone:260905-response-set-cookie
Sep 8, 2026
Merged

zmstone merged 1 commit into
emqx:masterfrom
zmstone:260905-response-set-cookie

Conversation

@zmstone

@zmstone zmstone commented Sep 5, 2026

Copy link
Copy Markdown
Member

Summary

A minirest handler cannot set a response cookie today. reply_with_body/4 passes the
handler's header map straight to cowboy_req:reply/4, and cowboy does not accept
set-cookie there:

%% cowboy_req.erl
reply(_, #{<<"set-cookie">> := _}, _, _) ->
    exit({response_error, invalid_header,
        'Response cookies must be set using cowboy_req:set_resp_cookie/3,4.'});

The reason is that set-cookie is the one response header that must not be folded into
a single line, so a response may carry several of them, while a map holds one value per
name. Cowboy keeps cookies in the request's resp_cookies field and fills the map key
itself at reply time, giving it a list value that each protocol expands into one header
per cookie (cowboy_http:headers_to_list/1, cowboy_http2:headers_to_list/1).

So the key is reserved and type-overloaded. A handler that returns a plain binary there
exits with response_error on cowboy 2.10 and later. On 2.9, which this repo builds
against, there is no guard: the value reaches headers_to_list/1, the list comprehension
gets a binary generator and raises bad_generator in the connection process, and a
cookie set earlier on the request is silently clobbered by response_headers/2.

This moves any set-cookie entry out of the header map into resp_cookies before
replying, which is the translation cowboy expects a framework layered on it to do.

Interface

Return the formatted cookie under the lower case set-cookie key:

login(post, _Params) ->
    Cookie = iolist_to_binary(
        cow_cookie:setcookie(<<"session">>, Token, #{path => <<"/api">>, http_only => true})
    ),
    {200, #{<<"set-cookie">> => Cookie}, #{}}.

The value is one cookie as a binary, or several as a list of binaries, each already
formatted by cow_cookie:setcookie/3. Anything else raises
{invalid_set_cookie_header, Value} at the point of the mistake, rather than deep in the
protocol. Cookies are keyed by name, as cowboy does, so setting the same cookie twice
replaces it instead of sending two headers the browser cannot reconcile, and a cookie a
middleware already set on the request is preserved.

The header name must be lower case. That matches how cowboy keys headers, and HTTP/2
requires it. A differently cased key passes through as an ordinary header, exactly as it
does today.

Compatibility

Handlers that do not return set-cookie are unaffected: one extra maps:take/2 per
response. Handlers that do return it currently crash, so there is no behaviour to keep.

Tests

t_set_cookie and t_set_cookies in minirest_handler_SUITE drive real requests through
the listener and assert the cookies arrive as separate set-cookie headers. The
assertions check the name=value pair and the requested attributes rather than the whole
string, because the attribute list differs between cowlib versions (2.9's cowlib appends
Version=1).

make ct (13 passed), make xref and make fmt-check are clean on OTP 27.2.

Why

Needed by an EMQX Dashboard SSO fix that binds each OIDC and SAML login round-trip to the
browser that started it with a login-start cookie checked at the callback. There is no
route from a minirest handler to a cookie without this.

`set-cookie` is the one response header cowboy does not take from the
headers map. A response may carry several of them, and a map holds one
value per name, so cowboy keeps cookies in the request's `resp_cookies`
field and fills the map key itself at reply time, letting each protocol
write one header per cookie.

minirest passed the handler's header map straight to `cowboy_req:reply/4`
and never touched `resp_cookies`, so a handler had no way to set a cookie.
Returning the header exits with `response_error` on cowboy 2.10 and later,
and silently clobbers any cookie already set on the request before that.

Move any `set-cookie` entry out of the header map and into `resp_cookies`
before replying. The value is one cookie as a binary, or several as a list
of binaries, each already formatted by `cow_cookie:setcookie/3`. Cookies
are keyed by name, as cowboy does, so setting the same cookie twice
replaces it instead of sending two headers the browser cannot reconcile.
zmstone added a commit to zmstone/emqx that referenced this pull request Sep 5, 2026
Temporary. Replace with a released tag once emqx/minirest#139 lands.
The SSO fix needs minirest to send a `set-cookie` returned by a handler;
without it every OIDC login start answers 500.
@zmstone
zmstone marked this pull request as ready for review September 6, 2026 15:39
@zmstone
zmstone marked this pull request as draft September 7, 2026 12:44
@zmstone
zmstone marked this pull request as ready for review September 7, 2026 19:24
@zmstone
zmstone merged commit 5ad9712 into emqx:master Sep 8, 2026
2 checks passed
@zmstone
zmstone deleted the 260905-response-set-cookie branch September 8, 2026 08:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants