Net.HTTP

empty constant

empty : Headers

Returns a field collection with no entries.

Examples

Building request headers immutably

Headers.empty
  .add("Accept", "application/json").try
  .add("User-Agent", "inventory-sync/1.0").try

from

from(entries: [(String, String)]) -> Result<Headers, NetError>

Validates header names and values without folding duplicates.

Duplicate fields stay in their original order. Invalid names and values containing line breaks are rejected instead of creating a malformed or injectable HTTP message.

Returns validated fields, or Parse

Examples

Forwarding an explicitly selected set of request headers

Headers.from([
  ("Accept", "application/json"),
  ("X-Request-ID", requestId)
]).try

parse

parse(text: String) -> Result<Headers, NetError>

Parses CRLF- or LF-separated header fields.

Use this at a protocol boundary when headers arrive as text. Application code normally builds them with from, add, and set.

Returns fields in source order, or Parse

Examples

Parsing headers captured from a diagnostic fixture

Headers.parse("Content-Type: text/plain\r\nX-Trace: abc\r\n").try

from

from(code: Integer) -> Result<Status, NetError>

Validates an HTTP status code.

Parameters

code

a status in 100..599

Returns the status, or Parse

Examples

Validating a configurable health-check success code

let code = ENV.get("HEALTH_STATUS").flatMap { |text| text.to(Integer) }.or(204)
let expected = Status.from(code).try

binary

binary(status: Integer, body: Binary, headers: Headers) -> Response<Binary>

Builds a buffered binary response with validated headers.

Examples

Returning a downloaded file without decoding it as text

Response.binary(200, archive, Headers.empty.add("Content-Type", "application/zip").try)

text

text(status: Integer, body: String) -> Response<Binary>

Builds a UTF-8 text response with an explicit text/plain content type.

Examples

A small health endpoint

Response.text(200, "ok")

empty

empty(status: Integer) -> Response<Binary>

Builds a response with an empty body.

Examples

A successful DELETE endpoint

Response.empty(204)

build constant

Examples

+Router.build.get("/health", { |request, context| Response.text(200, "ok") })+

start

start(endpoint: Net.Socket.TCP.Endpoint, router: Router, options: ServerOptions) -> Result<Running, NetError>

Starts a server with conservative defaults and returns immediately.

The returned handle owns the listener and active handlers. Use start when the process has other work to do; use serve for a foreground server whose main job is handling HTTP.

Examples

let router = Router.build.get("/health", do |request, context|
  Response.text(200, "ok")
end)
let endpoint = Net.Socket.TCP.Endpoint.loopback(Net.Port.from(0).try)
let server = Server.start(endpoint, router).try
Server.stop(server).try

serve

serve(endpoint: Net.Socket.TCP.Endpoint, router: Router, options: ServerOptions) -> Result<Void, NetError>

Starts with defaults and blocks until the server stops.

stop

stop(server: Running, grace: Duration) -> Result<ShutdownReport, NetError>

Gracefully stops using the duration captured at start.

New requests stop being accepted while in-flight handlers get their grace period to finish. The report says how much work completed or was forced down during shutdown.

Examples

Shutting down from an application lifecycle hook

let report = Server.stop(server).try
IO.printLine("closed after ${report.completed} requests")

join

join(server: Running) -> Result<Void, NetError>

Waits until the server owner exits.

running?

running?(server: Running) -> Bool

Returns whether the server owner is alive

localAddress

localAddress(server: Running) -> Net.Socket.TCP.Endpoint

Returns the bound address, including an operating-system-assigned port.

Returns the bound address

Examples

Publishing the actual address of a test server

let endpoint = Server.localAddress(server)
IO.printLine("test server: http://${endpoint.host}:${endpoint.port.string}")

open

open : Result<Client, NetError>
open(options: ClientOptions) -> Result<Client, NetError>

Opens an explicit pooled client with conservative defaults.

Reuse one client for related requests so keep-alive connections and DNS work can be reused. Close it when the owning service shuts down.

Examples

Fetching several pages through one connection pool

let client = Client.open.try
let first = client.get("https://api.example.com/items?page=1").try
let second = client.get("https://api.example.com/items?page=2").try
client.close.try

request

request : String -> String -> Headers -> Binary -> Result<Response<Binary>, NetError>

Sends one stateless buffered request with no redirect or hidden retry.

Each call owns a short-lived client. This is convenient for scripts and occasional requests; use Client for a service making repeated calls.

Examples

A one-off authenticated request in a command-line tool

let headers = Headers.empty.add("Authorization", "Bearer ${token}").try
HTTP.request("GET", url, headers).try

get

get(url: String) -> Result<Response<Binary>, NetError>

Sends one stateless buffered GET.

Examples

+HTTP.get("https://example.test/").try+

delete

delete(url: String) -> Result<Response<Binary>, NetError>

Sends one stateless DELETE with an empty body.

head

head(url: String) -> Result<Response<Binary>, NetError>

Sends one stateless HEAD and returns an empty response body.

options

options(url: String) -> Result<Response<Binary>, NetError>

Sends one stateless OPTIONS request.

post

post(url: String, body: Binary) -> Result<Response<Binary>, NetError>

Sends one stateless buffered binary POST.

put

put(url: String, body: Binary) -> Result<Response<Binary>, NetError>

Sends one stateless buffered binary PUT.

patch

patch(url: String, body: Binary) -> Result<Response<Binary>, NetError>

Sends one stateless buffered binary PATCH.