Skip to content

Commit 4d8c2e9

Browse files
Eslam-NawaraEslam-Nawara
authored
Merge pull request #7 from threefoldtech/development-add-node-registrar-client
add node registrar client
2 parents 90ca89a + 55d9ee5 commit 4d8c2e9

19 files changed

+2564
-4
lines changed

‎go.work.sum

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
github.com/PuerkitoBio/purell v1.1.1/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbtSwDGJws/X0=
22
github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578/go.mod h1:uGdkoq3SwY9Y+13GIhn11/XLaGBb4BfwItxLd5jeuXE=
3+
github.com/btcsuite/btcd v0.22.0-beta/go.mod h1:9n5ntfhhHQBIhUvlhDvD3Qg6fRUj4jkN0VB8L8svzOA=
34
github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311/go.mod h1:b583jCggY9gE99b6G5LEC39OIiVsWj+R97kbl5odCEk=
45
github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
56
github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
67
github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
78
github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc=
9+
github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
810
github.com/urfave/cli/v2 v2.3.0/go.mod h1:LJmUH05zAU44vOAcrfzZQKsZbVcdbOG8rtL3/XcUArI=
911
golang.org/x/telemetry v0.0.0-20240521205824-bda55230c457/go.mod h1:pRgIJT+bRLFKnoM1ldnzKoxTIn14Yxz928LQRYYgIN0=
1012
golang.org/x/term v0.21.0/go.mod h1:ooXLefLobQVslOqselCNF4SxFAaoS6KujMbsGzSDmX0=

