Network

HTTP, DNS and certificate management. Each function lists its parameters, defaults and return value.

HTTP Namespace

HTTP client functions.

Scope: Network

Functions

Function	Description
http.get()	Perform an HTTP GET request
http.post()	Perform an HTTP POST request
http.put()	Perform an HTTP PUT request
http.patch()	Perform an HTTP PATCH request
http.delete()	Perform an HTTP DELETE request
http.request()	Perform a custom HTTP request with full control
http.download()	Download a file from a URL
http.upload()	Upload a file to a URL

Common Parameters

These parameters are shared across http.get(), http.post(), http.put(), http.patch(), and http.delete().

Request Parameters

Parameter	Type	Default	Description
url	string	—	Request URL (required)
headers	map	—	Request headers
queryParams	map	—	URL query parameters

Authentication Parameters

Parameter	Type	Default	Description
authType	string	—	Auth type: "basic", "bearer", "apikey", "digest"
authUsername	string	—	Username for basic/digest auth
authPassword	string	—	Password for basic/digest auth
authToken	string	—	Token for bearer/apikey auth
authHeader	string	"Authorization"	Custom header name for API key

Options Parameters

Parameter	Type	Default	Description
timeout	int	30	Request timeout in seconds
insecureSkipVerify	bool	false	Skip TLS certificate verification

Common Returns

Field	Type	Description
success	bool	Whether request succeeded (2xx status)
statusCode	int	HTTP status code
body	string	Response body
headers	map	Response headers
latency	int	Request latency in milliseconds

http.get()

Perform an HTTP GET request.

Examples

// Simple GET
let resp = http.get({ url: "https://api.example.com/users" })
log("Status: " + resp.statusCode)
log("Body: " + resp.body)

// With headers and auth
let resp = http.get({
  url: "https://api.example.com/data",
  headers: { "Accept": "application/json" },
  authType: "bearer",
  authToken: "my-token"
})

// With query parameters
let resp = http.get({
  url: "https://api.example.com/search",
  queryParams: {
    q: "hello",
    limit: "10"
  }
})

http.post()

Perform an HTTP POST request.

Additional Parameters

Parameter	Type	Default	Description
body	any	—	Request body (string, map, or JSON-serializable value)
formData	map	—	Form data for application/x-www-form-urlencoded

Examples

// POST JSON
let resp = http.post({
  url: "https://api.example.com/users",
  body: { name: "Alice", email: "[email protected]" },
  headers: { "Content-Type": "application/json" }
})

// POST form data
let resp = http.post({
  url: "https://example.com/login",
  formData: {
    username: "admin",
    password: "secret"
  }
})

// POST with auth
let resp = http.post({
  url: "https://api.example.com/data",
  body: { key: "value" },
  authType: "basic",
  authUsername: "user",
  authPassword: "pass"
})

http.put()

Perform an HTTP PUT request. Same parameters as http.post().

Examples

// Update a resource
let resp = http.put({
  url: "https://api.example.com/users/123",
  body: { name: "Alice Updated" },
  headers: { "Content-Type": "application/json" },
  authType: "bearer",
  authToken: "my-token"
})

http.patch()

Perform an HTTP PATCH request. Same parameters as http.post().

Examples

// Partial update
let resp = http.patch({
  url: "https://api.example.com/users/123",
  body: { email: "[email protected]" },
  authType: "bearer",
  authToken: "my-token"
})

http.delete()

Perform an HTTP DELETE request. Same parameters as http.get().

Examples

// Delete a resource
let resp = http.delete({
  url: "https://api.example.com/users/123",
  authType: "bearer",
  authToken: "my-token"
})

http.request()

Perform a custom HTTP request with full control over method, body, files, redirects, and output.

Parameters

