Image Generation Pipeline, Queues & R2 Persistence
Accept-and-queue architecture via Cloudflare Queues, R2 temporary reference image offloading, pure-white product framing, magic-byte R2 persistence, and 10-minute zombie sweepers.
Image generation (POST /api/generate, server/src/imageJobs.ts, server/src/storage.ts, server/src/pureWhiteFrame.ts, and server/src/imageSweeper.ts) uses an Accept + Queue architecture designed for Cloudflare Workers' execution and memory limits.
1. Synchronous Inline vs. Async Cloudflare Queue Flow
When a user submits POST /api/generate:
- Validation & Compliance Gate:
- Validates prompt length,
count(1..4),aspectRatio(globalIMAGE_RATIOS+ per-modelsupportsRatio()), model readiness (resolveForRequest(rawModel)), and reference images (checkRefImageinserver/src/imageSniff.ts). - Screens requests carrying reference images against compliance redlines (
screenGenerationRequestblocks efficacy before/after comparisons and minor photo modifications withHTTP 400).
- Validates prompt length,
- Pre-Charge & Batch Creation:
- Generates a batch ID (
task_id = img_<timestamp>_<rand>) and insertscountrows ingenerations(kind = 'image',status = 'pending'). - Atomically deducts
model.credits * countviarepo.chargeCredit.
- Generates a batch ID (
- Dispatch (
acceptJob):- Primary Path — Cloudflare Queue (
IMAGE_QUEUE):- Queue name:
slloy-production-images(staging:slloy-staging-images), withmax_batch_size = 1,max_retries = 3, and dead-letter queueslloy-production-images-dlq. - Offloads any reference image data URLs to temporary R2 objects (
_refs/<batch>/<i>.<ext>), enqueues a compactImageJobMessage, and immediately returnsHTTP 202(status: "pending",batchId,generationIds) for the frontend to pollGET /api/generate/status/:batchId.
- Queue name:
- Fallback Path — Inline Execution:
- Used in local Node tests or if
IMAGE_QUEUEis unbound/unavailable. CallsrunImageJob()directly within the request (up toIMAGE_JOB_CONCURRENCY = 4parallel upstream requests;config.batchRefFirstOnlysends reference images only on index0when enabled).
- Used in local Node tests or if
- Primary Path — Cloudflare Queue (
Idempotent Queue Consumption (consumeImageQueue & runImageJob)
Because Cloudflare Queues provide at-least-once delivery, a retried message must never double-generate or double-refund an already settled image:
- Before calling upstream,
runImageJobqueriesrepo.getGeneration(id, userId)for eachgenerationIdin the batch. - Rows already in
status = 'success'orstatus = 'failed'are skipped (outcome.reused++). - Only rows still in
status = 'pending'are dispatched toprovider.generateImage. - Final DB writes use
repo.finishGeneration(id, ..., { onlyIfStatus: "pending" })orforceFailVideoGeneration(row-locked transaction).
2. R2 Temporary Reference Image Offloading (_refs/)
Cloudflare Queue messages have a strict 128 KB size limit, whereas normalized browser reference images are up to 2.5 MB each (up to 6 images).
- Write (
storeRefImages):- Converts each
data:image/(png|jpeg|jpg|webp);base64,...string into raw bytes and writes it to R2 under key_refs/<safeBatchId>/<index>.<ext>(REF_IMAGE_PREFIX = "_refs/"). - If writing any image in the batch fails,
storeRefImagesrolls back and deletes all already-written keys in that batch before rethrowing.
- Converts each
- Read (
loadRefImages):- The Queue consumer reads each
refKeyfrom R2 and reconstructs thedata:<contentType>;base64,...payload for upstream Ark/DashScope calls.
- The Queue consumer reads each
- Cleanup (
deleteRefImages&sweepRefImages):- Once
runImageJobcompletes cleanly (all items in terminalsuccessorfailedstate),consumeImageQueuedeletesmessage.body.refKeysand callsmessage.ack(). - If a consumer throws an infrastructure error and calls
message.retry(),_refs/objects are kept for the retry attempt. - Orphaned
_refs/objects (from messages that exhausted retries into DLQ or Worker crashes before enqueueing) are deleted bysweepRefImages()during the 5-minute Cron once older than1hour (REF_IMAGE_MAX_AGE_MS = 3,600,000 ms, up to200keys per round).
- Once
3. Pure-White Product Framing (pureWhiteFrame.ts)
For e-commerce product shots using preset PURE_WHITE_FRAME_PRESET = "product-photo-pure-white" (Family F F-02), upstream image models with reference images typically fill only 40%–45% of the frame rather than Amazon's required 85% product fill ratio.
Because Cloudflare Workers cannot run native sharp / libvips, server/src/pureWhiteFrame.ts implements deterministic pure-JS post-processing using jpeg-js and fast-png during R2 persistence (transform: PURE_WHITE_FRAME):
- Decode & Memory Guard:
- Sniffs magic bytes (
0xFF 0xD8 0xFFfor JPEG,0x89 0x50 0x4E 0x47for PNG) and decodes directly into a 3-channel 8-bitUint8ArrayRGB buffer (skipping alpha allocation to save25%memory). - Rejects images with
width * height > 24,000,000(MAX_PIXELS = 24MP) to stay safely within the128 MBWorker isolate memory limit.
- Sniffs magic bytes (
- Vignette-Resistant Bounding Box Detection (
contentBounds):- Treats any pixel with
R < 245 || G < 245 || B < 245(WHITE_THRESHOLD = 245) as non-white content (filtering out Seedream's248–249edge vignette noise while keeping contact shadows). - A row or column is counted as content only if at least
0.25%(CONTENT_FRACTION = 0.0025, min4pixels) of its pixels are non-white.
- Treats any pixel with
- 85% Target Canvas Sizing (
canvasSide):- If the content already fills
>= 97%(ALREADY_FRAMED = 0.97) of both dimensions, or if the image is all-white/non-white background, returnsnull(leaves original image untouched). - Computes target square canvas side:
target = Math.round(Math.max(bounds.width, bounds.height) / 0.85); // TARGET_FILL = 0.85 side = Math.min(originalSide, Math.max(Math.min(1000, originalSide), target)); // MIN_SIDE = 1000 - Never upscales the product (preventing blurry interpolation).
- If the content already fills
- Lossless PNG Output:
- Centers the cropped bounding box onto a pure white (
RGB 255, 255, 255) 3-channel square canvas and encodes as lossless.pngso background pixels are guaranteed to be exact255without JPEG ringing artifacts. - If any decoding or framing error occurs,
PURE_WHITE_FRAMElogsframe_failedand returnsnull, falling back to persisting the raw upstream image so a post-processing bug never drops a user's paid image.
- Centers the cropped bounding box onto a pure white (
4. R2 Media Persistence (storage.ts)
Upstream provider URLs (Volcengine TOS and Alibaba OSS) expire after 24 hours. persistImage() downloads the temporary URL immediately upon generation and stores it in Cloudflare R2 (slloy-production-uploads via env.BUCKET):
- Key Format (
buildKey):<YYYY>/<MM>/<genId>_<12-hex>.<ext>, served as a relative path/uploads/<YYYY>/<MM>/<genId>_<12-hex>.<ext>with HTTP Range support (206 Partial Contentfor video scrubbing). - Content-Type + Magic-Byte Sniffing (
download&sniffExt):- Checks the HTTP
Content-Typeheader first (image/png,image/jpeg,image/webp,image/gif,video/mp4). - Because Alibaba DashScope OSS frequently returns
Content-Type: application/octet-streamfor valid PNGs and MP4s,download()falls back to inspecting the first16magic bytes (89504e47->.png,ffd8ff->.jpg,47494638->.gif,52494646....57454250->.webp,....66747970->.mp4).
- Checks the HTTP
- Retry & Silent Degradation:
- Downloads use
STORAGE_TIMEOUT_MS = 120,000 ms(120s) and enforceconfig.storage.maxBytes. - Retries up to
PERSIST_ATTEMPTS = 3times (with2s,4sbackoff) on transient network/5xx errors; fatal validation errors (STORAGE_BAD_TYPE,STORAGE_TOO_LARGE,STORAGE_EMPTY_BODY,STORAGE_BAD_KEY) abort immediately. - If all 3 attempts fail on an active image generation,
runImageJoblogs[image-job] persist failedand falls back to saving the upstream temporary URL so the user can still view and download their image immediately.
- Downloads use
5. 10-Minute Stale Image Sweeper (imageSweeper.ts)
Executed every 5 minutes by videoSweeper.sweepOnce() (SWEEP_CRON = "*/5 * * * *"):
- Queries
repo.listStalePendingImages({ minAgeMin: 10, limit: 50 })for anykind = 'image'generation still instatus = 'pending'older than10minutes (well above the120supstream timeout and 3-attempt Queue retry window). - Calls
forceFailVideoGeneration(gen, { reason: "exceeded_max_age" }), which atomically transitions the row frompending->failedwithfailCode = "TIMEOUT",costCny = 0, and refunds the charged credits in the same PostgreSQL transaction. - Invokes
sweepRefImages()to delete any orphaned_refs/objects in R2 older than1hour.
Channel Procurement, Quotas & Cost Alerting
Active procurement rules, account balance thresholds, discount verification, and multi-layer alerting for Volcengine Ark, Alibaba DashScope, and Kuaishou Kling.
Video Generation, Polling & Atomic Settlement
Two-phase async video pipeline, portrait bridge, browser polling vs. 5-minute Cron sweeper, atomic conditional settlement, and 24-hour signed URL expiry rules.