centra
d2149b6249
- Replace form_urlencoded with RFC 3986 compliant URI encoding - Implement aws_uri_encode() matching AWS SigV4 spec exactly - Unreserved chars (A-Z,a-z,0-9,-,_,.,~) not encoded - All other chars percent-encoded with uppercase hex - Preserve slashes in paths, encode in query params - Normalize empty paths to '/' per AWS spec - Fix test expectations (body hash, HMAC values) - Add comprehensive SigV4 signature determinism test This fixes the canonicalization mismatch that caused signature validation failures in T047. Auth can now be enabled for production. Refs: T058.S1
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
|
|
- **Nightlight**: Prometheus metrics export
|
|
- **Platform Integration**: Complete E2E data flow
|
|
|
|
## Architecture
|
|
|
|
```
|
|
User → HTTP API → FlareDB (storage)
|
|
↓ ↓
|
|
IAM (auth) Metrics → Nightlight
|
|
```
|
|
|
|
## 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 Nightlight 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)
|