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

WebSocket client / server / channel objects are exposed to daScript as value-sized Handle<T> integers backed by HandleRegistry<T>. For leak diagnostics on these handles (and an overview of the other built-in leak detectors) see 6. HandleRegistry (dasHV handle objects) in the Memory Leak Detection — Diagnostics Cheat Sheet guide.

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

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.

HttpContext

HTTP request/response context passed to route handlers.

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.

HttpResponseWriter

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

4.3.3. Handled types

WebSocketClient

Opaque handle to an outbound WebSocket connection. Created by make_web_socket_client and released by destroy_web_socket_client; used by the HvWebSocketClient wrapper class.

WebSocketChannel

Opaque handle to a server-side WebSocket client connection. Passed to onWsOpen / onWsMessage / onWsClose and to send; becomes dead after the peer disconnects.

WebSocketServer

Opaque handle to a running HTTP/WebSocket server. Created by make_web_socket_server and released by destroy_web_socket_server; used by the HvWebServer wrapper class.

4.3.4. WebSocket client

close(self: WebSocketClient): int

Closes the WebSocket client connection. Returns 0 on success.

Arguments:
destroy_web_socket_client(arg0: WebSocketClient): bool

Releases the client handle. Returns true if the handle was live, false if already dead.

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.4.1. send

send(self: WebSocketClient; msg: string): int

Sends a text message over the WebSocket client connection. Returns the number of bytes sent, or a negative error code.

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

4.3.4.2. tick

tick(server: WebSocketServer)

Drains one batch of queued HTTP/WebSocket events and invokes the user callbacks. Call periodically from the owning thread.

Arguments:
tick(self: WebSocketClient)

4.3.5. WebSocket server lifecycle

destroy_web_socket_server(arg0: WebSocketServer): bool

Releases the server handle. Returns true if the handle was live. When this drops the last reference, ~hv::WebSocketServer runs and stops the background workers; call stop() explicitly if you keep other references to the server.

Arguments:
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’s background workers. Returns 0 on success, a negative error code otherwise.

Arguments:
stop(server: WebSocketServer): int

Stops the server and drains pending events. Returns 0 on success.

Arguments:

4.3.6. WebSocket channel send

4.3.7. Handle operations

WebSocketChannel!=(arg0: WebSocketChannel; arg1: WebSocketChannel): bool

Handle inequality: returns true if the two handles refer to different channels (or at least one is null).

Arguments:
WebSocketChannel==(arg0: WebSocketChannel; arg1: WebSocketChannel): bool

Handle equality: returns true if both refer to the same channel.

Arguments:
WebSocketClient!=(arg0: WebSocketClient; arg1: WebSocketClient): bool

Handle inequality: returns true if the two handles refer to different clients (or at least one is null).

Arguments:
WebSocketClient==(arg0: WebSocketClient; arg1: WebSocketClient): bool

Handle equality: returns true if both refer to the same client.

Arguments:
WebSocketServer!=(arg0: WebSocketServer; arg1: WebSocketServer): bool

Handle inequality: returns true if the two handles refer to different servers (or at least one is null).

Arguments:
WebSocketServer==(arg0: WebSocketServer; arg1: WebSocketServer): bool

Handle equality: returns true if both refer to the same live server.

Arguments:

4.3.7.1. is_alive

is_alive(arg0: WebSocketServer): bool

Returns true if the server handle is still live (not destroyed).

Arguments:
is_alive(arg0: WebSocketClient): bool
is_alive(arg0: WebSocketChannel): bool

4.3.8. HTTP route registration

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

Warning

This is unsafe operation.

Registers a handler that matches any HTTP method (GET/POST/PUT/etc) for the given URL path.

Arguments:

4.3.8.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.8.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.8.4. PATCH

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

Warning

This is unsafe operation.

Registers an HTTP PATCH handler for the given URL path.

Arguments:
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.8.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.8.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 a Server-Sent Events (SSE) streaming handler for the given URL path.

Arguments:

4.3.9. HTTP server configuration

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

Registers a static-file route: serves files under dir at the URL prefix path.

Arguments:
allow_cors(server: WebSocketServer)

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

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

Sets the root directory used for serving static files.

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

Sets the file served when the server returns an error response.

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

Sets the file served when a request maps to a directory (e.g. index.html).

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

Enables directory listing for the given directory path.

Arguments:

4.3.10. 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.10.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.10.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.11. 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.11.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.12. 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.13. 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.14. Cookies

4.3.15. 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.16. 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 a chunked/SSE response writer previously obtained from the server.

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: