@gravito/zenith 0.1.0-beta.1

package/docker-compose.yml

@@ -0,0 +1,40 @@
+version: '3.8'
+
+services:
+  # Main Persistence for Archive
+  mysql:
+    image: mysql:8.0
+    container_name: flux-mysql
+    ports:
+      - "3306:3306"
+    environment:
+      MYSQL_ROOT_PASSWORD: root
+      MYSQL_DATABASE: flux
+    healthcheck:
+      test: [ "CMD", "mysqladmin", "ping", "-h", "localhost" ]
+      timeout: 20s
+      retries: 10
+
+  # Real-time state store
+  redis:
+    image: redis:7-alpine
+    container_name: flux-redis
+    ports:
+      - "6379:6379"
+  # Flux Console (Optional: run locally via npm dev instead)
+  # console:
+  #   build: .
+  #   ports:
+  #     - "3000:3000"
+  #   environment:
+  #     - REDIS_URL=redis://redis:6379
+  #     - DB_DRIVER=mysql
+  #     - DB_HOST=mysql
+  #     - DB_USER=root
+  #     - DB_PASSWORD=root
+  #     - DB_NAME=flux
+  #   depends_on:
+  #     mysql:
+  #       condition: service_healthy
+  #     redis:
+  #       condition: service_started

package/docs/integrations/LARAVEL.md

