FlowState Server

A Deno web server that executes QuickJS code using the FetchFlow library with automatic pause/resume functionality for fetch calls.

Features

• ✅ Task Execution - Execute QuickJS code via REST API
• ✅ Automatic Pause/Resume - Automatically pauses on fetch() calls
• ✅ External HTTP Processing - Handles HTTP requests externally
• ✅ Flat File Storage - Persists task state in local JSON files
• ✅ Auto-Restart Logic - Automatically resumes tasks after fetch completion
• ✅ Multiple Fetch Cycles - Supports recursive pause/resume for multiple fetches

Quick Start

# Start the server
deno task start

# Or with custom port
PORT=3000 deno task start

API Endpoints

POST /task

Start a new task with QuickJS code.

Request:

{
  "id": "my-task-1",
  "name": "My Task",
  "code": "let result = await fetch('https://api.example.com/data'); result.json();"
}

Response:

{
  "success": true,
  "task": {
    "id": "my-task-1",
    "name": "My Task",
    "status": "paused",
    "pauseCount": 1,
    "fetchRequest": {
      "id": "fetch_1234567890_1",
      "url": "https://api.example.com/data"
    }
  }
}

POST /call

Resume a paused task with fetch response (usually called automatically).

Request:

{
  "taskId": "my-task-1",
  "fetchResponse": {
    "id": "fetch_1234567890_1",
    "success": true,
    "status": 200,
    "statusText": "OK",
    "data": {"result": "data"}
  }
}

GET /status

Get task status.

Single task: /status?id=my-task-1 All tasks: /status

How It Works

1. Submit Code - Send QuickJS code to /task endpoint
2. Automatic Pause - When code calls fetch(), execution pauses
3. External Processing - Server processes HTTP request externally
4. Auto-Resume - Server automatically calls /call to resume execution
5. Recursive Handling - If resumed code makes more fetch calls, cycle repeats
6. State Persistence - All state saved in ./states/ directory

Example Usage

Basic Task

curl -X POST http://localhost:8080/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "hello-world",
    "code": "console.log(\"Hello World\"); \"completed\""
  }'

Task with Fetch

curl -X POST http://localhost:8080/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "api-call",
    "code": "const response = await fetch(\"https://jsonplaceholder.typicode.com/posts/1\"); const data = await response.json(); data.title;"
  }'

Check Status

curl http://localhost:8080/status?id=api-call

List All Tasks

curl http://localhost:8080/status

File Structure

flowstate/
├── server.ts           # Main server implementation
├── deno.json          # Deno configuration
├── README.md          # This file
├── tasks/             # Task definitions (future use)
└── states/            # Task state persistence
    ├── task-1.json    # Task state files
    └── task-2.json

Environment Variables

• PORT - Server port (default: 8080)
• CALL_ENDPOINT - Call endpoint URL (default: http://localhost:8080/call)

Integration with FetchFlow

FlowState Server uses the FetchFlow library to:

• Execute QuickJS code in isolated contexts
• Automatically detect and pause on fetch() calls
• Serialize complete VM state for persistence
• Resume execution with external fetch responses
• Handle multiple fetch cycles recursively

This creates a powerful serverless-like environment where long-running JavaScript code can be paused, persisted, and resumed across different execution contexts.

Use Cases

• Serverless Functions - Long-running tasks that survive restarts
• Web Scraping - Handle rate limiting with automatic pausing
• API Orchestration - Complex multi-step API workflows
• Data Processing - Pausable ETL pipelines
• Workflow Automation - Step-by-step business processes
• Testing - Automated testing with external dependencies

Development

# Start with auto-reload
deno task dev

# Manual start
deno run --allow-read --allow-write --allow-net --allow-env server.ts