README

MatchBox App Server Example

This example demonstrates the routed MatchBox app server API built around web.server() and ColdBox-style handlers:

function( event, rc, prc ) { ... }

App-server scripts should import the namespace explicitly:

import boxlang.web;

It is a different product from the static/BXM webroot server. Use this app server when you want to build:

• JSON APIs
• lightweight microservices
• middleware pipelines
• signed webhook receivers
• server-rendered endpoints with explicit template rendering
• apps that need explicit static asset mounts inside a routed server

This example is for the native server runtime. ESP32 builds currently support only the lean routed direction and reject heavier features like app.listen(), templates, static asset mounts, webhooks, cookies, and sessions at compile time.

For a websocket-focused example, see websocket_counter.

Project Structure

• app.bxs: Main routed application.
• public/site.css: Static asset served through app middleware.
• views/home.bxm: Template rendered by event.setView().

Key Concepts

1. The Handler Shape

Each route handler receives three arguments:

• event: A native request/response object with ColdBox-style helpers.
• rc: The public request collection. Route params, query params, form fields, and top-level JSON object keys are merged here.
• prc: The private request collection for passing internal state across middleware and handlers.

2. Middleware

Middleware uses a fourth next argument:

app.use( function( event, rc, prc, next ) {
    prc.requestStarted = true;
    next.run();
} );

Middleware can mutate rc, prc, session, headers, cookies, status codes, and response bodies.

3. Templates

Routes can render templates explicitly:

event.setView( "views/home.bxm", {
    "title": "MatchBox"
} );

Templates receive:

• event
• rc
• prc
• session
• viewArgs

4. Static Files Middleware

Static assets can be mounted explicitly inside the app server:

app.use( app.middleware.buildStaticFiles( "/assets", "public" ) );

This serves files from the public directory at /assets/.... The directory is resolved relative to the app script root, missing files fall through to the normal app routing path, and traversal outside the mounted directory is blocked.

5. Webhook Builder

Webhook endpoints can be declared with a fluent builder:

app.webhook(
    app.buildWebhook()
        .path( "/webhooks/stripe" )
        .secret( env.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" );
    }
);

Running the Example

From the project root:

cargo run -p matchbox_server -- --app docs/examples/app_server/app.bxs

Then visit:

• http://localhost:8090/
• http://localhost:8090/api/hello/MatchBox
• http://localhost:8090/assets/site.css

What The Example Covers

• app-level middleware
• route groups
• cookies
• in-memory session state
• JSON responses
• static asset serving with app.middleware.buildStaticFiles()
• template rendering with setView()
• signed webhook route registration
• for websockets, see the dedicated websocket counter example