devflare 1.0.0-next.1 → 1.0.0-next.11

package/R2.md

@@ -0,0 +1,200 @@
+# R2
+
+A short guide for handling uploads and file delivery with Cloudflare R2.
+
+---
+
+## Quick rules
+
+- Use **presigned `PUT` URLs** for direct user uploads to R2
+- Use a **public bucket on a custom domain** for truly public assets
+- Use a **private bucket + Worker authorization** for authenticated/private assets
+- Use **Cloudflare Access** for teammate/org-only buckets
+- Use **WAF token auth / HMAC validation** or a **Worker** for expiring custom-domain media links
+- Do **not** use `r2.dev` for production delivery
+- If you protect a custom-domain bucket with Access or WAF, **disable `r2.dev`** or the bucket may still be reachable there
+
+---
+
+## Uploads
+
+The usual safe upload flow is:
+
+1. frontend asks your app for upload permission
+2. your Worker/app authenticates the user and validates file type, size, and target key
+3. your backend returns a short-lived **presigned `PUT` URL**
+4. the browser uploads **directly to R2**
+5. your app stores the **object key + metadata**, not the presigned URL
+
+Good practice:
+
+- generate keys server-side, for example `users/<userId>/<uuid>.jpg`
+- restrict `Content-Type` when signing uploads
+- keep upload URLs short-lived
+- configure bucket **CORS** if the browser uploads directly
+
+Cloudflare docs:
+
+- [Presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/)
+- [Configure CORS](https://developers.cloudflare.com/r2/buckets/cors/)
+- [Storing user generated content](https://developers.cloudflare.com/reference-architecture/diagrams/storage/storing-user-generated-content/)
+
+---
+
+## Viewing / serving files
+
+### Public files
+
+For public images, media, and assets:
+
+- use a **public bucket**
+- attach a **custom domain**
+- serve stable URLs from that domain
+- let Cloudflare cache them
+
+This is the best fit for avatars, product images, blog images, and other content that anyone may view.
+
+Cloudflare docs:
+
+- [Public buckets](https://developers.cloudflare.com/r2/buckets/public-buckets/)
+
+### Private or authenticated files
+
+For invoices, receipts, private user uploads, paid content, or tenant-scoped assets:
+
+- keep the bucket **private**
+- store only the object key in your database
+- serve through a **Worker** that checks session/JWT/permissions before reading from R2
+
+This is usually the best default when access depends on the current user.
+
+Cloudflare docs:
+
+- [Use R2 from Workers](https://developers.cloudflare.com/r2/api/workers/workers-api-usage/)
+
+### Time-limited direct access
+
+You can also mint a **presigned `GET` URL** for temporary direct viewing or download.
+
+Important caveat:
+
+- presigned URLs work on the **R2 S3 endpoint**
+- they **do not work with custom domains**
+- treat them as **bearer tokens**
+
+So they are good for short-lived direct access, but not for polished custom-domain media delivery.
+
+Cloudflare docs:
+
+- [Presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/)
+
+### Team-only / org-only files
+
+If access should be limited to employees or teammates, protect the R2 custom domain with **Cloudflare Access**.
+
+Cloudflare docs:
+
+- [Protect an R2 Bucket with Cloudflare Access](https://developers.cloudflare.com/r2/tutorials/cloudflare-access/)
+
+### Signed links on a custom domain
+
+If you want expiring links on `https://cdn.example.com/...`, R2 presigned URLs are not the right tool.
+
+Instead use:
+
+- a **Worker** that signs and verifies access tokens, or
+- **Cloudflare WAF token authentication / HMAC validation** on the custom domain
+
+Cloudflare docs:
+
+- [Configure token authentication](https://developers.cloudflare.com/waf/custom-rules/use-cases/configure-token-authentication/)
+- [HMAC validation function](https://developers.cloudflare.com/ruleset-engine/rules-language/functions/#hmac-validation)
+- [Workers request signing example](https://developers.cloudflare.com/workers/examples/signing-requests/)
+
+---
+
+## Development vs production
+
+### Development
+
+By default, local Worker development uses **local simulated bindings**, including local R2-style storage.
+
+Use this for normal development.
+
+Devflare-specific local note:
+
+- local R2 bindings are available to your Worker code, tests, and bridge helpers
+- Devflare does **not** currently publish a stable browser-facing local bucket URL contract
+- do **not** build frontend code around an assumed local bucket origin
+- for browser-visible local flows, serve objects through your Worker or app routes instead
+
+Practical local-serving example:
+
+```ts
+// src/routes/files/[...key].ts
+import type { FetchEvent } from 'devflare/runtime'
+
+export async function GET({ env, params }: FetchEvent<DevflareEnv>): Promise<Response> {
+	const object = await env.FILES.get(params.key)
+	if (!object) {
+		return new Response('Not Found', { status: 404 })
+	}
+
+	return new Response(object.body, {
+		headers: {
+			'Content-Type': object.httpMetadata?.contentType ?? 'application/octet-stream',
+			'Cache-Control': 'private, max-age=0'
+		}
+	})
+}
+```
+
+With that pattern, your browser talks to your app URL, not to an assumed local bucket URL. That keeps local behavior aligned with the Worker-auth or custom-domain patterns you are likely to use in production.
+
+Only connect to real remote buckets when you intentionally need integration testing, and prefer **separate dev/staging buckets** instead of production buckets.
+
+Important remote-dev reality:
+
+- remote bindings touch **real data**
+- remote bindings incur **real costs**
+- avoid pointing local development at production uploads unless absolutely necessary
+
+Cloudflare docs:
+
+- [Workers development & testing](https://developers.cloudflare.com/workers/development-testing/)
+- [Remote bindings](https://developers.cloudflare.com/workers/development-testing/#remote-bindings)
+
+### Production
+
+For production:
+
+- use a **custom domain**, not `r2.dev`
+- choose public vs private intentionally per bucket or per content class
+- keep sensitive content private behind a Worker, Access, or token validation
+- configure **CORS** intentionally for browser upload/download flows
+- use separate **dev**, **staging**, and **prod** buckets
+
+Optional performance feature:
+
+- if users upload from many regions, consider **Local Uploads** for better upload performance
+
+Cloudflare docs:
+
+- [Public buckets](https://developers.cloudflare.com/r2/buckets/public-buckets/)
+- [Local uploads](https://developers.cloudflare.com/r2/buckets/local-uploads/)
+
+---
+
+## Recommended defaults
+
+If you need a sane default architecture:
+
+- **public assets** → public bucket + custom domain
+- **user uploads** → presigned `PUT` upload + object key stored in DB
+- **private assets** → private bucket + Worker-gated reads
+- **internal assets** → custom domain + Cloudflare Access
+- **custom-domain expiring links** → Worker token auth or WAF HMAC validation
+
+If you only remember one rule, remember this:
+
+> Use **presigned URLs** for short-lived direct R2 access, but use a **Worker/custom domain auth layer** for polished private media delivery.