URLs, TCP and HTTP

Network programs still use ordinary functions, owned resources and checked errors. The runtime parks tasks on supported socket readiness operations. Your application chooses timeouts, message framing, supervision and how failures are reported.

Build a URL from data

DIM parameters AS DICT OF STRING TO STRING = DICT()
parameters["search"] = "Fred & Jane"
url = JoinURLPath("https://api.example.com/v1/?locale=en", "/customers", Query=parameters)
PRINT url

The helper appends the path and escapes query data. Query names supplied in the update replace existing values with those names, while unrelated parameters survive. A leading slash in JoinURLPath does not discard the existing base path. ResolveURL instead performs URI reference resolution. Choose the operation whose meaning matches your intent.

ParseURL gives a checked typed value. BuildURL and WithURL helpers construct components; SetURLQueryParameter updates through BYREF after staging a complete result. Raw components preserve encoded delimiters and presence; decoded accessors validate UTF-8. Ordered URLParameter lists preserve repeated names, bare flags and explicit empty values. Dictionary adapters serve simpler one/many-value cases. Typed URL values can be passed directly to HTTP clients.

Make an HTTP request

This example requires working DNS, network access and a peer server:

Example requirements: network program; requires reachable https://example.com and the matching TLS SDK.

response = HTTPGet("https://example.com/")
PRINT response.Status
PRINT DecodeUtf8(response.Body)

HTTPPost accepts text or bytes; RequestHTTP accepts explicit methods. Responses retain status, headers, body and trailers. Decode body text only when its encoding is appropriate. Typed JSON helpers distinguish HTTP status failure, a bodyless 204 response and a successful decoded value, including nested optional absence.

HTTPClientOptions combines protocol and TLS settings. Redirects are bounded; cross-origin changes strip authorization/cookies and HTTPS downgrade is forbidden by default. HTTPGetPlain rejects HTTPS and permits omitting TLS from a strictly plain-HTTP executable. HTTPS verifies certificates and hostnames by default.

Serve a route

Example requirements: server program; binds localhost port 8080 and runs until externally stopped.

router = HTTPRouter()
RouteGet(BYREF router, "/hello/{name}", Hello)
listener = ListenTCP("127.0.0.1", 8080)
ServeHTTP(listener, router)
FUNCTION Hello(request AS HTTPRequest) AS HTTPResponse
    RETURN TextResponse("Hello, " + Get(request.Parameters, "name", "world"))
END FUNCTION

Literal path segments take precedence over parameters and final remainder matches. Unknown routes yield 404; unsupported methods on a known path yield 405. HEAD uses GET fallback without body bytes. Paths are decoded once and validated; do not add another unstructured decode step in a handler.

Buffered handlers return HTTPResponse. Streaming handlers use a connection and BYREF HTTPExchange with ReadHTTPBody, StartHTTPResponse, WriteHTTPBody and FinishHTTPResponse. Consume/drain a body before reusing its connection. Explicit lengths must match bytes written. Abandon a connection after framing errors; the buffered convenience client handles this lifecycle automatically.

UseHTTP adds middleware and HTTPFallback installs fallback handling. These use checked named callbacks. ServeHTTPChecked lets a supervisor observe original typed application/transport failures. Convenience servers recover handler failures, report their concrete names and send suitable error responses when possible. Mutable route slots admit Error, so checked callers must account for that family.

MountDirectory/ServeDirectory implement contained file serving with explicit listing policy, MIME types, conditional responses and supported single ranges. Review the reference’s root-containment and hidden-file rules before exposing data.

Work below HTTP

ListenTCP/Accept and connection functions provide owned sockets. A task handling an accepted connection receives TAKE ownership; the connection closes after its handler and dependent operations finish. DNS uses bounded workers. TLS wraps the existing backend behind BASIL-owned options/resources; it does not expose OpenSSL internals as an application ownership model.

HTTP/1.1 is implemented. HTTP/2, WebSockets, automatic connection pools, proxies, cookie jars and transparent decompression are not part of this slice. The full HTTP reference gives framing, streaming, timeout and directory-serving limits; the TLS loopback example shows explicit transport.