Skip to content

Commit bbba65d

Browse files
Omarabdul3zizOmarabdul3ziz
committed
add docs for api pkg and nodeclient
1 parent 6137c97 commit bbba65d

File tree

4 files changed

+283
-1
lines changed

4 files changed

+283
-1
lines changed

‎nodeclient/README.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# NodeClient
2+
3+
NodeClient provides a simple interface to interact with ThreeFold nodes through JSON-RPC calls. It supports various operations including system information, network configuration, deployment management, and performance monitoring.
4+
5+
## Usage
6+
7+
```go
8+
package main
9+
10+
import (
11+
"context"
12+
"fmt"
13+
"log"
14+
15+
"github.com/threefoldtech/tfgrid-sdk-go/messenger"
16+
"github.com/threefoldtech/zosbase/nodeclient"
17+
)
18+
19+
func main() {
20+
// Create messenger instance
21+
msgr := messenger.NewMessenger(/* messenger config */)
22+
23+
// Create node client
24+
client := nodeclient.NewNodeClient(msgr, "node-destination-id")
25+
26+
ctx := context.Background()
27+
28+
// Get node version
29+
version, err := client.GetNodeVersion(ctx)
30+
if err != nil {
31+
log.Fatal(err)
32+
}
33+
fmt.Printf("Node version: %+v\n", version)
34+
35+
// Get system diagnostics
36+
diag, err := client.GetSystemDiagnostics(ctx)
37+
if err != nil {
38+
log.Fatal(err)
39+
}
40+
fmt.Printf("Diagnostics: %+v\n", diag)
41+
42+
// List deployments
43+
deployments, err := client.DeploymentList(ctx)
44+
if err != nil {
45+
log.Fatal(err)
46+
}
47+
fmt.Printf("Found %d deployments\n", len(deployments))
48+
}
49+
```

‎nodeclient/nodeclient.go

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@ type NodeClient struct {
1717
destination string
1818
}
1919

