Skip to content

Commit

Permalink
Improve WebSocket docs and spec
Browse files Browse the repository at this point in the history
  • Loading branch information
weavejester committed Sep 15, 2023
1 parent 1632c47 commit 0103527
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 15 deletions.
75 changes: 61 additions & 14 deletions SPEC-alpha.md
Original file line number Diff line number Diff line change
Expand Up @@ -242,6 +242,7 @@ It may also be used from an asynchronous handler.
```clojure
(fn [request respond raise]
(respond #:ring.websocket{:listener websocket-listener}))
```

A websocket response contains the following keys. Any key not marked as
**required** may be omitted.
Expand Down Expand Up @@ -275,14 +276,35 @@ protocol:
(on-close [listener socket code reason]))
```

The arguments are described as follows:
#### on-open

Called once when the websocket is first opened. Supplies a `socket`
argument that satisfies `ring.websocket/Socket`, described in section
3.3.

#### on-message

Called when a text or binary message frame is received from the client.
The `message` argument may be a `String` or a `java.nio.ByteBuffer`
depending on whether the message is text or binary.

#### on-pong

Called when a "pong" frame is received from the client. The `data`
argument is a `java.nio.ByteBuffer` that contains optional client
session data.

* `socket` - described in section 3.3.
* `message` - a `String` or `java.nio.ByteBuffer` containing a message
* `data` - a `java.nio.ByteBuffer` containing pong data
* `throwable` - an error inheriting from `java.lang.Throwable`
* `code` - an integer from 1000 to 4999
* `reason` - a string describing the reason for closing the socket
#### on-error

Called when an error occurs. This may cause the websocket to be closed.
The `throwable` argument is a `java.lang.Throwable` that was generated
by the error.

#### on-close

Called once when the websocket is closed. Guaranteed to be called, even
if an error occurs, so may be used for finalizing/cleanup logic. Takes
an integer `code` and a string `reason` as arguments.

### 3.3. Websocket Sockets

Expand All @@ -294,19 +316,44 @@ A socket must satisfy the `ring.websocket/Socket` protocol:
(-send [socket message])
(-ping [socket data])
(-pong [socket data])
(-close [socket status reason]))
(-close [socket code reason]))
```

The types of the arguments are the same as those described for the
`Listener` protocol. The `-open?` method must return true or false.

It *may* optionally satisfy the `ring.websocket/AsyncSocket` protocol:

```clojure
(defprotocol AsyncSocket
(-send-async [socket message succeed fail]))
```

Where `succeed` is a callback function that expects zero arguments, and
`fail` is a callback function expecting a single `java.lang.Throwable`
argument.
#### -open?

Returns a truthy or falsey value denoting whether the socket is
currently connected to the client.

#### -send

Sends a websocket message frame that may be a `String` (for text), or
a `java.nio.ByteBuffer` (for binary).

#### -send-async

As above, but does not block and requires two callback functions:

- `succeed` is called with zero arguments when the send succeeds
- `fail` is called with a single `java.lang.Throwable` argument when the
send fails

#### -ping

Sends a websocket ping frame with a `java.nio.ByteBuffer` of session
data (which may be empty).

#### -pong

Sends an unsolicited pong frame with a `java.nio.ByteBuffer` of session
data (which may be empty).

#### -close

Closes the websocket with the supplied integer code and reason string.
4 changes: 3 additions & 1 deletion ring-core/src/ring/websocket.clj
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,9 @@
:else (throw (ex-info "message is not a valid text or binary data type"
{:message message}))))

(defn open? [socket]
(defn open?
"Returns true if the Socket is open, false otherwise."
[socket]
(boolean (-open? socket)))

(defn send
Expand Down

0 comments on commit 0103527

Please sign in to comment.