muxpress

muxpress

import "github.com/szkiba/muxpress"

Package muxpress provides Express.js like micro web framework for goja.

Features

Easy integration was the main design goal. Major features:

- Express.js like JavaScript API

- Context-aware implementation

- Event loop ready, tested with goja_nodejs and k6 event loop

- Also works without event loop

package main

import (
	"fmt"
	"github.com/dop251/goja"
	req "github.com/imroc/req/v3"
	"github.com/szkiba/muxpress"
)

func main() {
	const SCRIPT = `
	const app = new Application()

	app.get("/", (req, res) => {
		res.text("Hello World!")
	})

	app.listen(3000)
  `
	runtime := goja.New()
	ctor, _ := muxpress.NewApplicationConstructor(runtime)

	runtime.Set("Application", ctor)

	runtime.RunScript("example", SCRIPT)

	message := req.MustGet("http://127.0.0.1:3000").String()

	fmt.Println(message)

}

Hello World!

package main

import (
	"context"
	"fmt"
	"github.com/dop251/goja"
	req "github.com/imroc/req/v3"
	"github.com/sirupsen/logrus"
	"github.com/szkiba/muxpress"
)

func main() {
	const SCRIPT = `
	const app = new Application()

	app.get("/", (req, res) => {
		res.text("Hello World!")
	})

	app.listen(3000)
	`
	runtime := goja.New()
	ctor, _ := muxpress.NewApplicationConstructor(
		runtime,
		muxpress.WithContext(context.TODO),
		muxpress.WithLogger(logrus.StandardLogger().WithField("example", "hello")),
	)

	runtime.Set("Application", ctor)

	message := req.MustGet("http://127.0.0.1:3000").String()

	fmt.Println(message)

}

Hello World!

package main

import (
	"fmt"
	"github.com/dop251/goja"
	req "github.com/imroc/req/v3"
	"github.com/szkiba/muxpress"
)

func main() {
	const SCRIPT = `
	const app = new Application()

	app.get("/", (req, res) => {
		res.text("Hello World!")
	})

	app.listen()

	app.port // goja runtime returns the last evaluated expression
  `
	runtime := goja.New()
	ctor, _ := muxpress.NewApplicationConstructor(runtime)

	runtime.Set("Application", ctor)

	port, _ := runtime.RunScript("example", SCRIPT)
	location := fmt.Sprintf("http://127.0.0.1:%d", port.ToInteger())

	message := req.MustGet(location).String()

	fmt.Println(message)

}

Hello World!

API

Variables

Declarations holds TypeScript declaration file contents for muxpress types.

var Declarations []byte

func NewApplicationConstructor

func NewApplicationConstructor(runtime *goja.Runtime, option ...Option) (func(call goja.ConstructorCall) *goja.Object, error)

NewApplicationConstructor creates an application constructor function. The returned constructor function is ready for use and assignable to any name in a given [goja.Runtime]. This allow to decide the name of the JavaScript constructor. You can pass [Option] parameters to customize the muxpress runtime behavior.

package main

import (
	"fmt"
	"github.com/dop251/goja"
	req "github.com/imroc/req/v3"
	"github.com/szkiba/muxpress"
)

func main() {
	const SCRIPT = `
	const app = new WebApp()

	app.get("/", (req, res) => {
			res.text("Hello World!")
	})

	app.listen()

	app.port // goja runtime returns the last evaluated expression
`

	runtime := goja.New()

	ctor, err := muxpress.NewApplicationConstructor(runtime)
	if err != nil {
		panic(err)
	}

	err = runtime.Set("WebApp", ctor)
	if err != nil {
		panic(err)
	}

	port, err := runtime.RunScript("example", SCRIPT)
	if err != nil {
		panic(err)
	}

	message := req.MustGet("http://localhost:" + port.String())

	fmt.Println(message)

}

Hello World!

package main

import (
	"context"
	"github.com/dop251/goja"
	"github.com/szkiba/muxpress"
	"time"
)

func main() {
	runtime := goja.New()

	ctx, cancel := context.WithTimeout(context.TODO(), time.Second)
	defer cancel()

	getContext := func() context.Context { return ctx }

	ctor, err := muxpress.NewApplicationConstructor(runtime, muxpress.WithContext(getContext))
	if err != nil {
		panic(err)
	}

	err = runtime.Set("WebApp", ctor)
	if err != nil {
		panic(err)
	}

}

package main

