Web server

MatchBox has two web runtimes. Both are implemented in the matchbox_server crate and run on the same VM as the CLI.

Webroot server

matchbox --serve --webroot ./site --port 8080

matchbox --serve accepts only these three flags and reads boxlang.json from the webroot. The --config <file> flag exists only on the matchbox_server binary, which you build from the MatchBox source tree with cargo build --release -p matchbox_server.

On startup the server prints the address, the resolved webroot and whether rewrites are enabled. Files are read on every request, so edits appear without a restart.

What gets served

HEAD returns the headers of the GET response with an empty body. A template that throws returns 500 with the error text.

Scopes in templates

All values are strings. Session values are stored as strings between requests, so a number or struct you assign comes back as its string form on the next request. Sessions have no expiry and are lost when the process stops.

To read an environment variable use getSystemSetting( "NAME", "default" ). There is no env scope.

boxlang.json

Place boxlang.json in the webroot. All keys are optional.

{
  "rewrites": true,
  "rewriteFileName": "index.bxm",
  "websocket": {
    "uri": "/ws",
    "listenerClass": "Chat",
    "listenerState": { "greeting": "hello" },
    "handler": "WebSocket.bx"
  }
}

If boxlang.json is not valid JSON, or a websocket block is missing one of uri, listenerClass or listenerState, the whole file is ignored without a warning and the defaults apply. Check the "Rewrites:" line printed at startup.

Give each directory an index template; directory requests do not fall back to the rewrite file.

WebSockets in the webroot server

The websocket block names a class and the file that defines it.

class Chat {
    function onConnect( channel ) {
        channel.sendJson( { "welcome": variables.greeting, "id": channel.getId() } );
    }

    function onMessage( message, channel ) {
        channel.broadcastMessage( "echo:" & message );
    }

    function onClose( channel ) {}
}

If the handler file is missing or does not compile, the server starts without a WebSocket endpoint. An error thrown in onConnect or onMessage is printed on the server's stderr and closes that connection with code 1011.

WebSocket channel API

The same channel object is passed to listeners in both server modes.

Listener hooks are onConnect( channel ), onMessage( message, channel ) and onClose( channel ). message is a string for text frames and bytes for binary frames. The channel has no properties: channel.id is null, use getId().

App server

The app server runs one script that builds a routed application with web.server(). It is started with the --app flag of the matchbox_server binary:

cargo run -p matchbox_server -- --app app.bxs

matchbox app.bxs cannot run such a script: the CLI does not install the web namespace, and web.server() fails with Method server not found on null. In --app mode the --port, --host, --webroot and --config flags are ignored; the address comes from app.listen().

import boxlang.web;

app = web.server();

app.get( "/hello/:name", function( event, rc, prc ) {
    event.renderJson( { "message": "Hello " & rc.name } );
} );

app.listen( 8090 );

The script is compiled once at startup and is not reloaded when the file changes. Its top level runs at startup and then again on every request, in a fresh VM, so variables set at the top of the script do not carry over between requests. Keep shared state in session, a file or a database.

Application object

Routes:

• A path segment that starts with : captures that segment. There are no wildcards or regular expressions.
• A route matches only when the number of segments is equal. The first registered match wins.
• Only get, post, put, patch and delete can be registered. Other methods get 404.
• An unmatched request returns 404 with the text Not Found.

Middleware has the signature function( event, rc, prc, next ) and continues the chain with next.run(). Handlers have the signature function( event, rc, prc ).

Request collections

JSON bodies are parsed when Content-Type is JSON. The server does not limit the request body size.

The event object

renderJSON writes numbers as floating point, so 1 is serialized as 1.0.

Errors

If a handler throws, the response status comes from the start of the error message:

The body is the error text, or {"error": "..."} when the request sends Accept: application/json.

Webhooks

app.webhook(
    app.buildWebhook()
        .path( "/webhooks/stripe" )
        .secret( getSystemSetting( "STRIPE_SECRET" ) )
        .signatureHeader( "stripe-signature" )
        .prefix( "sha256=" )
        .timestampHeader( "stripe-timestamp" )
        .toleranceSeconds( 300 )
        .replayHeader( "stripe-event-id" )
        .replayTtlSeconds( 300 ),
    function( event, rc, prc ) {
        event.renderText( "ok" );
    }
);

A webhook is a POST route. The server computes an HMAC-SHA256 of the raw request body with the secret and compares its lowercase hex form with the signature header, after removing prefix if the header starts with it. A bare hex signature is also accepted.

A missing or wrong signature, a missing or stale timestamp, or a missing delivery id returns 401.

WebSockets in the app server

listener = new ClickCounterSocket();
listener.configure();
app.enableWebSockets( "/ws", listener );

The listener and the channel API are the same as in the webroot server, except that the listener is an instance you create and configure yourself. Its state is captured when enableWebSockets() is called and restored inside the WebSocket runtime.