From b6e6a9cee8da4b2d6d96f0ec81c865db0e50b644 Mon Sep 17 00:00:00 2001 From: Marcelo Pires Date: Thu, 6 Sep 2018 16:31:05 +0200 Subject: [PATCH] more documentation --- extensions/debug.go | 1 + transport/transport.go | 21 +++++++++++++++++++-- transport/websocket/websocket.go | 18 ++++++++++++++++++ 3 files changed, 38 insertions(+), 2 deletions(-) diff --git a/extensions/debug.go b/extensions/debug.go index 20d3ffd..5041eb1 100644 --- a/extensions/debug.go +++ b/extensions/debug.go @@ -12,6 +12,7 @@ func debugJson(v interface{}) string { return string(b) } +// type DebugExtension struct { in *log.Logger out *log.Logger diff --git a/transport/transport.go b/transport/transport.go index 69b8e52..e12fdf6 100644 --- a/transport/transport.go +++ b/transport/transport.go @@ -5,8 +5,7 @@ import ( "time" ) -// handshake, connect, disconnect, subscribe, unsubscribe and publish - +//Options represents the connection options to be used by a transport type Options struct { Url string RetryInterval time.Duration @@ -17,15 +16,29 @@ type Options struct { //todo read/write deadline } +//Transport represents the transport to be used to comunicate with the faye server type Transport interface { + //Name returns the transport name Name() string + //Init initializes the transport with the provided options Init(options *Options) error + //Options return the transport Options Options() *Options + //Handshake initiates a connection negotiation by sending a message to the /meta/handshake channel. Handshake() error + //Connect is called after a client has discovered the server’s capabilities with a handshake exchange, + //a connection is established by sending a message to the /meta/connect channel Connect() error + //Disconnect closes all subscriptions and inform the server to remove any client-related state. + //any subsequent method call to the client object will result in undefined behaviour. Disconnect() error + //Subscribe informs the server that messages published to that channel are delivered to itself. Subscribe(subscription string, onMessage func(message message.Data)) error + //Unsubscribe informs the server that the client will no longer listen to incoming event messages on + //the specified channel/subscription Unsubscribe(subscription string) error + //Publish publishes events on a channel by sending event messages, the server MAY respond to a publish event + //if this feature is supported by the server use the OnPublishResponse to get the publish status. Publish(subscription string, message message.Data) (id string, err error) //OnPublishResponse sets the handler to be triggered if the server replies to the publish request //according to the spec the server MAY reply to the publish request, so its not guaranteed that this handler will @@ -34,6 +47,7 @@ type Transport interface { OnPublishResponse(subscription string, onMsg func(message *message.Message)) } +//MetaMessage are channels commencing with the /meta/ segment ans, are the channels used by the faye protocol itself. type MetaMessage = string const ( @@ -44,9 +58,12 @@ const ( MetaHandshake MetaMessage = "/meta/handshake" ) +//EventMessage are published in event messages sent from a faye client to a faye server +//and are delivered in event messages sent from a faye server to a faye client. type EventMessage = int const ( + // EventPublish EventMessage = iota EventDelivery ) diff --git a/transport/websocket/websocket.go b/transport/websocket/websocket.go index a7334f8..9be1620 100644 --- a/transport/websocket/websocket.go +++ b/transport/websocket/websocket.go @@ -17,6 +17,7 @@ func init() { transport.RegisterTransport(&Websocket{}) } +//Websocket represents an websocket transport for the faye protocol type Websocket struct { TransportOpts *transport.Options conn *websocket.Conn @@ -36,6 +37,7 @@ type Websocket struct { var _ transport.Transport = (*Websocket)(nil) +//Init initializes the transport with the provided options func (w *Websocket) Init(options *transport.Options) error { var ( err error @@ -137,6 +139,7 @@ func (w *Websocket) readWorker() error { } } +//Name returns the transport name (websocket) func (w *Websocket) Name() string { return transportName } @@ -152,10 +155,12 @@ func (w *Websocket) nextMsgID() string { return strconv.Itoa(int(atomic.AddUint64(w.msgID, 1))) } +//Options return the transport Options func (w *Websocket) Options() *transport.Options { return w.TransportOpts } +//Handshake initiates a connection negotiation by sending a message to the /meta/handshake channel. func (w *Websocket) Handshake() (err error) { m := message.Message{ Channel: transport.MetaHandshake, @@ -181,6 +186,8 @@ func (w *Websocket) Handshake() (err error) { return nil } +//Connect is called after a client has discovered the server’s capabilities with a handshake exchange, +//a connection is established by sending a message to the /meta/connect channel func (w *Websocket) Connect() error { m := message.Message{ Channel: transport.MetaConnect, @@ -193,6 +200,8 @@ func (w *Websocket) Connect() error { return w.sendMessage(&m) } +//Disconnect closes all subscriptions and inform the server to remove any client-related state. +//any subsequent method call to the client object will result in undefined behaviour. func (w *Websocket) Disconnect() error { m := message.Message{ Channel: transport.MetaDisconnect, @@ -212,6 +221,7 @@ func (w *Websocket) Disconnect() error { return w.sendMessage(&m) } +//Subscribe informs the server that messages published to that channel are delivered to itself. func (w *Websocket) Subscribe(subscription string, onMessage func(data message.Data)) error { m := &message.Message{ Channel: transport.MetaSubscribe, @@ -243,6 +253,8 @@ func (w *Websocket) Subscribe(subscription string, onMessage func(data message.D return nil } +//Unsubscribe informs the server that the client will no longer listen to incoming event messages on +//the specified channel/subscription func (w *Websocket) Unsubscribe(subscription string) error { //https://docs.cometd.org/current/reference/#_bayeux_meta_unsubscribe m := &message.Message{ @@ -262,6 +274,8 @@ func (w *Websocket) Unsubscribe(subscription string) error { return w.sendMessage(m) } +//Publish publishes events on a channel by sending event messages, the server MAY respond to a publish event +//if this feature is supported by the server use the OnPublishResponse to get the publish status. func (w *Websocket) Publish(subscription string, data message.Data) (id string, err error) { id = w.nextMsgID() m := &message.Message{ @@ -276,6 +290,10 @@ func (w *Websocket) Publish(subscription string, data message.Data) (id string, return id, nil } +//OnPublishResponse sets the handler to be triggered if the server replies to the publish request +//according to the spec the server MAY reply to the publish request, so its not guaranteed that this handler will +//ever be triggered +//can be used to identify the status of the published request and for example retry failed published requests func (w *Websocket) OnPublishResponse(subscription string, onMsg func(message *message.Message)) { w.onPubResponseMu.Lock() w.onPublishResponse[subscription] = onMsg