HTTP Server Functions
Working with HTTP servers and requests.
http-server
Creates a new HTTP server that listens on the specified address with a 10-second read header timeout.
addr String containing the server address (e.g., "
returns native Go-server object that can handle HTTP requests
http-server ":8080" |type?
; returns nativehttp-server 8080
; correctly causes error:
; `http-server`: first argument must be: String. Go-server//Serve
Starts the HTTP server listening and serving requests on the configured address (blocking call).
server Native Go-server object created by http-server
returns the server object after starting listening, or error if unable to serve
srv: http-server ":8080"
srv .Serve
Go-server//Handle
Registers an HTTP handler for a specific path pattern on the server, accepting string responses, Rye functions, or native Go handlers.
server Native Go-server object
path String URL path to handle (e.g., "/", "/api", "/static")
handler String (simple response), Function (w req -> response), or Native HTTP handler
returns the server object to allow method chaining
srv: http-server ":8080"
srv .Handle "/" "Hello World!"
srv .Handle "/api" fn { w req } { w .Write "API response" }
Go-server-response-writer//Write
Writes string content to the HTTP response body, used within HTTP request handlers to send response data to clients.
writer Native Go-server-response-writer object from HTTP handler
content String content to write to the HTTP response body
returns the response writer object for method chaining
; Inside a handler function { w req }:
; write w "Hello World!"
; w .Write "Response content"
Go-server-response-writer//Set-content-type
Sets the Content-Type header for the HTTP response, determining how the browser interprets the response data.
writer Native Go-server-response-writer object from HTTP handler
contentType String MIME type (e.g., "text/html", "application/json", "image/png")
returns the response writer object for method chaining
; Inside a handler: w .Set-content-type "application/json"
; Inside a handler: w .Set-content-type "text/html"
Go-server-response-writer//Set-header
Sets a custom HTTP header in the response, allowing control over caching, security, and other HTTP behaviors.
writer Native Go-server-response-writer object from HTTP handler
name Word representing the header name (e.g., 'cache-control, 'x-custom-header)
value String value to set for the header
returns the response writer object for method chaining
; Inside a handler: w .Set-header 'cache-control "no-cache"
; Inside a handler: w .Set-header 'x-custom-header "custom-value"
Go-server-response-writer//Add-header
Adds a custom HTTP header value in the response, preserving existing values for multi-value headers.
writer Native Go-server-response-writer object from HTTP handler
name Word representing the header name (e.g., 'set-cookie, 'vary)
value String value to add for the header
returns the response writer object for method chaining
; Inside a handler: w .Add-header 'set-cookie "a=1; Path=/; HttpOnly"
; Inside a handler: w .Add-header 'vary "Accept-Encoding"
Go-server-response-writer//Write-header
Sets the HTTP status code for the response (must be called before writing response body).
writer Native Go-server-response-writer object from HTTP handler
code Integer HTTP status code (200=OK, 404=Not Found, 500=Internal Server Error, etc.)
returns the response writer object for method chaining
; Inside a handler: w .Write-header 404
; Inside a handler: w .Write-header 200
; Inside a handler: w .Write-header 500
Go-server//Handle-ws
Registers a WebSocket handler for a specific path pattern on the server, upgrading HTTP connections to WebSocket protocol.
server Native Go-server object
path String URL path to handle WebSocket connections (e.g., "/ws")
handler Function that receives a WebSocket connection object
returns the server object to allow method chaining
; srv: http-server ":8080"
; srv .Handle-ws "/ws" fn { conn } { forever { msg: conn .Read , conn .Write "GOT: " + msg } }
Go-server-websocket//Read
Reads a message from a WebSocket connection, blocking until data is available or an error occurs.
conn Native Go-server-websocket connection object
returns string containing the message read from the WebSocket, or error if read fails
; conn .Read ; returns the message string received from the WebSocket client
Go-server-websocket//Write
Writes a message to a WebSocket connection, sending data to the connected client.
conn Native Go-server-websocket connection object
message String message to send to the WebSocket client
returns the message string on success, or error if write fails
; conn .Write "Hello from server"
Go-server-request//Query?
Retrieves a query parameter value from the HTTP request URL (e.g., from ?name=value&other=data).
request Native Go-server-request object from HTTP handler
key String name of the query parameter to retrieve
returns string value of the query parameter, or error if key is missing
; Inside a handler with request URL "/api?name=john&age=25":
; equal { req .Query? "name" } "john"
; equal { req .Query? "age" } "25"
; error { req .Query? "missing" }
Go-server-request//Header?
Gets a header value from the HTTP request by name.
request Native Go-server-request object from HTTP handler
name String header name to retrieve (e.g., "authorization", "content-type")
returns string header value (empty string if header is missing)
; Inside a handler: req .Header? "authorization"
; Inside a handler: req .Header? "content-type"
Go-server-request//Basic-auth?
Gets HTTP Basic Authentication credentials from the request as [username password].
request Native Go-server-request object from HTTP handler
returns block with username and password strings when Basic Auth is presenterror when Basic Auth credentials are missing
; Inside a handler: creds: req .Basic-auth?
; user: creds |first
; pass: creds |second
Go-server-request//Method?
Gets the HTTP request method.
request Native Go-server-request object from HTTP handler
returns string containing HTTP method (GET, POST, PUT, DELETE, ...)
; Inside a handler: req .Method?
; equal { req .Method? } "GET"
Go-server-request//Read-body
Reads the HTTP request body as a string.
request Native Go-server-request object from HTTP handler
returns string containing the request body
; Inside a handler: body: req .Read-body
; Inside a handler: print body
Go-server-request//Headers?
Gets all HTTP request headers as a dictionary.
request Native Go-server-request object from HTTP handler
returns dict containing all request headers
; Inside a handler: req .Headers?
; Inside a handler: req .Headers? |print
Go-server-request//Url?
Extracts the URL object from an HTTP request, providing access to path, query parameters, and other URL components.
request Native Go-server-request object from HTTP handler
returns native Go-server-url object containing the parsed request URL
; Inside a handler: url: req .Url?
; equal { url .type? } 'native
; error { "not-request" .Url? }
Go-server-url//Path?
Extracts the path component from a URL object (the part after the domain and before query parameters).
url Native Go-server-url object from request URL
returns string containing the path portion of the URL (without query parameters)
; Inside a handler with request to "/api/users/123":
; url: req .Url?
; equal { url .Path? } "/api/users/123"
; error { "not-url" .Path? }
Http-handler//Strip-prefix
Wraps an HTTP handler to strip a URL prefix from requests, useful for serving static files from a subdirectory.
handler Native Http-handler object (e.g., from new-static-handler)
prefix String URL prefix to strip from requests before passing to the handler
returns new Http-handler that strips the prefix from incoming request paths
; handler: new-static-handler %static/
; stripped: handler .Strip-prefix "/static/"
https-response//Status?
Gets the HTTP status code from a response object.
response native https-response object
returns integer containing the HTTP status code (200, 404, 500, etc.)
https-response//Status-text?
Gets the HTTP status text from a response object.
response native https-response object
returns string containing the HTTP status text (OK, Not Found, Internal Server Error, etc.)
Email Message
Creating and configuring email messages
email-message
Creates a new empty email message object that can be configured with headers, body, and attachments.
(none)
returns native gomail-message object for building email content
msg: email-message
equal { msg |type? } 'native
gomail-message//Set-header
Sets a standard email header field such as Subject, To, From, Cc, or Bcc with the specified value.
message Native gomail-message object
field String or Tagword representing header name (e.g., "Subject", 'to, 'from)
value String or Email containing the header value
returns the message object for method chaining
msg: email-message
msg .Set-header "Subject" "Test Email"
msg .Set-header 'to "user@example.com"
error { msg .Set-header "Subject" 123 }
gomail-message//Set-address-header
Sets an email address header with both email address and display name, commonly used for From, To, Cc, and Bcc fields.
message Native gomail-message object
field String header field name (e.g., "From", "To", "Cc", "Bcc")
address String email address
name String display name for the email address
returns the message object for method chaining
gomail-message//Set-body
Sets the main body content of the email with the specified MIME content type, supporting plain text and HTML formats.
message Native gomail-message object
contentType String MIME content type (e.g., "text/plain", "text/html")
content String containing the email body content
returns the message object for method chaining
gomail-message//Attach
Attaches a file to the email message using a file URI, making the file available as an email attachment.
message Native gomail-message object
file Uri pointing to the file to attach (must use file
returns the message object for method chaining
gomail-message//Add-alternative
Adds alternative content to the email (e.g., HTML version alongside plain text), allowing email clients to choose their preferred format.
message Native gomail-message object
contentType String MIME content type for the alternative content
content String containing the alternative body content
returns the message object for method chaining
new-email-dialer
Creates a new SMTP dialer configured with server details and authentication credentials for sending emails.
server String SMTP server hostname (e.g., "smtp.gmail.com", "mail.example.com")
port Integer SMTP port number (commonly 25, 465, 587, or 2525)
username String username for SMTP authentication
password String password for SMTP authentication
returns native gomail-dialer object configured for sending emails
gomail-dialer//Dial-and-send
Connects to the SMTP server and sends the specified email message, handling authentication and delivery.
dialer Native gomail-dialer object configured with SMTP settings
message Native gomail-message object containing the email to send
returns the dialer object on success, or error object if sending fails
Email parsing functions
reader//Parse-email
Parses email data from a reader.
reader native reader object containing email data
returns native parsed-email object
equal { reader %email.eml |parse-email |type? } 'native
equal { reader %email.eml |parse-email |kind? } 'parsed-email
parsed-email//Subject?
Gets the subject from a parsed email.
email native parsed-email object
returns string containing the email subject
equal { reader %email.eml |parse-email |subject? |type? } 'string
parsed-email//Message-id?
Gets the message ID from a parsed email.
email native parsed-email object
returns string containing the email message ID
equal { reader %email.eml |parse-email |message-id? |type? } 'string
parsed-email//Html-body?
Gets the HTML body from a parsed email.
email native parsed-email object
returns string containing the HTML body of the email
equal { reader %email.eml |parse-email |html-body? |type? } 'string
parsed-email//Text-body?
Gets the plain text body from a parsed email.
email native parsed-email object
returns string containing the plain text body of the email
equal { Reader %email.eml |parse-email |text-body? |type? } 'string
parsed-email//Attachments?
Gets the attachments from a parsed email.
email native parsed-email object
returns native object containing email attachments
parsed-email//Embedded-files?
Gets the embedded files from a parsed email.
email native parsed-email object
returns native object containing embedded files from the email
SMTP Server Functions
Creating and running SMTP mail servers.
smtp-server
Creates a new SMTP server that can receive incoming email messages on the specified address.
address String containing the server address (e.g., "
returns native smtpd object configured to listen on the specified address
smtp-server 2525 |type?
; returns nativesmtp-server ":2525" |kind?
; returns smtpdsmtpd//Serve
Starts the SMTP server listening for incoming emails and calls the handler function for each received message.
server Native smtpd object created by smtp-server
handler Function that processes incoming emails (reader from to origin -> ...)
appname String name for the SMTP server application
password String password for SMTP authentication (empty string for no auth)
returns the server object after starting to listen, or error if unable to serve
handler: fn { reader from to origin } { print "Got email from:" from }
smtp-server ":2525"
|Serve handler "TestSMTP" ""
MQTT Client Functions
mqtt-uri//Open
Opens a connection to an MQTT broker.
uri MQTT broker URI (format
returns native MQTT client connection (type: "mqtt-client")error if connection fails
; Connect to MQTT broker and subscribe to topics
client: Open mqtt://localhost:1883/my-client
client .Subscribe "sensors/+" 1 fn { payload msg } {
print "Topic: " + msg -> "topic"
print "Data: " + payload
}
; Publish messages
client .Publish-simple "sensors/temperature" "23.5"
client .Publish "sensors/humidity" "65" 1 0
; Clean up
client .Disconnect
mqtt-client//Disconnect
Disconnects from the MQTT broker.
client MQTT client connection (type
returns integer 1 for successerror if disconnection fails
mqtt-client//Close
Closes the MQTT client connection (alias for Disconnect).
client MQTT client connection (type
returns integer 1 for successerror if close fails
client: Open mqtt://localhost:1883/my-client client .Close |type?
; returns integermqtt-client//Publish
Publishes a message to an MQTT topic with specified QoS and retain flag.
client MQTT client connection (type
topic Topic to publish to (string)
payload Message payload (string)
qos Quality of Service level (integer 0, 1, or 2)
retain Whether message should be retained (boolean)
returns integer 1 for successerror if publish fails
mqtt-client//Publish-simple
Publishes a message to an MQTT topic with default settings (QoS 0, no retain).
client MQTT client connection (type
topic Topic to publish to (string)
payload Message payload (string)
returns integer 1 for success (uses QoS 0, no retain)error if publish fails
mqtt-client//Subscribe
Subscribes to an MQTT topic with a message handler function.
client MQTT client connection (type
topic Topic pattern to subscribe to (string, can include wildcards)
qos Quality of Service level (integer 0, 1, or 2)
handler Callback function to handle received messages
returns integer 1 for successerror if subscription fails
mqtt-client//Subscribe-simple
Subscribes to an MQTT topic with default QoS 0 and a message handler function.
client MQTT client connection (type
topic Topic pattern to subscribe to (string)
handler Callback function to handle received messages
returns integer 1 for success (uses QoS 0)error if subscription fails
mqtt-client//Unsubscribe
Unsubscribes from an MQTT topic.
client MQTT client connection (type
topic Topic to unsubscribe from (string)
returns integer 1 for successerror if unsubscription fails
mqtt-client//Is-connected
Checks if the MQTT client is currently connected to the broker.
client MQTT client connection (type
returns integer 1 if connected, 0 if not connected
mqtt-options
Creates a new MQTT client options object for advanced configuration.
returns new MQTT client options object (type: "mqtt-options")
mqtt-options//Set-broker
Sets the MQTT broker address in the options.
options MQTT options object (type
broker Broker URI string
returns the same options object (for method chaining)
mqtt-options//Set-client-id
Sets the client ID in the MQTT options.
options MQTT options object (type
client-id Client identifier string
returns the same options object (for method chaining)
mqtt-options//Set-keep-alive
Sets the keep alive interval in seconds.
options MQTT options object (type
seconds Keep alive interval in seconds (integer)
returns the same options object (for method chaining)
mqtt-options//Set-username
Sets the username for MQTT authentication.
options MQTT options object (type
username Username string for MQTT authentication
returns the same options object (for method chaining)
mqtt-options//Set-password
Sets the password for MQTT authentication.
options MQTT options object (type
password Password string for MQTT authentication
returns the same options object (for method chaining)
mqtt-options//Set-will
Sets the Last Will and Testament message with QoS and retain flag.
options MQTT options object (type
topic Will topic string
payload Will message payload string
qos Quality of Service level for will message (integer 0, 1, or 2)
retain Whether will message should be retained (integer 0 = false, 1 = true)
returns the same options object (for method chaining)
mqtt-options//Connect-with-options
Creates and connects an MQTT client using the configured options.
options MQTT options object (type
returns native MQTT client connection (type: "mqtt-client")error if connection fails