Skip to content

Commit

Permalink
add documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
SoMuchForSubtlety committed Sep 28, 2021
1 parent 581ff18 commit a768771
Show file tree
Hide file tree
Showing 5 changed files with 116 additions and 1 deletion.
50 changes: 50 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
ws-stomp is a simple wrapper over a websocket connection that allows it to play nice with [go-stomp/stomp](https://github.com/go-stomp/stomp).


## Example usage:

```golang
package main

import (
"context"
"log"
"time"

wsstomp "github.com/SoMuchForSubtlety/ws-stomp"
"github.com/go-stomp/stomp/v3"
)

func main() {
// timeout if the connection isn't established after ten seconds
ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
// connect to websocket
conn, err := wsstomp.Connect(ctx, "wss://test.com/ws", nil)
cancel()
if err != nil {
log.Printf("error during WS connect: %v", err)
return
}

// init STOMP connection using the websocket connections
stompConn, err := stomp.Connect(conn)
if err != nil {
conn.Close()
log.Printf("error during STOMP connect: %v", err)
return
}
defer func() {
err = stompConn.Disconnect()
if err != nil {
log.Printf("error during STOMP disconnect: %v", err)
}
}()

// send a message
err = stompConn.Send("/queue/a", "text/plain", []byte("hello world!"))
if err != nil {
log.Println(err)
return
}
}
```
44 changes: 44 additions & 0 deletions example_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
package wsstomp_test

import (
"context"
"log"
"time"

wsstomp "github.com/SoMuchForSubtlety/ws-stomp"
"github.com/go-stomp/stomp/v3"
)

// ExampleEstablishConnection demonstrates how to use this library to talk STOMP over a websocket connection
func Example_establishConnection() {
// timeout if the connection isn't established after ten seconds
ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
// connect to websocket
conn, err := wsstomp.Connect(ctx, "wss://test.com/ws", nil)
cancel()
if err != nil {
log.Printf("error during WS connect: %v", err)
return
}

// init STOMP connection using the websocket connections
stompConn, err := stomp.Connect(conn)
if err != nil {
conn.Close()
log.Printf("error during STOMP connect: %v", err)
return
}
defer func() {
err = stompConn.Disconnect()
if err != nil {
log.Printf("error during STOMP disconnect: %v", err)
}
}()

// send a message
err = stompConn.Send("/queue/a", "text/plain", []byte("hello world!"))
if err != nil {
log.Println(err)
return
}
}
5 changes: 4 additions & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,7 @@ module github.com/SoMuchForSubtlety/ws-stomp

go 1.16

require nhooyr.io/websocket v1.8.7
require (
github.com/go-stomp/stomp/v3 v3.0.3
nhooyr.io/websocket v1.8.7
)
9 changes: 9 additions & 0 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ github.com/go-playground/universal-translator v0.17.0 h1:icxd5fm+REJzpZx7ZfpaD87
github.com/go-playground/universal-translator v0.17.0/go.mod h1:UkSxE5sNxxRwHyU+Scu5vgOQjsIJAF8j9muTVoKLVtA=
github.com/go-playground/validator/v10 v10.2.0 h1:KgJ0snyC2R9VXYN2rneOtQcw5aHQB1Vv0sFl1UcHBOY=
github.com/go-playground/validator/v10 v10.2.0/go.mod h1:uOYAAleCW8F/7oMFd6aG0GOhaH6EGOAJShg8Id5JGkI=
github.com/go-stomp/stomp/v3 v3.0.3 h1:7YQGJCDMkbA05Rw8dS00LxwU1mhzEHS69gMlPjMZGDk=
github.com/go-stomp/stomp/v3 v3.0.3/go.mod h1:jTrybHBK20jPdM9iyh65m6GusX6aMf7atfEFZ1nIcgc=
github.com/gobwas/httphead v0.0.0-20180130184737-2c6c146eadee h1:s+21KNqlpePfkah2I+gwHF8xmJWRjooY+5248k6m4A0=
github.com/gobwas/httphead v0.0.0-20180130184737-2c6c146eadee/go.mod h1:L0fX3K22YWvt/FAX9NnzrNzcI4wNYi9Yku4O0LKYflo=
github.com/gobwas/pool v0.2.0 h1:QEmUOlnSjWtnpRGHF3SauEiOsy82Cup83Vf2LcMlnc8=
Expand All @@ -29,6 +31,11 @@ github.com/json-iterator/go v1.1.9 h1:9yzud/Ht36ygwatGx56VwCZtlI/2AD15T1X2sjSuGn
github.com/json-iterator/go v1.1.9/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/uOdHXbAo4=
github.com/klauspost/compress v1.10.3 h1:OP96hzwJVBIHYU52pVTI6CczrxPvrGfgqF9N5eTO0Q8=
github.com/klauspost/compress v1.10.3/go.mod h1:aoV0uJVorq1K+umq18yTdKaF57EivdYsUV+/s2qKfXs=
github.com/kr/pretty v0.2.1 h1:Fmg33tUaq4/8ym9TJN1x7sLJnHVwhP33CNkpYV/7rwI=
github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE=
github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
github.com/leodido/go-urn v1.2.0 h1:hpXL4XnriNwQ/ABnpepYM/1vCLWNDfUNts8dX3xTG6Y=
github.com/leodido/go-urn v1.2.0/go.mod h1:+8+nEpDfqqsY+g338gtMEUOtuK+4dEMhiQEgxpxOKII=
github.com/mattn/go-isatty v0.0.12 h1:wuysRhFDzyxgEmMf5xjvJ2M9dZoWAXNNr5LSBS7uHXY=
Expand All @@ -53,6 +60,8 @@ golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGm
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
gopkg.in/yaml.v2 v2.2.8 h1:obN1ZagJSUGI0Ek/LBmuj4SNLPfIny3KsKFopxRdj10=
gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
Expand Down
9 changes: 9 additions & 0 deletions wsstomp.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ const (
LineFeedByte = 0x0a
)

// Read messages from the websocket connection until the provided array is full.
// Any surplus data is preserved for the next Read call
func (w *WebsocketSTOMP) Read(p []byte) (int, error) {
// if we have no more data, read the next message from the websocket
if len(w.readerBuffer) == 0 {
Expand All @@ -34,6 +36,10 @@ func (w *WebsocketSTOMP) Read(p []byte) (int, error) {
return n, nil
}

// Write to the websocket.
//
// The written data is held back until a full STOMP frame has been written,
// then a WS message is sent.
func (w *WebsocketSTOMP) Write(p []byte) (int, error) {
var err error
w.writeBuffer = append(w.writeBuffer, p...)
Expand All @@ -52,6 +58,9 @@ func (w *WebsocketSTOMP) Close() error {
return w.connection.Close(websocket.StatusNormalClosure, "terminating connection")
}

// Establish a websocket connection with the provided URL.
// The context parameter will only be used for the connection handshake,
// and not for the full lifetime of the connection.
func Connect(ctx context.Context, url string, options *websocket.DialOptions) (*WebsocketSTOMP, error) {
con, _, err := websocket.Dial(ctx, url, options)
return &WebsocketSTOMP{
Expand Down

0 comments on commit a768771

Please sign in to comment.