x/platform
1
0
Fork 0
Code Issues Pull requests Projects Releases 3 Packages Wiki Activity Actions
3 releases 3 tags
  • v0.2.0 40c4540455

    v0.2.0 Stable

    x released this 2026-02-17 18:26:44 +00:00 | 0 commits to main since this release

    Signed by x
    GPG key ID: A14ACA8AB45A9C27

    VSKI v0.2.0

    Features

    Enhanced Webhook System

    • Retry Configuration: Configure retry limits (1-100 attempts, default 5) for all webhooks

      • Set retry limit per webhook for fine-grained control
      • Configurable via collection triggers, standalone webhooks, and cron jobs
      • Limits prevent runaway retry loops

    • Exponential Backoff Retry Mechanism:

      • Retry delay increases exponentially: 2^0=2s, 2^1=4s, 2^2=8s, 2^3=16s, 2^4=32s
      • Prevents hammering downstream services during outages
      • Reduces network load and server stress

    • JWT Authentication for Webhooks:

      • Optional JWT bearer tokens for webhook authentication
      • Tokens include roles: ["service", "webhook"] for easy server-side verification
      • Enable per-webhook for secure integrations

    • Restart-Proof Webhook Execution:

      • Webhook state persisted in _webhook_logs table
      • Automatic retry continuation after server restart
      • No lost webhook deliveries during deployments

    Standalone Webhook Management

    • CRUD API for Standalone Webhooks:

      • Create, read, update, delete standalone webhooks
      • Manage webhooks independent of collections
      • Useful for external integrations and scheduled tasks

    • Webhook Manager Service:

      • Dedicated service for webhook lifecycle management
      • Centralized webhook execution logic
      • Consistent behavior across all webhook sources

    • Webhook Registry in Database:

      • New webhooks table stores webhook configurations
      • Fields: name, url, method, headers, body, retryLimit, jwtEnabled, active
      • Persistent storage survives server restarts

    Cron Job Integration

    • Unified Webhook Execution:

      • Cron HTTP callbacks now use webhook service
      • Same retry logic and logging as collection webhooks
      • Consistent experience across all webhook types

    • Enhanced Cron Configuration:

      • Configure retry limit for HTTP cron jobs
      • Enable JWT auth for authenticated HTTP callbacks
      • Custom headers for request authentication
      • Request body for POST/PUT/PATCH methods

    • One-Time Execution:

      • New once flag for cron jobs
      • When once: true, job is automatically deleted after successful execution
      • Perfect for scheduled one-time tasks or delayed execution
      • Works with both SQL and HTTP cron jobs

    • Cron Job Updates:

      • New PATCH /api/cron/:name endpoint for updating existing cron jobs
      • Update schedule, command, and once flag without recreating the job
      • Cron scheduler automatically reloads updated job configuration
      • Frontend edit modal reuses the create form with pre-populated data

    Docker Enhancements

    • Standalone Docker Image:

      • New Docker image with embedded web UI (vski:standalone)
      • Multi-stage build process using denoland/deno:2.6.6 official image
      • Web frontend built and embedded during Docker build
      • No need to build web frontend separately

    • Docker Build Automation:

      • New docker-build-standalone make target for building standalone image
      • New docker-push-standalone make target for pushing standalone image
      • Automatic copying of web source from ../web/ before build
      • Versioned and latest tags automatically applied

    • Release Process Integration:

      • Both light and standalone images built and pushed during release
      • Consistent tagging across image variants ({VERSION}, latest)
      • Automated via release.ts script

    Frontend Enhancements

    • Updated Cron Settings UI:

      • Retry limit configuration (1-100, default 5)
      • JWT auth toggle for HTTP jobs
      • Custom headers input (JSON format)
      • Request body configuration
      • "Delete after successful execution" (once) checkbox

    • Webhooks Manager Page (/settings/webhooks):

      • List all standalone webhooks
      • Create/edit/delete webhooks
      • Manual webhook trigger for testing
      • Status indicators (active/inactive)

    Client SDK Updates

    • Enhanced Trigger Config Types:

      • retryLimit: number (optional)
      • jwtEnabled: boolean (optional)
      • method: string (optional)
      • headers: Record<string, string> (optional)

    • New Webhook Types:

      • Webhook: Standalone webhook configuration
      • CreateWebhookRequest: Input for creating webhooks
      • UpdateWebhookRequest: Input for updating webhooks

    • Webhooks Namespace:

      • sdk.webhooks.list(): List all webhooks
      • sdk.webhooks.get(id): Get webhook by ID
      • sdk.webhooks.create(data): Create new webhook
      • sdk.webhooks.update(id, data): Update webhook
        -sdk.webhooks.delete(id)`: Delete webhook
      • sdk.webhooks.trigger(id): Manually trigger webhook

    Backend API Endpoints

    • Standalone Webhook Management:

      • GET /api/webhooks - List all webhooks
      • GET /api/webhooks/:id - Get webhook details
      • POST /api/webhooks - Create webhook
      • PUT/PATCH /api/webhooks/:id - Update webhook
      • DELETE /api/webhooks/:id - Delete webhook
      • POST /api/webhooks/:id/trigger - Manually trigger webhook

    • Cron Job Management:

      • GET /api/cron - List all cron jobs
      • POST /api/cron - Create new cron job
      • PATCH /api/cron/:name - Update existing cron job
      • DELETE /api/cron/:name - Delete cron job

    • JWT Token Generation:

      • New GenerateTokenWithRoles(id, roles, tokenKey) method
      • Supports custom role claims (e.g., ["service", "webhook"])
      • Used by webhook service for authenticated requests

    Database Schema Changes

    • New webhooks Table:

      CREATE TABLE webhooks (
  id TEXT PRIMARY KEY,
  name TEXT UNIQUE NOT NULL,
  url TEXT NOT NULL,
  method TEXT DEFAULT 'POST',
  headers TEXT,
  body TEXT,
  retryLimit INTEGER DEFAULT 5,
  jwtEnabled BOOLEAN DEFAULT 0,
  active BOOLEAN DEFAULT 1,
  created TEXT DEFAULT (datetime('now')),
  updated TEXT DEFAULT (datetime('now'))
);

    • Updated cron_jobs Table:

      ALTER TABLE cron_jobs ADD COLUMN once BOOLEAN DEFAULT FALSE;
      • Added once column for one-time execution flag
      • Default value is false (recurring jobs)

    Installation

    Binary

    Download binary for your platform:

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

# Linux (API-only)
wget https://git.vski.sh/x/platform/releases/download/v0.2.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.2.0
docker pull git.vski.sh/x/vski:v0.2.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

# Run with custom environment variables
docker run -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  -e SERVER_PORT=3000 \
  -e DATA_DIR=/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

    Configuring Collection Triggers with Enhanced Options

    await client.settings.collections.update(collectionId, {
  options: JSON.stringify({
    triggers: [
      {
        action: "create",
        url: "https://your-endpoint.com/webhook",
        method: "POST",
        headers: {
          "Authorization": "Bearer token",
          "X-Custom-Header": "value"
        },
        retryLimit: 5,        // Maximum retry attempts
        jwtEnabled: true       // Include JWT bearer token
      }
    ]
  })
});

    Creating Standalone Webhooks

    // Create a new webhook
const webhook = await client.webhooks.create({
  name: "notification-service",
  url: "https://api.example.com/notify",
  method: "POST",
  headers: JSON.stringify({
    "Authorization": "Bearer your-token",
    "X-Source": "rocketbase"
  }),
  body: JSON.stringify({
    "message": "Hello from webhook"
  }),
  retryLimit: 3,
  jwtEnabled: true,
  active: true
});

// List all webhooks
const webhooks = await client.webhooks.list();

// Update a webhook
await client.webhooks.update(webhook.id, {
  retryLimit: 10,
  active: false
});

// Delete a webhook
await client.webhooks.delete(webhook.id);

// Manually trigger a webhook for testing
await client.webhooks.trigger(webhook.id);

    Configuring Cron Jobs with Webhook Options

    // Create HTTP cron job with retry and JWT
await client.cron.create({
  name: "daily_report",
  schedule: "0 9 * * *",      // 9 AM daily
  type: "http",
  url: "https://api.example.com/reports/daily",
  method: "POST",
  body: '{"report_type": "daily"}',
  headers: JSON.stringify({
    "X-Report-Auth": "secret-key"
  }),
  retryLimit: 5,
  jwtEnabled: true
});

// Create one-time cron job (deletes after successful execution)
await client.cron.create({
  name: "send_welcome_email",
  schedule: "*/5 * * * *",     // Run in 5 minutes
  type: "http",
  url: "https://api.example.com/send-email",
  method: "POST",
  body: JSON.stringify({
    "to": "user@example.com",
    "template": "welcome"
  }),
  once: true                   // Delete after execution
});

// Update an existing cron job
await client.cron.update("daily_report", {
  schedule: "0 8 * * *",       // Change schedule to 8 AM
  retryLimit: 10,              // Increase retry limit
  jwtEnabled: true             // Enable JWT authentication
});

    Webhook Retry Behavior

    Webhooks now retry with exponential backoff:

    Attempt Delay Description
    1 0s Initial attempt
    2 2s First retry
    3 4s Second retry
    4 8s Third retry
    5 16s Fourth retry
    6 32s Fifth retry (if limit 5)

    After exceeding retryLimit, webhook status is set to failed.

    JWT Token Format

    When jwtEnabled: true, webhooks include a JWT bearer token:

    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5c2VzdmUzIiwid2ViZCIsInR5c2VyX3dlYmhvb2siLCJleHAiOjE3OTY1MzY5MywiaWF0IjoxNzA4NDM2NjkzfQ.abc123...

    Token claims:

    {
  "id": "webhook-service",
  "roles": ["service", "webhook"],
  "tokenKey": "webhook-token",
  "exp": 1739843693
}

    Querying Webhook Logs

    // Filter by collection and status
const logs = await client.webhookLogs.list({
  collection: "posts",
  status: "success"
});

// Logs include retry information
const log = logs[0];
console.log(`Tries: ${log.tries} / ${log.retryLimit || 5}`);
console.log(`Status: ${log.status}`);

    Migration Notes

    Database Migration

    The webhooks table is automatically created on server startup. No manual migration required.

    Breaking Changes

    None. This release is fully backward compatible.

    Configuration Updates

    Existing webhook configurations will continue to work with default values:

    • retryLimit: Defaults to 5 if not specified
    • jwtEnabled: Defaults to false if not specified
    • method: Defaults to POST if not specified

    API Endpoints

    Standalone Webhooks

    Method Endpoint Description
    GET /api/webhooks List all webhooks
    GET /api/webhooks/:id Get webhook by ID
    POST /api/webhooks Create new webhook
    PUT /api/webhooks/:id Update webhook
    PATCH /api/webhooks/:id Partially update webhook
    DELETE /api/webhooks/:id Delete webhook
    POST /api/webhooks/:id/trigger Manually trigger webhook

    Webhook Logs

    Method Endpoint Query Params Description
    GET /api/webhooks/logs collection, status, page, perPage Query webhook delivery logs

    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

    Documentation

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

    Changelog

    v0.2.0 (2026-02-17)

    Added

    • Retry limit configuration (1-100, default 5)
    • Exponential backoff retry mechanism (2^n seconds)
    • JWT authentication for webhooks with service,webhook roles
    • Standalone webhook CRUD API and management UI
    • Cron HTTP job integration with webhook service
    • Webhook Manager Service for unified webhook handling
    • Webhooks client namespace for SDK
    • One-time execution flag (once) for cron jobs
    • Automatic deletion of cron jobs with once: true after successful execution
    • Cron job update API (PATCH /api/cron/:name) for modifying existing jobs
    • Cron job edit UI in frontend with pre-populated form data
    • Docker standalone image with embedded web UI (vski:standalone)
    • Multi-stage Docker build process for standalone version
    • Docker build automation targets (docker-build-standalone, docker-push-standalone)

    Changed

    • Cron HTTP jobs now use webhook service instead of direct HTTP calls
    • Enhanced retry logic from fixed 5 attempts to configurable limit
    • Retry delay increased from 5s to 2s initial with exponential growth
    • Docker build process now supports both light and standalone variants

    Fixed

    • Webhook state now persists across server restarts
    • Consistent logging for all webhook types (triggers, cron, standalone)
    Downloads