Parameter	Type	Default	Description
method	string	"GET"	HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
url	string	—	Request URL (required)
body	any	—	Request body
headers	map	—	Request headers
queryParams	map	—	URL query parameters
formData	map	—	Form data
files	array	—	Files to upload (array of {paramName, filePath, fileName, contentType})
authType	string	—	Authentication type
authUsername	string	—	Auth username
authPassword	string	—	Auth password
authToken	string	—	Auth token
authHeader	string	—	Custom auth header
timeout	int	30	Timeout in seconds
insecureSkipVerify	bool	false	Skip TLS verification
followRedirects	bool	true	Follow HTTP redirects
maxRedirects	int	10	Maximum redirects to follow
retryEnabled	bool	true	Enable automatic retries
retryCount	int	3	Number of retries
outputPath	string	—	Save response body to file

Examples

// Custom request with files
let resp = http.request({
  method: "POST",
  url: "https://api.example.com/upload",
  files: [
    {
      paramName: "file",
      filePath: "/tmp/data.csv",
      contentType: "text/csv"
    }
  ],
  authType: "bearer",
  authToken: "my-token"
})

// HEAD request
let resp = http.request({
  method: "HEAD",
  url: "https://example.com/large-file.zip"
})
log("Content-Length: " + resp.headers["Content-Length"])

// Save response to file
http.request({
  method: "GET",
  url: "https://example.com/report.pdf",
  outputPath: "/tmp/report.pdf"
})

http.download()

Download a file from a URL.

Parameters

Parameter	Type	Default	Description
url	string	—	URL to download from (required)
outputPath	string	—	Local path to save file (required)
headers	map	—	Request headers
authType	string	—	Authentication type
authToken	string	—	Auth token
timeout	int	30	Timeout in seconds

Returns

Field	Type	Description
success	bool	Whether download succeeded
statusCode	int	HTTP status code
latency	int	Download latency in milliseconds

Examples

// Download a file
http.download({
  url: "https://example.com/release-v1.0.tar.gz",
  outputPath: "/tmp/release.tar.gz"
})

// Download with auth
http.download({
  url: "https://api.example.com/artifacts/build.zip",
  outputPath: "/tmp/build.zip",
  authType: "bearer",
  authToken: "my-token"
})

http.upload()

Upload a file to a URL.

Parameters

Parameter	Type	Default	Description
url	string	—	URL to upload to (required)
filePath	string	—	Local file path to upload (required)
paramName	string	"file"	Form field name
headers	map	—	Request headers
authType	string	—	Authentication type
authToken	string	—	Auth token

Returns

Field	Type	Description
success	bool	Whether upload succeeded
statusCode	int	HTTP status code
body	string	Response body

Examples

// Upload a file
let resp = http.upload({
  url: "https://api.example.com/files",
  filePath: "/tmp/report.pdf",
  authType: "bearer",
  authToken: "my-token"
})

// Upload with custom param name
let resp = http.upload({
  url: "https://api.example.com/images",
  filePath: "/tmp/photo.jpg",
  paramName: "image",
  headers: { "X-Upload-Type": "profile" }
})

DNS Namespace

DNS record CRUD via libdns + system-resolver lookup.

Six providers in v1: cloudflare, route53, gcloud, azure, digitalocean, godaddy. Provider credentials are shared with the letsencrypt namespace’s DNS-01 challenge.

Scope: Network

Functions

Function	Description
dns.list()	Read records in a zone (optional filters)
dns.set()	Upsert by (name, type) — replaces existing RRset
dns.append()	Add records without touching existing ones
dns.delete()	Remove records by exact match
dns.lookup()	Query via system resolver — no provider creds

Common Parameters (CRUD)

Parameter	Type	Required	Description
provider	string	yes	cloudflare / route53 / gcloud / azure / digitalocean / godaddy
credentials	map	yes	Provider-specific (see below)
zone	string	yes	Zone name (example.com)
timeout	int or string	no	Wall-clock cap

Record shape

Field	Type	Description
type	string	DNS record type (uppercased internally)
name	string	Relative to zone (www); @ for apex
value	string	Record value. For MX: hostname. For SRV: "port target"
ttl	int or string	TTL ("5m" or seconds)
priority	int	MX or SRV priority
weight	int	SRV weight

dns.list()

Parameter	Type	Description
type	string	Optional filter by record type
name	string	Optional filter by record name

