#chord #dht #web3 #send-message #p2p #request-headers #request-body

no-std rings-rpc

Rings is a structured peer-to-peer network implementation using WebRTC, Chord algorithm, and full WebAssembly (WASM) support

5 releases (3 breaking)

0.6.0 Mar 28, 2024
0.5.1 Jan 2, 2024
0.3.0 Sep 21, 2023
0.2.7 Aug 17, 2023
0.2.6 Jun 29, 2023

#1818 in Network programming

Download history 18/week @ 2024-01-01 4/week @ 2024-02-19 8/week @ 2024-02-26 9/week @ 2024-03-04 136/week @ 2024-03-25 25/week @ 2024-04-01

162 downloads per month
Used in rings-node

GPL-3.0 license

160KB
3K SLoC

Rings Network

Rings RPC

rings-node

JSON-RPC API endpoints

Make requests

curl

Url curl to make the requests.

curl -X POST \
-H "Content-Type: application/json" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "nodeInfo", "params": []}' \
"http://127.0.0.1:50000"

javascript

TODO

JSON-RPC methods

This section lists the rings JSON-RPC API endpoints. You can call these APIs using a variety of tools.

Error codes

The follow list contains all possible error codes and associated messages:

code meaning category
-32000 Internal service error standard
-32001 Connect remote server with error occurred standard
-32002 Push or find pending transport failed standard
-32003 Transport not found standard
-32004 Create new transport failed standard
-32005 Close transport failed standard
-32006 Encode data error standard
-32007 Decode data error standard
-32008 Register ice failed standard
-32009 Create new offer failed standard
-32010 Create new answder failed standard
-32011 Invalid transport id standard
-32012 Invalid did standard
-32013 Invalid method standard
-32014 Send message with error occurred standard
-32015 Permission requires to do something standard
-32016 VNode action error standard
-32017 Register service with error occurred standard
-32018 Invalid data standard
-32019 Invalid message standard
-32020 Invalid service standard
-32021 Invalid address standard
-32022 Invalid auth data standard

Example error response:

{
    "id": 1,
    "jsonrpc": "2.0",
    "error": {
        "code": -32000,
        "message": "internal service error",
    }
}

nodeInfo

return rings node basic information.

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json

EXAMPLE

curl -X POST \
-H "Content-Type: application/json" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "nodeInfo", "params": []}' \
"http://127.0.0.1:50000"

RESPONSE

  • version - current running node version

BODY

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "version": "0.0.1"
    }
}

connectPeerViaHttp

Connect a peer with peer's jsonrpc endpoint

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json

EXAMPLE

## Replace REMOTE-JSONRPC-ENDPOINT with the url what you want to connect
curl -X POST \
-H "Content-Type: application/json" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "connectPeerViaHttp", "params": ["REMOTE-JSONRPC-ENDPOINT"]}' \
"http://127.0.0.1:50000"

RESPONSE

  • transport_did - the id of transport

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        "abcd-1234"
    ]
}

connectWithDid

Connect a peer with peer's did

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace REMOTE-PEER-DID with the did what you want to connect
## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "connectPeerWithDid", "params": ["REMOTE-PEER-DID"]}' \
"http://127.0.0.1:50000"

RESPONSE

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": null
}

connectWithSeed

Connect a peer with peer's seed

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace REMOTE-PEER-SEED with the did what you want to connect
## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "connectPeerWithSeed", "params": ["REMOTE-PEER-SEED"]}' \
"http://127.0.0.1:50000"

RESPONSE

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": null
}

createOffer

Create an offer for connection

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace REMOTE-PEER-SEED with the did what you want to connect
## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "createOffer", "params": [REMOTE-PEER-DID]}' \
"http://127.0.0.1:50000"

RESPONSE

  • transport_id: id of the transport
  • ice: ice message

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "transport_id": "1234",
        "ice": "abcd1234",
    }
}

answerOffer

Answer an offer for connection

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace REMOTE-PEER-SEED with the did what you want to connect
## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "createOffer", "params": ["REMOTE-PEER-SEED"]}' \
"http://127.0.0.1:50000"

RESPONSE

  • transport_id: id of the transport
  • ice: ice message

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "transport_id": "1234",
        "ice": "abcd1234",
    }
}

listPeers

List all node connected peers

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "listPeers", "params": []}' \
"http://127.0.0.1:50000"