‎node-registrar/client/README.md

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
# ThreeFold Grid Node Registrar Client
2+
3+
A Go client for interacting with the ThreeFold Grid Node Registrar service. Facilitates node registration and management on the ThreeFold Grid.
4+
5+
## Overview
6+
7+
The Node Registrar Client enables communication with the ThreeFold Grid's node registration service. It provides methods to:
8+
9+
* Register nodes
10+
* Manage node metadata
11+
* Retrieve node information
12+
* Delete node registrations
13+
14+
## Features
15+
16+
### Version
17+
18+
* **Get Zos Version**: Loads zos version for the current network
19+
* **Set Zos Version**: Set zos version to specific version (can only be done by the network admin)
20+
21+
### Accounts
22+
23+
* **Create Account**: Create new account on the registrar with uniqe key.
24+
* **Update Account**: Update the account configuration (relays & rmbEncKey).
25+
* **Ensure Account**: Ensures that an account is created with specific seed/mnemonic.
26+
* **Get Account**: Get an account using either its twin\_id or its public\_key.
27+
28+
### Farms
29+
30+
* **Create Farm**: Create new farm on the registrar with uniqe name.
31+
* **update Farm**: Update farm configuration (farm\_id, dedicated).
32+
* **Get Farm**: Get a farm using its farm\_id.
33+
34+
### Node
35+
36+
* **Register Node**: Register physical/virtual nodes with on TFGrid.
37+
* **Update Node**: Update node configuration (farm\_id, interfaces, resources, location, secure\_boot, virtualized).
38+
* **Get Node**: Fetch registered node details using (node\_id, twin\_id, farm\_id).
39+
* **Update Node Uptime**: Update node Uptime.
40+
41+
### API Methods
42+
43+
#### Version Operations
44+
45+
| Method | Description | Parameters | Returns |
46+
|-----------------|----------------------------------|------------------------------------|---------------------|
47+
| GetZosVersion | Get current zos version | None | (ZosVersion, error) |
48+
| SetZosVersion | Update zos version (admin-only) | version string, safeToUpgrade bool | error |
49+
50+
#### Account Management
51+
52+
| Method | Description | Parameters | Returns |
53+
|----------------|---------------------------|-----------------------------------|------------------|
54+
| CreateAccount | Create new account | relays []string, rmbEncKey string | (Account, error) |
55+
| EnsureAccount | Create account if missing | relays []string, rmbEncKey string | (Account, error) |
56+
| GetAccount | Get account by twin ID | twinID uint64 | (Account, error) |
57+
| GetAccountByPK | Get account by public key | publicKey string | (Account, error) |
58+
| UpdateAccount | Modify account config | ...UpdateOption | error |
59+
60+
#### Farm Operations
61+
62+
| Method | Description | Parameters | Returns |
63+
|-------------|------------------------|--------------------------------------------|-----------------|
64+
| CreateFarm | Register new farm | name string, twinID uint64, dedicated bool | (uint64, error) |
65+
| UpdateFarm | Modify farm properties | farmID uint64, ...UpdateOption | error |
66+
| GetFarm | Get farm by ID | farmID uint64 | (Farm, error) |
67+
| ListFarms | List farms | ...ListOption | ([]Farm, error) |
68+
69+
#### Node Operations
70+
71+
| Method | Description | Parameters | Returns |
72+
|-----------------|-----------------------|------------------------------------------------|-----------------|
73+
| RegisterNode | Register new node | farmID uint64, twinID uint64, interfaces []Interface, location Location, resources Resources, serial string, secureBoot bool, virtualized bool | (uint64, error) |
74+
| UpdateNode | Modify node config | ...UpdateOption | error |
75+
| GetNode | Get node by node ID | nodeID uint64 | (Node, error) |
76+
| GetNodeByTwinID | Get node by twin ID | twinID uint64 | (Node, error) |
77+
| ListNodes | List nodes | ...ListOption | ([]Node, error) |
78+
| ReportUptime | Submit uptime metrics | report UptimeReport | error |
79+
80+
## Installation
81+
82+
```bash
83+
go get github.com/threefoldtech/tfgrid4-sdk-go/node-registrar/client
84+
```
85+
86+
## Usage
87+
88+
### Initialize Client
89+
90+
```go
91+
import (
92+
"github.com/threefoldtech/tfgrid4-sdk-go/node-registrar/client"
93+
)
94+
95+
func main() {
96+
registrarURL := "https://registrar.dev4.grid.tf/v1"
97+
98+
// Generate 128-bit entropy (12-word mnemonic)
99+
entropy, err := bip39.NewEntropy(128)
100+
if err != nil {
101+
panic(err)
102+
}
103+
104+
// Generate mnemonic from entropy
105+
mnemonic, err = bip39.NewMnemonic(entropy)
106+
if err != nil {
107+
panic(err)
108+
}
109+
fmt.Println("New Mnemonic:", mnemonic)
110+
111+
cli, err := client.NewRegistrarClient(registrarURL, mnemonic)
112+
if err != nil {
113+
panic(err)
114+
}
115+
}
116+
```
117+
118+
### Get Zos Version
119+
120+
```go
121+
version, err := c.GetZosVersion()
122+
if err != nil {
123+
log.Fatal().Err(err).Msg("failed to set registrar version")
124+
}
125+
126+
log.Info().Msgf("%s version is: %+v", network, version)
127+
```
128+
129+
### Set Zos Version (ONLY for network admin)
130+
131+
```go
132+
err := c.SetZosVersion("v0.1.8", true)
133+
if err != nil {
134+
log.Fatal().Err(err).Msg("failed to set registrar version")
135+
}
136+
137+
log.Info().Msg("version is updated successfully")
138+
```
139+
140+
### Create Account
141+
142+
```go
143+
account, err := c.CreateAccount(relays, rmbEncKey)
144+
if err != nil {
145+
log.Fatal().Err(err).Msg("failed to create new account on registrar")
146+
}
147+
148+
log.Info().Uint64("twinID", account.TwinID).Msg("account created successfully")
149+
150+
```
151+
152+
### Get Account
153+
154+
#### Get Account By Public Key
155+
156+
```go
157+
account, err := c.GetAccountByPK(pk)
158+
if err != nil {
159+
log.Fatal().Err(err).Msg("failed to get account from registrar")
160+
}
161+
log.Info().Any("account", account).Send()
162+
```
163+
164+
#### Get Account By Twin ID
165+
166+
```go
167+
account, err := c.GetAccount(id)
168+
if err != nil {
169+
log.Fatal().Err(err).Msg("failed to get account from registrar")
170+
}
171+
log.Info().Any("account", account).Send()
172+
173+
```
174+
175+
### Update Account
176+
177+
```go
178+
err := c.UpdateAccount(client.UpdateAccountWithRelays(relays), client.UpdateAccountWithRMBEncKey(rmbEncKey))
179+
if err != nil {
180+
log.Fatal().Err(err).Msg("failed to get account from registrar")
181+
}
182+
log.Info().Msg("account updated successfully")
183+
```
184+
185+
### Ensure Account
186+
187+
```go
188+
account, err := c.EnsureAccount(relays, rmbEncKey)
189+
if err != nil {
190+
log.Fatal().Err(err).Msg("failed to ensure account account from registrar")
191+
}
192+
log.Info().Any("account", account).Send()
193+
```
194+
195+
### Create Farm
196+
197+
```go
198+
id, err := c.CreateFarm(farmName, twinID, false)
199+
if err != nil {
200+
log.Fatal().Err(err).Msg("failed to create new farm on registrar")
201+
}
202+
203+
log.Info().Uint64("farmID", id).Msg("farm created successfully")
204+
```
205+
206+
### Get Farm
207+
208+
```go
209+
farm, err := c.GetFarm(id)
210+
if err != nil {
211+
log.Fatal().Err(err).Msg("failed to get farm from registrar")
212+
}
213+
log.Info().Any("farm", farm).Send()
214+
```
215+
216+
### List Farms
217+
218+
```go
219+
farms, err := c.ListFarms(ListFarmWithName(name))
220+
if err != nil {
221+
log.Fatal().Err(err).Msg("failed to list farms from registrar")
222+
}
223+
log.Info().Any("farm", farms[0]).Send()
224+
```
225+
226+
### Update Farm
227+
228+
```go
229+
err := c.UpdateFarm(farmID, client.UpdateFarmWithName(name))
230+
if err != nil {
231+
log.Fatal().Err(err).Msg("failed to get farm from registrar")
232+
}
233+
log.Info().Msg("farm updated successfully")
234+
```
235+
236+
### Register a Node
237+
238+
```go
239+
id, err := c.RegisterNode(farmID, twinID, interfaces, location, resources, serialNumber, secureBoot, virtualized)
240+
if err != nil {
241+
log.Fatal().Err(err).Msg("failed to register a new node on registrar")
242+
}
243+
log.Info().Uint64("nodeID", id).Msg("node registered successfully")
244+
```
245+
246+
### Get Node
247+
248+
#### Get Node With Node ID
249+
250+
```go
251+
node, err := c.GetNode(id)
252+
if err != nil {
253+
log.Fatal().Err(err).Msg("failed to get node from registrar")
254+
}
255+
log.Info().Any("node", node).Send()
256+
```
257+
258+
#### Get Node With Twin ID
259+
260+
```go
261+
node, err := c.GetNodeByTwinID(id)
262+
if err != nil {
263+
log.Fatal().Err(err).Msg("failed to get node from registrar")
264+
}
265+
log.Info().Any("node", node).Send()
266+
```
267+
268+
### List Nodes
269+
270+
```go
271+
nodes, err := c.ListNodes(client.ListNodesWithFarmID(id))
272+
if err != nil {
273+
log.Fatal().Err(err).Msg("failed to list nodes from registrar")
274+
}
275+
log.Info().Any("node", node[0]).Send()
276+
```
277+
278+
### Update Node
279+
280+
```go
281+
err := c.UpdateNode(client.UpdateNodesWithLocation(location))
282+
if err != nil {
283+
log.Fatal().Err(err).Msg("failed to update node location on the registrar")
284+
}
285+
log.Info().Msg("node updated successfully")
286+
```
287+
288+
### Update Node Uptime
289+
290+
```go
291+
err := c.ReportUptime(report)
292+
if err != nil {
293+
log.Fatal().Err(err).Msg("failed to update node uptime in the registrar")
294+
}
295+
log.Info().Msg("node uptime is updated successfully")
296+
```

0 commit comments

Comments
 (0)