CHORUS/docs/comprehensive/api/http-server.md

HTTP Server API Reference

Overview

The CHORUS HTTP Server provides REST API endpoints for accessing the distributed Hypercore log, monitoring system health, and querying system status. All endpoints return JSON responses.

Base URL: http://localhost:8080/api (default)

Server Configuration

Initialization

server := api.NewHTTPServer(port, hypercoreLog, pubsub)
err := server.Start()

Parameters

• port (int) - HTTP port to listen on
• hypercoreLog (*logging.HypercoreLog) - Distributed log instance
• pubsub (*pubsub.PubSub) - Event broadcasting system

Server Lifecycle

// Start server (blocking)
err := server.Start()

// Stop server gracefully
err := server.Stop()

CORS Configuration

All endpoints support CORS with the following headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

OPTIONS preflight requests return 200 OK immediately.

Endpoints

1. Health Check

Check if the API server is running and responding.

Endpoint: GET /api/health

Parameters: None

Response:

{
  "status": "healthy",
  "timestamp": 1727712345,
  "log_entries": 1024
}

Response Fields:

• status (string) - Always "healthy" if server is responding
• timestamp (int64) - Current Unix timestamp in seconds
• log_entries (uint64) - Total number of log entries in the Hypercore log

Example:

curl -X GET http://localhost:8080/api/health

Status Codes:

• 200 OK - Server is healthy and responding

---

2. System Status

Get detailed system status including Hypercore statistics and API version.

Endpoint: GET /api/status

Parameters: None

Response:

{
  "status": "running",
  "timestamp": 1727712345,
  "hypercore": {
    "total_entries": 1024,
    "head_hash": "abc123...",
    "peer_id": "12D3KooW...",
    "replicators": 3
  },
  "api_version": "1.0.0"
}

Response Fields:

• status (string) - System operational status ("running")
• timestamp (int64) - Current Unix timestamp
• hypercore (object) - Hypercore log statistics
• api_version (string) - API version string

Example:

curl -X GET http://localhost:8080/api/status

Status Codes:

• 200 OK - Status retrieved successfully

---

3. Get Log Entries

Query log entries with flexible filtering by range or limit.

Endpoint: GET /api/hypercore/logs

Query Parameters:

• start (uint64, optional) - Starting index (inclusive)
• end (uint64, optional) - Ending index (exclusive, defaults to current length)
• limit (int, optional) - Maximum number of entries to return (default: 100, max: 1000)

Parameter Behavior:

• If neither start nor end are provided, returns most recent limit entries
• If only start is provided, returns from start to current end, up to limit
• If both start and end are provided, returns range [start, end), up to limit

Response:

{
  "entries": [
    {
      "index": 1023,
      "timestamp": "2025-09-30T14:25:45Z",
      "author": "12D3KooWAbC123...",
      "type": "task_completed",
      "data": {
        "task_id": "TASK-456",
        "result": "success",
        "duration_ms": 2340
      },
      "hash": "sha256:abc123...",
      "prev_hash": "sha256:def456...",
      "signature": "sig:789..."
    }
  ],
  "count": 1,
  "timestamp": 1727712345,
  "total": 1024
}

Response Fields:

• entries (array) - Array of log entry objects
• count (int) - Number of entries in this response
• timestamp (int64) - Response generation timestamp
• total (uint64) - Total number of entries in the log

Log Entry Fields:

• index (uint64) - Sequential entry index
• timestamp (string) - ISO 8601 timestamp
• author (string) - Peer ID that created the entry
• type (string) - Log entry type (see Log Types section)
• data (object) - Entry-specific data payload
• hash (string) - SHA-256 hash of this entry
• prev_hash (string) - Hash of the previous entry (blockchain-style)
• signature (string) - Digital signature

Examples:

# Get most recent 50 entries (default limit: 100)
curl -X GET "http://localhost:8080/api/hypercore/logs?limit=50"

# Get entries from index 100 to 200
curl -X GET "http://localhost:8080/api/hypercore/logs?start=100&end=200"

# Get entries starting at index 500 (up to current end)
curl -X GET "http://localhost:8080/api/hypercore/logs?start=500"

# Get last 10 entries
curl -X GET "http://localhost:8080/api/hypercore/logs?limit=10"

Status Codes:

• 200 OK - Entries retrieved successfully
• 400 Bad Request - Invalid parameter format
• 500 Internal Server Error - Failed to retrieve log entries

Error Examples:

# Invalid start parameter
curl -X GET "http://localhost:8080/api/hypercore/logs?start=invalid"
# Response: 400 Bad Request - "Invalid start parameter"

