Router lowering

Source e69e4b6f1381 · Published v1.0.0-beta.10

Uses the static Router authoring surface to define terminal middleware, route fallthrough, error handling, mounts, parameters, wildcards, and method-specific routes. Pulse lowers the flat Router execution graph into the same canonical native plan used by single-handler applications.

Code

Router application

import { Router } from '@pulse-compute/runtime'

interface User {
  id: number
  name: string
}

const users = new Router()
const api = new Router()
const app = new Router()

app.use(async (ctx, next) => {
  if (ctx.req.header('x-pulse-deny') === '1') {
    return ctx.json(
      { error: 'denied by middleware' },
      { status: 401 },
    )
  }
  return next()
})

api.use(async (ctx, next) => {
  if (ctx.req.header('x-api-state') === 'closed') {
    return ctx.text('api closed', { status: 503 })
  }
  return next()
})

users.get('/:id', async (ctx) => {
  const id = ctx.param('id')
  const user = await ctx
    .fetch('https://users.example.test/users/' + id)
    .json<User>()
  return ctx.json({ route: 'user', id, user })
})

api.get('/health', async (ctx, next) => {
  if (ctx.req.header('x-health-handler') === 'fallback') {
    return next()
  }
  return ctx.json({ ok: true, handler: 'primary' })
})
api.get('/health', async (ctx) => ctx.json({ ok: true, handler: 'fallback' }))
api.head('/health', async (ctx) => ctx.text('', {
  status: 204,
  headers: [['x-pulse-route', 'health']],
}))
api.post('/users', async (ctx) => ctx.json(
  { route: 'create', method: ctx.req.method },
  { status: 201 },
))
api.get('/files/*', async (ctx) => ctx.text(ctx.req.path))
api.get('/failure', async (ctx, next) => next('documented-failure'))

api.mount('/users', users)
app.mount('/api', api)

app.error(async (error, ctx, next) => {
  if (error === 'documented-failure') {
    return ctx.json({ error: 'handled' }, { status: 418 })
  }
  return next(error)
})

export default app

Project config

import { defineConfig } from '@pulse-compute/pulse'

export default defineConfig((_scope) => ({
  pulse: {
    entry: 'src/index.ts',
    tests: 'tests/pulse.harness.ts',
    defaultProfile: 'local',
    strict: true,
  },
  local: {
    host: 'node',
    target: 'native',
    outDir: 'dist',
    dev: {
      fetches: {
        'https://users.example.test/users/7': {
          value: { id: 7, name: 'Ada' },
        },
      },
    },
  },
}))

Request and response

Generated from the executable test harness below; these are tested requests or event frames, not an exhaustive application specification. Expected errors and emitted events are included; fixtures and provider setup remain in the harness.

Request	Expected response
mounted-health `GET /api/health`	`{"status":200,"json":{"ok":true,"handler":"primary"}}`
middleware-short-circuit `GET /api/health` Headers: `[["x-pulse-deny","1"]]`	`{"status":401,"json":{"error":"denied by middleware"}}`
scoped-middleware-short-circuit `GET /api/health` Headers: `[["x-api-state","closed"]]`	`{"status":503,"text":"api closed"}`
route-fallthrough `GET /api/health` Headers: `[["x-health-handler","fallback"]]`	`{"status":200,"json":{"ok":true,"handler":"fallback"}}`
error-middleware `GET /api/failure`	`{"status":418,"json":{"error":"handled"}}`
parameter-and-fetch `GET /api/users/7`	`{"status":200,"json":{"route":"user","id":"7","user":{"id":7,"name":"Ada"}}}`
method-specific-post `POST /api/users`	`{"status":201,"json":{"route":"create","method":"POST"}}`
trailing-wildcard `GET /api/files/guides/start`	`{"status":200,"text":"/api/files/guides/start"}`
default-not-found `GET /missing`	`{"status":404,"text":"Not Found"}`

Inspect

The selected profile is local; this checked excerpt identifies its target, provider and recognized capabilities. Paths, hashes and additional inspection fields are omitted.

npm run inspect -- --json

{
  "status": "ok",
  "project": {
    "target": "native"
  },
  "provider": {
    "id": "node"
  },
  "compiler": {
    "capabilities": [
      "fetch",
      "response.json",
      "response.text"
    ]
  }
}

Doctor

Check this project and its local toolchain before execution. This selected result is verified by the documentation gate; another machine may report different prerequisite checks.

npm run doctor -- --json

{
  "status": "passed",
  "summary": {
    "warnings": 0,
    "failed": 0
  }
}

Report

Build once into a separate directory, then replay the retained artifact without running or rebuilding the application. This checked excerpt accounts for registered handlers in the build evidence; it is not runtime request coverage.

npm run build -- --out .pulse-docs-build
npm exec -- pulse report --artifact .pulse-docs-build/pulse-build.json --json

{
  "kind": "pulse.application-report",
  "reportVersion": 1,
  "analytics": {
    "coverage": {
      "handlers": {
        "expected": 10,
        "observed": 10,
        "reason": null,
        "status": "complete"
      }
    }
  }
}

Optional offline HTML uses the same retained evidence:

npm exec -- pulse report --artifact .pulse-docs-build/pulse-build.json --html

Review reports before sharing. Missing, stale or incompatible evidence is an error; timings, paths and hashes are not presented as stable output.

Interactive report captured from this example at source e69e4b6f1381. Build evidence describes this captured build, not a runtime guarantee.

Open full report · Capture provenance

Workflow

pulse doctor
pulse inspect
pulse test
pulse dev
pulse compile
pulse build

The inspect result exposes Router execution entries and route/middleware ownership for effects and continuations. return next() terminates the current handler and advances dispatch; it never resumes.

pulse inspect --json

{
  "status": "ok",
  "provider": {
    "id": "node"
  },
  "compiler": {
    "authoring": {
      "kind": "router"
    },
    "routing": {
      "version": "pulse.router-authoring.v2",
      "routes": [
        {
          "method": "GET",
          "path": "/api/health"
        }
      ]
    },
    "effectCount": 1,
    "continuationCount": 1
  }
}

The documented test result below is also executed by the documentation gate.

Test result

pulse test --json

{
  "status": "passed",
  "provider": "node",
  "summary": {
    "total": 9,
    "passed": 9,
    "failed": 0
  },
  "cases": [
    {
      "name": "mounted-health",
      "status": "passed",
      "response": {
        "status": 200
      }
    }
  ]
}

Test harness

export default {
  cases: [
    {
      name: 'mounted-health',
      request: { method: 'GET', path: '/api/health' },
      expect: {
        status: 200,
        json: { ok: true, handler: 'primary' },
      },
    },
    {
      name: 'middleware-short-circuit',
      request: {
        method: 'GET',
        path: '/api/health',
        headers: { 'x-pulse-deny': '1' },
      },
      expect: {
        status: 401,
        json: { error: 'denied by middleware' },
      },
    },
    {
      name: 'scoped-middleware-short-circuit',
      request: {
        method: 'GET',
        path: '/api/health',
        headers: { 'x-api-state': 'closed' },
      },
      expect: { status: 503, text: 'api closed' },
    },
    {
      name: 'route-fallthrough',
      request: {
        method: 'GET',
        path: '/api/health',
        headers: { 'x-health-handler': 'fallback' },
      },
      expect: {
        status: 200,
        json: { ok: true, handler: 'fallback' },
      },
    },
    {
      name: 'error-middleware',
      request: { method: 'GET', path: '/api/failure' },
      expect: { status: 418, json: { error: 'handled' } },
    },
    {
      name: 'parameter-and-fetch',
      request: { method: 'GET', path: '/api/users/7' },
      fetches: {
        'https://users.example.test/users/7': {
          value: { id: 7, name: 'Ada' },
        },
      },
      expect: {
        status: 200,
        json: {
          route: 'user',
          id: '7',
          user: { id: 7, name: 'Ada' },
        },
      },
    },
    {
      name: 'method-specific-post',
      request: { method: 'POST', path: '/api/users' },
      expect: {
        status: 201,
        json: { route: 'create', method: 'POST' },
      },
    },
    {
      name: 'trailing-wildcard',
      request: {
        method: 'GET',
        path: '/api/files/guides/start',
      },
      expect: {
        status: 200,
        text: '/api/files/guides/start',
      },
    },
    {
      name: 'default-not-found',
      request: { method: 'GET', path: '/missing' },
      expect: { status: 404, text: 'Not Found' },
    },
  ],
}

Wasm size

For build settings, see Native build optimization.

Artifact	Default build
Portable guest `canonical-native.wasm`	7.2 KiB (7,407 bytes)

The executable documentation gate rebuilds and measures the default artifact. Measured with Node 24.18.0 and lockfile-pinned AssemblyScript 0.28.18. These are uncompressed on-disk sizes, not transfer sizes or platform limits. The artifact includes checks that transfer application data failures to the next error handler.