The rampart-url module¶

What is in this section?¶

This section of the documentation is intended to document feature (supported or not) that do not neatly fit into other sections.

Loading the module.¶

The module can be loaded in the normal manner.

var wserv = require("rampart-webserver");

Standard Server Layout¶

Using the rampart-webserver module assumes a standard layout for static and dynamic web content. Refer to the example webserver for a view of the expected location of content and scripts.

Usage from a configuration file¶

The easiest method of starting the rampart webserver is to copy the example webserver https://github.com/aflin/rampart/tree/main/web_server directory and edit the settings found in the web_server_conf.js script.

After editing, the server can be used as follows:

rampart@machine:~>$ rampart /path/to/web_server/web_server_conf.js start
Server has been started.

rampart@machine:~>$ rampart /path/to/web_server/web_server_conf.js help
usage:
  rampart web_server_conf.js [start|stop|restart|letssetup|status|dump|help]
      start     -- start the http(s) server
      stop      -- stop the http(s) server
      restart   -- stop and restart the http(s) server
      letssetup -- start http only to allow letsencrypt verification
      status    -- show status of server processes
      dump      -- dump the config object used for server.start()
      help      -- show this message

The usable settings in web_server_conf.js include all the possible settings applicable to the server.start() function as well as extras to simplify the process and add extra functionality.

Notable extras:

