DominScript — web

32 functionsnamespace websource plugins/web_util/WebUtilPlugin.c

Introduction

The web plugin provides web text-processing helpers: HTML and URL encoding, Base64 encoding, parsing of raw HTTP requests, handling of the Content-Type header and MIME types, and assembling complete HTTP responses. Its typical use is building a simple web server or web service in DominScript: you split the incoming request apart with the request parsers and produce the response with the response builders. The plugin is stateless — every call is standalone.

Text and blob

Most functions work with text (string), but the raw HTTP data — the incoming request and the outgoing response — is a blob, because it can contain arbitrary bytes (even 0 bytes). So the HTTP request parsers take a blob (the raw request), and the response builders return a blob (the finished, byte-exact response you can send directly).

Loading the plugin

plugin "builtin:print";
plugin "../plugins/web_util/WebUtilPlugin";

A typical flow — serving a request

// $req is the incoming raw request (a blob)
string $path[256];
blob $resp[1024];
$path = web.HttpRequestPath($req);
// ... decide based on $path ...
$resp = web.HttpTextResponse("200 OK", "text/plain", "Hello");
// send $resp back to the client

What to know about every function (the basics)

The plugin is stateless and standalone: no open/close, no handle. The functions are thread-safe.
The question-like (Is*) functions and ContentTypeMatches return an integer: 1 = true, 0 = false.
The parsers that return text (HttpHeaderValue, CookieValue, UrlFormValue, ContentTypeParam, etc.) return an empty string on no match — they do not fail.
An error (stopping the script) is caused only by a wrong argument count or type; Base64 decoding also raises an error for invalid input.
HTML escaping replaces the & < > " ' characters; UrlEncode encodes per RFC 3986 (a space becomes %20, not +).
The HTTP request parsers split apart the raw request (a blob); if the requested part is absent they return an empty string.

How to read the signatures

request is a raw HTTP request blob, contentType is the text of a Content-Type header. The type after the -> arrow is the return type. For example, web_util.HttpHeaderValue(request, name) -> string takes a request blob and a header name and returns the header's value as text.

HTML processing

Safely escaping and unescaping HTML text.

web_util.HtmlEscape

web.HtmlEscape(text) -> string

