AtlatestRenderedmarkdown
Readme

sigil-cloudflare

Cloudflare services for Sigil, starting with R2 object storage. Modules use hierarchical namespaces: (cloudflare r2) and (cloudflare r2 signing).

The initial client supports binary PUT, GET, HEAD and DELETE, S3 Signature V4 with R2's auto region, and public URLs through a separately configured custom domain. It uses sigil-http and sigil-crypto directly. No external signing process, AWS SDK, automatic redirect following or automatic retry is involved.

Use

(import (sigil core) (sigil io) (sigil process) (cloudflare r2))

(define storage
  (r2-client (getenv "R2_ACCOUNT_ID")
             (getenv "R2_ACCESS_KEY_ID")
             (getenv "R2_SECRET_ACCESS_KEY")
             "rezvibe-assets"
             public-base-url: "https://assets.rezvibe.com"))

(define result
  (r2-put-object storage "examples/hello.txt" (string->utf8 "Hello!")
    content-type: "text/plain" cache-control: "public, max-age=3600"))

(when (and result (= (dict-ref result status:) 200))
  (display (r2-public-url storage "examples/hello.txt")))

(r2-head-object storage "examples/hello.txt")
(r2-get-object storage "examples/hello.txt")
(r2-delete-object storage "examples/hello.txt")

Supply bucket-scoped R2 S3 credentials on the server, never in a browser or log. The client returns sigil-http's dictionary with status:, ordered header alist headers: and bytevector body:. Non-2xx responses are returned for the caller to handle; connection/framing failures return #f. An uncertain failed PUT may already have reached storage. Use unique application-generated object keys and explicit reconciliation/retry policy. Never log signed headers or response bodies. The closure-based client does not expose credentials through record accessors.

Object keys are raw UTF-8 strings, not URL-encoded strings. The signer preserves slashes and dot segments and encodes reserved bytes; applications should generate safe keys and should not use ./.. segments for public browser URLs. Public base URL must be an HTTPS origin without a trailing slash. Configure that custom domain on the R2 bucket; this helper does not create DNS or enable public access.

Scope and limits

Calls return a result directly and buffer request/response bodies in memory. This direct-return API does not imply that every stage is scheduler-friendly: sigil-http's nonblocking body I/O yields through Sigil's scheduler, but the current native DNS, TCP connect and TLS handshake paths can block the process. Connect/handshake waits are bounded by the configured timeout; DNS is subject to the system resolver's own limits. Spawning another cooperative task around an R2 call does not remove those native blocking stages. Fully cooperative connection establishment requires changes in shared socket/TLS/HTTP transport.

Set application upload limits; use this initial API for bounded assets. The timeout is sigil-http's connection and idle I/O timeout, not a total operation budget. Responses with a mismatched Content-Length are rejected. Generic response buffering/chunk framing retain sigil-http's limits. Streaming/multipart uploads, presigned URLs, jurisdictional endpoints, list operations, DNS/bucket administration and image processing are not implemented. This is not a complete Cloudflare API client.

Public logos and private support attachments require separate application access policies and storage configuration. The library does not authorize customers or validate image formats; Rezvibe must do that at its own boundary.

Verification

sigil deps install
sigil build
sigil test --sgl --strict
node test/http.mjs

Node 18+ is needed only for the independent fake HTTP service. Tests use public AWS signature vectors, UTF-8/query/header edge cases and a binary round trip through actual Sigil HTTP with signatures verified independently using Node crypto. They also check deletion, error status, truncated response rejection and that redirects/retries do not send extra requests. test-port: explicitly enables an HTTP endpoint restricted to 127.0.0.1 for fake-service tests; use fake credentials.

A separate live-provider verification on 2026-09-06 exercised a 4096-byte PUT/GET/HEAD/DELETE round trip against R2 and removed the temporary probe object. This manual check used authorized credentials outside the automated test suite.

References: Cloudflare R2 S3 API, custom domains, AWS SigV4 examples.

BSD-3-Clause; see LICENSE.