MALDA™ Reference Manual

The AI-First Programming Language - Version 1.0.11

Home / 25. HttpServer & HTML UI Generation

25. HttpServer & HTML UI Generation

This chapter covers MALDA's route-first web server, HTML page handlers, AI-generated page helpers, and HTML caching utilities. Use it when you want to serve pages with HttpServer and traditional request/response routes.

Start here: Read 23. Web UI Overview to compare UI models. This chapter focuses on HttpServer, @PAGE, @AIPAGE, and HTML generation helpers. For server components and ui.*, see Web UI Server Components. For API-first routes, see REST API Server.

25.1 Chapter Map

25.2 HttpServer Class

The HttpServer class provides a built-in HTTP server for static assets, server-generated HTML, AI-generated pages, form handling, and route handlers. It works well for route-first applications where each request returns a full document or a targeted response.

25.2.1 Constructor

var server = new HttpServer(port);
// OR
var server = new HttpServer(port, webDirectory);  // Custom web directory
// OR
var server = new HttpServer(port, webDirectory, pathBase, host);

port must be an integer in 1-65535. Privileged ports (1-1023, e.g. 80/443) are allowed; binding may still require elevated permissions or OS URL reservations.

Bind host defaults to localhost (loopback only). Pass host as the optional fourth argument, call setHost(host) before start(), or set the MALDA_HTTP_HOST environment variable. Use 0.0.0.0 or * to listen on all interfaces (same prefix rules as RestServer). The current bind host is available as the host property.

HTTPS is optional and cross-platform. Call enableHttps(certPath, password?) before start() with a .pfx/.p12 file, or a PEM .pem/.crt (private key beside it as .key). Environment alternatives: MALDA_HTTP_HTTPS=1, MALDA_HTTP_CERT, and optional MALDA_HTTP_CERT_PASSWORD. Properties: https, certPath. TLS is terminated by Kestrel; the existing request pipeline still runs on a loopback HttpListener.

25.2.2 Core methods

25.2.3 Minimal host example

var server = new HttpServer(8080);
server.start();

print("Server running at http://localhost:8080");

while (server.isRunning) {
    sleep(1000);
}

// HTTPS (optional):
// var tls = new HttpServer(8443);
// tls.setHost("0.0.0.0");
// tls.enableHttps("ask.pfx", "secret");
// tls.start();
// print("Server running at https://localhost:8443");

25.3 Request and Response Objects

Page and route handlers can receive request context and return either raw HTML or a structured response object.

When a route is API-style, framework failures return a standardized JSON payload with status, error, message, and correlationId, with optional details for validation failures.

25.4 Dynamic Pages with @PAGE

Use @PAGE for request-driven HTML pages. A page handler can return a full HTML document directly, and path parameters are bound from the URL.

@PAGE("/")
function handleHome() {
    return "<html><body><h1>Home</h1></body></html>";
}

@PAGE("/user/{id}")
function handleUser(id) {
    return "<html><body><h1>User: " + id + "</h1></body></html>";
}

Use @PAGE when the request should produce a complete page. If the page needs interactive fragments, live updates, or server-managed component state, move reusable UI into a component flow and keep the route as the entry point.

25.5 AI-Generated Pages with @AIPAGE

Use @AIPAGE when you want MALDA to generate the initial HTML based on a prompt-like description.

@AIPAGE("/", "Contact form with name, email, and message fields")
function homePage() {
    // AI generates the HTML automatically on first access
    return "";
}

25.5.1 Complete AI form example

var server = new HttpServer(8080);

@AIPAGE("/", "Contact form with name, email, and message fields")
function homePage() {
    return "";
}

@POST("/submit")
function handleSubmit(body) {
    print("Form submitted!");
    print("Name: " + body.name);
    print("Email: " + body.email);
    print("Message: " + body.message);

    return {
        "status": 200,
        "body": "<html><body><h1>Thank You!</h1><p>Your message has been received.</p><p><a href='/'>Back to form</a></p></body></html>"
    };
}

server.start();

25.6 GET/POST Routes in Page-Hosting Flows

HttpServer can host @GET and @POST routes alongside pages. That is useful for AJAX handlers, small JSON endpoints, or Server-Sent Events used by a page. For full API design guidance, advanced validation, and endpoint organization, use REST API Server as the primary reference.

25.6.1 GET handlers

@GET("/api/users")
function getUsers() {
    return {"status": 200, "users": ["Alice", "Bob", "Charlie"]};
}

@GET("/api/events")
function getEvents() {
    return {"sse": true};
}

25.6.2 POST handlers

@POST("/submit")
function handleSubmit(body) {
    print("Name: " + body.name);
    print("Email: " + body.email);
    return {
        "status": 200,
        "body": "<html><body><h1>Thank You!</h1></body></html>"
    };
}

25.7 Redirects with RedirectTo

Use redirect(location, status?) for explicit redirect responses, or the legacy alias RedirectTo(location) when migrating existing code.

@POST("/login")
function handleLogin(body) {
    if (body.username == "admin" && body.password == "secret") {
        return redirect("/dashboard");
    }
    return redirect("/login?error=invalid");
}

@PAGE("/old-page")
function oldPage() {
    return redirect("/new-page", 302);
}

For production HTML apps, prefer password hashing + JWT in a signed cookie instead of plaintext checks. See Examples/Web/auth_cookie_login.malda and the shared req.auth helpers (same surface as RestServer).

function requireAuth(req, res, next) {
    req.auth.authenticateCookieJwt("session", jwtSecret, cookieSecret);
    next();
}

server.use(requireAuth, { "except": ["/", "/login"] });

25.8 HTML Generation Helpers

MALDA includes helper utilities for generated HTML and server-rendered UI prototypes.

25.8.1 HTMLCache Class

The HTMLCache class stores generated HTML to reduce repeated LLM work and improve response times.

var cache = new HTMLCache(cacheDirectory?, maxSize?, expirationHours?);

25.8.2 extractHTML Function

extractHTML(markdown) extracts HTML from markdown code fences or returns HTML as-is.

var html = extractHTML(markdown);

25.8.3 markdownToHtml Function

markdownToHtml(markdown) converts Markdown to an HTML fragment (headings, emphasis, lists, tables, fenced code, and similar). Raw HTML tags in the input are disabled so untrusted model output is safer to embed in a page. Returns a string; wrap it in your own document chrome.

var body = markdownToHtml("**Hello** and a table:\n\n| A | B |\n|---|---|\n| 1 | 2 |");
return "<html><body class='md'>" + body + "</body></html>";

25.8.4 generateUI Function

generateUI is a convenience helper for prompt-driven HTML generation with optional caching and a custom agent.

var html = generateUI(description, cache?, agent?);

25.8.5 ui.generate Function

Use ui.generate when AI should return a structured server UI tree instead of an HTML string.

var tree = ui.generate("Dashboard with title, filter row, and data grid", uiAgent, cache);
var envelope = ui.mountEnvelope(tree, "dashboard-session");
return envelope;

25.9 Request-to-Render Lifecycle

  1. The browser requests a page or route handled by @PAGE, @AIPAGE, @GET, or @POST.
  2. HttpServer resolves the route and loads any required request context.
  3. The handler returns HTML, a redirect, JSON, SSE, or a generated UI artifact.
  4. The browser either renders the returned document, follows the redirect, or processes the API response.

25.10 Production Hardening

25.11 Testing and Troubleshooting

See Also

← Previous: 24. Web UI Server Components Next: 26. Browser JavaScript UI Backend→