@@ -0,0 +1,207 @@
+# Laravel Integration Guide for Gravito Zenith
+
+This guide outlines the architecture and implementation details for integrating Laravel applications with **Gravito Zenith**, enabling centralized monitoring, logging, and auditing for Laravel Queues.
+
+## Architecture Overview
+
++----------------+       +--------------+       +----------------+
+| Laravel App    |       | Redis Broker |       | Gravito Zenith |
+| (Horizon/Queue)| ----> | (Shared)     | <---- | Control Plane  |
++----------------+       +--------------+       +----------------+
+        |                       ^
+        |                       | Redis Pub/Sub & Lists
+        +--- [Zenith Connector] +
+
+The **Zenith Connector** acts as a bridge, translating Laravel's internal queue events into the Zenith Protocol.
+
+---
+
+## 1. Protocol Specification
+
+To be visible in Zenith, the Laravel connector must implement the following Redis interactions:
+
+### Namespace
+Default Prefix: `flux:` (configurable). Ensure this matches your Zenith configuration.
+
+### A. Worker Heartbeat (Process Discovery)
+The connector must run a background process (or scheduled command) to announce the worker's presence.
+
+- **Key**: `flux_console:worker:<worker-id>`
+- **TTL**: 60 seconds (refresh every 30s)
+- **Format**:
+```json
+{
+  "id": "laravel-worker-supervisor-1",
+  "hostname": "app-server-01",
+  "pid": 1234,
+  "uptime": 3600,
+  "queues": ["default", "emails"],
+  "concurrency": 10,
+  "memory": {
+    "rss": "100MB",
+    "heapTotal": "N/A",
+    "heapUsed": "N/A"
+  },
+  "timestamp": "ISO-8601 String"
+}
+```
+
+### B. Real-time Logs (Event Stream)
+The connector listens to Laravel Queue events and publishes them to Zenith.
+
+- **Channel**: `flux_console:logs`
+- **Format**:
+```json
+{
+  "level": "info",    // info | warn | error | success
+  "message": "Processing Job: App\\Jobs\\SendWelcomeEmail",
+  "workerId": "laravel-worker-supervisor-1",
+  "queue": "emails",
+  "timestamp": "ISO-8601 String",
+  "jobId": "uuid-..."  // Optional, enables specific tracing
+}
+```
+
+### C. Job Auditing (Time Travel)
+(Optional) For "Time Travel Audit" features, the connector should write to the persistent store if configured, or rely on Zenith's Redis scanning if utilizing standard Flux queue structures. Since Laravel uses its own queue structure, **Real-time Logs** are the primary integration point for v1.
+
+---
+
+## 2. Implementation Blueprint (PHP)
+
+This section provides the reference implementation for the `gravito/zenith-laravel` composer package.
+
+### Service Provider: `ZenithServiceProvider.php`
+
+This provider hooks into Laravel's Queue events.
+
+```php
+<?php
+
+namespace Gravito\Zenith\Laravel;
+
+use Illuminate\Support\ServiceProvider;
+use Illuminate\Support\Facades\Queue;
+use Illuminate\Support\Facades\Redis;
+use Illuminate\Queue\Events\JobProcessing;
+use Illuminate\Queue\Events\JobProcessed;
+use Illuminate\Queue\Events\JobFailed;
+
+class ZenithServiceProvider extends ServiceProvider
+{
+    public function boot()
+    {
+        // 1. Job Started
+        Queue::before(function (JobProcessing $event) {
+            $this->publishLog('info', $event);
+        });
+
+        // 2. Job Success
+        Queue::after(function (JobProcessed $event) {
+             $this->publishLog('success', $event);
+        });
+
+        // 3. Job Failed
+        Queue::failing(function (JobFailed $event) {
+             $this->publishLog('error', $event, $event->exception->getMessage());
+        });
+    }
+
+    protected function publishLog($level, $event, $extraMessage = '')
+    {
+        $payload = $event->job->payload();
+        $jobName = $payload['displayName'] ?? 'Unknown Job';
+        
+        // Simplify Job Name (remove namespace for display)
+        $shortName = class_basename($jobName);
+
+        $message = match($level) {
+            'info' => "Processing {$shortName}",
+            'success' => "Completed {$shortName}",
+            'error' => "Failed {$shortName}: {$extraMessage}",
+        };
+
+        $log = [
+            'level' => $level,
+            'message' => $message,
+            'workerId' => gethostname() . '-' . getmypid(), // Simple ID generation
+            'queue' => $event->job->getQueue(),
+            'timestamp' => now()->toIso8601String(),
+            'jobId' => $event->job->getJobId()
+        ];
+
+        // Fire and forget to Redis
+        try {
+            Redis::connection('zenith')->publish('flux_console:logs', json_encode($log));
+        } catch (\Exception $e) {
+            // Silently fail to not disrupt main application
+        }
+    }
+}
+```
+
+### Heartbeat Command: `zenith:heartbeat`
+
+This command should be run as a daemon (Supervisor) or scheduled every minute (less precise). For best results, run as a sidecar process.
+
+```php
+<?php
+
+namespace Gravito\Zenith\Laravel\Console;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Redis;
+
+class ZenithHeartbeat extends Command
+{
+    protected $signature = 'zenith:heartbeat';
+    protected $description = 'Send heartbeat to Gravito Zenith';
+
+    public function handle()
+    {
+        $this->info('Starting Zenith Heartbeat...');
+
+        while (true) {
+            $workerId = gethostname() . '-' . getmypid();
+            
+            $payload = [
+                'id' => $workerId,
+                'hostname' => gethostname(),
+                'pid' => getmypid(),
+                'uptime' => 0, // Calculate real uptime if needed
+                'queues' => config('queue.connections.redis.queue', ['default']),
+                'memory' => [
+                    'rss' => round(memory_get_usage() / 1024 / 1024, 2) . ' MB',
+                    'heapUsed' => 'N/A',
+                    'heapTotal' => 'N/A'
+                ],
+                'timestamp' => now()->toIso8601String()
+            ];
+
+            Redis::connection('zenith')->setex(
+                "flux_console:worker:{$workerId}",
+                30, // 30s TTL
+                json_encode($payload)
+            );
+
+            sleep(5);
+        }
+    }
+}
+```
+
+## 3. Configuration
+
+Users will need to configure a dedicated Redis connection for Zenith in `config/database.php` to avoid prefix collisions if they modify their default Redis prefix.
+
+```php
+'redis' => [
+    'zenith' => [
+        'host' => env('ZENITH_REDIS_HOST', '127.0.0.1'),
+        'password' => env('ZENITH_REDIS_PASSWORD', null),
+        'port' => env('ZENITH_REDIS_PORT', '6379'),
+        'database' => env('ZENITH_REDIS_DB', '0'),
+        'prefix' => '', // Ensure no prefix or match Zenith's expectation
+    ],
+],
+```

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@gravito/zenith",
+    "version": "0.1.0-beta.1",
+    "description": "Gravito Zenith: Zero-config control plane for Gravito Flux & Stream",
+    "type": "module",
+    "bin": {
+        "zenith": "./dist/bin.js",
+        "flux-console": "./dist/bin.js"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "scripts": {
+        "dev:server": "bun run --watch src/server/index.ts",
+        "dev:client": "vite",
+        "build": "vite build && bun build ./src/server/index.ts ./src/bin.ts --outdir ./dist --target bun",
+        "start": "bun ./dist/bin.js",
+        "test": "bun test",
+        "seed": "bun scripts/seed.ts",
+        "worker": "bun scripts/worker.ts"
+    },
+    "dependencies": {
+        "@gravito/atlas": "workspace:*",
+        "@gravito/photon": "workspace:*",
+        "@gravito/stream": "workspace:*",
+        "@tanstack/react-query": "^5.0.0",
+        "clsx": "^2.1.1",
+        "date-fns": "^4.1.0",
+        "framer-motion": "^12.23.26",
+        "ioredis": "^5.0.0",
+        "lucide-react": "^0.562.0",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0",
+        "react-router-dom": "^7.11.0",
+        "recharts": "^3.6.0",
+        "tailwind-merge": "^3.4.0"
+    },
+    "devDependencies": {
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "@vitejs/plugin-react": "^5.1.2",
+        "autoprefixer": "^10.4.0",
+        "postcss": "^8.4.0",
+        "tailwindcss": "^3.4.0",
+        "typescript": "^5.0.0",
+        "vite": "^6.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+    plugins: {
+        tailwindcss: {},
+        autoprefixer: {},
+    },
+}