20-
// TODO: paramter types in cleint/apirpc
2120
func NewNodeClient(msgr *messenger.Messenger, destination string) *NodeClient {
2221
return &NodeClient{
2322
rpcClient: messenger.NewJSONRPCClient(msgr),

‎mycelium-openrpc.json renamed to ‎openrpc.json

File renamed without changes.

‎pkg/api/README.md

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# ZOS API Package
2+
3+
The ZOS API package provides a transport-agnostic interface for interacting with ZOS (Zero OS) nodes. This package is designed with a clear separation between API definitions and transport implementations, ensuring flexibility and maintainability.
4+
5+
## Overview
6+
7+
The ZOS API package serves as the core interface layer for ZOS node operations. It provides a comprehensive set of methods for:
8+
9+
- System information and diagnostics
10+
- Network configuration and monitoring
11+
- Deployment management (create, update, delete, query)
12+
- Storage pool management
13+
- Performance monitoring and benchmarking
14+
15+
## Transport Agnostic Design
16+
17+
The API package is designed to be **transport-layer agnostic**, meaning it doesn't depend on specific transport protocols (RPC, REST, WebSocket, etc.). This design principle ensures:
18+
19+
### Key Benefits
20+
21+
1. **Protocol Independence**: The core API logic is separated from transport concerns
22+
2. **Clear Interfaces**: Well-defined parameter and return types that work with any transport
23+
4. **Future Flexibility**: New transport protocols can be added without changing core API logic
24+
5. **Maintainability**: Changes to transport don't affect API business logic
25+
26+
### Architecture
27+
28+
```
29+
┌─────────────────────────────────────────┐
30+
│ Transport Layer │
31+
│ (JSON-RPC, REST, gRPC, WebSocket...) │
32+
├─────────────────────────────────────────┤
33+
│ API Package │
34+
│ • Method definitions │
35+
│ • Parameter/Return types │
36+
│ • Business logic │
37+
│ • Mode handling (full/light) │
38+
├─────────────────────────────────────────┤
39+
│ Service Layer │
40+
│ • ZBus stubs │
41+
│ • Resource oracle │
42+
│ • Diagnostics manager │
43+
└─────────────────────────────────────────┘
44+
```
45+
46+
47+
## Operating Modes
48+
49+
either passing `light` or anything else will considered full/normal zos mode
50+
51+
## Current Protocol Support
52+
53+
### JSON-RPC Implementation
54+
55+
The primary transport protocol currently supported is **JSON-RPC**, implemented in the `pkg/api/jsonrpc` directory.
56+
57+
#### Handler Registration
58+
59+
The JSON-RPC handlers are registered in `pkg/api/jsonrpc/handlers.go`:
60+
61+
```go
62+
func RegisterHandlers(s *messenger.JSONRPCServer, r *RpcHandler) {
63+
// System endpoints
64+
s.RegisterHandler("system.version", r.handleSystemVersion)
65+
s.RegisterHandler("system.dmi", r.handleSystemDMI)
66+
67+
// Network endpoints
68+
s.RegisterHandler("network.interfaces", r.handleNetworkInterfaces)
69+
70+
// Deployment endpoints
71+
s.RegisterHandler("deployment.deploy", r.handleDeploymentDeploy)
72+
73+
// ... and many more
74+
}
75+
```
76+
77+
#### Integration Pattern
78+
79+
1. **RpcHandler**: Wraps the API instance and provides JSON-RPC specific handling
80+
2. **Parameter Extraction**: Converts JSON-RPC parameters to Go types
81+
3. **Method Delegation**: Calls the appropriate API method
82+
4. **Response Formatting**: Returns results in JSON-RPC format
83+
84+
This pattern allows the core API to remain transport-agnostic while providing a clean JSON-RPC interface.
85+
86+
## API Documentation Using the OpenRPC Specification
87+
88+
The `openrpc.json` file can be used with various tools:
89+
90+
- **API Documentation Generators**: Generate human-readable docs
91+
- **Client Code Generation**: Auto-generate client libraries
92+
- **API Testing Tools**: Validate requests and responses
93+
- **IDE Integration**: Provide autocomplete and validation
94+
95+
Example method definition from `openrpc.json`:
96+
```json
97+
{
98+
"name": "system.version",
99+
"params": [],
100+
"result": {
101+
"name": "Version",
102+
"schema": {
103+
"$ref": "#/components/schemas/Version"
104+
}
105+
}
106+
}
107+
```
108+
109+
## Usage Examples
110+
111+
### Basic API Initialization
112+
113+
```go
114+
package main
115+
116+
import (
117+
"context"
118+
"log"
119+
120+
"github.com/threefoldtech/zbus"
121+
"github.com/threefoldtech/zosbase/pkg/api"
122+
)
123+
124+
func main() {
125+
// Initialize ZBus client
126+
client, err := zbus.NewClient("unix:///var/run/redis.sock")
127+
if err != nil {
128+
log.Fatal(err)
129+
}
130+
defer client.Close()
131+
132+
// Create API instance in full mode
133+
apiInstance, err := api.NewAPI(client, "tcp://localhost:6379", "")
134+
if err != nil {
135+
log.Fatal(err)
136+
}
137+
138+
// Create API instance in light mode
139+
lightAPI, err := api.NewAPI(client, "tcp://localhost:6379", "light")
140+
if err != nil {
141+
log.Fatal(err)
142+
}
143+
144+
// Create JSON-RPC server
145+
server := messenger.NewJSONRPCServer()
146+
147+
// Create RPC handler
148+
rpcHandler := jsonrpc.NewRpcHandler(apiInstance)
149+
150+
// Register all handlers
151+
jsonrpc.RegisterHandlers(server, rpcHandler)
152+
153+
server.Start(ctx)
154+
}
155+
```
156+
157+
## Available API Commands
158+
159+
The following commands are available through the API. For complete parameter and return type specifications, refer to the `openrpc.json` file.
160+
161+
### System Commands
162+
163+
| Command | Description | Parameters | Returns |
164+
|---------|-------------|------------|---------|
165+
| `system.version` | Get ZOS and Zinit versions | None | Version object |
166+
| `system.dmi` | Get DMI (Desktop Management Interface) information | None | DMI object |
167+
| `system.hypervisor` | Detect hypervisor type | None | String |
168+
| `system.diagnostics` | Get comprehensive system diagnostics | None | Diagnostics object |
169+
| `system.features` | Get supported node features | None | NodeFeatures array |
170+
171+
### Network Commands
172+
173+
| Command | Description | Parameters | Returns |
174+
|---------|-------------|------------|---------|
175+
| `network.wg_ports` | List reserved WireGuard ports | None | Array of port numbers |
176+
| `network.public_config` | Get public network configuration | None | PublicConfig object |
177+
| `network.has_ipv6` | Check IPv6 support | None | Boolean |
178+
| `network.public_ips` | List public IP addresses | None | Array of IP addresses |
179+
| `network.private_ips` | List private IPs for network | `network_name` | Array of IP addresses |
180+
| `network.interfaces` | List network interfaces | None | Map of interface names to IPs |
181+
| `network.set_public_nic` | Set public network interface | `device` | Success/Error |
182+
| `network.get_public_nic` | Get current public interface | None | Interface name |
183+
| `network.admin.interfaces` | List admin interfaces | None | Interface information |
184+
185+
### Deployment Commands
186+
187+
| Command | Description | Parameters | Returns |
188+
|---------|-------------|------------|---------|
189+
| `deployment.deploy` | Deploy new workload | Deployment object | Success/Error |
190+
| `deployment.update` | Update existing deployment | Deployment object | Success/Error |
191+
| `deployment.get` | Get deployment by contract ID | `contract_id` | Deployment object |
192+
| `deployment.list` | List all deployments | None | Deployments array |
193+
| `deployment.changes` | Get deployment changes | `contract_id` | Workloads array |
194+
| `deployment.delete` | Delete deployment | `contract_id` | Success/Error |
195+
196+
### Performance Monitoring Commands
197+
198+
| Command | Description | Parameters | Returns |
199+
|---------|-------------|------------|---------|
200+
| `monitor.speed` | Run network speed test | None | Speed test results |
201+
| `monitor.health` | Run health check | None | Health check results |
202+
| `monitor.publicip` | Test public IP connectivity | None | Public IP test results |
203+
| `monitor.benchmark` | Run CPU benchmark | None | Benchmark results |
204+
| `monitor.all` | Run all performance tests | None | Combined test results |
205+
206+
### Storage Commands
207+
208+
| Command | Description | Parameters | Returns |
209+
|---------|-------------|------------|---------|
210+
| `storage.pools` | Get storage pool metrics | None | Pool metrics |
211+
212+
### GPU Commands
213+
214+
| Command | Description | Parameters | Returns |
215+
|---------|-------------|------------|---------|
216+
| `gpu.list` | List available GPUs | None | GPU information array |
217+
218+
### Statistics Commands
219+
220+
| Command | Description | Parameters | Returns |
221+
|---------|-------------|------------|---------|
222+
| `statistics` | Get node resource statistics | None | Statistics object |
223+
224+
### Location Commands
225+
226+
| Command | Description | Parameters | Returns |
227+
|---------|-------------|------------|---------|
228+
| `location.get` | Get node location information | None | Location object |
229+
230+
### VM Log Commands
231+
232+
| Command | Description | Parameters | Returns |
233+
|---------|-------------|------------|---------|
234+
| `vm.logs` | Get VM log content | `file_name` | Log content string |

0 commit comments

Comments
 (0)