What type of interface do we want to implement?

[mjohnson9]

We have a choice as to what type of interface we'd like to implement, with each having its pros and cons. I'd like to discuss that here.

The choices so far seem to be:

• The current master branch's event-driven approach
• What I originally proposed in Idiomatic Go implementation #1, our own interface with Send and Receive methods.
• net.Conn
• io.ReadWriteCloser

I personally support the idea of creating an interface very similar to net.TCPConn. After all, a TCP connection is conceptually very, very similar to a WebSocket. The primary advantage of this would be that once gopherjs/gopherjs#89 is resolved, WebSocket would be able to be used in the various libraries that desire a net.Conn. The disadvantage is, of course, that we're significantly straying from the underlying interface.

@shurcooL What do you think?

[dmitshur]

I think an API can be classified as one of two types:

1. A low-level, 1:1 mapping to the JavaScript equivalent API.
   • This is effectively the same as using the JavaScript API directly, except it lets you skip the js.Global.Get("WebSocket").New(url) and write slightly shorter websocket.New(url) code (with autocompletion).
   • In reality, at that point the wrapper mainly serves as good documentation. You can just look at godoc.org/github.com/gopherjs/websocket like any other Go package, and start using websockets faster if you're not familiar with the exact API.
     • This is basically what the the current master is, although it's not feature complete (it has minimal number of features implemented that I needed for my use of websocket).
2. A higher-level API that may be blocking, may be more idiomatic Go and may be easier to use, and would enable uses of other packages.
   • One example of such API is the suggested change in Idiomatic Go implementation #1.
   • Other alternatives are described in this issue above.

I still need to play with/use both (so far I've only actually used the master API) to be able to tell, but my guess is that we might want to support both types if the higher-level API has some disadvantages. Well, that's what we need to investigate, can the high-level API completely replace the low-level one?

If you look at @dominikh's XHR package, it seems to have a similar approach. It gives you a fully customizable low-level API to create a xhr.NewRequest, but also offers higher-level/convenience method to just xhr.Send.

---

On the topic of which high-level API to pick,

I personally like the idea of creating an interface very similar to net.TCPConn. After all, a TCP connection is conceptually very, very similar to a WebSocket. The primary advantage of this would be that once gopherjs/gopherjs#89 is resolved, WebSocket would be able to be used in the various libraries that desire a net.Conn.

I absolutely agree. Especially once gopherjs/gopherjs#89 is resolved, implementing net.Conn will be invaluable as it will allow... well, I've already explained the benefits in gopherjs/gopherjs#89 (comment).

The disadvantage is, of course, that we're significantly straying from the underlying interface.

If we confirm this to be a significant disadvantage, it can be resolved by offering the low-level API too.

• io.ReadWriteCloser

This is basically a subset of net.Conn, isn't it? I think either one of these is good, as going from one to the other is not hard.

• What I originally proposed in Idiomatic Go implementation #1, our own interface with Send and Receive methods.

How different is it, conceptually, from a io.ReadWriteCloser?

[dmitshur]

If @dominikh or @ajhager have some opinions or suggestions here, they would be absolutely welcome.

[mjohnson9]

my guess is that we might want to support both types if the higher-level API has some disadvantages.

I agree. Off the top of my head, the low-level interface would have the following advantages:

• The underlying events are broadcasts, as opposed to functions like Read, which read each message only once.
• The underlying socket's send method is a little bit more flexible than Write([]byte) and WriteString(string).

This is basically a subset of net.Conn, isn't it?

It is, indeed. The only differences are the Deadline functions.

How different is it, conceptually, from a io.ReadWriteCloser?

The interface proposed in #1 and currently in dev is pretty close to the same as io.ReadWriteCloser, but instead of a Read method, it has a Receive method that receives one full frame.

[dmitshur]

I agree. Off the top of my head, the low-level interface would have the following advantages

If that's the case, we'll need to see if they can coexist nicely within one Go package. I would hope so, because it would make it easier to switch from one to the other as 1) your needs change, and 2) you become more familiar with a new API and decide to explore it.

