AtlatestRepositorysigil-cloudflare
sigil-cloudflare / treeREADME.md
1
# sigil-cloudflare3
Cloudflare services for Sigil, starting with R2 object storage. Modules use4
hierarchical namespaces: `(cloudflare r2)` and `(cloudflare r2 signing)`.6
The initial client supports binary PUT, GET, HEAD and DELETE, S3 Signature V47
with R2's `auto` region, and public URLs through a separately configured custom8
domain. It uses sigil-http and sigil-crypto directly. No external signing process,9
AWS SDK, automatic redirect following or automatic retry is involved.11
## Use13
```scheme14
(import (sigil core) (sigil io) (sigil process) (cloudflare r2))16
(define storage17
(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 result24
(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
```35
Supply bucket-scoped R2 S3 credentials on the server, never in a browser or log.36
The client returns sigil-http's dictionary with `status:`, ordered header alist37
`headers:` and bytevector `body:`. Non-2xx responses are returned for the caller38
to handle; connection/framing failures return `#f`. An uncertain failed PUT may39
already have reached storage. Use unique application-generated object keys and40
explicit reconciliation/retry policy. Never log signed headers or response bodies.41
The closure-based client does not expose credentials through record accessors.43
Object keys are raw UTF-8 strings, not URL-encoded strings. The signer preserves44
slashes and dot segments and encodes reserved bytes; applications should generate45
safe keys and should not use `.`/`..` segments for public browser URLs. Public base46
URL must be an HTTPS origin without a trailing slash. Configure that custom domain47
on the R2 bucket; this helper does not create DNS or enable public access.49
## Scope and limits51
Calls return a result directly and buffer request/response bodies in memory.52
This direct-return API does not imply that every stage is scheduler-friendly:53
sigil-http's nonblocking body I/O yields through Sigil's scheduler, but the54
current native DNS, TCP connect and TLS handshake paths can block the process.55
Connect/handshake waits are bounded by the configured timeout; DNS is subject56
to the system resolver's own limits. Spawning another cooperative task around57
an R2 call does not remove those native blocking stages. Fully cooperative58
connection establishment requires changes in shared socket/TLS/HTTP transport.60
Set application upload limits;61
use this initial API for bounded assets. The timeout is sigil-http's connection62
and idle I/O timeout, not a total operation budget. Responses with a mismatched63
Content-Length are rejected. Generic response buffering/chunk framing retain64
sigil-http's limits. Streaming/multipart uploads, presigned URLs, jurisdictional65
endpoints, list operations, DNS/bucket administration and image processing are66
not implemented. This is not a complete Cloudflare API client.68
Public logos and private support attachments require separate application access69
policies and storage configuration. The library does not authorize customers or70
validate image formats; Rezvibe must do that at its own boundary.72
## Verification74
```sh75
sigil deps install76
sigil build77
sigil test --sgl --strict78
node test/http.mjs79
```81
Node 18+ is needed only for the independent fake HTTP service. Tests use public82
AWS signature vectors, UTF-8/query/header edge cases and a binary round trip83
through actual Sigil HTTP with signatures verified independently using Node crypto.84
They also check deletion, error status, truncated response rejection and that85
redirects/retries do not send extra requests. `test-port:` explicitly enables86
an HTTP endpoint restricted to 127.0.0.1 for fake-service tests; use fake credentials.88
A separate live-provider verification on 2026-09-06 exercised a 4096-byte89
PUT/GET/HEAD/DELETE round trip against R2 and removed the temporary probe object.90
This manual check used authorized credentials outside the automated test suite.92
References: [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).96
BSD-3-Clause; see LICENSE.