package/scripts/flood-logs.ts

@@ -0,0 +1,21 @@
+import { QueueService } from '../src/server/services/QueueService'
+
+const svc = new QueueService(process.env.REDIS_URL || 'redis://localhost:6379')
+await svc.connect()
+
+console.log('🌊 Flooding 500 logs in burst...')
+const start = Date.now()
+const promises = []
+for (let i = 0; i < 500; i++) {
+  promises.push(
+    svc.publishLog({
+      level: 'info',
+      message: `Flood log ${i} - ${Date.now()}`,
+      workerId: 'flood-bot',
+      queue: 'test-flood',
+    })
+  )
+}
+await Promise.all(promises)
+console.log(`✅ Sent 500 logs in ${Date.now() - start}ms`)
+process.exit(0)

package/scripts/seed.ts

@@ -0,0 +1,213 @@
+#!/usr/bin/env bun
+import { Job, QueueManager } from '@gravito/stream'
+import Redis from 'ioredis'
+
+/**
+ * Flux Console Unified Seed Script
+ *
+ * Usage:
+ *   bun scripts/seed.ts [mode]
+ *
+ * Modes:
+ *   standard  - Small set of diverse jobs (Waiting, Delayed, Failed)
+ *   stress    - Many queues and many jobs for performance testing
+ *   batch     - Setup for batch operation testing (100+ jobs)
+ *   cron      - Register recurring schedules
+ *   cleanup   - Flush Redis and clear logs
+ */
+
+const mode = process.argv[2] || 'standard'
+const redis = new Redis('redis://localhost:6379')
+const prefix = 'queue:'
+
+// Simple Job class for testing
+class GenericJob extends Job {
+  constructor(
+    id: any = null,
+    public data: any = {}
+  ) {
+    super()
+    this.id = id
+  }
+  async handle() {}
+}
+
+const manager = new QueueManager({
+  default: 'redis',
+  connections: {
+    redis: {
+      driver: 'redis',
+      client: redis,
+      prefix,
+    },
+  },
+})
+
+manager.registerJobClasses([GenericJob])
+
+async function cleanup() {
+  console.log('🧹 Cleaning up Redis...')
+  const keys = await redis.keys(`${prefix}*`)
+  const internalKeys = await redis.keys('flux_console:*')
+  const allKeys = [...keys, ...internalKeys]
+
+  if (allKeys.length > 0) {
+    await redis.del(...allKeys)
+  }
+  console.log(`✅ Removed ${allKeys.length} keys.`)
+}
+
+async function seedStandard() {
+  console.log('🚀 Seeding standard data...')
+
+  // Orders Queue
+  for (let i = 1; i <= 5; i++) {
+    const job = new GenericJob(`ORD-${1000 + i}`, { amount: Math.random() * 100 })
+    job.queueName = 'orders'
+    await manager.push(job)
+  }
+
+  // Failed Jobs
+  for (let i = 1; i <= 3; i++) {
+    const jobInstance = new GenericJob(`FAIL-${i}`, { error: 'Payment Timeout' })
+    jobInstance.queueName = 'orders'
+    const serialized = manager.getSerializer().serialize(jobInstance)
+
+    await redis.lpush(
+      `${prefix}orders:failed`,
+      JSON.stringify({
+        ...serialized,
+        status: 'failed',
+        failedReason: 'Payment Timeout',
+        failedAt: Date.now(),
+      })
+    )
+  }
+
+  // Delayed Jobs
+  for (let i = 1; i <= 3; i++) {
+    const job = new GenericJob(`DLY-${i}`, { type: 'reminder' })
+    job.queueName = 'notifications'
+    job.delay(3600 * 1000) // 1 hour
+    await manager.push(job)
+  }
+}
+
+async function seedStress() {
+  console.log('🔥 Stress Mode: Creating 15 queues with jobs...')
+  const queues = [
+    'billing',
+    'shipping',
+    'inventory',
+    'marketing',
+    'crm',
+    'auth',
+    'logs',
+    'backups',
+    'indexing',
+    'cache',
+    'sync',
+    'webhooks',
+    'api',
+    'metrics',
+    'events',
+  ]
+
+  for (const q of queues) {
+    const count = 10 + Math.floor(Math.random() * 40)
+    for (let i = 0; i < count; i++) {
+      const job = new GenericJob(`JOB-${q}-${i}`, { timestamp: Date.now() })
+      job.queueName = q
+      await manager.push(job)
+    }
+    console.log(`  - ${q}: ${count} jobs`)
+  }
+}
+
+async function seedBatch() {
+  console.log('📦 Batch Mode: Setting up specialized data for batch testing...')
+
+  // 100 Waiting jobs
+  for (let i = 1; i <= 100; i++) {
+    const job = new GenericJob(`BATCH-WAIT-${i}`)
+    job.queueName = 'test-batch'
+    await manager.push(job)
+  }
+
+  // 50 Failed jobs
+  for (let i = 1; i <= 50; i++) {
+    const jobInstance = new GenericJob(`BATCH-FAIL-${i}`, { error: 'Database Connection Lost' })
+    jobInstance.queueName = 'test-batch-fail'
+    const serialized = manager.getSerializer().serialize(jobInstance)
+
+    await redis.lpush(
+      `${prefix}test-batch-fail:failed`,
+      JSON.stringify({
+        ...serialized,
+        status: 'failed',
+        attempts: 3,
+        failedAt: Date.now(),
+      })
+    )
+  }
+}
+
+async function seedCron() {
+  console.log('⏰ Cron Mode: Registering recurring schedules...')
+  const scheduler = manager.getScheduler()
+  const serializer = manager.getSerializer()
+
+  const rawSchedules = [
+    { id: 'cleanup-tmp', cron: '*/1 * * * *', queue: 'system', name: 'CleanupTmp' },
+    { id: 'daily-report', cron: '0 0 * * *', queue: 'reports', name: 'DailyReport' },
+    { id: 'health-check', cron: '*/5 * * * *', queue: 'monitoring', name: 'HealthCheck' },
+    { id: 'high-frequency', cron: '*/1 * * * *', queue: 'fast', name: 'Pulse' },
+  ]
+
+  for (const s of rawSchedules) {
+    const jobInstance = new GenericJob(s.id, { task: s.name })
+    jobInstance.queueName = s.queue
+    const serialized = serializer.serialize(jobInstance)
+
+    await scheduler.register({
+      id: s.id,
+      cron: s.cron,
+      queue: s.queue,
+      job: serialized,
+    })
+    console.log(`  - Registered: ${s.id} (${s.cron})`)
+  }
+}
+
+async function main() {
+  try {
+    if (mode === 'cleanup') {
+      await cleanup()
+    } else if (mode === 'standard') {
+      await cleanup()
+      await seedStandard()
+    } else if (mode === 'stress') {
+      await seedStress()
+    } else if (mode === 'batch') {
+      await seedBatch()
+    } else if (mode === 'cron') {
+      await seedCron()
+    } else if (mode === 'all') {
+      await cleanup()
+      await seedStandard()
+      await seedStress()
+      await seedBatch()
+      await seedCron()
+    } else {
+      console.log('❌ Unknown mode. Try: standard, stress, batch, cron, cleanup, all')
+    }
+  } catch (err) {
+    console.error('💥 Error:', err)
+  } finally {
+    redis.disconnect()
+    console.log('\n🏁 Done.')
+    process.exit(0)
+  }
+}
+
+main()

