4.3. HTTP and WebSocket library (libhv)

The DASHV module provides HTTP and WebSocket networking built on top of the libhv library. It exposes WebSocket client/server types, HTTP request/response handling, route registration, cookie and form-data helpers, and an HTTP client for making outbound requests.

Use dashv_boost for the high-level daScript wrappers (HvWebServer, HvWebSocketClient). The low-level C++ bindings live in this module.

All functions and symbols are in “dashv” module, use require to get access to it.

require dashv

See also:

4.3.1. Enumerations

http_method

HTTP request method.

Values:

  • DELETE = 0 - Delete resource

  • GET = 1 - Get resource

  • HEAD = 2 - Head request (headers only)

  • POST = 3 - Post data

  • PUT = 4 - Put resource

  • CONNECT = 5 - Connect tunnel

  • OPTIONS = 6 - Options inspection

  • TRACE = 7 - Trace echo

  • COPY = 8 - WebDAV copy

  • LOCK = 9 - WebDAV lock

  • MKCOL = 10 - WebDAV create collection

  • MOVE = 11 - WebDAV move

  • PROPFIND = 12 - WebDAV property find

  • PROPPATCH = 13 - WebDAV property patch

  • SEARCH = 14 - WebDAV search

  • UNLOCK = 15 - WebDAV unlock

  • BIND = 16 - WebDAV bind

  • REBIND = 17 - WebDAV rebind

  • UNBIND = 18 - WebDAV unbind

  • ACL = 19 - WebDAV ACL

  • REPORT = 20 - WebDAV report

  • MKACTIVITY = 21 - WebDAV make activity

  • CHECKOUT = 22 - WebDAV checkout

  • MERGE = 23 - WebDAV merge

  • MSEARCH = 14 - UPnP multicast search

  • NOTIFY = 25 - UPnP notify

  • SUBSCRIBE = 26 - UPnP subscribe

  • UNSUBSCRIBE = 27 - UPnP unsubscribe

  • PATCH = 28 - Partial update

  • PURGE = 29 - Cache purge

  • MKCALENDAR = 30 - CalDAV create calendar

  • LINK = 31 - Link resources

  • UNLINK = 32 - Unlink resources

  • SOURCE = 33 - Retrieve source

http_status

HTTP response status code.