Escapes the characters that are special in HTML (& < > " ') into their entities.

Parameters

Parameter	Type	Description
text	string	The text to escape.

Return value

The escaped text (for example < becomes <).

Example

print.Line(web.HtmlEscape("a<b>&\"c\""));

Output after running

a&lt;b&gt;&amp;&quot;c&quot;

When to use

Before inserting user text into HTML: this protects against HTML injection (XSS), because the control characters are not interpreted as code.

web_util.HtmlUnescape

web.HtmlUnescape(text) -> string

Unescapes HTML entities back into the original characters.

Parameters

Parameter	Type	Description
text	string	The text to unescape, containing entities.

Return value

The unescaped text (for example < becomes <).

Example

print.Line(web.HtmlUnescape("a&lt;b&gt;&amp;c"));

Output after running

a<b>&c

When to use

To recover the original form of text extracted from HTML — for example when processing a value read from an HTML attribute or text node.

URL encoding

Converting text to and from a URL-safe (percent-encoded) form.

web_util.UrlEncode

web.UrlEncode(text) -> string

Encodes the text into a form safely embeddable in a URL (percent-encoding per RFC 3986).

Parameters

Parameter	Type	Description
text	string	The text to encode.

Return value

The encoded text (unsafe bytes as %XX, a space as %20).

Example

print.Line(web.UrlEncode("a b&c=d"));

Output after running

a%20b%26c%3Dd

When to use

To assemble URL parameters or path segments from user data, so special characters (&, =, space) do not break the URL's structure.

web_util.UrlDecode

web.UrlDecode(text) -> string

Decodes URL-encoded (percent-encoded) text back to its original form.

Parameters

Parameter	Type	Description
text	string	The text to decode, containing %XX sequences.

Return value

The decoded text.

Example

print.Line(web.UrlDecode("a%20b%26c%3Dd"));

Output after running

a b&c=d

When to use

To restore the original form of a value extracted from a URL or form data (the counterpart of UrlEncode). For some fields UrlFormValue does this automatically.

Base64

Converting data to and from Base64 text. Separate variants for text and blob.

web_util.Base64EncodeText

web.Base64EncodeText(text) -> string

Encodes a text into Base64 text.

Parameters

Parameter	Type	Description
text	string	The text to encode.

Return value

The Base64-encoded text.

Example

print.Line(web.Base64EncodeText("hello"));

Output after running

aGVsbG8=

When to use

To put text into a form safely transportable over a text channel (for example in a header or a JSON field).

web_util.Base64EncodeBlob

web.Base64EncodeBlob(data) -> string

Encodes a blob's raw bytes into Base64 text.

Parameters

Parameter	Type	Description
data	blob	The binary data to encode.

Return value

The Base64-encoded text.

Example

blob $B[8];
$B = blob.FromText("hi");
print.Line(web.Base64EncodeBlob($B));

Output after running

aGk=

When to use

To put binary data (an image, a file, a hash) into text form — for example to embed in a data: URI or a text protocol.

web_util.Base64DecodeToText

web.Base64DecodeToText(text) -> string

Decodes a Base64 text and returns the result as text.

Parameters

Parameter	Type	Description
text	string	The Base64 text to decode.

Return value

The decoded text. Invalid Base64 causes a runtime error. (A 0 byte becomes the ? character.)

Example

print.Line(web.Base64DecodeToText("aGVsbG8="));

Output after running

hello

When to use

To decode textual Base64 content. If the decoded data is binary (may contain 0 bytes), Base64DecodeToBlob is correct, since it does not truncate.

web_util.Base64DecodeToBlob

web.Base64DecodeToBlob(text) -> blob

Decodes a Base64 text into a raw blob.

Parameters

Parameter	Type	Description
text	string	The Base64 text to decode.

Return value

The decoded raw bytes as a blob. Invalid Base64 causes a runtime error.

Example

blob $B[16];
$B = web.Base64DecodeToBlob("aGk=");
printf("%d\n", $B.Length);

Output after running

When to use

To decode binary Base64 content (an image, a file), where the 0 byte must be preserved. The counterpart of Base64EncodeBlob.

HTTP request parsing

Extracting the parts of a raw HTTP request (a blob): the request line, the method, the path, the headers, a cookie, and the body.

web_util.HttpRequestLine

web.HttpRequestLine(request) -> string

Extracts the first line of the request (the request line).

Parameters

Parameter	Type	Description
request	blob	The raw HTTP request.

Return value

The request line (for example “GET /path HTTP/1.1”).

Example

blob $R[256];
$R = blob.FromText("GET /p?q=1 HTTP/1.1\r\nHost: x\r\n\r\n");
print.Line(web.HttpRequestLine($R));

Output after running

GET /p?q=1 HTTP/1.1

When to use

For a quick overview or logging of the request. For detailed processing, use the more targeted HttpRequestMethod/Path/Query functions.

web_util.HttpRequestMethod

web.HttpRequestMethod(request) -> string

Extracts the request's HTTP method.

Parameters

Parameter	Type	Description
request	blob	The raw HTTP request.

Return value

The method (for example “GET”, “POST”).

Example

blob $R[256];
$R = blob.FromText("GET /p HTTP/1.1\r\n\r\n");
print.Line(web.HttpRequestMethod($R));

Output after running

GET

When to use

To branch by the request's kind: for example read on GET, write on POST.

web_util.HttpRequestTarget

web.HttpRequestTarget(request) -> string

Extracts the request's full target (path and query together).

Parameters

Parameter	Type	Description
request	blob	The raw HTTP request.

Return value

The full target (for example “/path?q=1&x=2”).

Example

blob $R[256];
$R = blob.FromText("GET /path?q=1&x=2 HTTP/1.1\r\n\r\n");
print.Line(web.HttpRequestTarget($R));

Output after running

/path?q=1&x=2

When to use

When you need the path and query together. Separately, HttpRequestPath and HttpRequestQuery give them.

web_util.HttpRequestPath

web.HttpRequestPath(request) -> string

Extracts the request's path (without the query part).

Parameters

Parameter	Type	Description
request	blob	The raw HTTP request.

Return value

The path (the part before the ?, for example “/path/page”).

Example

blob $R[256];
$R = blob.FromText("GET /path/page?q=1 HTTP/1.1\r\n\r\n");
print.Line(web.HttpRequestPath($R));

Output after running

/path/page

When to use

For routing: based on the path you decide which handler serves the request.

web_util.HttpRequestQuery

web.HttpRequestQuery(request) -> string

Extracts the request's query part (the part after the ?).

Parameters

Parameter	Type	Description
request	blob	The raw HTTP request.

Return value

The query part (for example “q=1&x=2”), or an empty string if there is none.

Example

blob $R[256];
$R = blob.FromText("GET /p?q=1&x=2 HTTP/1.1\r\n\r\n");
print.Line(web.HttpRequestQuery($R));

Output after running

q=1&x=2

When to use

To process the query parameters. You read an individual parameter's value out of it with UrlFormValue.

web_util.HttpRequestBodyText

web.HttpRequestBodyText(request) -> string

Extracts the request's body as text (the part after the headers).

Parameters

Parameter	Type	Description
request	blob	The raw HTTP request.

Return value

The request body as text.

Example

blob $R[256];
$R = blob.FromText("POST /p
HTTP/1.1\r\n\r\nname=Ada&age=36");
print.Line(web.HttpRequestBodyText($R));

Output after running

name=Ada&age=36

When to use

To process the content of POST/PUT requests (form data, JSON). An individual field of an urlencoded form is read by UrlFormValue.

web_util.HttpHeaderValue

web.HttpHeaderValue(request, name) -> string

Extracts the value of a given header from the request.

Parameters

Parameter	Type	Description
request	blob	The raw HTTP request.
name	string	The header's name (case-insensitive).

Return value

The header's value, or an empty string if there is no such header.

Example

blob $R[256];
$R = blob.FromText("GET / HTTP/1.1\r\nHost:
example.com\r\n\r\n");
print.Line(web.HttpHeaderValue($R, "Host"));

Output after running

example.com

When to use

To read any header (Host, Authorization, Content-Length, etc.). A non-existent header gives an empty string, so its presence can be checked with an empty test.

web_util.HttpCookieValue

web.HttpCookieValue(request, name) -> string

Extracts the value of a given cookie directly from the request.

Parameters

Parameter	Type	Description
request	blob	The raw HTTP request.
name	string	The cookie's name.

Return value

The cookie's value, or an empty string if there is no such cookie.

Example

blob $R[256];
$R = blob.FromText("GET / HTTP/1.1\r\nCookie: sid=abc;
theme=dark\r\n\r\n");
print.Line(web.HttpCookieValue($R, "theme"));

Output after running

dark

When to use

To read a session id or a setting from the request in one step. (CookieValue works directly from the text of the Cookie header.)

web_util.HttpRequestUsesChunked

web.HttpRequestUsesChunked(request) -> int

Tells whether the request uses chunked transfer encoding.

Parameters

Parameter	Type	Description
request	blob	The raw HTTP request.

Return value

1 if the request is Transfer-Encoding: chunked; otherwise 0.

Example

blob $R[256];
$R = blob.FromText("GET / HTTP/1.1\r\nHost: x\r\n\r\n");
printf("%d\n", web.HttpRequestUsesChunked($R));

Output after running

When to use

To read the request body correctly: with chunked, the body arrives in pieces and must be processed differently from a Content-Length-based one.

Cookie, form, Content-Type and MIME

Reading cookie and urlencoded-form fields, parsing the Content-Type header, handling MIME types, and building a header line.

web_util.CookieValue

web.CookieValue(cookieHeader, name) -> string

Extracts a cookie value from the text of a Cookie header.

Parameters

Parameter	Type	Description
cookieHeader	string	The Cookie header value (for example “sid=abc; theme=dark”).
name	string	The name of the cookie sought.

Return value

The cookie's value, or an empty string if there is none.

Example

print.Line(web.CookieValue("sid=abc; theme=dark", "theme"));

Output after running

dark

When to use

When you have already extracted the Cookie header text (for example with HttpHeaderValue) and want to read a specific cookie from it. Directly from the request, HttpCookieValue works.

web_util.UrlFormValue

web.UrlFormValue(text, key) -> string

Extracts a field value from an urlencoded form or query string (resolving the percent-encoding).

Parameters

Parameter	Type	Description
text	string	The urlencoded text (for example “name=Ada&age=36”).
key	string	The name of the field sought.

Return value

The field's (decoded) value, or an empty string if there is no such key.

Example

print.Line(web.UrlFormValue("name=Ada&age=36", "age"));

Output after running

When to use

To read an individual field from a POST form body or the query part (HttpRequestQuery). It automatically decodes percent-encoded values.

web_util.HttpHeaderLine

web.HttpHeaderLine(name, value) -> string

Assembles a proper HTTP header line (with name, value, and trailing CRLF).

Parameters

Parameter	Type	Description
name	string	The header's name.
value	string	The header's value.

Return value

The finished header line, in the form “Name: value\r\n”.

Example

print.Print(web.HttpHeaderLine("X-Test", "yes"));

Output after running

X-Test: yes

When to use

To assemble your own headers for the response builders' extraHeaders argument. You can pass several lines concatenated one after another.

web_util.ContentTypeMediaType

web.ContentTypeMediaType(contentType) -> string

Extracts the media-type part of a Content-Type header (without the parameters).

Parameters

Parameter	Type	Description
contentType	string	The full Content-Type value (for example “text/html; charset=utf-8”).

Return value

The media type (for example “text/html”).

Example

print.Line(web.ContentTypeMediaType("text/html;
charset=utf-8"));

Output after running

text/html

When to use

When you only need the type (text/html, application/json), without the charset and other parameters — for example to decide how to process the content.

web_util.ContentTypeParam

web.ContentTypeParam(contentType, paramName) -> string

Extracts the value of a parameter of the Content-Type header (for example the charset).

Parameters

Parameter	Type	Description
contentType	string	The full Content-Type value.
paramName	string	The name of the parameter sought (for example “charset”).

Return value

The parameter's value, or an empty string if there is none.

Example

print.Line(web.ContentTypeParam("text/html; charset=utf-8",
"charset"));

Output after running

utf-8

When to use

To read the character encoding (charset) or the multipart boundary, when it is needed to interpret the content correctly.

web_util.ContentTypeMatches

web.ContentTypeMatches(contentType, mediaType) -> int

Tells whether a Content-Type belongs to the given media type (ignoring the parameters).

Parameters

Parameter	Type	Description
contentType	string	The full Content-Type value.
mediaType	string	The media type to check (for example “text/html”).

Return value

1 if it matches; otherwise 0.

Example

printf("%d\n", web.ContentTypeMatches("text/html; charset=utf-8",
"text/html"));

Output after running

When to use

To branch by content type: it correctly compares a header given with a charset against the desired type.

web_util.MimeTypeFromPath

web.MimeTypeFromPath(path) -> string

Gives the MIME type matching a file based on its extension.

Parameters

Parameter	Type	Description
path	string	The file's path or name (the extension matters).

Return value

The MIME type (for example “text/css; charset=utf-8” or “image/png”).

Example

print.Line(web.MimeTypeFromPath("style.css"));
print.Line(web.MimeTypeFromPath("img.png"));

Output after running

text/css; charset=utf-8
image/png

When to use

When serving static files, to set the correct Content-Type header based on the file name — so the browser interprets the content correctly.

web_util.IsTextContentType

web.IsTextContentType(contentType) -> int

Tells whether the Content-Type denotes text-like content.

Parameters

Parameter	Type	Description
contentType	string	The Content-Type value to check.

Return value

1 if it is text-like (for example text/*, application/json); otherwise 0.

Example

printf("%d\n", web.IsTextContentType("text/plain"));

Output after running

When to use

To decide whether to treat the content as text or as binary data (for example when logging or choosing an encoding).

web_util.IsFormUrlEncoded

web.IsFormUrlEncoded(contentType) -> int

Tells whether the Content-Type denotes an urlencoded form.

Parameters

Parameter	Type	Description
contentType	string	The Content-Type value to check.

Return value

1 if it is application/x-www-form-urlencoded; otherwise 0.

Example

printf("%d\n",
web.IsFormUrlEncoded("application/x-www-form-urlencoded"));

Output after running

When to use

Before processing a POST request: if it is an urlencoded form, you can split the body into fields with UrlFormValue.

web_util.IsTransferEncodingChunked

web.IsTransferEncodingChunked(transferEncoding) -> int

Tells whether a Transfer-Encoding header value denotes chunked.

Parameters

Parameter	Type	Description
transferEncoding	string	The Transfer-Encoding header value.

Return value

1 if it is chunked; otherwise 0.

Example

printf("%d\n", web.IsTransferEncodingChunked("chunked"));

Output after running

When to use

When you have already extracted the Transfer-Encoding header value and want to decide whether the transfer is chunked. Directly from the request, HttpRequestUsesChunked works.

Building HTTP responses

Assembling a finished, byte-exact HTTP response (status line, headers, body), returned as a blob. Separate variants for text and binary body, and with extra headers.

web_util.HttpTextResponse

web.HttpTextResponse(statusLine, contentType, body) -> blob

Assembles a complete HTTP response with a text body.

Parameters

Parameter	Type	Description
statusLine	string	The status (for example “200 OK”).
contentType	string	The content type (for example “text/plain”).
body	string	The response body.

Return value

The finished HTTP response as a blob (status line + headers + body).

Example

blob $R[256];
$R = web.HttpTextResponse("200 OK", "text/plain", "Hello");
printf("%d\n", $R.Length);

Output after running

When to use

The most common response: returning text or HTML to the client. The plugin automatically sets the correct length and headers. For extra headers, use HttpTextResponseWithHeaders.

web_util.HttpTextResponseWithHeaders

web.HttpTextResponseWithHeaders(statusLine, contentType,
extraHeaders, body) -> blob

Like HttpTextResponse, but you can also provide additional headers.

Parameters

Parameter	Type	Description
statusLine	string	The status (for example “200 OK”).
contentType	string	The content type.
extraHeaders	string	Additional headers (one “Name: value\r\n” per line, for example built with HttpHeaderLine).
body	string	The response body.

Return value

The finished HTTP response as a blob.

Example

blob $R[256];
$R = web.HttpTextResponseWithHeaders("200 OK", "text/plain", "X-A:
1\r\n", "Hi");
printf("%d\n", $R.Length);

Output after running

When to use

When you also need to send your own headers (a cookie setting, cache control, CORS) alongside the text response. Build the extraHeaders lines with HttpHeaderLine.

web_util.HttpBlobResponse

web.HttpBlobResponse(statusLine, contentType, body) -> blob

Assembles a complete HTTP response with a binary (blob) body.

Parameters

Parameter	Type	Description
statusLine	string	The status (for example “200 OK”).
contentType	string	The content type (for example “image/png”).
body	blob	The binary response body.

Return value

The finished HTTP response as a blob.

Example

blob $B[8];
blob $R[256];
$B = blob.FromText("BIN");
$R = web.HttpBlobResponse("200 OK", "application/octet-stream",
$B);
printf("%d\n", $R.Length);

Output after running

When to use

To return binary content (an image, a downloaded file, a PDF), where the body is raw bytes and the 0 byte must be preserved.

web_util.LocalIPv4

web.LocalIPv4() -> string

A best-effort local, non-loopback IPv4 address of this host (falls back to 127.0.0.1). On POSIX it scans the active interfaces first, then resolves the host name; on Windows it uses Winsock. Useful for printing a copyable network URL when a listener binds to all interfaces. Moved here from the retired runtimeutil plugin — the only verb of this plugin that touches the network stack.

Example

print.Line("http://" + web.LocalIPv4() + ":18080/");

Output after running

http://192.168.1.20:18080/

web_util.HttpBlobResponseWithHeaders

web.HttpBlobResponseWithHeaders(statusLine, contentType,
extraHeaders, body) -> blob

Like HttpBlobResponse, but you can also provide additional headers.

Parameters

Parameter	Type	Description
statusLine	string	The status (for example “200 OK”).
contentType	string	The content type.
extraHeaders	string	Additional headers (one “Name: value\r\n” per line).
body	blob	The binary response body.

Return value

The finished HTTP response as a blob.

Example

blob $B[8];
blob $R[256];
$B = blob.FromText("BIN");
$R = web.HttpBlobResponseWithHeaders("200 OK",
"application/octet-stream", "X-A: 1\r\n", $B);
printf("%d\n", $R.Length);

Output after running

When to use

For a binary response with your own headers — for example with a Content-Disposition header set, for a file download.

Practical notes

What the web plugin is good for

Building a simple web server or web service: splitting the incoming request apart and assembling the response.
Handling user data safely: HTML escaping against XSS, URL encoding for parameters.
Transporting data as text: Base64 encoding for binary data so it can be sent over a text channel.
Content-type handling: choosing the correct processing mode and response header based on the Content-Type and the file extension.

Request in, response out

The typical flow: you split the raw request (a blob) apart with the HttpRequest* and HttpHeaderValue/HttpCookieValue functions, decide based on the path/method, then assemble the response with HttpTextResponse / HttpBlobResponse (or the …WithHeaders variants). The response is a finished, byte-exact blob you can send directly to the client.

Safety

ALWAYS run user text inserted into HTML through HtmlEscape (XSS protection).
Encode a value inserted into a URL with UrlEncode, so the special characters do not break the URL.
Read form and query fields with UrlFormValue, decoded — do not process the raw text by hand.

Text vs blob

HTTP data (a request, a response) is a blob, because it can contain arbitrary bytes. The text helpers (escaping, encoding) work with strings. For a binary body, use the …Blob… variants, because a string would be truncated at the first 0 byte. Base64DecodeToText turns a 0 byte into the ? character — if that is undesirable, Base64DecodeToBlob is correct.

Error handling

A wrong argument count or type, and invalid Base64 input, are reported by the runtime as a runtime error, and the script stops. The parsers that return text signal no match with a neutral empty string (they do not fail), and the question-like (Is*) functions with 0/1 — so the usual cases need no extra guard checks, just inspect the return value.