Package io.meeds.mcp.server.tool.util

Class UploadToolUtils

java.lang.Object

io.meeds.mcp.server.tool.util.UploadToolUtils

public final class UploadToolUtils
extends Object

Helpers to turn an image (from a URL or base64) into a platform UploadService uploadId that any upload-consuming API (activity/comment attachments, note featured image, avatars, documents…) accepts. This is the missing "materialize" side of UploadService, which otherwise only registers/reads resources.

Fetching an image from a URL happens server-side, so the URL is validated against SSRF (only public http/https hosts are allowed).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	UploadToolUtils.FetchedContent	A downloaded image: its bytes, resolved mime type and a file name.
static final record	UploadToolUtils.ImageSource	The three mutually-exclusive ways to provide an image to resolveImage(org.exoplatform.social.attachment.AttachmentService, org.exoplatform.commons.file.services.FileService, org.exoplatform.services.security.Identity, io.meeds.mcp.server.tool.util.UploadToolUtils.ImageSource, long): a public http(s) URL, base64-encoded bytes, or a reference to an existing platform attachment (attachmentObjectType + attachmentObjectId).

Field Summary

Fields

Modifier and Type	Field	Description
static final long	DEFAULT_MAX_BYTES	10 MB default ceiling for a fetched/decoded image.

Method Summary

Modifier and Type	Method	Description
static byte[]	decodeBase64(String data)
static UploadToolUtils.FetchedContent	fetchImage(String url, long maxBytes)	Downloads an image over http(s) after validating the URL against SSRF.
static UploadToolUtils.FetchedContent	fetchUrl(String url, long maxBytes, String defaultFileName)	Downloads any file (not restricted to images) over http(s) after validating the URL against SSRF.
static String	materialize(org.exoplatform.upload.UploadService uploadService, byte[] bytes, String fileName, String mimeType)	Stages raw bytes to a temp file and registers an UploadResource, returning its uploadId.
static String	materializeFromUrlOrBase64(org.exoplatform.upload.UploadService uploadService, String imageUrl, String imageBase64, long maxBytes)	Resolves an image from exactly one of an http(s) URL or a base64 string, stages it and registers it with UploadService.
static void	release(org.exoplatform.upload.UploadService uploadService, String uploadId)	Removes the upload resource and its temp file.
static UploadToolUtils.FetchedContent	resolveImage(org.exoplatform.social.attachment.AttachmentService attachmentService, org.exoplatform.commons.file.services.FileService fileService, org.exoplatform.services.security.Identity aclIdentity, UploadToolUtils.ImageSource source, long maxBytes)	Resolves an image from exactly one of three mutually exclusive sources — an http(s) URL, a base64 string, or an ACL-checked reference to a file already attached to a platform object (attachment_object_type + attachment_object_id) — into its raw bytes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DEFAULT_MAX_BYTES

public static final long DEFAULT_MAX_BYTES

10 MB default ceiling for a fetched/decoded image.

See Also:

• Constant Field Values

Method Details

materializeFromUrlOrBase64

public static String materializeFromUrlOrBase64(org.exoplatform.upload.UploadService uploadService,
 String imageUrl,
 String imageBase64,
 long maxBytes)

Resolves an image from exactly one of an http(s) URL or a base64 string, stages it and registers it with UploadService.

Returns:

the generated uploadId to pass to a consumer API

resolveImage

public static UploadToolUtils.FetchedContent resolveImage(org.exoplatform.social.attachment.AttachmentService attachmentService,
 org.exoplatform.commons.file.services.FileService fileService,
 org.exoplatform.services.security.Identity aclIdentity,
 UploadToolUtils.ImageSource source,
 long maxBytes)
                                                   throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Resolves an image from exactly one of three mutually exclusive sources — an http(s) URL, a base64 string, or an ACL-checked reference to a file already attached to a platform object (attachment_object_type + attachment_object_id) — into its raw bytes. Consumers that need an uploadId pass the result to materialize(org.exoplatform.upload.UploadService, byte[], java.lang.String, java.lang.String); consumers that need raw bytes (avatars/banners) use it directly.

The attachment reference is read as the given user via AttachmentService.getAttachmentFileIds(String, String, Identity), so platform ACLs are enforced (an unreadable object throws IllegalAccessException — no IDOR).

Returns:

the resolved image bytes, mime type and file name

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

fetchImage

public static UploadToolUtils.FetchedContent fetchImage(String url,
 long maxBytes)

Downloads an image over http(s) after validating the URL against SSRF.

fetchUrl

public static UploadToolUtils.FetchedContent fetchUrl(String url,
 long maxBytes,
 String defaultFileName)

Downloads any file (not restricted to images) over http(s) after validating the URL against SSRF. The mime type is resolved from the Content-Type response header (falling back to application/octet-stream) and the file name is derived from the URL path (falling back to defaultFileName). Used by document / generic file upload tools.

Parameters:

url - the http(s) URL to download

maxBytes - the maximum number of bytes to read before failing

defaultFileName - a file name to use when the URL path has none

Returns:

the downloaded bytes, resolved mime type and file name

materialize

public static String materialize(org.exoplatform.upload.UploadService uploadService,
 byte[] bytes,
 String fileName,
 String mimeType)

Stages raw bytes to a temp file and registers an UploadResource, returning its uploadId.

release

public static void release(org.exoplatform.upload.UploadService uploadService,
 String uploadId)

Removes the upload resource and its temp file. Safe to call in a finally.

decodeBase64

public static byte[] decodeBase64(String data)