Critical Update for ESHOPMAN Custom File Providers: Addressing an Undocumented Encoding Change

Critical Update for ESHOPMAN Custom File Providers: Addressing an Undocumented Encoding Change

The flexibility of ESHOPMAN, as a headless commerce platform deeply integrated with HubSpot, empowers merchants and developers to customize every aspect of their storefronts, including how media assets are managed. Custom file providers are a cornerstone of this flexibility, allowing ESHOPMAN to connect with various storage solutions beyond the default. However, keeping these custom integrations robust requires vigilance, especially when core platform updates introduce subtle yet significant changes.

The Core Issue: A Silent Encoding Shift in ESHOPMAN Admin API

Recently, the ESHOPMAN community identified a critical, undocumented breaking change in the ESHOPMAN Admin API's file upload mechanism. Specifically, between ESHOPMAN versions 2.8.x and 2.15.3, the encoding used for file content passed to custom file providers via the /admin/uploads route underwent a silent but impactful transformation. Previously, file buffers were converted to a 'binary' string, but in newer versions, this was changed to 'base64'.

Impact on Custom File Providers

This change has a profound effect on any custom file provider (such as those integrating with MinIO or similar storage services) that relied on the 'binary' encoding for processing uploaded files. If your custom provider's implementation uses Buffer.from(file.content, 'binary') to reconstruct the file, it will silently corrupt all uploaded files. The ESHOPMAN Admin API will report a successful upload with a 200 status code, and the file might even appear with the correct size in your storage. However, upon attempting to download or open the file, it will be unreadable.

Understanding the Technical Change

The core of the issue lies in how the file buffer is converted to a string before being passed to your custom provider and how your provider then attempts to convert it back.

• In ESHOPMAN v2.8.x (and earlier):

  content: f.buffer.toString("binary")

  Your custom provider would then correctly interpret this using:

  Buffer.from(file.content, 'binary')

• In ESHOPMAN v2.15.3 (and later):

  content: f.buffer.toString("base64")

  If your custom provider still uses Buffer.from(file.content, 'binary'), it will misinterpret the base64 encoded string, leading to corrupted files. The fix requires updating your custom provider to match the new encoding:

Buffer.from(file.content, 'base64')

Actionable Solution for Developers

To prevent or resolve file corruption issues in your ESHOPMAN setup, developers managing custom file providers must update their code to expect and handle base64 encoding for file content. Review your custom provider's implementation, particularly the part responsible for converting the file.content string back into a buffer for storage.

Ensure your code reflects the following change:

// BEFORE (potentially problematic with newer ESHOPMAN versions)
const fileBuffer = Buffer.from(file.content, 'binary');

// AFTER (correct for ESHOPMAN v2.15.3 and later)
const fileBuffer = Buffer.from(file.content, 'base64');

This adjustment is crucial for maintaining the integrity of all media assets, product images, and other files managed through your ESHOPMAN Admin API and subsequently deployed via HubSpot CMS.

Best Practices for ESHOPMAN Upgrades

This incident underscores the importance of thorough testing, especially for custom integrations, when upgrading ESHOPMAN versions. While ESHOPMAN strives for clear documentation, undocumented changes can occur. Engaging with the ESHOPMAN community and regularly reviewing release notes (even for minor versions) can help identify potential breaking changes early. The ESHOPMAN ecosystem thrives on shared knowledge, and insights like these are invaluable for all developers and merchants leveraging the power of headless commerce with HubSpot.