🛠️ Valkey Sandbox Developer Guide

Where distributed computing meets rubber ducks 🦆

🎯 Current Status

Core Components

✅ Frontend (Vue.js 3 with WebSocket)
✅ Backend (Node.js with Express)
✅ Code Execution System (Docker-based)
✅ Real-time Updates (WebSocket)
🟡 Testing Framework (Help wanted!)
🟡 Documentation System (Work in progress)

Language Support

✅ Node.js (Valkey-glide, iovalkey)
✅ Python (Valkey-glide, valkey-py)
🟨 Java (Compilation support coming soon)
🟨 Go (Runtime integration planned)

Features

✅ Monaco Code Editor
✅ Real-time Code Execution
✅ Task Manager Demo
✅ Leaderboard Demo
✅ Code Templates (Python, Node.js, Java)
🟡 Challenge System (Under construction)
🟡 Documentation Browser (Needs love)

🏗️ Architecture

[Frontend 8080] ←→ [Backend 3000] ←→ [Valkey Services]
      ↓               ↓                ↑
Vue.js + Monaco   Node.js + Express    |
WebSocket Client  WebSocket Server     |
                      ↓               |
                Docker Executors ─────┘
                (Python/Node.js)

🚀 Quick Start

Clone & Setup:

git clone https://github.com/avifenesh/valkey-sandbox.git
cd valkey-sandbox
./setup.sh --dev  # For development
# or
./setup.sh        # For production

Access:

Frontend: http://localhost:8080
Backend: http://localhost:3000
Valkey Standalone: localhost:6379
Valkey Cluster: localhost:7000-7005

💻 Code Execution

System Overview

Docker-based isolated environments with resource limits
Multi-language support (Python/Node.js)
Real-time output streaming
Security pattern analysis

Language Examples

Python with Valkey-glide

from valkey_glide import GlideClient

# Connect to Valkey
client = GlideClient(host='valkey-standalone', port=6379)

# Basic operations
await client.set('key', 'value')
result = await client.get('key')
print(f"Retrieved: {result}")

# Example response
{
  'output': 'Retrieved: value\n',
  'error': None,
  'execution_time': 0.001,
  'memory_used': 8192
}

Node.js with Valkey-glide

import { GlideClient } from '@valkey/valkey-glide';

// Connect to Valkey
const client = await GlideClient.createClient({
  host: 'valkey-standalone',
  port: 6379
});

// Basic operations
await client.set('key', 'value');
const result = await client.get('key');
console.log('Retrieved:', result);

// Example response
{
  output: "Retrieved: value\n",
  error: null,
  executionTime: 0.001,
  memoryUsed: 15925248
}

📡 Communication & Security

WebSocket Protocol

// Execute code
{
  action: 'runCode',
  data: {
    language: 'python|javascript',
    code: string,
    mode: 'standalone|cluster'
  }
}

// Task management
{
  action: 'startTasks',
  data: { tasks: Task[] }
}

Security Features

// Resource limits
{
  memory: "128mb",
  cpu: "5s",
  fileSize: "1mb",
  processes: 5
}

// Forbidden patterns
const forbidden = [
  "process.env",
  'require("child_process")',
  'import("child_process")',
  "eval",
  "Function",
];

🚀 Frontend Performance

1. Core Features

Lazy loading & code splitting
WebSocket optimizations
Virtual scrolling
Service worker caching
Memory caching
State management

2. Implementation Examples

// Lazy loading with code splitting
const routes = [
  {
    path: '/playground',
    component: () => import('@/views/Playground.vue')
  }
];

// WebSocket message batching
const wsManager = {
  queuedMessages: [],
  retryDelay: 5000,
  maxRetries: 5,
  
  sendBatch() {
    if (this.queuedMessages.length) {
      this.ws.send(JSON.stringify(this.queuedMessages));
      this.queuedMessages = [];
    }
  }
};

🎨 Vue Components Architecture

Core Components

Watch-in-Action Components

// Key visualization components for real-time demos
components/
├── watch/
│   ├── WatchContainer.vue       # Main container for watch-in-action demos
│   ├── ActionSelect.vue         # Demo selection interface
│   ├── visualizations/
│   │   ├── LeaderboardVisualization.vue    # Real-time sorted sets demo
│   │   └── TaskManagerVisualization.vue     # Distributed locks & queues demo
│   └── components/
       ├── WatchEditor.vue       # Specialized code editor for demos
       └── WatchTerminal.vue     # Real-time output terminal

Editor Components

// Base editor components with Monaco integration
components/
├── base/
│   ├── BaseEditor.vue          # Monaco editor wrapper
│   └── BaseTerminal.vue        # Xterm.js terminal wrapper
└── Editor.vue                  # Main editor component with language support

Layout Components

// Core layout and navigation components
components/layout/
├── Sidebar.vue                # Main navigation sidebar
├── TopTabs.vue               # Tab-based navigation
└── LoadingOverlay.vue        # Loading states & transitions

Key Features

Real-time Visualization

// WatchContainer.vue
const wsManager = useWebSocket();
const terminalInstance = ref(null);

// Handles real-time updates
const messageHandler = (event) => {
  switch (event.action) {
    case "taskUpdate":
      handleTaskUpdate(event.payload);
      break;
    case "leaderboardUpdate":
      handleLeaderboardUpdate(event.payload);
      break;
  }
};