Values:

  • CONTINUE = 100 - 100 Continue

  • SWITCHING_PROTOCOLS = 101 - 101 Switching Protocols

  • PROCESSING = 102 - 102 Processing

  • OK = 200 - 200 OK

  • CREATED = 201 - 201 Created

  • ACCEPTED = 202 - 202 Accepted

  • NON_AUTHORITATIVE_INFORMATION = 203 - 203 Non-Authoritative Information

  • NO_CONTENT = 204 - 204 No Content

  • RESET_CONTENT = 205 - 205 Reset Content

  • PARTIAL_CONTENT = 206 - 206 Partial Content

  • MULTI_STATUS = 207 - 207 Multi-Status

  • ALREADY_REPORTED = 208 - 208 Already Reported

  • IM_USED = 226 - 226 IM Used

  • MULTIPLE_CHOICES = 300 - 300 Multiple Choices

  • MOVED_PERMANENTLY = 301 - 301 Moved Permanently

  • FOUND = 302 - 302 Found

  • SEE_OTHER = 303 - 303 See Other

  • NOT_MODIFIED = 304 - 304 Not Modified

  • USE_PROXY = 305 - 305 Use Proxy

  • TEMPORARY_REDIRECT = 307 - 307 Temporary Redirect

  • PERMANENT_REDIRECT = 308 - 308 Permanent Redirect

  • BAD_REQUEST = 400 - 400 Bad Request

  • UNAUTHORIZED = 401 - 401 Unauthorized

  • PAYMENT_REQUIRED = 402 - 402 Payment Required

  • FORBIDDEN = 403 - 403 Forbidden

  • NOT_FOUND = 404 - 404 Not Found

  • METHOD_NOT_ALLOWED = 405 - 405 Method Not Allowed

  • NOT_ACCEPTABLE = 406 - 406 Not Acceptable

  • PROXY_AUTHENTICATION_REQUIRED = 407 - 407 Proxy Authentication Required

  • REQUEST_TIMEOUT = 408 - 408 Request Timeout

  • CONFLICT = 409 - 409 Conflict

  • GONE = 410 - 410 Gone

  • LENGTH_REQUIRED = 411 - 411 Length Required

  • PRECONDITION_FAILED = 412 - 412 Precondition Failed

  • PAYLOAD_TOO_LARGE = 413 - 413 Payload Too Large

  • URI_TOO_LONG = 414 - 414 URI Too Long

  • UNSUPPORTED_MEDIA_TYPE = 415 - 415 Unsupported Media Type

  • RANGE_NOT_SATISFIABLE = 416 - 416 Range Not Satisfiable

  • EXPECTATION_FAILED = 417 - 417 Expectation Failed

  • MISDIRECTED_REQUEST = 421 - 421 Misdirected Request

  • UNPROCESSABLE_ENTITY = 422 - 422 Unprocessable Entity

  • LOCKED = 423 - 423 Locked

  • FAILED_DEPENDENCY = 424 - 424 Failed Dependency

  • UPGRADE_REQUIRED = 426 - 426 Upgrade Required

  • PRECONDITION_REQUIRED = 428 - 428 Precondition Required

  • TOO_MANY_REQUESTS = 429 - 429 Too Many Requests

  • REQUEST_HEADER_FIELDS_TOO_LARGE = 431 - 431 Request Header Fields Too Large

  • UNAVAILABLE_FOR_LEGAL_REASONS = 451 - 451 Unavailable For Legal Reasons

  • INTERNAL_SERVER_ERROR = 500 - 500 Internal Server Error

  • NOT_IMPLEMENTED = 501 - 501 Not Implemented

  • BAD_GATEWAY = 502 - 502 Bad Gateway

  • SERVICE_UNAVAILABLE = 503 - 503 Service Unavailable

  • GATEWAY_TIMEOUT = 504 - 504 Gateway Timeout

  • HTTP_VERSION_NOT_SUPPORTED = 505 - 505 HTTP Version Not Supported

  • VARIANT_ALSO_NEGOTIATES = 506 - 506 Variant Also Negotiates

  • INSUFFICIENT_STORAGE = 507 - 507 Insufficient Storage

  • LOOP_DETECTED = 508 - 508 Loop Detected

  • NOT_EXTENDED = 510 - 510 Not Extended

  • NETWORK_AUTHENTICATION_REQUIRED = 511 - 511 Network Authentication Required

ws_opcode

WebSocket frame opcode.

Values:

  • WS_OPCODE_CONTINUE = 0 - Continuation frame

  • WS_OPCODE_TEXT = 1 - Text frame

  • WS_OPCODE_BINARY = 2 - Binary frame

  • WS_OPCODE_CLOSE = 8 - Close connection

  • WS_OPCODE_PING = 9 - Ping keepalive

  • WS_OPCODE_PONG = 10 - Pong reply

ws_session_type

WebSocket session type.

Values:

  • WS_CLIENT = 0 - Client session

  • WS_SERVER = 1 - Server session

4.3.2. Handled structures

HttpMessage

Base type for HTTP messages, providing header access.

HttpResponse

HTTP response with status code, headers, and body.

Fields:

  • body : das_string - Response body content.

  • content : void? - Content string.

  • status_code : http_status - HTTP status code.

WebSocketClient

Low-level WebSocket client handle. Use HvWebSocketClient for a higher-level API.

HttpRequest

HTTP request with URL, method, headers, body, and parameters.

Fields:

  • body : das_string - Request body content.

  • method : http_method - HTTP method (GET, POST, etc.).

  • url : das_string - Full request URL.

  • scheme : das_string - URL scheme (http or https).

  • host : das_string - Host name.

  • port : int - Port number.

  • path : das_string - URL path component.

  • timeout : uint16 - Overall request timeout in seconds.

  • connect_timeout : uint16 - Connection timeout in seconds.

HttpResponseWriter

HTTP response writer for streaming responses. Supports chunked transfer encoding and SSE events. Obtained through async HTTP handlers registered with SSE.

HttpContext

HTTP request/response context passed to route handlers.

WebSocketChannel

A connected WebSocket channel for sending messages to a client.

WebSocketServer

Low-level WebSocket/HTTP server handle. Use HvWebServer for a higher-level API.

4.3.3. WebSocket client

close(self: WebSocketClient): int

Closes the WebSocket client connection. Returns 0 on success.

Arguments:
is_connected(self: WebSocketClient): bool