RESPONSE

  • peers - list of connected peers
    • transport_id - id of the transport
    • did - did of remote peer
    • state - transport state

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        {
            "did": "abcd1234"
            "transport_id": "1234",
            "state": "connected",
        }
    ]
}

closeConnection

Close a connected connection with the did of peer

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace REMOTE-PEER-DID with ice what you got from others
## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "closeConnection", "params": ["REMOTE-PEER-DID"]}' \
"http://127.0.0.1:50000"

RESPONSE

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {}
}

listPendings

List all pending connections

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "closeConnection", "params": []}' \
"http://127.0.0.1:50000"

RESPONSE

  • transport_infos - list of all pending transports
    • transport_id - id of the transport
    • state - state of the transport

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        {
            "transport_id": "abcd1234",
            "state": "new"
        }
    ]
}

closePendingTransport

Close a specific pending transport

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
## Replace TRANSPORT-ID with the transport_id which in listPendings
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "closePendingTransport", "params": ["TRANSPORT-ID"]}' \
"http://127.0.0.1:50000"

RESPONSE

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {}
}

sendHttpRequestMessage

Send a http request message to remote peer, the remote peer should provide the service you want to use

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
## Replace REMOTE-PEER-DID with did of remote peer
## Replace HTTP-REQUEST-ARG with your request arguments
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "sendSimpleTextMessage", "params": ["REMOTE-PEER-DID", {HTTP-REQUEST-ARG}]}' \
"http://127.0.0.1:50000"
  • HTTP-REQUEST-ARG
    • name - service name
    • method - http method
    • path - resource path
    • timeout - timeout of remote request, optional
    • headers - remote request with headers, optional
    • body - request body what you want to send to remote service, optional

RESPONSE

  • tx_id - transaction id

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
         "tx_id": "abcd1234"
    }
}

sendSimpleTextMessage

Send simple text message to a peer

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
## Replace REMOTE-PEER-DID with did of remote peer
## Replace TEXT with what you want to send
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "sendSimpleTextMessage", "params": ["REMOTE-PEER-DID", "TEXT"]}' \
"http://127.0.0.1:50000"

RESPONSE

  • tx_id - transaction id

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
         "tx_id": "abcd1234"
    }
}

sendCustomMessage

Send custom message to a peer

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
## Replace REMOTE-PEER-DID with did of remote peer
## Replace MESSAGE-TYPE with type of your message
## Replace DATA with message payload after base64
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "sendCustomMessage", "params": ["REMOTE-PEER-DID", "MESSAGE-TYPE", "DATA"]}' \
"http://127.0.0.1:50000"

RESPONSE

  • tx_id - transaction id

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
         "tx_id": "abcd1234"
    }
}

publishMessageToTopic

Publish data message to specific topic

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
## Replace TOPIC with message topic
## Replace DATA with message payload after base64
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "publishMessageToTOpic", "params": ["TOPIC", "DATA"]}' \
"http://127.0.0.1:50000"

RESPONSE

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {}
}

fetchMessageToTopic

Fetch message from specific topic

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
## Replace TOPIC with message topic
## Replace DATA with message payload after base64
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "fetchMessageToTopic", "params": ["TOPIC", "INDEX"]}' \
"http://127.0.0.1:50000"

RESPONSE

  • MESSAGES - message vec of specific topic

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        "topic_message",
    ]
}

registerService

Register custom service to rings network

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
## Replace NAME with the service name what you want to publish to rings network
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "registerService", "params": ["NAME"]}' \
"http://127.0.0.1:50000"

RESPONSE

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {}
}

lookupService

Lookup custom service from rings network, you can find all dids of node which provide service you want.

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
## Replace NAME with the service name what you want to lookup in rings network
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "lookupService", "params": ["NAME"]}' \
"http://127.0.0.1:50000"

RESPONSE

  • DIDS - did list of nodes which provide service with specific name

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        "did1",
        "did2",
    ]
}

pollMessage

Use this method, you can pull messages received by this node, to provide your custom service, But we suggest use websocket endpoint realtime get messages.

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
## Replace WAIT with a bool value, true will block the request, until new message receive.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "pollMessage", "params": ["WAIT"]}' \
"http://127.0.0.1:50000"

RESPONSE

  • message - custom message received

EXAMPLE

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "message": {
          message_type: 1,
          data: "base64 text"
      }
    }
}

Dependencies

~4–20MB
~267K SLoC