From 2a8aa6f390fabd71821b29fe0ac818a3fc62eca1 Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Thu, 23 Oct 2025 15:34:56 +0200 Subject: [PATCH 1/4] Updated readme --- README.md | 40 +++++----------------------------------- msgpackrpc/README.md | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 35 deletions(-) create mode 100644 msgpackrpc/README.md diff --git a/README.md b/README.md index 55ae155..818149d 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,12 @@ -## MessagePack RPC Connection `msgpackrpc` +# `arduino-router` is a MessagePack RPC Router -This package implements a MessagePack RPC point-to-point communication. The actors on each side of the communication can perform RPC calls to the other side so, technically, they can act simultaneously as client or server.\ -By the way, for the sake of simplicity, from now on we will refer to them simply with "client"). +This package implements a MessagePack RPC Router that allows RPC calls between multiple MessagePack RPC clients, connected together in a star topology network, where the Router is the central node. -The protocol supported is defined here https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md. We have 3 types of messages defined as: - -- REQUEST: this message is an array of 4 elements containing in order: - 1. `type`: Fixed as number `0` (to identify the message as a REQUEST). - 2. `msgid`: A message ID, a 32-bit unsigned integer used as a sequence number to match the response (the server's response to the REQUEST will have the same `msgid`). - 3. `method`: A string containing the called method name. - 4. `params`: An array of the function arguments. - -- RESPONSE: this message is an array of 4 elements containing in order: - 1. `type`: Fixed as number `1` (to identify the message as a RESPONSE). - 2. `msgid`: A message ID. - 3. `error`: The error returned from the method, or `null` if the method was successful. - 4. `result`: The result of the method. It should be `null` if an error occurred. - -- NOTIFICATION: this message is an array of 3 elements containing in order: - 1. `type`: Fixed number `2` (to identify this message as a NOTIFICATION). - 2. `methods`: The method name. - 3. `params`: An array of the function parameters. - -### RPC Request cancelation support - -The MessagePack RPC protocol implemented in this package provides also a way for a client to cancel a REQUEST. To do so the client must send a NOTIFICATION to the `$/cancel` method with a single parameter matching the `msgid` of the REQUEST to cancel. - -``` -[2 "$/cancel" [ MSGID ]] -``` - -The server will send an interrupt to the subroutine handling the original REQUEST to inform that the client is no longer interested in the RESPONSE. The server could return immediately an empty RESPONSE with an "interrupted" error, or it may ignore the cancel notification, in this latter case the cancelation will not produce any visible effect. - -## MessagePack RPC Router `msgpackrouter` +Each client can connect to the Router and expose RPC services by registering his methods using a special RPC call implemented in the Router. During normal operation, when the Router receives an RPC request, it redirects the request to the client that has previously registered the corresponding method and it will forwards back the response to the client that originated the RPC request. -This package implements a MessagePack RPC Router. A Router allows RPC calls between multiple MessagePack RPC clients, connected together in a star topology network, where the Router is the central node. +To understand more about MessagePack encoding see: -Each client can connect to the Router and expose RPC services by registering his methods using a special RPC call implemented in the Router. During normal operation, when the Router receives an RPC request, it redirects the request to the client that has previously registered the corresponding method and it will forwards back the response to the client that originated the RPC request. +This package provides also a MessagePack RPC client in `msgpackrpc` package. To get more details about MessagePack RPC and this implementation see [here](msgpackrpc/README.md). ### Methods implemented in the Router diff --git a/msgpackrpc/README.md b/msgpackrpc/README.md new file mode 100644 index 0000000..c506ab5 --- /dev/null +++ b/msgpackrpc/README.md @@ -0,0 +1,32 @@ +# A MessagePack RPC client/server implementation. + +This package implements a MessagePack RPC point-to-point communication. The actors on each side of the communication can perform RPC calls to the other side so, technically, they can act simultaneously as client or server. By the way, for the sake of simplicity, from now on we will refer to them simply with "client". + +The protocol supported is defined here https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md. We have 3 types of messages defined as: + +- REQUEST: this message is an array of 4 elements containing in order: + 1. `type`: Fixed as number `0` (to identify the message as a REQUEST). + 2. `msgid`: A message ID, a 32-bit unsigned integer used as a sequence number to match the response (the server's response to the REQUEST will have the same `msgid`). + 3. `method`: A string containing the called method name. + 4. `params`: An array of the function arguments. + +- RESPONSE: this message is an array of 4 elements containing in order: + 1. `type`: Fixed as number `1` (to identify the message as a RESPONSE). + 2. `msgid`: A message ID. + 3. `error`: The error returned from the method, or `null` if the method was successful. + 4. `result`: The result of the method. It should be `null` if an error occurred. + +- NOTIFICATION: this message is an array of 3 elements containing in order: + 1. `type`: Fixed number `2` (to identify this message as a NOTIFICATION). + 2. `methods`: The method name. + 3. `params`: An array of the function parameters. + +### RPC Request cancelation support + +The MessagePack RPC protocol implemented in this package provides also a way for a client to cancel a REQUEST. To do so the client must send a NOTIFICATION to the `$/cancel` method with a single parameter matching the `msgid` of the REQUEST to cancel. + +``` +[2 "$/cancel" [ MSGID ]] +``` + +The server will send an interrupt to the subroutine handling the original REQUEST to inform that the client is no longer interested in the RESPONSE. The server could return immediately an empty RESPONSE with an "interrupted" error, or it may ignore the cancel notification, in this latter case the cancelation will not produce any visible effect. From ac471ac00f159027adad3c07e77246484512f641 Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Fri, 24 Oct 2025 14:29:01 +0200 Subject: [PATCH 2/4] Apply suggestion from @per1234 Co-authored-by: Per Tillisch --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 818149d..f3e10d0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # `arduino-router` is a MessagePack RPC Router -This package implements a MessagePack RPC Router that allows RPC calls between multiple MessagePack RPC clients, connected together in a star topology network, where the Router is the central node. +This module implements a MessagePack RPC Router that allows RPC calls between multiple MessagePack RPC clients, connected together in a star topology network, where the Router is the central node. Each client can connect to the Router and expose RPC services by registering his methods using a special RPC call implemented in the Router. During normal operation, when the Router receives an RPC request, it redirects the request to the client that has previously registered the corresponding method and it will forwards back the response to the client that originated the RPC request. From 8739d222d0a2118d148d7265fc1beb047d3f2c65 Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Fri, 24 Oct 2025 14:29:09 +0200 Subject: [PATCH 3/4] Apply suggestion from @per1234 Co-authored-by: Per Tillisch --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f3e10d0..d99342d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This module implements a MessagePack RPC Router that allows RPC calls between multiple MessagePack RPC clients, connected together in a star topology network, where the Router is the central node. -Each client can connect to the Router and expose RPC services by registering his methods using a special RPC call implemented in the Router. During normal operation, when the Router receives an RPC request, it redirects the request to the client that has previously registered the corresponding method and it will forwards back the response to the client that originated the RPC request. +Each client can connect to the Router and expose RPC services by registering its methods using a special RPC call implemented in the Router. During normal operation, when the Router receives an RPC request, it redirects the request to the client that has previously registered the corresponding method and it will forward back the response to the client that originated the RPC request. To understand more about MessagePack encoding see: From 189ed351406a8c9f2b9da72ccf394b2038e6c80c Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Fri, 24 Oct 2025 14:29:15 +0200 Subject: [PATCH 4/4] Apply suggestion from @per1234 Co-authored-by: Per Tillisch --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d99342d..c9191e1 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Each client can connect to the Router and expose RPC services by registering its To understand more about MessagePack encoding see: -This package provides also a MessagePack RPC client in `msgpackrpc` package. To get more details about MessagePack RPC and this implementation see [here](msgpackrpc/README.md). +This module provides also a MessagePack RPC client in the `msgpackrpc` package. To get more details about MessagePack RPC and this implementation see [here](msgpackrpc/README.md). ### Methods implemented in the Router