Mesch.Jyro.Http 0.1.1

Jyro HTTP Functions

HTTP functions for the Jyro scripting language. This package provides network access as an opt-in capability. With this package, hosts can explicitly enable HTTP by calling .UseHttpFunctions() on the builder.

Setup

This library provides the namespace Mesch.Jyro.Http

using Mesch.Jyro.Http;

Then register the builder.

// Basic — uses a default HttpClient
var result = new JyroBuilder()
    .WithSource(script)
    .WithData(data)
    .UseHttpFunctions()
    .Execute();

// Configured — inject your own HttpClient, restrict domains, etc.
var result = new JyroBuilder()
    .WithSource(script)
    .WithData(data)
    .UseHttpFunctions(options => {
        options.HttpClient = myHttpClient;
        options.AllowedDomains = ["api.example.com"];
        options.DefaultTimeout = TimeSpan.FromSeconds(10);
        options.DefaultHeaders = new Dictionary<string, string> {
            ["X-Api-Key"] = "..."
        };
    })
    .Execute();

Configuration Options

Encoding-Only Mode

To register UrlEncode, UrlDecode, and FormEncode without allowing outbound HTTP requests, clear the allowed methods:

var result = new JyroBuilder()
    .WithSource(script)
    .WithData(data)
    .UseHttpFunctions(options => {
        options.AllowedHttpMethods.Clear();
    })
    .Execute();

Any call to InvokeRestMethod will throw a runtime error. The encoding functions work normally.

InvokeRestMethod

Performs a synchronous HTTP request and returns a structured response object.

Signature

InvokeRestMethod(string method, string url, object headers?, any body?)

Parameters

• method (string, required): The HTTP method. Supported values: "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS". Case-insensitive.
• url (string, required): The full URL. Must use http or https scheme.
• headers (object, optional): Key-value pairs added as request headers. Script headers override default headers from options.
• body (any, optional): The request body. Objects, arrays, numbers, and booleans are serialized as JSON with Content-Type: application/json. Strings are sent as-is with Content-Type: text/plain. Set Content-Type in the headers object to override.

Returns

• object: A response object with the following properties:

Description

Executes a blocking HTTP request using the host-provided HttpClient. All blocking operations (rate-limit waits, the HTTP request, and response body reading) respect the execution context's CancellationToken, so the host's resource limiter and external cancellation signals can terminate in-flight work. Non-2xx responses do not throw — the script inspects statusCode and decides how to handle errors. If the host configured an AllowedDomains whitelist, requests to unlisted domains throw a runtime error.

Examples

# Simple GET
var response = InvokeRestMethod("GET", "https://api.example.com/users")
if response.isSuccess then
    Data.users = response.body
else
    fail "API error: " + response.statusCode
end

# POST with JSON body
var payload = {"name": "Alice", "email": "alice@example.com"}
var response = InvokeRestMethod("POST", "https://api.example.com/users", null, payload)
Data.newUserId = response.body.id

# With custom headers
var headers = {"Authorization": "Bearer " + Data.token}
var response = InvokeRestMethod("GET", "https://api.example.com/me", headers)
Data.profile = response.body

# PUT with headers and body
var headers = {
    "Authorization": "Bearer " + Data.token,
    "X-Request-Id": NewGuid()
}
var body = {"status": "active"}
var response = InvokeRestMethod("PUT", "https://api.example.com/users/1", headers, body)

# Check status codes explicitly
var response = InvokeRestMethod("GET", "https://api.example.com/item/999")
if response.statusCode == 404 then
    Data.error = "Item not found"
elseif not response.isSuccess then
    fail "Unexpected error: " + response.statusCode
end

UrlEncode

Percent-encodes a string for safe use in URLs.

Signature

UrlEncode(string value)

Parameters

• value (string): The string to encode.

Returns

• string: The percent-encoded string.

Description

Uses RFC 3986 percent-encoding. Spaces become %20, special characters are escaped. Use this when building query strings or path segments from dynamic values.

Examples

var encoded = UrlEncode("hello world")
# encoded = "hello%20world"

var query = UrlEncode("name=Alice&role=admin")
# query = "name%3DAlice%26role%3Dadmin"

# Build a query string safely
var search = UrlEncode(Data.searchTerm)
var url = "https://api.example.com/search?q=" + search
var response = InvokeRestMethod("GET", url)

UrlDecode

Decodes a percent-encoded string.

Signature

UrlDecode(string value)

Parameters

• value (string): The percent-encoded string to decode.

Returns

• string: The decoded string.

Description

Reverses percent-encoding. %20 becomes a space, %3D becomes =, etc.

Examples

var decoded = UrlDecode("hello%20world")
# decoded = "hello world"

var decoded = UrlDecode("name%3DAlice%26role%3Dadmin")
# decoded = "name=Alice&role=admin"

FormEncode

Encodes an object as an application/x-www-form-urlencoded string.

Signature

FormEncode(object obj)

Parameters

• obj (object): The object whose properties will be encoded as form fields. Values are converted to strings.

Returns

• string: The form-encoded string (e.g. key1=value1&key2=value2).

Description

Iterates over the object's properties and encodes each key-value pair using percent-encoding, joined by &. Useful for building form POST bodies or query strings from structured data.

Examples

var params = {"name": "Alice", "age": 30, "city": "New York"}
var encoded = FormEncode(params)
# encoded = "name=Alice&age=30&city=New%20York"

# Use as a query string
var query = FormEncode({"q": Data.search, "page": 1, "limit": 20})
var url = "https://api.example.com/search?" + query
var response = InvokeRestMethod("GET", url)

# Use as a form POST body
var formData = FormEncode({"username": Data.user, "password": Data.pass})
var headers = {"Content-Type": "application/x-www-form-urlencoded"}
var response = InvokeRestMethod("POST", "https://example.com/login", headers, formData)