let zone = dns.list({
  provider: "cloudflare",
  credentials: { api_token: cfToken },
  zone: "example.com",
  type: "A"
})
log("A records: " + zone.records.length)

dns.set()

dns.set({
  provider: "cloudflare",
  credentials: { api_token: cfToken },
  zone: "example.com",
  records: [
    { type: "TXT", name: "@", value: "v=spf1 -all" }
  ]
})

dns.append()

// Add a record without disturbing other TXTs at the same name
dns.append({
  provider: "cloudflare",
  credentials: { api_token: cfToken },
  zone: "example.com",
  records: [
    { type: "TXT", name: "_dmarc", value: "v=DMARC1; p=none;" }
  ]
})

dns.delete()

Records are matched by name + type + ttl + value. Leave any of those zero to match by the remaining fields (libdns convention).

dns.delete({
  provider: "cloudflare",
  credentials: { api_token: cfToken },
  zone: "example.com",
  records: [
    { type: "A", name: "stale", value: "192.0.2.99" }
  ]
})

// Delete every record at a name regardless of type/value:
dns.delete({
  provider: "cloudflare",
  credentials: { api_token: cfToken },
  zone: "example.com",
  records: [
    { name: "old-subdomain" }   // type, value left zero
  ]
})

dns.lookup()

System-resolver query. No provider credentials needed.

Parameter	Type	Description
name	string	FQDN (required)
type	string	A / AAAA / CNAME / TXT / MX / NS / SRV (required)
server	string	Resolver override (1.1.1.1:53)
timeout	int or string	Default 5s

// Confirm propagation via Cloudflare's public resolver
let r = dns.lookup({
  name: "www.example.com",
  type: "A",
  server: "1.1.1.1:53",
  timeout: "10s"
})
if (r.records.length === 0) {
  throw "DNS not propagated yet"
}
log("resolved to " + r.records[0].value)

Provider credentials

cloudflare

Key	Description
api_token	Cloudflare API token (required)

route53

Key	Description
access_key	AWS access key (optional — env / IAM role fallback)
secret_key	AWS secret key
session_token	STS session token (optional)
region	AWS region
profile	Named AWS profile

gcloud

Key	Description
project	GCP project ID (required)
service_account_json_path	Path to SA JSON
service_account_json	Inline SA JSON (written to a temp file)

Falls back to Application Default Credentials when neither is set.

azure

Key	Description
subscription_id	Required
resource_group	Required
tenant_id	Service-principal tenant
client_id	Service-principal client
client_secret	Service-principal secret

Omit the service-principal triple to use managed identity / Azure CLI.

digitalocean

Key	Description
api_token	DO personal access token (required)

godaddy

Key	Description
api_key	GoDaddy API key (required)
api_secret	GoDaddy API secret (required)

Letsencrypt Namespace

ACME certificate management via certmagic. Default CA is Let’s Encrypt; the caURL parameter accepts any ACME-compatible directory.

DNS-01 challenges reuse the six libdns providers wired into the dns namespace, so credentials shapes are shared between them.

Scope: Network

Replaces the old acme namespace. lego is no longer a dependency.

Functions

Function	Description
letsencrypt.obtain()	Issue a certificate (or load from storage if already present)
letsencrypt.renew()	Renew an existing certificate
letsencrypt.revoke()	Revoke a certificate at the CA
letsencrypt.info()	Read X.509 details from a cached cert
letsencrypt.list()	Enumerate cached certs

Common Parameters

Every function accepts these in addition to its own surface.

Parameter	Type	Default	Description
caURL	string	LE production	ACME directory URL. Shortcuts: letsencrypt, staging, zerossl
email	string	—	Account contact email (required for obtain/renew/revoke)
storage	string	$XDG_DATA_HOME/letsencrypt	Filesystem path
keyType	string	ECDSA-P256	ECDSA-P256 / ECDSA-P384 / RSA-2048 / RSA-4096 / ED25519
timeout	int or string	—	Wall-clock cap

Challenge Configuration

Used by obtain and renew.

