Hub server

A hub server is the control plane of a NanoPing setup: nodes authenticate with it, and every node on the same hub can find and manage the others. Use this service to list the nodes on the hub, follow them as they come and go, remove nodes, and approve or reject nodes that ask to join. The node hosting the API must host the hub server or be authenticated with one, otherwise calls fail with FailedPrecondition.

Get nodes

Get the nodes authenticated with the hub server, optionally filtered.

REST

GET/v1/nodes

Query parameters

• metadata_filtersmap<string, NodeMetadataItem>

  Metadata filters keyed by metadata key. A node is included only if it has every key with an equal value of the same type. Leave empty to not filter by metadata.

• service_filtersNodeService[]

  Service filters. A node is included only if it offers every listed service. Leave empty to not filter by service.

Example

TypeScript

import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

const response = await client.hubServer.getNodes({
  metadataFilters: {
    key: {
      bytesValue: ""
    }
  },
  serviceFilters: [
    "HUB_SERVER"
  ]
});

Python

from nanoping_api import NanopingClient, NodeMetadataItem, NodeService

client = NanopingClient("http://127.0.0.1:10565")

response = client.hub_server.get_nodes(
    metadata_filters={"key": NodeMetadataItem(string_value="example")},
    service_filters=[NodeService.HUB_SERVER],
)

curl

curl 'http://127.0.0.1:10565/v1/nodes'

POST/v1/nodes/search

Request body

• metadataFiltersmap<string, NodeMetadataItem>

  Metadata filters keyed by metadata key. A node is included only if it has every key with an equal value of the same type. Leave empty to not filter by metadata.

• serviceFiltersNodeService[]

  Service filters. A node is included only if it offers every listed service. Leave empty to not filter by service.

Example

TypeScript

import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

const response = await client.hubServer.getNodes({
  metadataFilters: {
    key: {
      bytesValue: ""
    }
  },
  serviceFilters: [
    "HUB_SERVER"
  ]
});

Python

from nanoping_api import NanopingClient, NodeMetadataItem, NodeService

client = NanopingClient("http://127.0.0.1:10565")

response = client.hub_server.get_nodes(
    metadata_filters={"key": NodeMetadataItem(string_value="example")},
    service_filters=[NodeService.HUB_SERVER],
)

curl

curl -X POST 'http://127.0.0.1:10565/v1/nodes/search' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadataFilters": {
      "key": {
        "bytesValue": ""
      }
    },
    "serviceFilters": [
      "HUB_SERVER"
    ]
  }'

Response

• nodesNode[]

  The nodes matching the filters.

gRPC

rpc getNodes(GetNodesRequest) returns (GetNodesResponse)

Method /nanopinggrpc.hub.HubServerService/getNodes

Request

• metadata_filtersmap<string, NodeMetadataItem>

  Metadata filters keyed by metadata key. A node is included only if it has every key with an equal value of the same type. Leave empty to not filter by metadata.

• service_filtersNodeService[]

  Service filters. A node is included only if it offers every listed service. Leave empty to not filter by service.

Response

• nodesNode[]

  The nodes matching the filters.

Example

Go

import (
    client "github.com/nanoping-labs/nanoping-api-go/v11"
    "github.com/nanoping-labs/nanoping-api-go/v11/hub_node"
    "github.com/nanoping-labs/nanoping-api-go/v11/hub_server"
)

c, err := client.Connect("127.0.0.1:10432")
defer c.Close()

response, err := c.HubServer.GetNodes(ctx, &hub_server.GetNodesRequest{
    MetadataFilters: map[string]*hub_node.NodeMetadataItem{
        "key": &hub_node.NodeMetadataItem{
            Value: &hub_node.NodeMetadataItem_StringValue{StringValue: "example"},
        },
    },
    ServiceFilters: []hub_node.NodeService{
        hub_node.NodeService_HUB_SERVER,
    },
})

Go (generated gRPC)

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "github.com/nanoping-labs/nanoping-api-go/v11/hub_node"
    "github.com/nanoping-labs/nanoping-api-go/v11/hub_server"
)

conn, err := grpc.NewClient("127.0.0.1:10432", grpc.WithTransportCredentials(insecure.NewCredentials()))
defer conn.Close()
stub := hub_server.NewHubServerServiceClient(conn)

response, err := stub.GetNodes(ctx, &hub_server.GetNodesRequest{
    MetadataFilters: map[string]*hub_node.NodeMetadataItem{
        "key": &hub_node.NodeMetadataItem{
            Value: &hub_node.NodeMetadataItem_StringValue{StringValue: "example"},
        },
    },
    ServiceFilters: []hub_node.NodeService{
        hub_node.NodeService_HUB_SERVER,
    },
})

Remove node

Remove a node from the hub server. This disconnects the node from the hub server and removes it from its networks.

REST

DELETE/v1/nodes/{node_id}

Path parameters

• node_idstring

  Id of the node to remove.

Example

TypeScript

import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

await client.hubServer.removeNode({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f"
});

Python

