hdds-gateway
REST API Gateway with Web UI for monitoring HDDS applications.
Overview
hdds-gateway provides HTTP access to the HDDS Admin API, enabling:
- REST API: JSON endpoints for integration with monitoring tools
- Web UI: Browser-based dashboard for real-time monitoring
- Prometheus-compatible: Metrics endpoint for Grafana dashboards
Architecture
┌──────────────┐ HTTP ┌───────────────┐ TCP ┌──────────────┐
│ Browser / │◄─────────────►│ hdds-gateway │◄────────────►│ HDDS App │
│ curl / API │ :8080 │ │ :4243 │ (Admin API) │
└──────────────┘ └───────────────┘ └──────────────┘
Installation
cargo install hdds-gateway
Or build from source:
cd crates/hdds-gateway
cargo build --release
Quick Start
- Enable Admin API in your HDDS application:
let participant = ParticipantBuilder::new()
.domain_id(0)
.enable_admin_api(4243) // TCP port
.build()?;
- Start the gateway:
hdds-gateway --admin-addr 127.0.0.1:4243
- Access the Web UI:
Open http://localhost:8080 in your browser.
CLI Reference
hdds-gateway [OPTIONS]
Options:
-p, --port <PORT> HTTP port [default: 8080]
-b, --bind <ADDR> Bind address [default: 0.0.0.0]
-a, --admin-addr <ADDR> Admin API address [default: 127.0.0.1:4243]
--api-only Disable Web UI, serve only REST API
-h, --help Print help
-V, --version Print version
Examples
# Default: Web UI + API on port 8080
hdds-gateway
# Custom ports
hdds-gateway --port 3000 --admin-addr 192.168.1.100:4243
# API only (no Web UI)
hdds-gateway --api-only
# Bind to specific interface
hdds-gateway --bind 127.0.0.1 --port 8080
REST API
API Version
All endpoints are versioned under /api/v1/. Legacy endpoints (without version prefix) are available for backward compatibility.
Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/v1/info | GET | Gateway information and available endpoints |
/api/v1/health | GET | Health status of connected HDDS application |
/api/v1/mesh | GET | Discovery mesh (participants, locators) |
/api/v1/topics | GET | Active topics with type information |
/api/v1/metrics | GET | Performance metrics |
/api/v1/writers | GET | DataWriter endpoints |
/api/v1/readers | GET | DataReader endpoints |
Response Format
All responses are JSON:
{
"status": "ok",
"data": { ... }
}
Error responses:
{
"error": "Connection refused",
"code": 503
}
GET /api/v1/info
Gateway information:
curl http://localhost:8080/api/v1/info
{
"name": "hdds-gateway",
"version": "1.0.0",
"api_version": "v1",
"endpoints": [
"/api/v1/health",
"/api/v1/mesh",
"/api/v1/topics",
"/api/v1/metrics",
"/api/v1/writers",
"/api/v1/readers",
"/api/v1/info"
]
}
GET /api/v1/health
Health check:
curl http://localhost:8080/api/v1/health
{
"status": "ok",
"participant_guid": "01.0f.aa.bb.cc.dd.ee.ff.00.00.01.c1",
"domain_id": 0,
"uptime_secs": 3600
}
GET /api/v1/mesh
Discovery mesh showing all discovered participants:
curl http://localhost:8080/api/v1/mesh
{
"participants": [
{
"guid": "01.0f.aa.bb.cc.dd.ee.ff.00.00.01.c1",
"vendor_id": "0x01aa",
"vendor_name": "HDDS",
"locators": [
"udp/239.255.0.1:7400",
"udp/192.168.1.100:7411"
]
}
],
"total": 1
}
GET /api/v1/topics
Active topics:
curl http://localhost:8080/api/v1/topics
{
"topics": [
{
"name": "sensor/temperature",
"type_name": "SensorData",
"writers": 1,
"readers": 2
}
],
"total": 1
}
GET /api/v1/metrics
Performance metrics:
curl http://localhost:8080/api/v1/metrics
{
"samples_sent": 12456,
"samples_received": 8923,
"bytes_sent": 1234567,
"bytes_received": 892345,
"nacks_sent": 12,
"heartbeats_sent": 456,
"discovery_messages": 89
}
GET /api/v1/writers
DataWriter endpoints:
curl http://localhost:8080/api/v1/writers
{
"writers": [
{
"guid": "01.0f.aa.bb.cc.dd.ee.ff.00.00.03.02",
"topic": "sensor/temperature",
"type_name": "SensorData",
"qos": {
"reliability": "reliable",
"durability": "volatile"
},
"matched_readers": 2
}
],
"total": 1
}
GET /api/v1/readers
DataReader endpoints:
curl http://localhost:8080/api/v1/readers
{
"readers": [
{
"guid": "01.0f.aa.bb.cc.dd.ee.ff.00.00.04.07",
"topic": "sensor/temperature",
"type_name": "SensorData",
"qos": {
"reliability": "reliable",
"durability": "volatile"
},
"matched_writers": 1
}
],
"total": 1
}
Web UI
The embedded Web UI provides:
- Dashboard: Overview of participants, topics, and metrics
- Mesh View: Visual discovery graph
- Topics List: Active topics with reader/writer counts
- Metrics: Real-time performance charts
Access at http://localhost:8080/.
Disable Web UI
For API-only deployments:
hdds-gateway --api-only
Integration
Prometheus
Metrics endpoint is compatible with Prometheus scraping:
# prometheus.yml
scrape_configs:
- job_name: 'hdds'
static_configs:
- targets: ['localhost:8080']
metrics_path: '/api/v1/metrics'
Grafana
Import the HDDS dashboard (ID: coming soon) or create custom panels using the REST API.
curl Examples
# Health check
curl -s http://localhost:8080/api/v1/health | jq
# List topics
curl -s http://localhost:8080/api/v1/topics | jq '.topics[].name'
# Watch metrics (every 2 seconds)
watch -n 2 'curl -s http://localhost:8080/api/v1/metrics | jq'
Python Client
import requests
class HddsGatewayClient:
def __init__(self, base_url="http://localhost:8080"):
self.base_url = base_url
def health(self):
return requests.get(f"{self.base_url}/api/v1/health").json()
def topics(self):
return requests.get(f"{self.base_url}/api/v1/topics").json()
def metrics(self):
return requests.get(f"{self.base_url}/api/v1/metrics").json()
# Usage
client = HddsGatewayClient()
print(client.health())
for topic in client.topics()["topics"]:
print(f"Topic: {topic['name']}")
Error Codes
| HTTP Code | Description |
|---|---|
| 200 | Success |
| 503 | Admin API connection refused |
| 504 | Admin API timeout |
| 500 | Internal server error |
CORS
CORS is enabled by default, allowing browser-based clients from any origin.
Related
- Admin API - Binary protocol details
- Telemetry - Metrics collection
- Configuration - HDDS configuration