add type information to the `webSocketHandler` onConnection callback

[devoncarew]

Currently, the onConnection callback to webSocketHandler is untyped (it's just a Function).

Handler webSocketHandler(Function onConnection,
    {Iterable<String>? protocols,
    Iterable<String>? allowedOrigins,
    Duration? pingInterval})

onConnection is expecting one of two forms:

void Function(WebSocketChannel webSocket)

or

void Function(WebSocketChannel webSocket, String? subprotocol)

If the first form is passed into the param then it is automatically promoted to the 2nd form

  if (onConnection is! void Function(Never, Never)) {
    final innerOnConnection = onConnection;
    // ignore: inference_failure_on_untyped_parameter, avoid_dynamic_calls
    onConnection = (webSocket, _) => innerOnConnection(webSocket);
  }

I'd like to convert the param to include type information. I think it has to be like this:

typedef ConnectionCallback = void Function(
    WebSocketChannel ws, String? subprotocol);

i.e., the caller has to pass in a closure that has two params, even if they never intend to use the subprotocol param. I suspect that 99% of users are currently just passing in a closure w/ one param, so this would require them to update their code.

Even making the typedef into something like typedef ConnectionCallback = void Function(WebSocketChannel ws, [String? subprotocol]); would require their closure to still define the optional param.

Is there any typedef that would let the user not need to have a closure w/ two params?

Or should we specialize webSocketHandler; have the current one take a closure w/ one param (the created websocket), and have a webSocketHandlerSubProtocol() which takes a closure w/ two params?

[devoncarew]

@natebosch - thoughts?

[natebosch]

There is not clean type system solution for this problem. Adding a signature that specifies both arguments is the right pattern to use. It is breaking, but I think we can manage a breaking version release of shelf pretty easily