Skip to Content
Slloy Docs
Generation, Settlement & Safeguards

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:

  1. Validation & Compliance Gate:
    • Validates prompt length, count (1..4), aspectRatio (global IMAGE_RATIOS + per-model supportsRatio()), model readiness (resolveForRequest(rawModel)), and reference images (checkRefImage in server/src/imageSniff.ts).
    • Screens requests carrying reference images against compliance redlines (screenGenerationRequest blocks efficacy before/after comparisons and minor photo modifications with HTTP 400).
  2. Pre-Charge & Batch Creation:
    • Generates a batch ID (task_id = img_<timestamp>_<rand>) and inserts count rows in generations (kind = 'image', status = 'pending').
    • Atomically deducts model.credits * count via repo.chargeCredit.
  3. Dispatch (acceptJob):
    • Primary Path — Cloudflare Queue (IMAGE_QUEUE):
      • Queue name: slloy-production-images (staging: slloy-staging-images), with max_batch_size = 1, max_retries = 3, and dead-letter queue slloy-production-images-dlq.
      • Offloads any reference image data URLs to temporary R2 objects (_refs/<batch>/<i>.<ext>), enqueues a compact ImageJobMessage, and immediately returns HTTP 202 (status: "pending", batchId, generationIds) for the frontend to poll GET /api/generate/status/:batchId.
    • Fallback Path — Inline Execution:
      • Used in local Node tests or if IMAGE_QUEUE is unbound/unavailable. Calls runImageJob() directly within the request (up to IMAGE_JOB_CONCURRENCY = 4 parallel upstream requests; config.batchRefFirstOnly sends reference images only on index 0 when enabled).

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, runImageJob queries repo.getGeneration(id, userId) for each generationId in the batch.
  • Rows already in status = 'success' or status = 'failed' are skipped (outcome.reused++).
  • Only rows still in status = 'pending' are dispatched to provider.generateImage.
  • Final DB writes use repo.finishGeneration(id, ..., { onlyIfStatus: "pending" }) or forceFailVideoGeneration (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, storeRefImages rolls back and deletes all already-written keys in that batch before rethrowing.
  • Read (loadRefImages):
    • The Queue consumer reads each refKey from R2 and reconstructs the data:<contentType>;base64,... payload for upstream Ark/DashScope calls.
  • Cleanup (deleteRefImages & sweepRefImages):
    • Once runImageJob completes cleanly (all items in terminal success or failed state), consumeImageQueue deletes message.body.refKeys and calls message.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 by sweepRefImages() during the 5-minute Cron once older than 1 hour (REF_IMAGE_MAX_AGE_MS = 3,600,000 ms, up to 200 keys per round).

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):

  1. Decode & Memory Guard:
    • Sniffs magic bytes (0xFF 0xD8 0xFF for JPEG, 0x89 0x50 0x4E 0x47 for PNG) and decodes directly into a 3-channel 8-bit Uint8Array RGB buffer (skipping alpha allocation to save 25% memory).
    • Rejects images with width * height > 24,000,000 (MAX_PIXELS = 24MP) to stay safely within the 128 MB Worker isolate memory limit.
  2. 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's 248–249 edge vignette noise while keeping contact shadows).
    • A row or column is counted as content only if at least 0.25% (CONTENT_FRACTION = 0.0025, min 4 pixels) of its pixels are non-white.
  3. 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, returns null (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).
  4. Lossless PNG Output:
    • Centers the cropped bounding box onto a pure white (RGB 255, 255, 255) 3-channel square canvas and encodes as lossless .png so background pixels are guaranteed to be exact 255 without JPEG ringing artifacts.
    • If any decoding or framing error occurs, PURE_WHITE_FRAME logs frame_failed and returns null, falling back to persisting the raw upstream image so a post-processing bug never drops a user's paid image.

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 Content for video scrubbing).
  • Content-Type + Magic-Byte Sniffing (download & sniffExt):
    • Checks the HTTP Content-Type header first (image/png, image/jpeg, image/webp, image/gif, video/mp4).
    • Because Alibaba DashScope OSS frequently returns Content-Type: application/octet-stream for valid PNGs and MP4s, download() falls back to inspecting the first 16 magic bytes (89504e47 -> .png, ffd8ff -> .jpg, 47494638 -> .gif, 52494646....57454250 -> .webp, ....66747970 -> .mp4).
  • Retry & Silent Degradation:
    • Downloads use STORAGE_TIMEOUT_MS = 120,000 ms (120s) and enforce config.storage.maxBytes.
    • Retries up to PERSIST_ATTEMPTS = 3 times (with 2s, 4s backoff) 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, runImageJob logs [image-job] persist failed and falls back to saving the upstream temporary URL so the user can still view and download their image immediately.

5. 10-Minute Stale Image Sweeper (imageSweeper.ts)

Executed every 5 minutes by videoSweeper.sweepOnce() (SWEEP_CRON = "*/5 * * * *"):

  1. Queries repo.listStalePendingImages({ minAgeMin: 10, limit: 50 }) for any kind = 'image' generation still in status = 'pending' older than 10 minutes (well above the 120s upstream timeout and 3-attempt Queue retry window).
  2. Calls forceFailVideoGeneration(gen, { reason: "exceeded_max_age" }), which atomically transitions the row from pending -> failed with failCode = "TIMEOUT", costCny = 0, and refunds the charged credits in the same PostgreSQL transaction.
  3. Invokes sweepRefImages() to delete any orphaned _refs/ objects in R2 older than 1 hour.

On this page