import (
	"github.com/dop251/goja"
	"github.com/sirupsen/logrus"
	"github.com/szkiba/muxpress"
)

func main() {
	runtime := goja.New()

	logger := logrus.StandardLogger().WithField("source", "script")

	ctor, err := muxpress.NewApplicationConstructor(runtime, muxpress.WithLogger(logger))
	if err != nil {
		panic(err)
	}

	err = runtime.Set("WebApp", ctor)
	if err != nil {
		panic(err)
	}

}

type Option

Option is an option for the [NewApplicationConstructor] factory function.

type Option = func(*options)

func WithContext

func WithContext(context func() context.Context) Option

WithContext returns an Option that specifies a [context.Context] getter function to be used for stopping application when context is canceled or done. Default is to use [context.TODO].

func WithFS

func WithFS(filesystem afero.Fs) Option

WithFS returns an Option that specifies a [afero.Fs] filesystem to be used for accessing static files.

func WithLogger

func WithLogger(logger logrus.FieldLogger) Option

WithLogger returns an Option that specifies a [logrus.FieldLogger] logger to be used for logging.

func WithRunOnLoop

func WithRunOnLoop(runOnLoop func(func(*goja.Runtime))) Option

WithRunOnLoop returns an Option that specifies [RunOnLoop] function from [goja_nodejs] package to be used for execute middlewares for incoming requests.

[RunOnLoop]: https://pkg.go.dev/github.com/dop251/goja_nodejs/eventloop#EventLoop.RunOnLoop [goja_nodejs]: https://github.com/dop251/goja_nodejs

func WithRunner

func WithRunner(runner RunnerFunc) Option

WithRunner returns an Option that specifies a runner function to be used for execute middlewares for incoming requests. This option allows you to schedule middleware calls in the event loop.

Since [goja.Runtime] is not goroutine-safe, the default is to execute middlewares in synchronous way.

func syncRunner() RunnerFunc {
  var mu sync.Mutex

  return func(fn func() error) {
    mu.Lock()
    defer mu.Unlock()

    if err := fn(); err != nil {
      panic(err)
    }
  }
}

type RunnerFunc

RunnerFunc is used to execute middlewares on incoming requests.

type RunnerFunc func(func() error)

JavaScript API

muxpress is an Express.js like micro web framework for goja.

Class: Application

An application object represents a web application.

The following example starts a server and listens for connections on port 3000. The application responds with a JSON object for requests to the root URL. All other routes are answered with a 404 not found message.

In this example, the name of the constructor is Application, but the name you use is up to you.

Example

const app = new Application()

app.get('/', (req, res) => {
  res.json({message:"Hello World!"})
})

app.listen(3000)

Constructors

constructor

• new Application()

Creates a new application instance.

index.d.ts:40

Methods

delete

▸ delete(path, ...middleware): void

Routes HTTP DELETE requests to the specified path with the specified middleware functions.

You can provide multiple middleware functions.

void

index.d.ts:100

get

▸ get(path, ...middleware): void

Routes HTTP GET requests to the specified path with the specified middleware functions.

You can provide multiple middleware functions.

void

index.d.ts:50

head

▸ head(path, ...middleware): void

Routes HTTP HEAD requests to the specified path with the specified middleware functions.

You can provide multiple middleware functions.

void

index.d.ts:60

listen

▸ listen(addr?, callback?): void

Starts the server.

void

The instance for fluent/chaining API

index.d.ts:135

options

▸ options(path, ...middleware): void

Routes HTTP OPTIONS requests to the specified path with the specified middleware functions.

You can provide multiple middleware functions.

void

index.d.ts:110

patch

▸ patch(path, ...middleware): void

Routes HTTP PATCH requests to the specified path with the specified middleware functions.

You can provide multiple middleware functions.

void

index.d.ts:90

post

▸ post(path, ...middleware): void

Routes HTTP POST requests to the specified path with the specified middleware functions.

You can provide multiple middleware functions.

void

index.d.ts:70

put

▸ put(path, ...middleware): void

Routes HTTP PUT requests to the specified path with the specified middleware functions.

You can provide multiple middleware functions.

void

index.d.ts:80

static

▸ static(path, docroot): void

Mount static web content from given source directory.

void

index.d.ts:126

use

▸ use(path, ...middleware): void

Uses the specified middleware function or functions.

void

index.d.ts:118

Interface: Request

The req object represents the HTTP request and has properties for the request query string, parameters, body, HTTP headers, and so on.