Parameter	Type	Default	Description
challenge	string	"dns-01"	"dns-01" / "http-01" / "tls-alpn-01"
mustStaple	bool	false	Set OCSP must-staple

DNS-01

Parameter	Type	Description
dnsProvider	string	One of the six libdns providers (see dns.md)
dnsCredentials	map	Provider credentials (same shape as the dns namespace)
dnsPropagation	int or string	Propagation delay before asking the CA to verify
dnsResolvers	[]string	Resolvers used to verify propagation (e.g. ["1.1.1.1:53"])

HTTP-01

Parameter	Type	Default	Description
httpAddress	string	":80"	Bind address

TLS-ALPN-01

Parameter	Type	Default	Description
tlsAddress	string	":443"	Bind address

letsencrypt.obtain()

Parameter	Type	Required	Description
domains	[]string	yes	First is CN; the rest become SANs on the same cert

Returns

{
  success: bool,
  cert: {
    subject, issuer, domains,
    notBefore, notAfter,           // RFC 3339
    serial, fingerprint,           // "sha256:<hex>"
    daysRemaining,
    certPath, keyPath, fullchainPath
  },
  error
}

Examples

// DNS-01 with SAN
let r = letsencrypt.obtain({
  email: "[email protected]",
  storage: "/var/lib/letsencrypt",
  domains: ["example.com", "www.example.com", "api.example.com"],
  challenge: "dns-01",
  dnsProvider: "cloudflare",
  dnsCredentials: { api_token: cfToken }
})
log("issued: " + r.cert.domains.join(", "))

// HTTP-01
letsencrypt.obtain({
  email: "[email protected]",
  domains: ["app.example.com"],
  challenge: "http-01"
})

// Staging (test against LE staging, no rate-limit pressure)
letsencrypt.obtain({
  caURL: "staging",
  email: "[email protected]",
  domains: ["dev.example.com"],
  challenge: "dns-01",
  dnsProvider: "cloudflare",
  dnsCredentials: { api_token: cfToken }
})

letsencrypt.renew()

Same parameters as obtain, plus:

Parameter	Type	Description
force	bool	Renew regardless of the renewal window

letsencrypt.renew({
  email: "[email protected]",
  domains: ["example.com", "www.example.com"],
  force: true,
  challenge: "dns-01",
  dnsProvider: "cloudflare",
  dnsCredentials: { api_token: cfToken }
})

letsencrypt.revoke()

Parameter	Type	Description
domain	string	First domain of the cert (looked up via storage)
certPath	string	Or an explicit cert PEM path
reason	int	RFC 5280 reason code (default 0 — unspecified)

Common reasons: 0 unspecified, 1 keyCompromise, 3 affiliationChanged, 4 superseded, 5 cessationOfOperation.

letsencrypt.revoke({
  email: "[email protected]",
  domain: "oops.example.com",
  reason: 1,                                // keyCompromise
  challenge: "dns-01",
  dnsProvider: "cloudflare",
  dnsCredentials: { api_token: cfToken }
})

letsencrypt.info()

Parameter	Type	Description
domain	string	Look up via storage
certPath	string	Or an explicit cert path

Returns the same cert shape as obtain. Touches no network.

let r = letsencrypt.info({
  storage: "/var/lib/letsencrypt",
  domain: "www.example.com"
})
log(r.cert.domains[0] + " expires in " + r.cert.daysRemaining + " days")

letsencrypt.list()

No verb-specific parameters. When caURL is set, lists only certs for that CA.

let r = letsencrypt.list({ storage: "/var/lib/letsencrypt" })
for (let c of r.certs) {
  log(c.domains.join(", ") + " — " + c.daysRemaining + " days left")
}

Behaviour notes

• obtain is idempotent: if a cert already exists in storage and isn’t within its renewal window, the call is a no-op and returns the existing cert info.
• renew only renews when the cert is within its renewal window; pass force: true to override.
• For Let’s Encrypt production, every successful issuance counts against your per-domain rate limit (50/week as of writing). Use the staging CA shortcut to test without pressure.
• Storage uses certmagic’s filesystem backend. The lib-storage adapter is out of scope for v1.