Crosser Protocol

The Crosser Protocol is very simple and text-based. It was very much inspired by the protocol written by the people at NATS.IO, especially the idea about using a zero allocation byte parser. The simplicity of the protocol makes it easy to write new clients or just connect via TELNET to test functionality. Although the protocol is inspired by NATS they are much different in functionality. The Crosser Protocol supports RPC/RMI as well as PUB/SUB pattern.

Crosser Protocol Operations

This table provides an overview for each protocol operation in the Crosser Protocol. The PUB/SUB operations are case sensitive. The RPC/RMI operation are NOT case sensitive.

OPERATION	SENDER	DESCRIPTION	PATTERN	PROTOCOL
INFO	Server	Information about the server sent when a TCP/IP connection is established	-	V1,V2
HI	Client	Set information about the connection	-	V1,V2
BYE	Client	Close the connection	-	V1,V2
CALL	Both	Call a controller/method on server/client	RPC/RMI	V1,V2
CALLACK	Both	Confirmation that the CALL operation was received	RPC/RMI	V2
CB	Server	A callback to the client after the client doing a CALL to the server with a callback-id attached	RPC/RMI	V1,V2
SUB	Client	A subscription sent from the client to the server.	PUB/SUB	V1,V2
SUBACK	Server	Confirmation that the SUB was received	PUB/SUB	V2
PUB	Client	A publish message sent to the server from a client	PUB/SUB	V1,V2
PUBACK	Server	Confirmation that the PUB was received	PUB/SUB	V2
MSG	Server	A message sent to subscribing client(s) from the server	PUB/SUB	V1,V2
MSGACK	Client	Confirmation that the MSG was received	PUB/SUB	V2
UNSUB	Client	A client unsubscribe by sending a UNSUB message to the server	PUB/SUB	V1,V2
UNSUBACK	Server	Confirmation that the UNSUB was received	PUB/SUB	V2
PING	Both	Heartbeat, PING	-	V1,V2
PONG	Both	Heartbeat, PONG	-	V1,V2
+OK	Server	Confirmation that the message sent from the client was accepted by the protocol (sent only when Endpoint was started in Interactive mode)	-	V1,V2
-ERR	Server	Protocol Error, will terminate the connection	-	V1,V2

INFO

Syntax

INFO {<key>:<value>,<key>:<value>,...}\r\n

TODO: Add list of parameters sent back from the server.

Description

INFO is sent from the server when a client connects to a Crosser Endpoint. This message will not be sent to half-duplex endpoints such as HTTP.

Example

INFO {"Id":"320a4a6e-c382-4a1d-8336-bafd56314970","Version":"0.0.5.0","Framework":".NETSTANDARD_1_6","Location":"localhost","Port":"6661","PingTimeout":"0","AuthRequired":"False","AuthTimeout":"1000","SecureRequired":"False","Interactive":"False","ProtocolVersions":"V1","CertificateRequired":"False","SslProtocols":"Tls12"}

HI

Syntax

HI {<key>:<value>,<key>:<value>,...}\r\n

You can add custom key/value parameters, but the ones below wil lbe automatically populated by the server-side if provided. All values passed will be found on the server-side under ConnectionContext.Vars dictionary

- interactive: if true the server will confirm every valid operation parsed.
- todo: ...
- todo: ...
- todo: ...

Description

If the client INFO message states that the client have to authenticate the client have to send the HI message before anything else is sent to the server.

Example

TODO: Show example output from telnet

BYE

Syntax

BYE

Description

BYE will gracefully close the connection and cleanup resources.

Example

The following will send the close operation to the server

BYE\r\n

CALL

Syntax V1

CALL <controller> <method> <payload-length> [callback-id]\r\n[payload]\r\n 

Syntax V2

CALL <controller> <method> <payload-length> <call-id> [callback-id]\r\n[payload]\r\n 

Description

CALL will let you call a server-side method on a specific controller.

Example

V1

This example will call the method Bar on the controller Foo with the payload Hello World.

CALL foo bar 11\r\nHello World\r\n

V2

This example will call the method Bar on the controller Foo with the payload Hello World and the call-id c1.

CALL foo bar 11 c1\r\nHello World\r\n

CALLACK

Syntax

CALLACK <call-id>\r\n[payload]\r\n 

Description

CALLACK is sent from the server-side to the client as a response to the client doing a CALL with a call-id included. The CALLACK will be sent back as soon as the server has parsed the message sent form the client.

Example

This is an example where the client sends a CALL to the controller foo and method bar with call-id c1. The payload is hello world

CALL foo bar 11 c1\r\nHello World\r\n

CALLBACK

Syntax

CB <controller> <method> <payload-length> <callback-id>\r\n[payload]\r\n 

Description

CB is sent from the server-side to the client and includes the result of the method called on the server-side. The CALLBACK is only executed if the client has passed in a callback-id in the CALL

Example

This is an example where the client sends a CALL to the controller foo and method bar with callback-id cbid1. The payload is hello world. The method does not return anything and therefor this example has the length 0 in the callback.

CALL foo bar 11 cbid1\r\nHello World\r\n

CB foo bar 0 cbid1\r\n\r\n

SUB

Syntax

SUB <topic> [max-messages]\r\n 

Description

SUB is sent from the client-side to the server. Note that topics are case sensitive. The topic can contain wild-cards, + for level wild-card and # for full wild-card. If the optional [max-messages] is sent the client will be unsibscribed by the server after receiving a number of messages equivalent to [max-messages].

Example

This is an example where the client sends a SUB to the server with topic foo.

SUB foo\r\n

This is an example where the client sends a SUB to the server with topic a level wild-card foo/+/bar.

SUB foo/+/bar\r\n

SUBACK

TBD (V2)

PUB

Syntax

PUB <topic> <payload-length>\r\n[payload]\r\n  

Description

PUB is sent from the client-side to the server. Note that topics are case sensitive.

Example

This is an example where the client sends a PUB to the server with topic foo.

SUB foo\r\n

This is an example where the client sends a PUB to the server with a topic that will match the wild-card subscription shown in the SUB section.

PUB foo/boo/bar 5\r\nHello\r\n

PUBACK

TBD (V2)

MSG

Syntax

MSG <topic> <payload-length>\r\n[payload]\r\n  

Description

MSG is sent from the server-side to the clients. This is the server sending a message to all subscribers found when a client sent a PUB to the server

Example

This is an example where the server sends a MSG to the clients with topic foo and payload Hello.

MSG foo 5\r\nHello\r\n

MSGACK

TBD (V2)

UNSUB

Syntax

UNSUB <topic>\r\n

Description

UNSUB is sent from the client-side to the server to remove a subscription.

Example

This is an example where a client removes a subscription for the topic foo

UNSUB foo\r\n

UNSUBACK

TBD (V2)

PING

TBD

PONG

TBD

OK

Syntax

+OK

If the Endpoint of the connection has interact+ set, the server acknowledges each successfully parsed operation from the client with a +OK message.

ERR

Syntax

-ERR <error message>

The -ERR message is used by the server indicate a protocol, authorization, or other runtime connection error to the client. These errors result in the server closing the connection.

Protocol error messages:

-ERR 'Protocol Violation'
-ERR 'Controller/Method Not Found'
-ERR 'Maximum Payload Length Exceeded'
-ERR 'Authentication Timeout'
-ERR 'Authentication Failed'
-ERR 'Security Violation'
-ERR 'Dead Connection'