Returns true if the WebSocket client is currently connected.

Arguments:
make_web_socket_client(class: void?; info: StructInfo const?): WebSocketClient?

Creates a new low-level WebSocket client bound to a daScript class instance.

Arguments:

  • class : void? implicit

  • info : StructInfo? implicit

open(self: WebSocketClient; url: string): int

Opens a WebSocket connection to the specified URL. Returns 0 on success.

Arguments:

4.3.3.1. send

send(channel: WebSocketChannel?; msg: string; opcode: ws_opcode; fin: bool): int

Sends a WebSocket message through a channel with the specified opcode and fin flag.

Arguments:
send(self: WebSocketClient; msg: string; len: int; opcode: ws_opcode): int
send(channel: WebSocketChannel?; msg: string; len: int; opcode: ws_opcode; fin: bool): int
send(self: WebSocketClient; msg: string): int
send(channel: WebSocketChannel?; msg: string; len: int; fragment: int; opcode: ws_opcode): int

4.3.3.2. tick

tick(server: WebSocketServer?)

Processes pending events on the server or client; must be called periodically.

Arguments:
tick(self: WebSocketClient)

4.3.4. WebSocket server lifecycle

make_web_socket_server(port: int; https_port: int; pathToCert: string; class: void?; info: StructInfo const?): WebSocketServer?

Creates a new low-level WebSocket/HTTP server on the given port, optionally with TLS.

Arguments:

  • port : int

  • https_port : int

  • pathToCert : string implicit

  • class : void? implicit

  • info : StructInfo? implicit

start(server: WebSocketServer?): int

Starts the server, spawning network threads. Returns 0 on success.

Arguments:
stop(server: WebSocketServer?): int

Stops the server. Returns 0 on success.

Arguments:

4.3.5. WebSocket channel send

4.3.6. HTTP route registration

ANY(server: WebSocketServer?; url: string; lambda: lambda<():void>)

Warning

This is unsafe operation.

Registers a route handler that matches any HTTP method.

Arguments:

  • server : WebSocketServer? implicit

  • url : string implicit

  • lambda : lambda<void>

4.3.6.1. DELETE

DELETE(url: string; block: block<(HttpResponse?):void>)

Registers a DELETE route handler, or performs an HTTP DELETE client request.

Arguments:

  • url : string implicit

  • block : block<( HttpResponse?):void> implicit

DELETE(server: WebSocketServer?; url: string; lambda: lambda<():void>)
DELETE(url: string; headers: table<string, string>; block: block<(HttpResponse?):void>)

4.3.6.2. GET

GET(url: string; headers: table<string, string>; block: block<(HttpResponse?):void>)

Registers a GET route handler, or performs an HTTP GET client request.

Arguments:

  • url : string implicit

  • headers : table<string;string> implicit

  • block : block<( HttpResponse?):void> implicit

GET(url: string; block: block<(HttpResponse?):void>)
GET(server: WebSocketServer?; url: string; lambda: lambda<():void>)

4.3.6.4. PATCH

PATCH(server: WebSocketServer?; url: string; lambda: lambda<():void>)

Warning

This is unsafe operation.

Registers a PATCH route handler, or performs an HTTP PATCH client request.

Arguments:

  • server : WebSocketServer? implicit

  • url : string implicit

  • lambda : lambda<void>

PATCH(url: string; text: string; block: block<(HttpResponse?):void>)
PATCH(url: string; text: string; headers: table<string, string>; block: block<(HttpResponse?):void>)
PATCH(url: string; text: string; headers: table<string, string>; from: table<string, string>; block: block<(HttpResponse?):void>)

4.3.6.5. POST

POST(url: string; text: string; headers: table<string, string>; block: block<(HttpResponse?):void>)

Registers a POST route handler, or performs an HTTP POST client request.

Arguments:

  • url : string implicit

  • text : string implicit

  • headers : table<string;string> implicit

  • block : block<( HttpResponse?):void> implicit

POST(url: string; text: string; block: block<(HttpResponse?):void>)
POST(url: string; text: string; headers: table<string, string>; from: table<string, string>; block: block<(HttpResponse?):void>)
POST(server: WebSocketServer?; url: string; lambda: lambda<():void>)

4.3.6.6. PUT

PUT(url: string; text: string; block: block<(HttpResponse?):void>)

Registers a PUT route handler, or performs an HTTP PUT client request.