Code Editor Integration

// BaseEditor.vue
const editorOptions = {
  fontFamily: "JetBrains Mono",
  fontSize: 14,
  minimap: { enabled: false },
  automaticLayout: true,
  scrollBeyondLastLine: false
};

WebSocket Communication

// Example from WatchVisualization
const handleActionSelect = async ({ action, client }) => {
  wsManager.send({
    action: "init",
    component: action,
    client: client
  });
  // Handle response in messageHandler
};

State Management

// Store integration example
const state = reactive({
  currentClient: savedState.currentClient,
  executionMode: savedState.executionMode,
  currentTab: getTabFromHash(),
  watchState: null
});

Component Communication

Event Bus Pattern

const eventBus = {
  on: (event, callback) => { /* ... */ },
  emit: (event, data) => { /* ... */ },
  off: (event, callback) => { /* ... */ }
};

Props & Events

<!-- Parent-child communication -->
<WatchVisualization
  :ws="wsInstance"
  :isConnected="isConnected"
  @terminal-write="handleTerminalWrite"
/>

Dependency Injection

// Provide at app level
provide('wsManager', wsManager);
provide('eventBus', eventBus);

// Inject in components
const wsManager = inject('wsManager');
const eventBus = inject('eventBus');

Performance Optimizations

Lazy Loading

const DocComponents = {
  GeneralConcepts: defineAsyncComponent(() => 
    import('./content/GeneralConcepts.vue')
  ),
  CommandsReference: defineAsyncComponent(() => 
    import('./content/CommandsReference.vue')
  )
};

Virtual Scrolling

<virtual-scroller
  :items="commandList"
  :item-height="40"
  v-slot="{ item }"
>
  <command-item :command="item" />
</virtual-scroller>

Debounced Updates

const debouncedUpdate = debounce((value) => {
  store.saveState(value);
}, 300);

🔧 Development Setup

Using Setup Script

The setup.sh script provides additional options:

./setup.sh --dev   # Development mode with hot-reloading
./setup.sh         # Production mode
./setup.sh --cleanup  # Clean up all running processes
./setup.sh --log  # Enable logging
./setup.sh --rebuild  # Rebuild Docker images
./setup.sh --reinstall  # Reinstall dependencies

Features:

Automatic dependency checking
Service health monitoring
Development/Production environment setup
Clean process management
Logging configuration

Manual Setup

Frontend Development:

cd frontend
npm install
npm run serve

Backend Development:

cd backend
npm install
npm run dev

Docker Development

Modify docker-compose.yml for development:

Use volume mounts for hot reloading
Enable debug ports
Set environment to development

🎯 Project Roadmap

Planned Improvements

Testing Infrastructure
- Jest for backend
- Vue Test Utils for frontend
- Cypress for E2E tests
- GitHub Actions CI/CD
Documentation
- OpenAPI/Swagger for REST endpoints
- WebSocket protocol documentation
- Example collection
Features
- Valkey cluster management UI
- Challenge system
- Template marketplace
Security
- Authentication system?
- Rate limiting
- Sandbox environment isolation
- Code analysis

Current Limitations

No test coverage
Limited error handling
Basic monitoring
Missing CI/CD pipeline

📝 Coding Standards

Use ESLint and Prettier for code formatting
Follow Vue.js style guide for frontend code
Write meaningful commit messages
Document new features and APIs

🔄 Workflow

Create feature branch from main
Implement changes
Write tests
Submit PR with description
Code review
Merge to main

📚 API Documentation

Backend Endpoints

POST /execute - Run code
GET /templates - Get code templates
WS /appws - WebSocket connection

Valkey Integration

Standalone mode: Direct connection
Cluster mode: Managed through proxy

🔍 Debugging

WebSocket Debugging

// Enable debug mode
const ws = new WebSocket("ws://localhost:8080/appws");
ws.onmessage = (e) => console.log("WS:", JSON.parse(e.data));

Docker Logs

# View specific service
docker-compose logs -f backend

# View all services
docker-compose logs -f

Resource Monitoring

# Check container stats
docker stats

# Monitor cluster
watch -n1 'docker-compose exec valkey-cluster valkey-cli -p 7000 cluster info'

Files

DEVELOPER.md

Latest commit

History

DEVELOPER.md

File metadata and controls

🛠️ Valkey Sandbox Developer Guide

🎯 Current Status

Core Components

Language Support

Features

🏗️ Architecture

🚀 Quick Start

💻 Code Execution

System Overview

Language Examples

Python with Valkey-glide

Node.js with Valkey-glide

📡 Communication & Security

WebSocket Protocol

Security Features

🚀 Frontend Performance

1. Core Features

2. Implementation Examples

🎨 Vue Components Architecture

Core Components

Watch-in-Action Components

Editor Components

Layout Components

Key Features

Component Communication

Performance Optimizations

🔧 Development Setup

Using Setup Script

Manual Setup

Docker Development

🎯 Project Roadmap

Planned Improvements

Current Limitations

📝 Coding Standards

🔄 Workflow

📚 API Documentation

Backend Endpoints

Valkey Integration

🔍 Debugging

WebSocket Debugging

Docker Logs

Resource Monitoring

📚 Additional Resources

API Documentation

Examples