centra
5c6eb04a46
- netboot-base.nix with SSH key auth - Launch scripts for node01/02/03 - Node configuration.nix and disko.nix - Nix modules for first-boot automation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
132 lines
3.3 KiB
Markdown
132 lines
3.3 KiB
Markdown
# PlasmaCloud Demo API
|
|
|
|
Minimal HTTP API demonstrating PlasmaCloud MVP-Alpha E2E functionality.
|
|
|
|
## Overview
|
|
|
|
This demo validates that all PlasmaCloud components work together for real applications:
|
|
- **IAM**: Token-based authentication
|
|
- **FlareDB**: Persistent key-value storage
|
|
- **Metricstor**: Prometheus metrics export
|
|
- **Platform Integration**: Complete E2E data flow
|
|
|
|
## Architecture
|
|
|
|
```
|
|
User → HTTP API → FlareDB (storage)
|
|
↓ ↓
|
|
IAM (auth) Metrics → Metricstor
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
| Method | Path | Auth Required | Description |
|
|
|--------|------|---------------|-------------|
|
|
| GET | /health | No | Health check |
|
|
| GET | /metrics | No | Prometheus metrics |
|
|
| POST | /items | Yes | Create item |
|
|
| GET | /items/:id | No | Retrieve item |
|
|
| DELETE | /items/:id | Yes | Delete item |
|
|
|
|
## Prerequisites
|
|
|
|
Running PlasmaCloud services:
|
|
- `flaredb-server` on port 8001
|
|
- `iam-server` on port 8002 (default)
|
|
|
|
## Build
|
|
|
|
```bash
|
|
cd docs/por/T029-practical-app-demo
|
|
nix develop /home/centra/cloud -c cargo build
|
|
```
|
|
|
|
## Run
|
|
|
|
```bash
|
|
# Set environment variables (optional)
|
|
export FLAREDB_ADDR=127.0.0.1:8001
|
|
export IAM_ADDR=http://127.0.0.1:8002
|
|
export BIND_ADDR=0.0.0.0:3000
|
|
|
|
# Run the server
|
|
./target/debug/plasma-demo-api
|
|
```
|
|
|
|
## Usage Example
|
|
|
|
```bash
|
|
# 1. Health check
|
|
curl http://localhost:3000/health
|
|
|
|
# 2. Create item (requires IAM token)
|
|
TOKEN=$(curl -X POST http://localhost:8002/auth/token \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"tenant_id":"test","user_id":"demo"}' | jq -r '.token')
|
|
|
|
curl -X POST http://localhost:3000/items \
|
|
-H "Authorization: Bearer $TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"id":"item1","data":"Hello PlasmaCloud"}'
|
|
|
|
# 3. Retrieve item (no auth required)
|
|
curl http://localhost:3000/items/item1
|
|
|
|
# 4. Check metrics
|
|
curl http://localhost:3000/metrics | grep items
|
|
|
|
# 5. Delete item (requires IAM token)
|
|
curl -X DELETE http://localhost:3000/items/item1 \
|
|
-H "Authorization: Bearer $TOKEN"
|
|
```
|
|
|
|
## Data Persistence
|
|
|
|
Items are stored in FlareDB with key format: `item:{id}`
|
|
|
|
Data persists across server restarts as long as FlareDB is running.
|
|
|
|
## Metrics
|
|
|
|
Exported Prometheus metrics:
|
|
- `http_requests_total` - Total HTTP requests
|
|
- `items_created_total` - Total items created
|
|
- `items_retrieved_total` - Total items retrieved
|
|
|
|
Metrics are scraped by Metricstor on the `/metrics` endpoint.
|
|
|
|
## Implementation
|
|
|
|
- **HTTP Framework**: Axum
|
|
- **Storage Client**: flaredb-client (raw KV operations)
|
|
- **Auth Client**: iam-client (token validation)
|
|
- **Metrics**: Prometheus (text export format)
|
|
- **Runtime**: Tokio async
|
|
|
|
## Code Structure
|
|
|
|
```
|
|
src/main.rs
|
|
├── AppState - Shared state (DB, IAM, Metrics)
|
|
├── Metrics - Prometheus registry and counters
|
|
├── Routes
|
|
│ ├── /health - Health check
|
|
│ ├── /metrics - Prometheus metrics
|
|
│ ├── POST /items - Create item
|
|
│ ├── GET /items/:id - Get item
|
|
│ └── DELETE /items/:id - Delete item
|
|
└── Middleware
|
|
└── auth_middleware - IAM token validation
|
|
```
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [x] Application deploys successfully
|
|
- [x] CRUD operations work
|
|
- [x] Data persists in FlareDB
|
|
- [x] IAM authentication validates tokens
|
|
- [x] Metrics exported to /metrics endpoint
|
|
|
|
## Time Budget
|
|
|
|
Implementation: ~2 hours (Option A minimal scope)
|