from nanoping_api import NanopingClient

client = NanopingClient("http://127.0.0.1:10565")

client.hub_server.remove_node(node_id="3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f")

curl

curl -X DELETE 'http://127.0.0.1:10565/v1/nodes/<node_id>'

Response

No fields.

gRPC

rpc removeNode(RemoveNodeRequest) returns (RemoveNodeResponse)

Method /nanopinggrpc.hub.HubServerService/removeNode

Request

• node_idstring

  Id of the node to remove.

Response

No fields.

Example

Go

import (
    client "github.com/nanoping-labs/nanoping-api-go/v11"
    "github.com/nanoping-labs/nanoping-api-go/v11/hub_server"
)

c, err := client.Connect("127.0.0.1:10432")
defer c.Close()

_, err = c.HubServer.RemoveNode(ctx, &hub_server.RemoveNodeRequest{
    NodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
})

Go (generated gRPC)

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "github.com/nanoping-labs/nanoping-api-go/v11/hub_server"
)

conn, err := grpc.NewClient("127.0.0.1:10432", grpc.WithTransportCredentials(insecure.NewCredentials()))
defer conn.Close()
stub := hub_server.NewHubServerServiceClient(conn)

_, err = stub.RemoveNode(ctx, &hub_server.RemoveNodeRequest{
    NodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
})

Stream nodes

Stream the nodes authenticated with the hub server. The matching nodes are sent first, followed by an update every time a node is authenticated, deauthenticated, connects, disconnects or changes its details. Updates are not filtered. The stream stays open until the caller closes it.

REST

GET/v1/streams/nodes

Server-sent events. A : ready comment is sent when the stream is ready, then each message is a data: line holding the response below. A failure after that is an error event.

Query parameters

• metadata_filtersmap<string, NodeMetadataItem>

  Metadata filters keyed by metadata key. A node is included only if it has every key with an equal value of the same type. Leave empty to not filter by metadata.

• service_filtersNodeService[]

  Service filters. A node is included only if it offers every listed service. Leave empty to not filter by service.

Example

TypeScript

import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

for await (const response of client.hubServer.streamNodes({
  metadataFilters: {
    key: {
      bytesValue: ""
    }
  },
  serviceFilters: [
    "HUB_SERVER"
  ]
})) {
}

Python

from nanoping_api import NanopingClient, NodeMetadataItem, NodeService

client = NanopingClient("http://127.0.0.1:10565")

for response in client.hub_server.stream_nodes(
    metadata_filters={"key": NodeMetadataItem(string_value="example")},
    service_filters=[NodeService.HUB_SERVER],
):
    print(response)

curl

curl -N 'http://127.0.0.1:10565/v1/streams/nodes'

POST/v1/streams/nodes

Server-sent events. A : ready comment is sent when the stream is ready, then each message is a data: line holding the response below. A failure after that is an error event.

Request body

• metadataFiltersmap<string, NodeMetadataItem>

  Metadata filters keyed by metadata key. A node is included only if it has every key with an equal value of the same type. Leave empty to not filter by metadata.

• serviceFiltersNodeService[]

  Service filters. A node is included only if it offers every listed service. Leave empty to not filter by service.

Example

TypeScript

import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

for await (const response of client.hubServer.streamNodes({
  metadataFilters: {
    key: {
      bytesValue: ""
    }
  },
  serviceFilters: [
    "HUB_SERVER"
  ]
})) {
}

Python

from nanoping_api import NanopingClient, NodeMetadataItem, NodeService

client = NanopingClient("http://127.0.0.1:10565")

for response in client.hub_server.stream_nodes(
    metadata_filters={"key": NodeMetadataItem(string_value="example")},
    service_filters=[NodeService.HUB_SERVER],
):
    print(response)

curl

curl -N -X POST 'http://127.0.0.1:10565/v1/streams/nodes' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadataFilters": {
      "key": {
        "bytesValue": ""
      }
    },
    "serviceFilters": [
      "HUB_SERVER"
    ]
  }'

Response messages

• initialResponseStreamNodesInitialResponseone of response

  Sent once as the first message, with the nodes matching the filters when the stream opened.

• updateResponseStreamNodesUpdateResponseone of response

  Sent for every later change to a node.

gRPC

rpc streamNodes(GetNodesRequest) returns (stream StreamNodesResponse)

Method /nanopinggrpc.hub.HubServerService/streamNodes

Request

• metadata_filtersmap<string, NodeMetadataItem>

  Metadata filters keyed by metadata key. A node is included only if it has every key with an equal value of the same type. Leave empty to not filter by metadata.

• service_filtersNodeService[]

  Service filters. A node is included only if it offers every listed service. Leave empty to not filter by service.

Response messages

• initialResponseStreamNodesInitialResponseone of response

  Sent once as the first message, with the nodes matching the filters when the stream opened.

• updateResponseStreamNodesUpdateResponseone of response

  Sent for every later change to a node.

Example

Go