Arguments:

  • url : string implicit

  • text : string implicit

  • block : block<( HttpResponse?):void> implicit

PUT(url: string; text: string; headers: table<string, string>; block: block<(HttpResponse?):void>)
PUT(server: WebSocketServer?; url: string; lambda: lambda<():void>)
PUT(url: string; text: string; headers: table<string, string>; from: table<string, string>; block: block<(HttpResponse?):void>)
SSE(server: WebSocketServer?; url: string; lambda: lambda<():void>)

Warning

This is unsafe operation.

Registers an SSE (Server-Sent Events) handler on the server for the given URL path. Uses ANY method matching so both GET and POST requests reach the handler. The lambda receives the request and response and returns an HTTP status code.

Arguments:

  • server : WebSocketServer? implicit

  • url : string implicit

  • lambda : lambda<void>

4.3.7. HTTP server configuration

STATIC(server: WebSocketServer?; path: string; dir: string)

Serves static files from a directory under the given URL path prefix.

Arguments:

  • server : WebSocketServer? implicit

  • path : string implicit

  • dir : string implicit

allow_cors(server: WebSocketServer?)

Enables cross-origin resource sharing (CORS) on the server.

Arguments:
set_document_root(server: WebSocketServer?; dir: string)

Sets the document root directory for static file serving.

Arguments:
set_error_page(server: WebSocketServer?; filename: string)

Sets a custom error page filename.

Arguments:
set_home_page(server: WebSocketServer?; filename: string)

Sets the default home page filename (e.g., index.html).

Arguments:
set_index_of(server: WebSocketServer?; dir: string)

Enables directory listing for the specified directory.

Arguments:

4.3.8. HTTP response helpers

DATA(response: HttpResponse?; data: string; length: int; status: http_status = dashv::http_status.OK): http_status

Sends raw data as the response body with the given status code.

Arguments:
JSON(response: HttpResponse?; json_string: string; status: http_status = dashv::http_status.OK): http_status

Sends a JSON response with the given status code.

Arguments:
REDIRECT(response: HttpResponse?; location: string; status: http_status): http_status

Sends an HTTP redirect response to the specified location.

Arguments:
SERVE_FILE(response: HttpResponse?; filepath: string): http_status

Sends a file as the response body, setting the content type automatically.

Arguments:

  • response : HttpResponse? implicit

  • filepath : string implicit

TEXT_PLAIN(response: HttpResponse?; text: string; status: http_status = dashv::http_status.OK): http_status

Sends a plain-text response with the given status code.

Arguments:

4.3.8.1. set_content_type

set_content_type(response: HttpResponse?; content_type: string)

Sets the Content-Type header on a response or request.

Arguments:

  • response : HttpResponse? implicit

  • content_type : string implicit

set_content_type(request: HttpRequest?; content_type: string)

4.3.8.2. set_header

set_header(response: HttpResponse?; key: string; value: string)

Sets a response or request header.

Arguments:

  • response : HttpResponse? implicit

  • key : string implicit

  • value : string implicit

set_header(request: HttpRequest?; key: string; value: string)

4.3.9. HTTP client requests

request(request: HttpRequest?; block: block<(HttpResponse?):void>)

Sends an HTTP request configured via an HttpRequest object and invokes the block with the response.

Arguments:

4.3.9.1. request_cb

request_cb(request: HttpRequest?; on_body: block<(uint8 const?;int):void>; on_complete: block<(HttpResponse?):void>)

Sends an HTTP request and invokes on_body with raw bytes (uint8? pointer and size) for each body chunk as it arrives, then calls on_complete with the final response. Use this for binary streaming or when exact byte counts are needed.

Arguments:

  • request : HttpRequest? implicit

  • on_body : block<(uint8?;int):void> implicit

  • on_complete : block<( HttpResponse?):void> implicit

request_cb(request: HttpRequest?; on_body: block<(string):void>; on_complete: block<(HttpResponse?):void>)
status_message(response: HttpResponse?): string

Returns the status message string for the given HTTP response.

Arguments:

4.3.10. Message and header access

HttpResponse.content_length(self: HttpResponse): int

Returns the content length of the HTTP response body.

Arguments:
each_header(message: HttpMessage?; block: block<(string;string):void>)

Iterates over all headers of an HTTP message, invoking the block with each key-value pair.

Arguments:

  • message : HttpMessage? implicit

  • block : block<(string;string):void> implicit

