x/platform
1
0
Fork 0
Code Issues Pull requests Projects Releases 12 Packages Wiki Activity Actions
12 releases 12 tags
  • v0.3.0 99d95aa494

    v0.3.0 Stable

    x released this 2026-02-21 13:34:29 +00:00 | 9 commits to main since this release

    Signed by x
    GPG key ID: A14ACA8AB45A9C27

    VSKI v0.3.0

    Features

    OpenAPI Specification Support

    • OpenAPI 3.0.3 Specification:

      • Complete OpenAPI spec generation for all API endpoints
      • Served via /openapi.json and /openapi.html

    • Interactive API Documentation:

      • Embedded Redoc UI with index.html
      • Beautiful, responsive API documentation with Try It Now functionality
      • JWT Bearer authentication support documented
      • Custom theme matching VSKI branding

    • API Endpoint:

      • GET /openapi.json - Retrieve OpenAPI 3.0.3 specification
      • Can be imported into API clients (Postman, Insomnia, etc.)
      • Used for auto-generating SDKs and documentation

    Enhanced Database Management

    • Database Creation API:

      • POST /api/databases - Create new database files dynamically
      • Supports custom descriptions for user databases
      • Automatic registration in _databases table
      • Proper error handling and validation

    • Database Listing Improvements:

      • GET /api/databases - List all databases with metadata
      • Proper NULL handling for descriptions
      • Alphabetical sorting for better UX
      • Detailed error logging with structured logs (slog)

    • Database Management Service:

      • Physical database file creation in DATA_DIR
      • Automatic cleanup on creation failure
      • Integration with existing database provider

    • Reserved Database Protection:

      • default and stats databases are protected from deletion
      • Cannot create databases with reserved names
      • Clear error messages for reserved name violations

    Collection Creation Restrictions

    • Stats Database Protection:

      • Prevent collection creation in stats database
      • stats is reserved for system metrics and analytics
      • Returns clear error message when attempting to create collections

    • Enhanced Validation:

      • Collection creation service now validates database name
      • Prevents accidental data in system databases

    Build Process Improvements

    • Simplified Default Build:

      • make build now produces production binary without UPX compression
      • Faster build times for development iterations
      • Smaller binary footprint for production deployments

    • New Build Targets:

      • make build-release - Production build with UPX compression for smallest size
      • make build-prod - Production build without compression
      • Clear separation between development and release builds

    Installation

    Binary

    Download binary for your platform:

    # Linux (standalone with embedded UI)
wget https://git.vski.sh/x/platform/releases/download/v0.3.0/vski-standalone
chmod +x vski-standalone
./vski-standalone

# Linux (API-only)
wget https://git.vski.sh/x/platform/releases/download/v0.3.0/vski
chmod +x vski
./vski

    Docker

    Pull and run official Docker image:

    # Light version (API only, no embedded UI)
docker pull git.vski.sh/x/vski:latest

# Standalone version (with embedded web UI)
docker pull git.vski.sh/x/vski:latest-standalone

# Pull specific version
docker pull git.vski.sh/x/vski:v0.3.0
docker pull git.vski.sh/x/vski:v0.3.0-standalone

# Run light version with default configuration
docker run -p 3000:3000 -v $(pwd)/data:/app/data git.vski.sh/x/vski:latest

# Run standalone version with embedded web UI
docker run -p 3000:3000 -v $(pwd)/data:/app/data git.vski.sh/x/vski:latest-standalone

    Configuration

    Create a .env file:

    DATA_DIR=./data
SERVER_PORT=3000
JWT_SECRET=your-secret-key

    Usage

    Accessing OpenAPI Specification

    # Get OpenAPI JSON spec
curl http://localhost:3000/openapi.json > openapi.json

# View interactive documentation
open http://localhost:3000/

    Creating Databases via API

    // Create a new database
const response = await fetch('http://localhost:3000/api/databases', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: JSON.stringify({
    name: 'analytics',
    description: 'User analytics database'
  })
});

const database = await response.json();
console.log(database);
// { id: 'analytics', name: 'analytics', description: 'User analytics database' }

    Listing Databases

    // List all databases
const response = await fetch('http://localhost:3000/api/databases', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
});

const databases = await response.json();
console.log(databases);
// [
//   { id: 'default', name: 'default', description: 'Main database', created: '...', updated: '...' },
//   { id: 'stats', name: 'stats', description: 'Statistics database', created: '...', updated: '...' },
//   { id: 'analytics', name: 'analytics', description: 'User analytics database', created: '...', updated: '...' }
// ]

    Error Handling

    // Attempt to create reserved database name