import (
    client "github.com/nanoping-labs/nanoping-api-go/v11"
    "github.com/nanoping-labs/nanoping-api-go/v11/hub_node"
    "github.com/nanoping-labs/nanoping-api-go/v11/hub_server"
)

c, err := client.Connect("127.0.0.1:10432")
defer c.Close()

stream, err := c.HubServer.StreamNodes(ctx, &hub_server.GetNodesRequest{
    MetadataFilters: map[string]*hub_node.NodeMetadataItem{
        "key": &hub_node.NodeMetadataItem{
            Value: &hub_node.NodeMetadataItem_StringValue{StringValue: "example"},
        },
    },
    ServiceFilters: []hub_node.NodeService{
        hub_node.NodeService_HUB_SERVER,
    },
})
for response, err := range client.Receive(stream) {
    if err != nil {
        return err
    }
}

Go (generated gRPC)

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "github.com/nanoping-labs/nanoping-api-go/v11/hub_node"
    "github.com/nanoping-labs/nanoping-api-go/v11/hub_server"
)

conn, err := grpc.NewClient("127.0.0.1:10432", grpc.WithTransportCredentials(insecure.NewCredentials()))
defer conn.Close()
stub := hub_server.NewHubServerServiceClient(conn)

stream, err := stub.StreamNodes(ctx, &hub_server.GetNodesRequest{
    MetadataFilters: map[string]*hub_node.NodeMetadataItem{
        "key": &hub_node.NodeMetadataItem{
            Value: &hub_node.NodeMetadataItem_StringValue{StringValue: "example"},
        },
    },
    ServiceFilters: []hub_node.NodeService{
        hub_node.NodeService_HUB_SERVER,
    },
})
for {
    response, err := stream.Recv()
    if err != nil {
        return err
    }
}

Authentication by requests

Receive the authentication requests sent to the hub server on the node hosting the API, and accept or reject each one. Nothing is sent when the stream opens. A request is sent each time a node asks to authenticate, and the caller answers it by sending an answer for that request.

Use this on the node hosting the hub server to decide which nodes may join. Every node that calls authenticate by request arrives as a request. Answer it before the request times out; the node's call returns as soon as the answer is in.

REST

WS/v1/streams/hub-server/authentication-requests

WebSocket. Send each request below as a JSON text message. Each message received holds a result with the response below, or an error.

Messages sent

• requestIduint64

  Id of the request being answered, as received in the request.

• acceptbool

  True to accept the request, false to reject it.

Example

TypeScript

import { NanopingClient, answerJoinRequests } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

// Let nodes named "edge-node-1" join, and reject the rest. Runs until the
// signal aborts.
const stop = new AbortController();
await answerJoinRequests(client, (request) => request.node?.name === "edge-node-1", { signal: stop.signal });

Python

from nanoping_api import NanopingClient

client = NanopingClient("http://127.0.0.1:10565")

# Let nodes named "edge-node-1" join, and reject the rest. Runs until the
# stream ends.
client.answer_join_requests(lambda request: request.node.name == "edge-node-1")

Message

ws://127.0.0.1:10565/v1/streams/hub-server/authentication-requests

{
  "requestId": "0",
  "accept": false
}

Response messages

• nodeNode

  Information about the node asking to authenticate.

• requestIduint64

  Id of the request, used when answering it.

gRPC

rpc authenticationByRequests(stream AuthenticationByRequestAnswer) returns (stream AuthenticationByRequestRequest)

Method /nanopinggrpc.hub.HubServerService/authenticationByRequests

Request messages

• request_iduint64

  Id of the request being answered, as received in the request.

• acceptbool

  True to accept the request, false to reject it.

Response messages

• nodeNode

  Information about the node asking to authenticate.

• request_iduint64

  Id of the request, used when answering it.

Example

Go

import (
    client "github.com/nanoping-labs/nanoping-api-go/v11"
    "github.com/nanoping-labs/nanoping-api-go/v11/hub_server"
)

c, err := client.Connect("127.0.0.1:10432")
defer c.Close()

// Let nodes named "edge-node-1" join, and reject the rest. Runs until ctx is
// canceled.
err = c.AnswerJoinRequests(ctx, func(request *hub_server.AuthenticationByRequestRequest) bool {
    return request.Node.Name == "edge-node-1"
})

Go (generated gRPC)

import (
    "github.com/nanoping-labs/nanoping-api-go/v11/hub_server"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

conn, err := grpc.NewClient("127.0.0.1:10432", grpc.WithTransportCredentials(insecure.NewCredentials()))
defer conn.Close()
stub := hub_server.NewHubServerServiceClient(conn)

stream, err := stub.AuthenticationByRequests(ctx)
if err != nil {
    return err
}

for {
    request, err := stream.Recv()
    if err != nil {
        return err
    }

    // Let nodes named "edge-node-1" join, and reject the rest.
    err = stream.Send(&hub_server.AuthenticationByRequestAnswer{
        RequestId: request.RequestId,
        Accept:    request.Node.Name == "edge-node-1",
    })
    if err != nil {
        return err
    }
}