Skip to main content
Version: 1.0.0

createRenderJob

Function Name: createRenderJob

Author: Gabriele Gilio Creation Date: 25/09/2025
Last Reviewer: Gabriele Gilio

Trigger: HTTPS (onRequest)

Purpose: Handles the creation of 3D thumbnail rendering jobs by validating requests, saving them to Firestore, and queueing them via Google Cloud Tasks for asynchronous processing.

Detailed Functionality​

This Firebase Function manages the complete workflow for 3D thumbnail rendering requests through an asynchronous processing architecture:

1. REQUEST VALIDATION AND CORS HANDLING​

  • Accepts POST requests with CORS support for frontend calls
  • Validates required parameters: modelId, templateId, imageWidth, imageHeight
  • Optional parameters: reflect (boolean as string), noShadows (boolean as string)
  • Returns 400 Bad Request for missing required parameters
  • Returns 405 Method Not Allowed for non-POST requests

2. JOB ID GENERATION AND FIRESTORE STORAGE​

  • Generates unique job ID using UUID v4
  • Creates document in 'RenderingJobs' collection with:
    • status: "queued"
    • createdAt: ISO timestamp
    • modelId: provided model ID
    • templateId: provided template ID
    • imageWidth: provided width
    • imageHeight: provided height
  • CRITICAL: If Firestore save fails, execution is immediately terminated with 500 error
  • Returns error message: "Unable to save the rendering job in the database. Try again later."
  • Logs job creation details for debugging and monitoring

3. TEMPLATE CONFIGURATION RETRIEVAL​

  • Retrieves template document from 'RenderingTemplates' collection using templateId
  • Returns 404 error if template not found
  • Extracts and transforms template data into worker format:
    • camera_fov: from fieldOfView
    • camera_position: from cameraPosition
    • camera_rotation: from cameraRotation
    • camera_look_at: from cameraLookAt
    • view_name: from viewName
    • light_exposition: from lightExposition (default: 1)

4. PAYLOAD PREPARATION​

  • Creates base payload with: modelId, templateConfig, outputWidth, outputHeight, jobId, frontendUrl
  • Conditionally adds reflect and noShadows parameters if provided
  • Sets frontendUrl to staging environment: "https://ars-renderer-staging.web.app/Renderer"

5. ENVIRONMENT-SPECIFIC PROCESSING​

Development Environment (Local Emulator):

  • Makes direct HTTP request to local worker at "http://127.0.0.1:8080/process-render"
  • Uses axios for immediate processing without queueing
  • Provides immediate feedback on worker response
  • Returns error if HTTP request fails

Production Environment (Staging/Production):

6. CLOUD TASKS CONFIGURATION​

  • Queue: 'thumbnail-render-queue'
  • Region: 'europe-central2'
  • HTTP Method: POST
  • Content-Type: application/json
  • Schedule delay: 5 seconds
  • Payload: Base64 encoded JSON

7. WORKER COMMUNICATION​

The worker receives:

  • modelId: ID of the 3D model to render
  • templateConfig: Camera configuration from template
  • outputWidth/outputHeight: Image dimensions (imageWidth x imageHeight)
  • jobId: Unique job ID for tracking
  • frontendUrl: Frontend URL for potential callbacks
  • reflect: Optional reflective plane setting
  • noShadows: Optional shadow rendering setting

8. RESPONSE HANDLING​

  • Returns 202 Accepted status for successful queueing
  • Includes jobId, status ("queued"), and environment-specific message
  • Development message: "Rendering request sent to local worker successfully."
  • Production message: "Rendering request queued successfully."
  • Returns 500 Internal Server Error for failures in task creation or worker communication

9. ERROR HANDLING AND LOGGING​

  • Comprehensive logging for each phase of the process
  • BLOCKING ERROR HANDLING: Firestore save failures immediately terminate execution with 500 error
  • Separate error handling for: missing parameters, template not found, Firestore failures, task creation failures
  • CRITICAL DEPENDENCY: Job tracking requires successful Firestore save before proceeding
  • Detailed payload and response logging for debugging
  • Environment detection and URL selection logging

Technical Features​

  • PROTOCOL: HTTPS with CORS support
  • ARCHITECTURE: Asynchronous processing with immediate response
  • QUEUE: Google Cloud Tasks for reliable job processing
  • STORAGE: Firestore for job persistence and template configuration
  • WORKER: Cloud Run service for actual rendering processing
  • UUID: Version 4 for unique job identification
  • REGIONS: europe-central2 for optimal performance
  • TIMEOUT: No explicit timeout (relies on Cloud Tasks and worker timeouts)

Integration​

  • Called by: Frontend applications, external APIs
  • Input: modelId, templateId, imageWidth, imageHeight, reflect?, noShadows?
  • Output: {jobId: string, status: string, message: string}
  • Dependencies: Firebase Firestore, Google Cloud Tasks, UUID, Axios (dev), CORS
  • Worker Integration: Cloud Run service for actual rendering processing

Input (Payload):​

{
  "modelId": "OV4QJCsmwROVBKXsdqrB",
  "templateId": "2gzlELEmDgTJcI10uuAC",
  "imageWidth": 1400,
  "imageHeight": 628,
  "reflect": "true",
  "noShadows": "true"
}

Parameters:

  • modelId (string, required): ID of the document in the Variants collection containing variant details
  • templateId (string, required): ID of the document in the RenderingTemplates collection containing rendering template details
  • imageWidth (number, required): Width of the rendering image output
  • imageHeight (number, required): Height of the rendering image output
  • reflect (string, optional): If equals to "true", a reflective plane is rendered under the scene
  • noShadows (string, optional): If equals to "true", shadows are not rendered in the output

Output (Success):​

{
  "jobId": "00ea49e1-6b24-4bf3-8f80-091189de8ae7",
  "status": "queued",
  "message": "Rendering request queued successfully."
}

Response Properties:

  • jobId (string): UUID v4 ID of the document in the RenderingJobs collection generated by this function
  • status (string): Status of the rendering job (always "queued" for successful requests)
  • message (string): Environment-specific feedback message. Local environment: "Rendering request sent to local worker successfully.", Production environment: "Rendering request queued successfully."

Testing​

URL (if HTTPS): http://127.0.0.1:5001/arshadesstaging/europe-central2/createRenderJob

Test with Emulator:

  1. Start the Firebase emulator: firebase emulators:start --only functions
  2. Ensure you're using Node.js version 20: nvm use 20
  3. Test with curl:
curl -X POST "http://127.0.0.1:5001/arshadesstaging/europe-central2/createRenderJob" \
-H "Content-Type: application/json" \
-d '{
  "modelId": "OV4QJCsmwROVBKXsdqrB",
  "templateId": "2gzlELEmDgTJcI10uuAC",
  "imageWidth": 1400,
  "imageHeight": 628,
  "reflect": "true",
  "noShadows": "true"
}'

Postman Testing:

Deploy Command:​

firebase deploy --only functions:createRenderJob

Production URL:​

createRenderJob: https://europe-central2-arshades-7e18a.cloudfunctions.net/createRenderJob