# route-ops

**Repository Path**: mirrors_creationix/route-ops

## Basic Information

- **Project Name**: route-ops
- **Description**: JavaScript Builder API for Edge Routing
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-15
- **Last Updated**: 2026-05-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Route-Ops: JavaScript Builder API for Edge Routing

Write edge routing logic in JavaScript that compiles to compact bytecode for execution at the CDN edge.

## Why

Traditional CDN routing uses declarative JSON configs that are verbose, hard to maintain, and limited in expressiveness. This system lets you write **real JavaScript** that compiles to optimized bytecode.

**Key benefits:**

- Familiar JavaScript syntax with real functions, loops, and variables
- Type-safe with TypeScript support
- Powerful: multi-region execution, concurrent operations, advanced caching
- Efficient: compiles to compact bytecode embedded in `routes.json`

## How It Works

**Build time:** JavaScript runs once to build a computation graph → serializes to bytecode → embeds in `routes.json`

**Runtime:** Bytecode interpreter executes at the edge with stack-based middleware semantics

**Key concept:** Builder operations return `RuntimeValue<T>` - opaque handles representing future runtime values. JavaScript Proxy makes them feel natural (array access, destructuring, method calls all work).

## Example 1: Basic Routing

```javascript
// Simple path rewrite with conditional headers

const path = req.getPath()
const match = path.match(/^\/api\/(.+)$/)

when(match, ([apiPath]) => {
  req.setPath(str.concat('/v2/api/', apiPath))

  // Add headers conditionally
  const host = req.getHost()
  when(host.equals('dashboard.example.com'), () => {
    res.setHeader('X-Robots-Tag', 'noindex')
  })

  next()  // Continue to next layer
})
```

**What's happening:**

- Pattern matching with regex (capture groups work via destructuring)
- String operations use builder methods (`str.concat()` instead of `+`)
- Conditional logic uses `when()` instead of `if` (captures in graph)
- `next()` continues to inner middleware layers (stack-based execution)

## Example 2: Static Shell + Dynamic Content

```javascript
// Send static shell immediately, then append dynamic content

// Fetch static shell from CDN
const shell = static.fetch('/shell.html')

// Start streaming response
stream.begin(200, {'Content-Type': 'text/html'})
stream.write(shell)

// Compute dynamic content at origin (blocking)
const dynamic = compute.call('renderContent', req.getPath(), 'origin')

// Append to response
stream.write(dynamic)
stream.end()
```

**What's happening:**

- `static.fetch()` loads pre-built assets from CDN
- `stream.begin()` starts response immediately (fast TTFB)
- `compute.call()` executes serverless function at origin region
- Operations block by default - no promises/async complexity
- Response is streamed progressively to client

## Example 3: Multi-Region Stale-While-Revalidate

```javascript
// Sophisticated caching across edge → shield → origin with helper function

const path = req.getPath()

// Start with edge, fallback through shield to origin
checkCacheTier('edge', 'shield', 'origin')

// Helper: check cache tier with hit/stale/miss handling
function checkCacheTier(region, ...upstreamRegions) {
  const cached = cache.getDetailed(path, region)

  when(cached, ({ body, isStale }) => {
    // Hit - serve immediately
    pipe(body).toResponse()

    // If stale, revalidate in background
    when(isStale(), () => spawn(() => {
      revalidate(...upstreamRegions)
    }))
  })
  .otherwise(() => {
    // Miss - check next tier or render
    if (upstreamRegions.length > 0) {
      const [next, ...rest] = upstreamRegions
      checkCacheTier(next, ...rest)
    } else {
      // No more tiers - render fresh
      const fresh = compute.call('render', path, 'origin')

      // Backfill all cache tiers
      pipe(fresh)
        .toCache(path, 60, 'origin')
        .toCache(path, 60, 'shield')
        .toCache(path, 60, 'edge')
        .toResponse()
    }
  })
}

function revalidate(...regions) {
  const fresh = compute.call('render', path, 'origin')

  // Update all specified regions
  let p = pipe(fresh).toCache(path, 60, 'origin')
  for (const region of regions) {
    p = p.toCache(path, 60, region)
  }
}

```

**What's happening:**

- **Helper function** factors out hit/stale/miss logic for any cache tier
- **Recursive fallback:** edge miss → shield, shield miss → origin, origin miss → render
- **Stale-while-revalidate:** On stale hit, serve immediately + revalidate in background
- **Build-time helpers:** Regular JS functions at build time compose builder operations
- Each tier handles 3 cases (hit, stale, miss) with the same reusable logic

## Key Features

**RuntimeValue Proxy Magic:**

```javascript
// Array access and destructuring work naturally
const [user, recs] = joinAll([userThread, recsThread])
const apiPath = groups[0]

// Property access via Proxy
const { body, isStale } = cacheDetails

// Method calls build graph nodes
path.equals('/api')
path.startsWith('/admin')
```

**Concurrent Execution:**

```javascript
// Spawn parallel threads
const userThread = spawn(() => compute.call('getUser', userId, 'origin'))
const recsThread = spawn(() => cache.get('recs:' + userId, 'shield'))

// Join results
const [user, recs] = join(userThread, recsThread)
```

**Stack-Based Middleware:**

```javascript
// Measure request duration
const before = time.now()
next()  // Run inner layers
const after = time.now()
res.setHeader('X-Duration', str.concat(after - before, 'ms'))
```

## Technical Notes

- **Build-time vs Runtime:** Your script runs once at build time with normal JS control flow. The builder captures operations as bytecode nodes.
- **No JavaScript operators on RuntimeValue:** Can't use `===`, `+`, etc. on runtime values (use `.equals()`, `str.concat()` instead)
- **Blocking by default:** Operations like `compute.call()` and `http.fetch()` block until complete. Use `spawn()` for concurrency.
- **No promises at bytecode level:** We have threads you can `join()`, not promises. Much simpler mental model.

## Bytecode Output

The builder generates compact bytecode that:

- Embeds as a string in `routes.json`
- Supports random access execution (byte offsets for jumps)
- Includes all semantics: concurrency, multi-region, streaming, middleware stack
- Executes efficiently at the edge with minimal overhead

**Flow:**

1. Developer writes `routes.js` using builder API
2. Build tool executes script to construct computation graph
3. Graph serializes to bytecode string
4. Bytecode embeds in `routes.json`
5. Edge servers parse and execute bytecode per request