• bindAll - Boolean, if true, bind the server to 0.0.0.0 and [::] ip addresses
• port - Number, use this value to set ipPort and ipv6Port.
• redirPort - Number, when launching a secure https server, also launch a http server using this port to redirect requests to the https server (assuming default port 443).
• redir - Boolean, if true, set redirPort to 80.
• rotateLogs - Boolean, if true, launch a monitor process to rotate the access and error log files at a given time. Default is false.
• rotateStart - String, the time to start rotating the logs. Default is 00:00 (for localtime, midnight).
• rotateInterval - Number, how often to rotate the logs. Default is 86400 (for every 24 hours). It may also be given as the Strings "hourly", "daily" or "weekly".
• letsencrypt - String, for secure serving, the directory where the letsencrypt certificates can be found. Set to "example.com would therefore look for certificates in the /etc/letsencrypt/live/example.com/ directory. See Use with Letsencrypt below.
• serverRoot - String, the root directory (e.g. "/path/to/my/web_server". Default is the current working directory.
• map - Object, replace the map and only use this Object to pass to the server.start() function.
• appendMap - Object, append default mappings passed to the server.start() function.
• monitor - Boolean, if true, launch a monitor process to continuously check that the server is running (every 10 seconds) and that the root index.html file can be reached (every 60 seconds). Default is false.
• stop - Boolean, if true, stop the server, along with the redirect server and monitor processes if either was launched.

Building a command line utility¶

To aid in starting a server from the command line without having to configure it from a JavaScript script, a small script such as the following can be used:

var wserv = require("rampart-webserver");
webserv.cmdLine(2);

The webserv.cmdLine(2); function will process options from command line arguments, starting with the second one (skipping argv[0] (rampart) and argv[1] (script_name.js). It will then launch a server using the processed options.

The same functionality is also available from the main rampart executable and can be used as such:

rampart@machine:~>$ rampart --server ~/web_server/
Server has been started.
rampart@machine:~>$ rampart --server --stop ~/web_server/
server stopped
rampart@machine:~>$ rampart --server --help
rampart built-in server help:

Usage: rampart --[quick]server [options] [root_dir]
    --server        - run as a full server
    --quickserver   - run as a test server
    --help, -h      - this help message
    --lsopts        - print details on all options
    --showdefaults  - print the list of default settings for --server or --quickserver
    --OPTION [val]  - where OPTION is one of options listed from '--lsopts'

If root_dir is not specified, the current directory will be used

rampart@machine:~>$ rampart --server --lsopts
--ipAddr             String. The ipv4 address to bind
--ipv6Addr           String. The ipv6 address to bind
--bindAll            Bool.   Set ipAddr and ipv6Addr to '0.0.0.0' and '[::]' respectively
--ipPort             Number. Set ipv4 port
--ipv6Port           Number. Set ipv6 port
--port               Number. Set both ipv4 and ipv6 port
--redirPort          Number. Launch http->https redirect server and set port
--redir              Bool.   Launch http->https redirect server and set to port 80
--htmlRoot           String. Root directory from which to serve files
--appsRoot           String. Root directory from which to serve apps
--wsappsRoot         String. Root directory from which to serve wsapps
--dataRoot           String. Setting for user scripts
--logRoot            String. Log directory
--accessLog          String. Log file name. "" for stdout
--errorLog           String. error log file name. "" for stderr
--log                Bool.   Whether to log requests and errors
--rotateLogs         Bool.   Whether to rotate the logs
--rotateInterval     Number. Interval between log rotations in seconds
--rotateStart        String. Time to start log rotations
--user               String. If started as root, switch to this user
--threads            Number. Limit the number of threads used by the server.
                     Default (-1) is the number of cores on the system
--sslKeyFile         String. If https, the ssl/tls key file location
--sslCertFile        String. If https, the ssl/tls cert file location
--secure             Bool.   Whether to use https.  If true sslKeyFile and sslCertFile must be set
--developerMode      Bool.   Whether script errors result in 500 and return a stack trace.  Otherwise 404
--letsencrypt        String. If using letsencrypt, the 'domain.tld' name for automatic setup of https
                     (assumes --secure true and looks for '/etc/letsencrypt/live/domain.tld/' directory)
                     (if redir is set, also map ./letsencrypt-wd/.well-known/ --> http://mydom.com/.well-known/)
                     (if set to "setup", don\'t start https server, but do map ".well-known/" for http)
                     (sets port:443 unless set otherwise)
--rootScripts        Bool.   Whether to treat *.js files in htmlRoot as apps (not secure)
--directoryFunc      Bool.   Whether to provide a directory listing if no index.html is found
--daemon             Bool.   whether to detach from terminal
--monitor            fork and run a monitor as a daemon which restarts server w/in 10 seconds if it dies
--scriptTimeout      Number  Max time to wait for a script module to return a reply in seconds (default 20)
--connectTimeout     Number  Max time to wait for client send request in seconds (default 20)
-d                   alias for '--daemon true'
--detach             alias for '--daemon true'
--stop               stop the server.  Also stop the monitor and log rotation, if started

The default settings, whether used from the command line or with a script such as the included web_server_conf.js script are visible with the following commands:

rampart@machine:~>$ rampart --server --showdefaults ~/web_server
Defaults for --server:
{
   "ipAddr": "127.0.0.1",
   "ipv6Addr": "[::1]",
   "bindAll": false,
   "ipPort": 8088,
   "ipv6Port": 8088,
   "port": -1,
   "redirPort": -1,
   "redir": false,
   "htmlRoot": "/home/rampart/web_server/html",
   "appsRoot": "/home/rampart/web_server/apps",
   "wsappsRoot": "/home/rampart/web_server/wsapps",
   "dataRoot": "/home/rampart/web_server/data",
   "logRoot": "/home/rampart/web_server/logs",
   "accessLog": "/home/rampart/web_server/logs/access.log",
   "errorLog": "/home/rampart/web_server/logs/error.log",
   "log": true,
   "rotateLogs": false,
   "rotateInterval": 86400,
   "rotateStart": "00:00",
   "user": "nobody",
   "threads": -1,
   "sslKeyFile": "",
   "sslCertFile": "",
   "secure": false,
   "developerMode": true,
   "letsencrypt": "",
   "rootScripts": false,
   "directoryFunc": false,
   "monitor": false,
   "daemon": true,
   "scriptTimeout": 20,
   "connectTimeout": 20,
   "quickserver": false,
   "appendProcTitle": false,
   "serverRoot": "/home/rampart/web_server",
   "fullServer": 1
}

rampart@machine:~/dir_with_files>$ rampart --quickserver --showdefaults
Defaults for --quickserver:
{
   "ipAddr": "127.0.0.1",
   "ipv6Addr": "[::1]",
   "bindAll": false,
   "ipPort": 8088,
   "ipv6Port": 8088,
   "port": -1,
   "redirPort": -1,
   "htmlRoot": "/home/rampart/dir_with_files/",
   "appsRoot": "",
   "wsappsRoot": "",
   "dataRoot": "",
   "logRoot": "/home/rampart/dir_with_files/logs",
   "accessLog": "",
   "errorLog": "",
   "log": false,
   "rotateLogs": false,
   "rotateInterval": 86400,
   "rotateStart": "00:00",
   "user": "nobody",
   "threads": 1,
   "sslKeyFile": "",
   "sslCertFile": "",
   "secure": false,
   "developerMode": true,
   "letsencrypt": "",
   "rootScripts": false,
   "directoryFunc": true,
   "monitor": false,
   "daemon": false,
   "scriptTimeout": 20,
   "connectTimeout": 20,
   "quickserver": true,
   "appendProcTitle": false,
   "serverRoot": "/home/rampart/dir_with_files",
   "fullServer": 0
}

Use with Letsencrypt¶

A shortcut for setting up a secure server with letsencrypt is available via the letsencrypt keys in web_server_conf or using rampart --server --letsencrypt example.com. Setting the value to the appropriate domain name (e.g. example.com) will set the following keys automatically:

{
    "secure":        true,
    "sslKeyFile":    "/etc/letsencrypt/live/example.com/privkey.pem",
    "sslCertFile":   "/etc/letsencrypt/live/example.com/fullchain.pem",
}

Obtaining a key via the letsencrypt certbot utility requires access to http://example.com:80/.well-known/ and the corresponding mapped directory on the filesystem. If the redir or redirPort setting is set along with the letsencrypt:"example.com", the directory /path/to/my/web_server/letsencrypt_wd/.well-known will automatically be created and mapped to http://example.com:80/.well-known/.

In addition, the letsencrypt key may be set to "setup" (or by doing rampart ./web_server_conf.js letssetup) to prevent starting the secure server when the certificates have not yet been issued by letsencrypt.

A full example of obtaining a certificate using certbot, substituting the desired domain name with example.com:

# work must be performed as root
~>$ sudo bash

# install the certbot using appropriate package manager
[email protected]:~# apt install certbot

# change to the location of your web_server.
[email protected]:~# cd /path/to/my/web_server

# edit web_server_conf.js file and set ``"letsencrypt": "example.com"``
[email protected]:/path/to/my/web_server# vi ./web_server_conf.js

# start the http webserver in letsencrypt setup mode (don't start https)
[email protected]:/path/to/my/web_server# rampart ./web_server_conf.js letssetup

# verify redirect server has mapped .well-known/
[email protected]:/path/to/my/web_server# ls -a letsencrypt_wd/
.  ..  .well-known

# request a certificate (this machine must be reachable at [www.]example.com)
[email protected]:/path/to/my/web_server# certbot certonly --webroot \
--webroot-path /path/to/my/web_server/letsencrypt_wd \
-d example.com,www.example.com

# if certs were issued without error, the server can now be restarted
# with https enabled
[email protected]:/path/to/my/web_server# rampart ./web_server_conf.js restart

A root crontab entry will keep the certificate up to date:

0 5 * * * /usr/bin/certbot renew --quiet --renew-hook "rampart /path/to/my/web_server/web_server_conf.js restart" 2>/dev/null

Loading the module¶

var llm = require("rampart-llm.js");

Creating a connection¶

The module exports two constructors, one for each supported backend. Both accept an Object of options and verify that the server is reachable on construction.

// llama-server (llama.cpp)
var client = new llm.llamaCpp({
    server: "127.0.0.1",   // default
    port:   8080            // default
});

// Ollama
var client = new llm.ollama({
    server: "127.0.0.1",   // default
    port:   11434           // default
});

An error is thrown if the server is not running at the given address.

Note: llama-server loads a single model at startup, so the model property described below is required by the API format but its value is ignored. With Ollama, the model name selects which model to use.

Instance properties¶

After construction, set properties on the instance before calling query().

• model - String. The model name. Required for Ollama (e.g. "qwen2.5-coder:7b"). For llamaCpp, any non-empty string will do since llama-server always uses its loaded model.
• params - Object. Sampling and generation parameters that are merged directly into the /v1/chat/completions POST body. Common parameters include:
  • temperature - Number. Controls randomness (0.0 – 2.0).
  • max_tokens - Number. Maximum tokens to generate.
  • top_p - Number. Nucleus sampling threshold (0.0 – 1.0).
  • top_k - Number. Top-k sampling.
  • repeat_penalty - Number. Repetition penalty (1.0 = off; 1.1 – 1.3 typical).
  • frequency_penalty - Number. Penalize tokens by frequency (0.0 – 1.0).
  • presence_penalty - Number. Penalize tokens by presence (0.0 – 1.0).
• cancel - Boolean. Set to true to abort an in-flight query. The stream will stop on the next chunk and the final callback will fire.

Example:

client.model  = "qwen2.5-3b-instruct-q4_k_m.gguf";
client.params = {temperature: 0.2, max_tokens: 4096};

query()¶

The query() method sends a prompt to the server and streams the response back through callbacks.

client.query(prompt, perTokenCallback, finalCallback);

Where:

• prompt - Array or String. If an Array, it is sent as messages to the /v1/chat/completions endpoint (chat mode). Each element is an Object with role ("system", "user", or "assistant") and content properties. If a String, it is sent as prompt to the /v1/completions endpoint (completion mode).
• perTokenCallback - Function. Called for each streamed token and on error or completion. May be null if only finalCallback is needed. The callback receives a single Object argument with the following properties:
  • token - String. The token text.
  • thinking - Boolean. true if this token is reasoning/thinking content (from <think> tags or the --reasoning-format flag in llama-server).
  • error - Set if the server returned an error.
  • done - Boolean. true when the stream has ended.
  • serverResponse - The raw HTTP response object.
• finalCallback - Function. Called once after the stream ends. Receives a single Object with:
  • fullText - String. The complete response text (excluding thinking content).
  • thinkingText - String. The complete thinking/reasoning text (only present if the model produced thinking output).
  • answer - String. The answer portion after thinking (only present if thinkingText is present).
  • serverResponse - The raw HTTP response object.
  • error - Set if the query failed.

At least one of perTokenCallback or finalCallback must be provided.

Chat example¶

A basic chat completion with streaming output:

var llm = require("rampart-llm.js");
var client = new llm.llamaCpp({server: "127.0.0.1", port: 8080});

client.params = {temperature: 0.7, max_tokens: 2048};

var prompt = [
    {role: "system",  content: "You are a helpful assistant."},
    {role: "user",    content: "What is the capital of France?"}
];

client.query(
    prompt,

    // per-token callback — print each token as it arrives
    function(res) {
        if (res.error) {
            fprintf(stderr, "Error: %J\n", res.error);
            return;
        }
        if (res.done) return;

        if (res.thinking)
            fprintf(stderr, "(thinking) %s", res.token);
        else
            printf("%s", res.token);
    },

    // final callback — runs once when the stream ends
    function(res) {
        if (res.error) {
            fprintf(stderr, "Query failed: %J\n", res.error);
            return;
        }
        printf("\n\n--- Complete response ---\n%s\n", res.fullText);
    }
);

Multi-turn conversation¶

To maintain a conversation, accumulate messages and send the full array on each turn. The server is stateless — it needs the entire history every time.

var conversation = [
    {role: "system", content: "You are a helpful assistant."}
];

function ask(question, callback) {
    conversation.push({role: "user", content: question});

    client.query(conversation, null, function(res) {
        if (!res.error) {
            conversation.push({role: "assistant", content: res.fullText});
            printf("%s\n", res.fullText);
        }
        if (callback) callback();
    });
}

ask("What is the capital of France?", function() {
    ask("What is its population?");
});

Cancelling a query¶

Setting cancel to true on the instance will abort the current stream on the next chunk.

// start a query
client.query(prompt, function(res) {
    if (res.done) {
        printf("(cancelled or complete)\n");
        return;
    }
    printf("%s", res.token);
});

// cancel it after 2 seconds
setTimeout(function() {
    client.cancel = true;
}, 2000);

Overriding params per query¶

The params property can be saved and temporarily replaced for a side-query (e.g. a short classification task) without affecting the main conversation settings.

var savedParams = client.params;
client.params = {temperature: 0.1, max_tokens: 2048};

client.query(classifyPrompt, null, function(res) {
    client.params = savedParams;  // restore original params
    printf("Classification: %s\n", res.fullText);
});

Thinking/reasoning models¶

Some models produce internal reasoning wrapped in <think>...</think> tags or via a separate reasoning_content field (when llama-server is started with --reasoning-format deepseek). The module handles both formats transparently:

• In the per-token callback, res.thinking is true for reasoning tokens and false for answer tokens.
• In the final callback, res.thinkingText contains the full reasoning and res.answer contains only the answer. res.fullText contains the full non-thinking output.

Note that thinking tokens consume the max_tokens budget but do not appear in fullText. When using thinking models, set max_tokens high enough to accommodate both reasoning and answer (4096 or more is recommended, as reasoning can easily consume several thousand tokens before the visible answer begins).

Context window management¶

When a conversation grows long enough to exceed the server’s context window, the server will return an error. There are two approaches to handling this:

llama-server (llama.cpp): Start the server with the --context-shift flag to allow automatic context shifting — older tokens are discarded from the KV cache to make room for new ones. This is a server-start flag and cannot be set per-request. The context size is set with -c (e.g. -c 32768). When using --parallel for multiple slots, the context is divided evenly among slots.

llama-server also exposes several useful REST endpoints beyond the OpenAI-compatible /v1/ API:

• /props — returns server properties including default_generation_settings.n_ctx (the configured context size).
• /slots — returns per-slot information including n_ctx (the actual per-slot context size, which accounts for --parallel).
• /health — returns server health status.

These can be queried with rampart-curl to discover the context size at runtime, for example to display a token usage indicator to the user.

Ollama: Context shifting is handled automatically. The context window size defaults to 2048 tokens but can be increased by passing num_ctx in the params (e.g. client.params = {num_ctx: 32768}). Ollama will silently shift context when the window fills up.

Using with the Rampart web server¶

The module is designed to work well in websocket scripts. The req object in a websocket handler persists across messages, so an llm instance created during the handshake (req.count == 0) can be reused for all subsequent messages in the connection. See the llmchat.js example in the Rampart LLM demo for a complete working implementation.

var llm = require("rampart-llm.js");

function handler(req) {
    if (req.count == 0) {
        // handshake — create connection, store on req
        req.llm = new llm.llamaCpp({server: "127.0.0.1", port: 8080});
        req.llm.params = {temperature: 0.5};
        return;
    }

    // subsequent messages
    var userText = sprintf("%s", req.body);  // Buffer to string

    var prompt = [
        {role: "system", content: "You are a helpful assistant."},
        {role: "user",   content: userText}
    ];

    req.llm.query(prompt,
        function(res) {
            if (res.error || res.done) return;
            req.wsSend(res.token);
        },
        function(res) {
            req.wsSend({end: true});
        }
    );
}

module.exports = handler;

Creating a C Module template¶

The first step is to copy the make_cmod_template.js into a new directory for the project. After copying, it can be run as such:

rampart@machine:~>$ mkdir my_module
rampart@machine:~>$ cd my_module
rampart@machine:~/my_module>$ cp /usr/local/rampart/unsupported_extras/c_module_template_maker/make_cmod_template.js  ./
rampart@machine:~/my_module>$ rampart make_cmod_template.js -- --help
usage:
    make_cmod_template.js -h
        or
    make_cmod_template.js c_file_name [-f function_args] [-m make_file_name] [-t test_file_name]

where:

    c_file_name     - The c template file to write.

    make_file_name  - The name of the makefile to write (default "Makefile")

    test_file_name  - The name of the JavaScript test file (default c_file_name-test.js)

    function_args   - Create c functions that will be exported to JavaScript.
                    - May be specified more than once.
                    - Format: cfunc_name:jsfunc_name[:nargs[:input_types]]

    function_args format (each argument separated by a ':'):

        cfunc_name:  The name of the c function.

        jsfunc_name: The name of the javascript function to export.

        nargs: The number of arguments the javascript function can take (-1 for variadic)

        input_types: Require a variable type for javascript options:
            A character for each argument. [n|i|u|s|b|B|o|a|f].
            Corresponding to require
             [  number|number(as int)|number(as int>-1)|string|
                boolean|buffer|object|array|function             ]

A ready to compile, testable module will be produced if both "nargs" and "input_types" are provided.

Example to create a module that exports two functions which each take a String and Number:

rampart make_cmod_template example.c -f my_func:myFunc:2:sn -f my_func2:myFunc2:2:sn

Example usage to create a module¶

The following is an example of how to make a simple C module that capitalizes a string.

First, run the script with appropriate options to create the template files. In this case it is used to create a module named "myutil.so" which will export an Object with the function "capitalize". Calling this function from JavaScript will run a C function named my_capitalization_func.

rampart@machine:~/my_module>$ rampart make_cmod_template.js myutil -f my_capitalize_func:capitalize:1:s
rampart@machine:~/my_module>$ ls
make_cmod_template.js  Makefile  myutil.c  myutil-test.js
rampart@machine:~/my_module>$ make
cc -Wall -g -O2 -std=c99 -I/usr/local/rampart/include  -fPIC -shared -Wl,-soname,myutil.so -o myutil.so myutil.c
myutil.c: In function ‘my_capitalize_func’:
myutil.c:5:18: warning: unused variable ‘js_arg1’ [-Wunused-variable]
    5 |     const char * js_arg1 = REQUIRE_STRING(ctx, 0, "capitalize: argument 1 must be a string");
      |                  ^~~~~~~

At this stage, the function does not actually do anything (hence the warning above). But it is a fully functioning module which can now be edited to add actual functionality. The myutil.c file will contain the following:

#include "/usr/local/rampart/include/rampart.h"

static duk_ret_t my_capitalize_func(duk_context *ctx)
{
    const char * js_arg1 = REQUIRE_STRING(ctx, 0, "capitalize: argument 1 must be a string");

    /* YOUR CODE GOES HERE */

    return 1;
}

/* **************************************************
   Initialize module
   ************************************************** */
duk_ret_t duk_open_module(duk_context *ctx)
{
    /* the return object when var mod=require("myutil") is called. */
    duk_push_object(ctx);


    /* js function is mod.capitalize and it calls my_capitalize_func */
    duk_push_c_function(ctx, my_capitalize_func, 1);
    duk_put_prop_string(ctx, -2, "capitalize");

    return 1;
}

We can add the needed #includes and replace the /* YOUR CODE GOES HERE */ with the following:

//for linux and strdup and -std=c99
#define _DEFAULT_SOURCE
#include <ctype.h>
#include <string.h>
#include "/usr/local/rampart/include/rampart.h"

static duk_ret_t my_capitalize_func(duk_context *ctx)
{
    const char * js_arg1 = REQUIRE_STRING(ctx, 0, "capitalize: argument 1 must be a string");

    char *capped = strdup(js_arg1), *s=capped;
    while(*s) *(s++)=toupper(*s);
    duk_push_string(ctx, capped);
    free(capped);

    return 1;
}

Then recompile:

rampart@machine:~/my_module>$ make

Also created is a script to test the new module named mymod-test.js.

rampart.globalize(rampart.utils);

var myutil = require("myutil");

function testFeature(name,test,error)
{
    if (typeof test =='function'){
        try {
            test=test();
        } catch(e) {
            error=e;
            test=false;
        }
    }
    printf("testing %-50s - ", name);
    if(test)
        printf("passed\n")
    else
    {
        printf(">>>>> FAILED <<<<<\n");
        if(error) printf('%J\n',error);
        process.exit(1);
    }
    if(error) console.log(error);
}


testFeature("myutil.capitalize basic functionality", function(){
    var lastarg = "String";
    return lastarg == myutil.capitalize(lastarg);
});

Next step is to modify the testFeature() call in mymod-test.js to verify the new function works as expected:

testFeature("myutil.capitalize basic functionality", function(){
    var mystring = "String";
    var expected = "STRING";
    return expected == myutil.capitalize(mystring);
});

Running the test script results in the following output:

rampart@machine:~/my_module>$ rampart myutil-test.js
testing myutil.capitalize basic functionality              - passed

See:

Macros below for some useful macros.

See also:

Duktape Api