# System error
# Response: 500 Internal Server Error - "Failed to get log entries: database error"

---

4. Get Recent Log Entries

Retrieve the most recent log entries (convenience endpoint).

Endpoint: GET /api/hypercore/logs/recent

Query Parameters:

• limit (int, optional) - Maximum number of entries to return (default: 50, max: 1000)

Response:

{
  "entries": [
    {
      "index": 1023,
      "timestamp": "2025-09-30T14:25:45Z",
      "author": "12D3KooWAbC123...",
      "type": "task_completed",
      "data": {...}
    }
  ],
  "count": 50,
  "timestamp": 1727712345,
  "total": 1024
}

Response Fields: Same as "Get Log Entries" endpoint

Examples:

# Get last 10 entries
curl -X GET "http://localhost:8080/api/hypercore/logs/recent?limit=10"

# Get last 50 entries (default)
curl -X GET "http://localhost:8080/api/hypercore/logs/recent"

# Get last 100 entries
curl -X GET "http://localhost:8080/api/hypercore/logs/recent?limit=100"

Status Codes:

• 200 OK - Entries retrieved successfully
• 500 Internal Server Error - Failed to retrieve entries

---

5. Get Logs Since Index

Retrieve all log entries created after a specific index (useful for incremental synchronization).

Endpoint: GET /api/hypercore/logs/since/{index}

Path Parameters:

• index (uint64, required) - Starting index (exclusive - returns entries after this index)

Response:

{
  "entries": [
    {
      "index": 1001,
      "timestamp": "2025-09-30T14:20:00Z",
      "type": "task_claimed",
      "data": {...}
    },
    {
      "index": 1002,
      "timestamp": "2025-09-30T14:21:00Z",
      "type": "task_progress",
      "data": {...}
    }
  ],
  "count": 2,
  "since_index": 1000,
  "timestamp": 1727712345,
  "total": 1024
}

Response Fields:

• entries (array) - Array of log entries after the specified index
• count (int) - Number of entries returned
• since_index (uint64) - The index parameter provided in the request
• timestamp (int64) - Response generation timestamp
• total (uint64) - Current total number of entries in the log

Examples:

# Get all entries after index 1000
curl -X GET "http://localhost:8080/api/hypercore/logs/since/1000"

# Get all new entries (poll from last known index)
LAST_INDEX=950
curl -X GET "http://localhost:8080/api/hypercore/logs/since/${LAST_INDEX}"

Use Cases:

• Incremental Sync: Clients can poll this endpoint periodically to get new entries
• Change Detection: Detect new log entries since last check
• Event Streaming: Simple polling-based event stream

Status Codes:

• 200 OK - Entries retrieved successfully
• 400 Bad Request - Invalid index parameter
• 500 Internal Server Error - Failed to retrieve entries

---

6. Get Log Statistics

Get comprehensive statistics about the Hypercore log.

Endpoint: GET /api/hypercore/logs/stats

Parameters: None

Response:

{
  "total_entries": 1024,
  "head_hash": "sha256:abc123...",
  "peer_id": "12D3KooWAbC123...",
  "replicators": 3,
  "entry_types": {
    "task_announced": 234,
    "task_claimed": 230,
    "task_completed": 215,
    "task_failed": 15,
    "task_progress": 320,
    "peer_joined": 5,
    "peer_left": 3,
    "consensus_reached": 2
  },
  "authors": {
    "12D3KooWAbC123...": 567,
    "12D3KooWDef456...": 457
  },
  "first_entry_time": "2025-09-25T08:00:00Z",
  "last_entry_time": "2025-09-30T14:25:45Z"
}

Response Fields:

• total_entries (uint64) - Total number of log entries
• head_hash (string) - Current head hash of the log chain
• peer_id (string) - Local peer ID
• replicators (int) - Number of active replication connections
• entry_types (object) - Count of entries by type
• authors (object) - Count of entries by author peer ID
• first_entry_time (string) - Timestamp of first entry
• last_entry_time (string) - Timestamp of most recent entry

Example:

curl -X GET "http://localhost:8080/api/hypercore/logs/stats"

Status Codes:

• 200 OK - Statistics retrieved successfully

---

Log Entry Types

The Hypercore log supports multiple entry types for different system events:

Task Coordination (BZZZ)

• task_announced - New task announced to the swarm
• task_claimed - Agent claims a task
• task_progress - Progress update on a task
• task_completed - Task successfully completed
• task_failed - Task execution failed

