AtlatestRepositorysigil-cloudflare
1# sigil-cloudflare
2
3Cloudflare services for Sigil, starting with R2 object storage. Modules use
4hierarchical namespaces: `(cloudflare r2)` and `(cloudflare r2 signing)`.
5
6The initial client supports binary PUT, GET, HEAD and DELETE, S3 Signature V4
7with R2's `auto` region, and public URLs through a separately configured custom
8domain. It uses sigil-http and sigil-crypto directly. No external signing process,
9AWS SDK, automatic redirect following or automatic retry is involved.
11## Use
13```scheme
14(import (sigil core) (sigil io) (sigil process) (cloudflare r2))
16(define storage
17 (r2-client (getenv "R2_ACCOUNT_ID")
18 (getenv "R2_ACCESS_KEY_ID")
19 (getenv "R2_SECRET_ACCESS_KEY")
20 "rezvibe-assets"
21 public-base-url: "https://assets.rezvibe.com"))
23(define result
24 (r2-put-object storage "examples/hello.txt" (string->utf8 "Hello!")
25 content-type: "text/plain" cache-control: "public, max-age=3600"))
27(when (and result (= (dict-ref result status:) 200))
28 (display (r2-public-url storage "examples/hello.txt")))
30(r2-head-object storage "examples/hello.txt")
31(r2-get-object storage "examples/hello.txt")
32(r2-delete-object storage "examples/hello.txt")
33```
35Supply bucket-scoped R2 S3 credentials on the server, never in a browser or log.
36The client returns sigil-http's dictionary with `status:`, ordered header alist
37`headers:` and bytevector `body:`. Non-2xx responses are returned for the caller
38to handle; connection/framing failures return `#f`. An uncertain failed PUT may
39already have reached storage. Use unique application-generated object keys and
40explicit reconciliation/retry policy. Never log signed headers or response bodies.
41The closure-based client does not expose credentials through record accessors.
43Object keys are raw UTF-8 strings, not URL-encoded strings. The signer preserves
44slashes and dot segments and encodes reserved bytes; applications should generate
45safe keys and should not use `.`/`..` segments for public browser URLs. Public base
46URL must be an HTTPS origin without a trailing slash. Configure that custom domain
47on the R2 bucket; this helper does not create DNS or enable public access.
49## Scope and limits
51Calls return a result directly and buffer request/response bodies in memory.
52This direct-return API does not imply that every stage is scheduler-friendly:
53sigil-http's nonblocking body I/O yields through Sigil's scheduler, but the
54current native DNS, TCP connect and TLS handshake paths can block the process.
55Connect/handshake waits are bounded by the configured timeout; DNS is subject
56to the system resolver's own limits. Spawning another cooperative task around
57an R2 call does not remove those native blocking stages. Fully cooperative
58connection establishment requires changes in shared socket/TLS/HTTP transport.
60Set application upload limits;
61use this initial API for bounded assets. The timeout is sigil-http's connection
62and idle I/O timeout, not a total operation budget. Responses with a mismatched
63Content-Length are rejected. Generic response buffering/chunk framing retain
64sigil-http's limits. Streaming/multipart uploads, presigned URLs, jurisdictional
65endpoints, list operations, DNS/bucket administration and image processing are
66not implemented. This is not a complete Cloudflare API client.
68Public logos and private support attachments require separate application access
69policies and storage configuration. The library does not authorize customers or
70validate image formats; Rezvibe must do that at its own boundary.
72## Verification
74```sh
75sigil deps install
76sigil build
77sigil test --sgl --strict
78node test/http.mjs
79```
81Node 18+ is needed only for the independent fake HTTP service. Tests use public
82AWS signature vectors, UTF-8/query/header edge cases and a binary round trip
83through actual Sigil HTTP with signatures verified independently using Node crypto.
84They also check deletion, error status, truncated response rejection and that
85redirects/retries do not send extra requests. `test-port:` explicitly enables
86an HTTP endpoint restricted to 127.0.0.1 for fake-service tests; use fake credentials.
88A separate live-provider verification on 2026-09-06 exercised a 4096-byte
89PUT/GET/HEAD/DELETE round trip against R2 and removed the temporary probe object.
90This manual check used authorized credentials outside the automated test suite.
92References: [Cloudflare R2 S3 API](https://developers.cloudflare.com/r2/api/s3/api/),
93[custom domains](https://developers.cloudflare.com/r2/buckets/public-buckets/),
94[AWS SigV4 examples](https://docs.aws.amazon.com/AmazonS3/latest/developerguide/sig-v4-header-based-auth.html).
96BSD-3-Clause; see LICENSE.