[mjohnson9]

If that's the case, we'll need to see if they can coexist nicely within one Go package. I would hope so, because it would make it easier to switch from one to the other as 1) your needs change, and 2) you become more familiar with a new API and decide to explore it.

I actually just pushed such a thing to the try-NetConn branch. (It's nowhere near complete, of course) 👍

Let me know what you think.

[dmitshur]

I think the try-NetConn branch is starting to look really good. The net.Conn interface implementation in particular looks spot on. It's just a shame it might be a while before we can actually complete and be able to use it.

For the low level, the New() returns right away (just like JavaScript API). How should the user proceed to know when it's safe to use? Are they supposed to add an "open" listener, or check the ReadyState?

[mjohnson9]

How should the user proceed to know when it's safe to use? Are they supposed to add an "onopen" listener, or check the ReadyState?

I believe best practice would be to follow the JavaScript idiom of adding an open event listener. I'll document that soon.

I'm also planning on adding a Dial method that follows the Go idiom of blocking until success/error and returning appropriately.

[dmitshur]

Makes sense.

Yeah, we'll want to have the "getting started" basics/usage example documented. That includes connecting and dealing with success/error, and then sending/receiving. I think the XHR godoc top section is a good example to follow.

Thanks!

[mjohnson9]

I've implemeneted Conn.Read & Conn.Write: 854504c. It's quite a large commit, sorry about that.

A fair bit of the code is copied & modified from the old try-NetConn. I refined the idea of the openCh by only having it exist within Dial and removing the event handlers once they're no longer needed.

After reading up on the W3C spec, I've found out that onerror seems to be redundant for our purposes. Calls to send() should throw exceptions when the WebSocket buffer is full and early disconnection is handled in Conn.onClose.

[dmitshur]

How should the user proceed to know when it's safe to use? Are they supposed to add an "onopen" listener, or check the ReadyState?

I believe best practice would be to follow the JavaScript idiom of adding an open event listener. I'll document that soon.

Would it be a good idea to have OnOpen helper func?

func (ws *WebSocket) OnOpen(handler func(event js.Object)) {
    ws.AddEventListener("open", false, handler)
}

I think that would make the godoc and autocomplete very helpful at helping users figure out what to do.

Or, a section on top like XHR with a complete example that shows how to use ws.AddEventListener("open", ...).

Because the current API (using New) is very unhelpful at figuring out what to do next:

type WebSocket
    func New(url string) (ws *WebSocket, err error)
    func (ws *WebSocket) Close() (err error)
    func (ws *WebSocket) Send(data interface{}) (err error)

[dmitshur]

I'll try Dial(url string) (*Conn, error) API next up.

[dmitshur]

Just tried the net.Conn interface (not extremely thoroughly, just basic connect read and write in my sample app), and it worked really well. It's looking really good!

Dial blocking until connection/error and returning err is awesome. Using Read instead of "onmessage" callback is great. And hopefully there will be some breakthrough in solving gopherjs/gopherjs#89 (comment) sometime to make it that much more useful.

[mjohnson9]

How should the user proceed to know when it's safe to use? Are they supposed to add an "onopen" listener, or check the ReadyState?

I believe best practice would be to follow the JavaScript idiom of adding an open event listener. I'll document that soon.

Would it be a good idea to have OnOpen helper func?

func (ws *WebSocket) OnOpen(handler func(event js.Object)) {
  ws.AddEventListener("open", false, handler)
}

I think that would make the godoc and autocomplete very helpful at helping users figure out what to do.

Or, a section on top like XHR with a complete example that shows how to use ws.AddEventListener("open", ...).

Because the current API (using New) is very unhelpful at figuring out what to do next:

type WebSocket
  func New(url string) (ws *WebSocket, err error)
  func (ws *WebSocket) Close() (err error)
  func (ws *WebSocket) Send(data interface{}) (err error)

I've added package documentation in 797776f. I didn't add a helper, as I felt that the low-level wrapper should be more like idiomatic JavaScript while the high-level one should be more like idiomatic Go. Does that make sense?