get_header(message: HttpMessage?; key: string): string

Returns the value of a specific HTTP header from a message.

Arguments:

  • message : HttpMessage? implicit

  • key : string implicit

4.3.11. Request configuration

allow_redirect(request: HttpRequest?; on: bool)

Enables or disables automatic following of HTTP redirects.

Arguments:
each_param(request: HttpRequest?; block: block<(string;string):void>)

Iterates over all query parameters of an HTTP request, invoking the block with each key-value pair.

Arguments:

  • request : HttpRequest? implicit

  • block : block<(string;string):void> implicit

get_param(request: HttpRequest?; key: string): string

Returns the value of a query parameter from an HTTP request.

Arguments:

  • request : HttpRequest? implicit

  • key : string implicit

set_basic_auth(request: HttpRequest?; username: string; password: string)

Sets HTTP Basic authentication credentials on a request.

Arguments:

  • request : HttpRequest? implicit

  • username : string implicit

  • password : string implicit

set_bearer_token_auth(request: HttpRequest?; token: string)

Sets a Bearer token authentication header on a request.

Arguments:

  • request : HttpRequest? implicit

  • token : string implicit

set_connect_timeout(request: HttpRequest?; seconds: int)

Sets the connection timeout in seconds.

Arguments:
set_param(request: HttpRequest?; key: string; value: string)

Sets a query parameter on an HTTP request.

Arguments:

  • request : HttpRequest? implicit

  • key : string implicit

  • value : string implicit

set_timeout(request: HttpRequest?; seconds: int)

Sets the overall request timeout in seconds.

Arguments:

4.3.12. Cookies

4.3.13. Form data

each_form_field(request: HttpRequest?; block: block<(string;string;string):void>)

Iterates over all form fields of a server-side request, invoking the block with name, filename, and content type.

Arguments:

  • request : HttpRequest? implicit

  • block : block<(string;string;string):void> implicit

get_form_data(request: HttpRequest?; name: string): string

Returns the value of a form field from a server-side request.

Arguments:

  • request : HttpRequest? implicit

  • name : string implicit

get_url_encoded(request: HttpRequest?; key: string): string

Returns the value of a URL-encoded form field from a server-side request.

Arguments:

  • request : HttpRequest? implicit

  • key : string implicit

save_form_file(request: HttpRequest?; name: string; path: string): int

Saves an uploaded form file to disk. Returns 0 on success.

Arguments:

  • request : HttpRequest? implicit

  • name : string implicit

  • path : string implicit

set_form_data(request: HttpRequest?; name: string; value: string)

Sets a form field value on a multipart request.

Arguments:

  • request : HttpRequest? implicit

  • name : string implicit

  • value : string implicit

set_form_file(request: HttpRequest?; name: string; filepath: string)

Attaches a file to a multipart request.

Arguments:

  • request : HttpRequest? implicit

  • name : string implicit

  • filepath : string implicit

set_url_encoded(request: HttpRequest?; key: string; value: string)

Sets a URL-encoded form field on a request.

Arguments:

  • request : HttpRequest? implicit

  • key : string implicit

  • value : string implicit

4.3.14. SSE response writer

close_writer(writer: HttpResponseWriter?): int

Closes the response writer’s underlying connection. Use this to forcefully terminate a long-lived streaming connection. Returns 0 on success.

Arguments:
end_headers(writer: HttpResponseWriter?; key: string; value: string): int

Sends the response headers through the writer, adding one final header (key/value pair). Call this before writing body chunks or SSE events. Returns 0 on success.

Arguments:
end_response(writer: HttpResponseWriter?): int

Ends the chunked response by sending a zero-length terminating chunk. Call this after all data has been written to signal the end of the response. Returns 0 on success.

Arguments:
release_writer(server: WebSocketServer?; writer: HttpResponseWriter?)

Releases the server’s reference to a response writer, allowing it to be destroyed. Call this after end_response or close_writer to free the writer’s resources.

Arguments:
sse_event(writer: HttpResponseWriter?; data: string; event: string): int

Sends an SSE event through the response writer. Formats the data and event type according to the SSE wire protocol. Returns 0 on success.

Arguments:
write_chunked(writer: HttpResponseWriter?; data: string; length: int): int

Writes a chunk of data through the response writer using HTTP chunked transfer encoding. Returns 0 on success.

Arguments: