Run JavaScript as http.Server middleware

  • By
  • Last update: Mar 24, 2023
  • Comments: 2

😅 Heresy

GoDoc FOSSA Status

What is it?

noun, /ˈher.ə.si/

(the act of having) an opinion or belief that is the opposite of
    or against what is the official or popular opinion,
    or an action that shows that you have no respect for the official opinion.

Heresy is a pure Go runtime that lets you:

  1. Embed the runtime and run JavaScript as middleware for http.Server in either Express.js style, or Web Worker FetchEvent style;
    • The handler script can be reloaded on-the-fly!
  2. Run the runtime as a reverse proxy to some backend services, with the power of JavaScript as scripting language to intercept requests;
  3. Or spin up the runtime as a standalone server to run JavaScript application, with the power of Go.

What is it not?

  1. It is not a secure/isolated runtime to run untrusted user code;
  2. It is not a sandbox similar to v8::Isolate.


Express.js style

function httpHandler({ req, res, next }) {
    if (req.path === "/") {
    } else {
        res.status(403).send({error: 'access denied'})


FetchEvent style

async function eventHandler(event) {
    if (event.request.method === "POST") {
        event.respondWith(new Response(event.request.body, {
            headers: event.request.headers
    // to the next handler in http.Server


With network access

async function httpHandler({ res, fetch }) {
    const resp = await fetch("")
    res.send(await resp.text())

registerExpressHandler(httpHandler, {
    fetch: true

// ... similarly in FetchEvent
// async function eventHandler(event) {
//     const { fetch } = event
//     const resp = await fetch("")
//     event.respondWith(resp)
// }

// registerEventHandler(eventHandler, {
//     fetch: true
// })

Supported ECMAScript Features

The JavaScript runtime is provided by goja. Currently it supports most features up to ES2018, with the notable exceptions of:

  1. async iterator (async function* foo() and for await...of);
  2. SharedArrayBuffer;
  3. ES2015 modules (import foo from 'bar', please use a bundler that outputs UMD or CJS).

The recommended transpile target is ES2017. However, if you run into problems, ES6 can be used as a fallback.

Runtime Features Matrix

Supported Features via Polyfill
TextEncoder/TextDecoder (UTF-8 Only)
Web Streams API (ReadableStream, etc), backed by io.Reader/io.Writer
Fetch API (Headers, Request, Response)
Component Status req/request resp/respondWith next
Express.js WIP Partial implementations
(see request_context_request.go)
Partial implementations
(see request_context_response.go)
FetchEvent Implemented* Works Works Works
Fetch API Implemented

*: Even though ECMAScript is single-threaded in nature, heresy runtime manages data access and IOs asynchronously. Therefore, once your event handler returns, it should not call any methods from FetchEvent.

The following usage will result in a race and crash the runtime:

function eventHandler(evt) {
    // ...
    evt.respondWith(/* ... */)
    setTimeout(() => {
        evt.fetch(/* ... */)
    }, 100)
    // evt.fetch will be called after your handler returns!

Use .waitUntil instead:

function eventHandler(evt) {
    // ...
    evt.respondWith(/* ... */)
    evt.waitUntil((async () => {
        // e.g. send request metrics
        await evt.fetch(/* ... */)
        await evt.fetch(/* ... */)

The first rule still applies if you use .waitUntil incorrectly. The following usage will also crash the runtime:

function eventHandler(evt) {
    // ...
    evt.respondWith(/* ... */)
    setTimeout(() => {
        evt.waitUntil((async () => {
            await evt.fetch(/* ... */)
    }, 100)
    // evt.waitUntil will be called after your handler returns!

TODO: Complete this README


FOSSA Status



  • 1

    Add license scan report and status

    Your FOSSA integration was successful! Attached in this PR is a badge and license report to track scan status in your README.

    Below are docs for integrating FOSSA license checks into your CI:

  • 2

    performance focus refactoring

    ext/common/x: use custom object pool implementation to keep runtime objects long-lived, as VM objects allocations are serialized

    ext/common/shared: lazy initialization of header properties ext/fetch: lazy initialization of response properties express: lazy initialization of all properties/methods event: lazy initialization of all properties/methods

    ext/stream: create new ReadableStream instead of reusing as ReadableStream is not reusable in JavaScript

    ext/promise: use async/await for resolver to improve VM allocations behavior under high concurrent requests

    js: use BYOBReader when draining ReadableStream

    cmd/example: move examples into separate folders

    transpile: remove go-typescript due to GPL-3 incompatibility

    README: updated to be more explicit about intended usage and supported ECMAScript features