package/scripts/verify-throttle.ts

@@ -0,0 +1,45 @@
+console.log('🎧 Connecting to log stream...')
+const req = await fetch('http://localhost:3000/api/logs/stream')
+if (!req.body) throw new Error('No body')
+
+const reader = req.body.getReader()
+const decoder = new TextDecoder()
+
+let logCount = 0
+const start = Date.now()
+
+// Count for 2 seconds
+const DURATION = 2000
+
+console.log(`⏳ Measuring received logs for ${DURATION}ms...`)
+
+async function readStream() {
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+
+    const chunk = decoder.decode(value)
+    // SSE format: event: log\ndata: ...\n\n
+    const matches = chunk.match(/event: log/g)
+    if (matches) {
+      logCount += matches.length
+    }
+
+    if (Date.now() - start > DURATION) {
+      break
+    }
+  }
+
+  console.log(`📊 Result: Received ${logCount} logs in ${(Date.now() - start) / 1000}s`)
+  console.log(`ℹ️  Expected max: ~50-60 logs (50/sec limit + potential buffer/history)`)
+
+  if (logCount > 150) {
+    console.error('❌ Throttling FAILED! Too many logs received.')
+    process.exit(1)
+  } else {
+    console.log('✅ Throttling PASSED!')
+    process.exit(0)
+  }
+}
+
+readStream()