try {
  const response = await fetch('http://localhost:3000/api/databases', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_JWT_TOKEN'
    },
    body: JSON.stringify({
      name: 'default'  // Reserved name!
    })
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(error);
    // { error: 'Cannot create reserved database names (default, stats)' }
  }
} catch (error) {
  console.error('Failed to create database:', error);
}

// Attempt to create collection in stats database
try {
  const response = await fetch('http://localhost:3000/api/collections', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_JWT_TOKEN',
      'x-dbname': 'stats'  // Reserved database!
    },
    body: JSON.stringify({
      name: 'my_collection',
      schema: {}
    })
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(error);
    // { error: 'cannot create collection in reserved database "stats"' }
  }
} catch (error) {
  console.error('Failed to create collection:', error);
}

    Building from Source

    # Clone repository
git clone https://git.vski.sh/x/platform.git
cd platform/vski

# Build production binary (no compression)
make build

# Build release binary (with UPX compression)
make build-release

# Run binary
./bin/vski

    Migration Notes

    Database Migration

    No manual migration required. The _databases table is automatically initialized with default entries on server startup.

    Breaking Changes

    Database Creation Restrictions:

    • Cannot create databases named default or stats (reserved for system use)
    • Cannot create collections in stats database
    • These restrictions were previously unenforced but always intended

    Build Process Changes:

    • make build no longer uses UPX compression by default
    • Use make build-release for compressed (smallest size) binaries
    • This change speeds up development builds while maintaining optimization for releases

    Configuration Updates

    No configuration changes required. All existing configurations work without modification.

    API Endpoints

    OpenAPI Specification

    Method Endpoint Description
    GET /openapi.json Retrieve OpenAPI 3.0.3 spec

    Database Management

    Method Endpoint Request Body Description
    GET /api/databases - List all databases
    POST /api/databases {name, description?} Create new database
    DELETE /api/databases/:name - Delete database

    Database Creation Response

    {
  "id": "analytics",
  "name": "analytics",
  "description": "User analytics database"
}

    Database List Response

    [
  {
    "id": "default",
    "name": "default",
    "description": "Main database",
    "created": "2026-02-21T12:00:00Z",
    "updated": "2026-02-21T12:00:00Z"
  },
  {
    "id": "stats",
    "name": "stats",
    "description": "Statistics database",
    "created": "2026-02-21T12:00:00Z",
    "updated": "2026-02-21T12:00:00Z"
  }
]

    Testing

    Run E2E Tests

    cd vski
make build
make e2e TEST=19_webhooks_test.ts  # Test webhook triggers
make e2e TEST=10_cron_test.ts       # Test cron integration

    Test OpenAPI Spec

    # Start server
./bin/vski

# Get and validate OpenAPI spec
curl http://localhost:3000/openapi.json | jq .

# Validate spec with OpenAPI validator
# (requires npx or global install)
npx @apidevtools/swagger-cli validate http://localhost:3000/openapi.json

    Test Database Management

    # Create database
curl -X POST http://localhost:3000/api/databases \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name":"testdb","description":"Test database"}'

# List databases
curl http://localhost:3000/api/databases \
  -H "Authorization: Bearer YOUR_TOKEN"

# Try to create reserved database (should fail)
curl -X POST http://localhost:3000/api/databases \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name":"default"}'

    Documentation

    Full documentation available at: https://git.vski.sh/x/platform

    Interactive API documentation:

    • Local: http://localhost:3000/ (when running standalone binary)
    • OpenAPI Spec: http://localhost:3000/openapi.json

    Changelog

    v0.3.0 (2026-02-21)

    Added

    • OpenAPI 3.0.3 specification generation for all API endpoints
    • /openapi.json endpoint for retrieving machine-readable API spec
    • Embedded Redoc UI (index.html) with interactive documentation
    • Database creation API (POST /api/databases)
    • Database listing with metadata and descriptions
    • Database deletion API with reserved name protection
    • Reserved database protection (default, stats from deletion)
    • Collection creation restriction in stats database
    • build-release make target for UPX-compressed production builds
    • logs/ directory to .gitignore

    Changed

    • Default make build no longer applies UPX compression
    • Database list endpoint now sorts results alphabetically
    • Database creation now validates against reserved names
    • Collection creation service validates database name before creation
    • Database list now uses proper NULL handling for descriptions

    Fixed

    • Database creation now creates physical database files
    • Database listing returns proper error messages on failure
    • Clear error messages for reserved database violations
    • Proper error logging with structured logs (slog)

    Technical

    • Added github.com/getkin/kin-openapi v0.133.0 for OpenAPI spec generation
    • Updated related dependencies for OpenAPI support
    • Enhanced error handling throughout database management APIs
    • Improved documentation in AGENTS.md
    Downloads