Meta-Discussion (HMMM)

• plan_proposed - Agent proposes a plan
• objection_raised - Another agent raises an objection
• collaboration - Collaborative work event
• consensus_reached - Group consensus achieved
• escalation - Issue escalated for human review
• task_help_requested - Agent requests help with a task
• task_help_offered - Agent offers help with a task
• task_help_received - Help received and acknowledged

System Events

• peer_joined - New peer joined the network
• peer_left - Peer disconnected from the network
• capability_broadcast - Agent broadcasts its capabilities
• network_event - General network-level event

Data Payload Examples

Task Announced

{
  "type": "task_announced",
  "data": {
    "task_id": "TASK-123",
    "description": "Implement user authentication",
    "capabilities_required": ["go", "security", "api"],
    "priority": "high",
    "estimated_duration_minutes": 180
  }
}

Task Completed

{
  "type": "task_completed",
  "data": {
    "task_id": "TASK-123",
    "result": "success",
    "duration_ms": 172340,
    "commits": ["abc123", "def456"],
    "tests_passed": true,
    "coverage_percent": 87.5
  }
}

Consensus Reached

{
  "type": "consensus_reached",
  "data": {
    "discussion_id": "DISC-456",
    "proposal": "Refactor authentication module",
    "participants": ["agent-1", "agent-2", "agent-3"],
    "votes": {"yes": 3, "no": 0, "abstain": 0},
    "next_steps": ["create_subtasks", "assign_agents"]
  }
}

Error Responses

400 Bad Request

Invalid query parameters or path parameters:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Invalid start parameter

500 Internal Server Error

Server-side processing error:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

Failed to get log entries: database connection failed

Performance Recommendations

Pagination

Always use appropriate limit values to avoid retrieving large result sets:

# Good: Limited result set
curl "http://localhost:8080/api/hypercore/logs/recent?limit=50"

# Bad: Could return thousands of entries
curl "http://localhost:8080/api/hypercore/logs"

Polling Strategy

For incremental updates, use the "logs since" endpoint:

# Initial fetch
LAST_INDEX=$(curl -s "http://localhost:8080/api/hypercore/logs/recent?limit=1" | jq '.entries[0].index')

# Poll for updates (every 5 seconds)
while true; do
    NEW_ENTRIES=$(curl -s "http://localhost:8080/api/hypercore/logs/since/${LAST_INDEX}")
    if [ $(echo "$NEW_ENTRIES" | jq '.count') -gt 0 ]; then
        echo "$NEW_ENTRIES" | jq '.entries'
        LAST_INDEX=$(echo "$NEW_ENTRIES" | jq '.entries[-1].index')
    fi
    sleep 5
done

Caching

Consider caching statistics and status responses that change infrequently:

# Cache stats for 30 seconds
curl -H "Cache-Control: max-age=30" "http://localhost:8080/api/hypercore/logs/stats"

WebSocket Support (Future)

WebSocket support is planned for real-time log streaming:

// Future WebSocket API
const ws = new WebSocket('ws://localhost:8080/api/ws/logs');

ws.onmessage = (event) => {
  const logEntry = JSON.parse(event.data);
  console.log('New log entry:', logEntry);
};

Testing

Using curl

# Health check
curl -v http://localhost:8080/api/health

# Get recent logs with pretty-printing
curl -s http://localhost:8080/api/hypercore/logs/recent?limit=5 | jq '.'

# Monitor for new entries
watch -n 2 'curl -s http://localhost:8080/api/hypercore/logs/recent?limit=1 | jq ".entries[0]"'

Using httpie

# Install httpie
pip install httpie

# Make requests
http GET localhost:8080/api/health
http GET localhost:8080/api/hypercore/logs/recent limit==10
http GET localhost:8080/api/status

Integration Testing

package api_test

import (
    "testing"
    "net/http"
    "net/http/httptest"
)

func TestHealthEndpoint(t *testing.T) {
    // Create test server
    server := api.NewHTTPServer(0, mockHypercoreLog, mockPubSub)

    // Create test request
    req := httptest.NewRequest("GET", "/api/health", nil)
    rec := httptest.NewRecorder()

    // Execute request
    server.ServeHTTP(rec, req)

    // Assert response
    if rec.Code != http.StatusOK {
        t.Errorf("Expected 200, got %d", rec.Code)
    }
}

Related Documentation

• API Overview - API architecture and integration points
• Hypercore Log System - Distributed log internals
• Setup Manager - Configuration API (future document)
• Authentication - Authentication guide (future document)