In this documentation and by convention, the object is always referred to as req (and the HTTP response is res) but its actual name is determined by the parameters to the callback function in which you’re working.

Example

app.get("/user/:id", function (req, res) {
  res.send("user " + req.params.id);
});

Properties

body

• body: Record<string, any>

Contains key-value pairs of data submitted in the request body. By default, it is undefined, and is populated when the request Content-Type is application/json.

index.d.ts:155

cookies

• cookies: Record<string, string>

This property is an object that contains cookies sent by the request.

index.d.ts:160

get

• get: (field: string) => string

▸ (field): string

Returns the specified HTTP request header field (case-insensitive match).

string

the header field value.

index.d.ts:207

header

• header: (field: string) => string

▸ (field): string

Returns the specified HTTP request header field (case-insensitive match).

string

the header field value.

index.d.ts:215

method

• method: string

Contains a string corresponding to the HTTP method of the request: GET, POST, PUT, and so on.

index.d.ts:165

params

• params: Record<string, string>

This property is an object containing properties mapped to the named route parameters. For example, if you have the route /user/:name, then the “name” property is available as req.params.name. This object defaults to empty.

index.d.ts:172

path

• path: string

Contains the path part of the request URL.

index.d.ts:177

protocol

• protocol: string

Contains the request protocol string: either http or (for TLS requests) https.

index.d.ts:182

query

• query: Record<string, any>

This property is an object containing a property for each query string parameter in the route.

For example:

// GET /search?q=tobi+ferret
console.dir(req.query.q);
// => 'tobi ferret'

// GET /shoes?color=blue&color=black&color=red
console.dir(req.query.color);
// => ['blue', 'black', 'red']

index.d.ts:199

Interface: Response

The res object represents the HTTP response that a server sends when it gets an HTTP request.

In this documentation and by convention, the object is always referred to as res (and the HTTP request is req) but its actual name is determined by the parameters to the callback function in which you’re working.

Example

app.get("/user/:id", function (req, res) {
  res.send("user " + req.params.id);
});

Properties

append

• append: (field: string, value: string) => Response

▸ (field, value): Response

Appends the specified value to the HTTP response header field. If the header is not already set, it creates the header with the specified value.

Response

index.d.ts:235

binary

• binary: (body: string | number[] | ArrayBuffer) => Response

▸ (body): Response

Sends a binray response. This method sends a response (with the "application/octet-stream" content-type) that is the body paramter.

Response

index.d.ts:263

html

• html: (body: string) => Response

▸ (body): Response

Sends a HTML text response. This method sends a response (with the correct content-type) that is the body string paramter.

Response

index.d.ts:256

json

• json: (body: Record<string, any>) => Response

▸ (body): Response

Sends a JSON response. This method sends a response (with the correct content-type) that is the parameter converted to a JSON string.

Response

index.d.ts:242

redirect

• redirect: (code: number, loc: string) => Response

▸ (code, loc): Response

Redirects to the URL, with specified status, a positive integer that corresponds to an HTTP status code.

Response

index.d.ts:311

send

• send: (body: string | number[] | ArrayBuffer) => Response

▸ (body): Response

Sends the HTTP response.

When the parameter is a ArrayBuffer or number[], the method sets the Content-Type response header field to “application/octet-stream”. When the parameter is a String, the method sets the Content-Type to “text/html”. Otherwise the method sets the Content-Type to "application/json" and convert paramter to JSON representation before sending.

Response

index.d.ts:274

set

• set: (field: string, value: string) => Response

▸ (field, value): Response

Sets the response’s HTTP header field to value.

Response

index.d.ts:303

status

• status: (code: number) => Response

▸ (code): Response

Sets the HTTP status for the response.

Response

index.d.ts:281

text

• text: (format: string, v?: any[]) => Response

▸ (format, v?): Response

Sends a plain text response. This method sends a response (with the correct content-type) that is the string formatting result.

Response

index.d.ts:250

type

• type: (mime: string) => Response

▸ (mime): Response

Sets the Content-Type HTTP header to the MIME type as from mime parameter.

Params

mime the content type

Response

index.d.ts:288

vary

• vary: (header: string) => Response

▸ (header): Response

Adds the header field to the Vary response header.

Response

index.d.ts:295

Auxiliary

Classes

• Application

Interfaces

• Request
• Response

Type Aliases

Middleware

Ƭ Middleware: (req: Request, res: Response, next: () => void) => void

▸ (req, res, next): void

Middleware defines middleware and request handler callback function.

void

index.d.ts:16