Web UI Server

Built-in web interface and REST API for managing your database

Overview

jasonisnthappy includes an optional built-in web server that provides:

The web UI feature is enabled by default but can be disabled at compile time if not needed.

Getting Started

Start the web server to access the dashboard and REST API:

use jasonisnthappy::{Database, WebServer};
use std::sync::Arc;

fn main() -> Result<(), Box> {
    // Open database
    let db = Arc::new(Database::open("my.db")?);

    // Start web server on port 8080
    let server = WebServer::start(db.clone(), "127.0.0.1:8080")?;

    println!("Web UI running at http://127.0.0.1:8080");

    // Keep server running
    std::thread::park();

    Ok(())
}
from jasonisnthappy import Database, WebServer
import time

# Open database
db = Database.open("my.db")

# Start web server
server = WebServer.start(db, "127.0.0.1:8080")

print("Web UI running at http://127.0.0.1:8080")

# Keep server running
try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    server.shutdown()
    db.close()
const { Database, WebServer } = require('jasonisnthappy');

// Open database
const db = Database.open('my.db');

// Start web server
const server = WebServer.start(db, '127.0.0.1:8080');

console.log('Web UI running at http://127.0.0.1:8080');

// Graceful shutdown
process.on('SIGINT', () => {
    server.shutdown();
    db.close();
    process.exit(0);
});
package main

import (
    "fmt"
    "github.com/sohzm/jasonisnthappy-go"
    "os"
    "os/signal"
    "syscall"
)

func main() {
    // Open database
    db, err := jasonisnthappy.Open("my.db")
    if err != nil {
        panic(err)
    }
    defer db.Close()

    // Start web server
    server, err := jasonisnthappy.StartWebServer(db, "127.0.0.1:8080")
    if err != nil {
        panic(err)
    }
    defer server.Shutdown()

    fmt.Println("Web UI running at http://127.0.0.1:8080")

    // Wait for interrupt
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
    <-sigChan
}

Web Dashboard

Access the web dashboard by navigating to the server's root URL (e.g., http://127.0.0.1:8080/).

The dashboard provides:

REST API

The web server exposes a REST API for programmatic access to your database.

Base URL

http://127.0.0.1:8080/api

Response Format

All responses are in JSON format. Successful operations return appropriate HTTP status codes (200, 201) with result data. Errors return 404, 500 status codes with error messages.

API Endpoints

Health Check

GET /health

Returns the health status of the database server.

{
  "status": "ok"
}

Metrics

GET /metrics

Returns database performance metrics including cache hits, page reads/writes, and transaction stats.

{
  "cache_hits": 1523,
  "cache_misses": 47,
  "page_reads": 892,
  "page_writes": 234,
  "transactions_committed": 156,
  "transactions_aborted": 3
}

List Collections

GET /api/collections

Returns an array of all collection names in the database.

["users", "posts", "comments"]

Create Collection

POST /api/collections
Content-Type: application/json

{
  "name": "products"
}

Creates a new collection with the specified name.

{
  "status": "created",
  "name": "products"
}

Rename Collection

PATCH /api/collections/{collection_name}
Content-Type: application/json

{
  "new_name": "items"
}

Renames a collection.

{
  "status": "renamed",
  "old_name": "products",
  "new_name": "items"
}

Drop Collection

DELETE /api/collections/{collection_name}

Deletes a collection and all its documents.

{
  "status": "deleted",
  "name": "products"
}

List Documents

GET /api/collections/{collection_name}

Returns all documents in the specified collection.

[
  {
    "_id": "doc1",
    "name": "Alice",
    "age": 30
  },
  {
    "_id": "doc2",
    "name": "Bob",
    "age": 25
  }
]

Create Document

POST /api/collections/{collection_name}
Content-Type: application/json

{
  "name": "Charlie",
  "age": 35,
  "email": "charlie@example.com"
}

Creates a new document in the collection.

{
  "id": "doc3"
}

Update Document

PUT /api/collections/{collection_name}/{document_id}
Content-Type: application/json

{
  "name": "Charlie",
  "age": 36,
  "email": "charlie@example.com"
}

Updates an existing document by ID.

{
  "status": "updated"
}

Delete Document

DELETE /api/collections/{collection_name}/{document_id}

Deletes a document by ID.

{
  "status": "deleted"
}

Usage Examples

Using curl

# Check health
curl http://localhost:8080/health

# Get metrics
curl http://localhost:8080/metrics

# List collections
curl http://localhost:8080/api/collections

# Create a collection
curl -X POST http://localhost:8080/api/collections \
  -H "Content-Type: application/json" \
  -d '{"name":"users"}'

# Create a document
curl -X POST http://localhost:8080/api/collections/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","age":30,"email":"alice@example.com"}'

# Get all documents
curl http://localhost:8080/api/collections/users

# Update a document
curl -X PUT http://localhost:8080/api/collections/users/doc1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","age":31,"email":"alice@example.com"}'

# Delete a document
curl -X DELETE http://localhost:8080/api/collections/users/doc1

# Drop a collection
curl -X DELETE http://localhost:8080/api/collections/users

Using JavaScript fetch

// Create a document
const response = await fetch('http://localhost:8080/api/collections/users', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        name: 'Alice',
        age: 30,
        email: 'alice@example.com'
    })
});

const result = await response.json();
console.log('Document created with ID:', result.id);

// Get all documents
const docs = await fetch('http://localhost:8080/api/collections/users')
    .then(res => res.json());
console.log('Documents:', docs);

// Update a document
await fetch(`http://localhost:8080/api/collections/users/${docId}`, {
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        name: 'Alice',
        age: 31,
        email: 'alice@example.com'
    })
});

// Delete a document
await fetch(`http://localhost:8080/api/collections/users/${docId}`, {
    method: 'DELETE'
});

Using Python requests

import requests

base_url = 'http://localhost:8080'

# Create a document
response = requests.post(
    f'{base_url}/api/collections/users',
    json={
        'name': 'Alice',
        'age': 30,
        'email': 'alice@example.com'
    }
)
doc_id = response.json()['id']
print(f'Document created with ID: {doc_id}')

# Get all documents
docs = requests.get(f'{base_url}/api/collections/users').json()
print(f'Documents: {docs}')

# Update a document
requests.put(
    f'{base_url}/api/collections/users/{doc_id}',
    json={
        'name': 'Alice',
        'age': 31,
        'email': 'alice@example.com'
    }
)

# Delete a document
requests.delete(f'{base_url}/api/collections/users/{doc_id}')

Security Considerations