Add support for protocol upgrades #1119

mtrudel · 2022-10-03T23:07:30Z

This PR is the first step on the road to overhauling how WebSocket server support is exposed to & used by Plug-based applications such as Phoenix (see phoenixframework/phoenix#5003 for background).

Support is added here for a new Plug.Conn.upgrade_adapter/3 function, and a backing Plug.Conn.Adapter.upgrade/3 callback. The intent of this PR is solely to provide the minimal plumbing necessary for Plug applications to be able to request a protocol upgrade from the underlying web server; beyond this minimum plumbing no requirements are put on the upgrade process, supported protocols, or how a Plug application is expected to determine if a connection is suitable for upgrading.

This PR represents the total extent of changes expected to the Plug API as a result of the work laid out in the linked issue above, and can be reviewed & merged as-is, or kept open & considered as part of the overall workup; it's up to you.

Companion PRs for this are at elixir-plug/plug_cowboy#88 and mtrudel/bandit#38.

* Update a number of existing tests on :sent that were too narrow in scope * Update docs to reflect widening of scope

lib/plug/conn.ex

mtrudel · 2022-10-16T20:16:50Z

@josevalim as requested, this work is done and ready for review! See phoenixframework/phoenix#5003 for an overview & merge proposal.

lib/plug/test.ex

mtrudel · 2022-10-28T16:57:16Z

If I may make the gentlest & most humble request to have this work reviewed it would be greatly appreciated. I've got a pretty significant backlog of work on Bandit whose release is blocked on this. No need to get to the rest of phoenixframework/phoenix#5003, but this one PR making its way into a Plug release would really unblock forward progress on Bandit.

Of course, if there's anything I can do to help, please let me know.

A most gracious thank you!

ericmj

I like the idea of a generic upgrade function but if we only need to support websockets for now maybe we can make it an upgrade_websocket function instead so that we can actually document the functionality in plug itself and make it generic for all adapters?

If we need to support more upgrade protocols in the future it would be easier to reason about a generic API for it since we will have more than a single protocol to design around.

lib/plug/conn.ex

mtrudel · 2022-10-29T14:40:05Z

I like the idea of a generic upgrade function but if we only need to support websockets for now maybe we can make it an upgrade_websocket function instead so that we can actually document the functionality in plug itself and make it generic for all adapters?

If we need to support more upgrade protocols in the future it would be easier to reason about a generic API for it since we will have more than a single protocol to design around.

José and I had a back and forth on this exact detail previously; see the discussion from phoenixframework/phoenix#4973 (comment) downwards. The outcome of this drives a relevant response to all the other issues you've raised above. To be clear, I don't care too much one way or the other (they're both internally consistent perspectives), though I do have a minor bias towards treating this as a lower level adapter concern since it purposely keeps the upgrade semantics vague.

In terms of other future uses, I'm planning on adding explicit h2c upgrade support to Bandit as part of the 0.7 release later in 2022, and will be using this same mechanism to accomplish it.

Since you and José have expressed opposing (and both valid!) points on the shape of this API, I think we should let him weigh in here to get consensus.

Thanks for the review!

ericmj · 2022-10-29T14:43:46Z

If you already came to a decision on this then let's go with that. I didn't realize this had already been discussed.

mtrudel · 2022-10-29T14:46:08Z

@ericmj sounds good! I'll comment on your issues above with that understanding.

josevalim · 2022-10-29T14:52:57Z

This looks great to me! My only question is about opts.

We could make it term, as I originally proposed, but we could also force it to be a keyword list? For example, Cowboy would do this:

upgrade_adapter(conn, :websocket, handler: {Foo, arg}, fullsweep_after: 400)

Which maybe is better than:

upgrade_adapter(conn, :websocket, {Foo, arg, fullsweep_after: 400})

Do you have any preferences @mtrudel / @ericmj?

josevalim · 2022-10-29T14:56:22Z

Another concern with the current API is that someone could do:

upgrade_adapter(conn, :websocket, opts)

instead of:

upgrade_adapter(conn, :websockets, opts)

And it would work as a no-op and can be hard to debug. Maybe we should hardcode the existing upgrades to avoid those situations? I assume it is a small list anyway?

mtrudel · 2022-10-29T14:57:30Z

To your original point José, I think the intentional vagueness of term is the right way to go here. No strong feeling on it though.

mtrudel · 2022-10-29T15:00:39Z

And it would work as a no-op and can be hard to debug. Maybe we should hardcode the existing upgrades to avoid those situations? I assume it is a small list anyway?

Good catch. I think this should be the duty of the underlying sever to raise loudly on an upgrade request that isn't supported (raising is appropriate here I think, since there's no otherwise correct way to fallback in this case; it's an obvious programmer error).

I can update the Plug.Cowboy and Bandit PRs to match this if we agree

mtrudel · 2022-10-29T15:09:16Z

(Note that I updated opts to args above)

josevalim · 2022-10-29T15:18:11Z

Good catch. I think this should be the duty of the underlying sever to raise loudly on an upgrade request that isn't supported (raising is appropriate here I think, since there's no otherwise correct way to fallback in this case; it's an obvious programmer error).

When would we return {:error, _} then?

mtrudel · 2022-10-29T15:23:00Z

That's a good question! I might suggest that we keep the adapter contract as 'return an ok or error tuple' and have Plug.Conn be the one to raise that as an error (ie: raise at https://github.com/elixir-plug/plug/pull/1119/files#diff-a6b7dff2ccb7fd0cb9c7d1893c4c05f3ec3c714ad04495ef87240449ed3446f3R1401).

This keeps adapters from worrying about use particulars of how to surface the error, keeping that logic in a consolidated place within Plug.Conn.

To be clear, this error is not 'the application requested a valid upgrade type but was unable to do the upgrade based on the client request', but rather 'the application requested an upgrade to a protocol I don't know about'. Presumably this is going to be squarely a programmer error and not a data or client error, so a raise would be appropriate.

WDYT?

josevalim · 2022-10-29T16:03:08Z

Agreed on matching on {:error, _} and raising then!

mtrudel · 2022-10-29T16:06:13Z

Super. I'll have this done within the hour.

mtrudel · 2022-10-29T16:20:03Z

Changes complete! To summarize the plan to get phoenixframework/phoenix#5030 ready for review into 1.7:

@josevalim to review & merge this PR, and cut a plug point release
@mtrudel to update Implement WebSocket support based on Plug.Conn.Adapter.upgrade/3 plug_cowboy#88 based on code comments therein & depending on the version of Plug released in this PR
@josevalim to review & merge that work & cut a plug_cowboy point release (subject to changes, of course)
@mtrudel to update Implement WebSocket support based on Plug.Conn.Adapter.upgrade/3 mtrudel/bandit#38 on these same lines
We can focus on Implement WebSocket negotiation support based on Plug.Conn.upgrade_adapter/3 phoenixframework/phoenix#5030 in isolation!

josevalim · 2022-10-29T16:23:54Z

Yup, perfect!

Co-authored-by: José Valim <jose.valim@gmail.com>

josevalim

Perfect! I think this is good to go, let's just wait to be double sure we can tackle everything on Cowboy side. :)

lib/plug/conn.ex

josevalim · 2022-10-30T08:12:24Z

lib/plug/adapters/test/conn.ex

@@ -119,6 +119,16 @@ defmodule Plug.Adapters.Test.Conn do
    :ok
  end

+  def upgrade(%{owner: owner, ref: ref} = state, :supported = protocol, opts) do


Shouldn't this be :websocket instead of :supported? Because I think folks may want to test that a given connection upgrades at certain moments?

In fact, maybe we should allow everything and only support :unsupported to test the :unsupported cases.

I'd intentionally used :supported and :unsupported to help illustrate that this implementation was only useful to test whether or not an upgrade is supported or not (specifically, users wouldn't get confused seeing :websocket and wondering why a full-fledged client upgrade didn't work).

The test process still gets send a message in this case, which should be sufficient for users to test against. Really, all this needs to do is be able to replicate the return value for a supported and unsupported upgrade.

But as-is it means I wouldn’t be able to test that a specific route is triggering a websocket upgrade, right? Because we would get a function clause error?

Oh yes, I see your concern now. I suppose given that this is a test plug all bets are off with respect to upgrades (or anything else, really) actually doing anything.

I'll update

josevalim · 2022-10-30T14:33:47Z

lib/plug/adapters/test/conn.ex

@@ -119,6 +119,16 @@ defmodule Plug.Adapters.Test.Conn do
    :ok
  end

+  def upgrade(%{owner: owner, ref: ref}, :unsupported = protocol, opts) do


Maybe call it :not_supported for consistency?

josevalim

This is great to me! ❤️ Let's get the Cowboy one ready and I can ship both!

josevalim · 2022-10-31T15:20:14Z

💚 💙 💜 💛 ❤️

mtrudel · 2022-10-31T15:21:45Z

🥳

ericmj · 2022-10-31T16:38:27Z

Thank you @mtrudel!

mtrudel added 2 commits September 28, 2022 21:54

Define :upgraded Plug.Conn state

dba4979

* Update a number of existing tests on :sent that were too narrow in scope * Update docs to reflect widening of scope

Add Plug.Conn.upgrade_adpater/3 & supporting Plug.Conn.Adapter callback

010dcdf

mtrudel commented Oct 3, 2022

View reviewed changes

lib/plug/conn.ex Show resolved Hide resolved

mtrudel commented Oct 3, 2022

View reviewed changes

lib/plug/conn.ex Show resolved Hide resolved

mtrudel commented Oct 3, 2022

View reviewed changes

lib/plug/conn.ex Show resolved Hide resolved

Minor doc updates

e3bf900

mtrudel mentioned this pull request Oct 16, 2022

Implement WebSocket support based on Plug.Conn.Adapter.upgrade/3 mtrudel/bandit#38

Merged

Gazler reviewed Oct 18, 2022

View reviewed changes

lib/plug/test.ex Outdated Show resolved Hide resolved

Fix minor copy-pasta variable name issue

804a68f

mtrudel mentioned this pull request Oct 21, 2022

Implement WebSocket negotiation support based on Plug.Conn.upgrade_adapter/3 phoenixframework/phoenix#5030

Merged

ericmj reviewed Oct 29, 2022

View reviewed changes

lib/plug/conn.ex Outdated Show resolved Hide resolved

lib/plug/conn.ex Outdated Show resolved Hide resolved

lib/plug/conn.ex Show resolved Hide resolved

lib/plug/conn.ex Show resolved Hide resolved

Prefer 'args' over 'opts' to demonstrate opacity

8df9c71

Raise an ArgumentError on unsupported upgrade protocols

4d1884e

Update lib/plug/conn.ex

608a72a

Co-authored-by: José Valim <jose.valim@gmail.com>

josevalim approved these changes Oct 30, 2022

View reviewed changes

josevalim reviewed Oct 30, 2022

View reviewed changes

lib/plug/conn.ex Outdated Show resolved Hide resolved

josevalim reviewed Oct 30, 2022

View reviewed changes

mtrudel added 3 commits October 30, 2022 10:13

Reformat upgrade error message

1aff012

Merge branch 'elixir-plug:main' into plug_upgrade

e6882eb

Support all upgrades other than :unsupported

29ddd8a

josevalim reviewed Oct 30, 2022

View reviewed changes

s/unsupported/not_supported

a46e2f5

josevalim approved these changes Oct 30, 2022

View reviewed changes

josevalim merged commit 12dbfb8 into elixir-plug:main Oct 31, 2022

mtrudel deleted the plug_upgrade branch October 31, 2022 15:21

mtrudel mentioned this pull request Nov 2, 2022

Plug.Conn.upgrade_adapter/3 doc updates #1120

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add support for protocol upgrades #1119

Add support for protocol upgrades #1119

mtrudel commented Oct 3, 2022 •

edited

mtrudel commented Oct 16, 2022

mtrudel commented Oct 28, 2022 •

edited

ericmj left a comment

mtrudel commented Oct 29, 2022 •

edited

ericmj commented Oct 29, 2022

mtrudel commented Oct 29, 2022

josevalim commented Oct 29, 2022 •

edited

josevalim commented Oct 29, 2022

mtrudel commented Oct 29, 2022

mtrudel commented Oct 29, 2022

mtrudel commented Oct 29, 2022

josevalim commented Oct 29, 2022

mtrudel commented Oct 29, 2022 •

edited

josevalim commented Oct 29, 2022

mtrudel commented Oct 29, 2022

mtrudel commented Oct 29, 2022 •

edited

josevalim commented Oct 29, 2022

josevalim left a comment

josevalim Oct 30, 2022

josevalim Oct 30, 2022

mtrudel Oct 30, 2022

josevalim Oct 30, 2022

mtrudel Oct 30, 2022

mtrudel Oct 30, 2022

josevalim Oct 30, 2022

mtrudel Oct 30, 2022

josevalim left a comment

josevalim commented Oct 31, 2022

mtrudel commented Oct 31, 2022

ericmj commented Oct 31, 2022

Add support for protocol upgrades #1119

Add support for protocol upgrades #1119

Conversation

mtrudel commented Oct 3, 2022 • edited

mtrudel commented Oct 16, 2022

mtrudel commented Oct 28, 2022 • edited

ericmj left a comment

Choose a reason for hiding this comment

mtrudel commented Oct 29, 2022 • edited

ericmj commented Oct 29, 2022

mtrudel commented Oct 29, 2022

josevalim commented Oct 29, 2022 • edited

josevalim commented Oct 29, 2022

mtrudel commented Oct 29, 2022

mtrudel commented Oct 29, 2022

mtrudel commented Oct 29, 2022

josevalim commented Oct 29, 2022

mtrudel commented Oct 29, 2022 • edited

josevalim commented Oct 29, 2022

mtrudel commented Oct 29, 2022

mtrudel commented Oct 29, 2022 • edited

josevalim commented Oct 29, 2022

josevalim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

josevalim left a comment

Choose a reason for hiding this comment

josevalim commented Oct 31, 2022

mtrudel commented Oct 31, 2022

ericmj commented Oct 31, 2022

mtrudel commented Oct 3, 2022 •

edited

mtrudel commented Oct 28, 2022 •

edited

mtrudel commented Oct 29, 2022 •

edited

josevalim commented Oct 29, 2022 •

edited

mtrudel commented Oct 29, 2022 •

edited

mtrudel commented Oct 29, 2022 •

edited