native_dynamic_media.h

Go to the documentation of this file.

/**
 * @file
 * @brief Media and static asset serving for in-process dynamic handling.
 *
 * Resolves and serves files from the app's artifact directory for
 * routes that map to static assets such as CSS, JavaScript, images,
 * and JSON metadata files.
 *
 * Also provides media mutation helpers (upload, delete, path resolution)
 * so that the dynamic runtime can handle file uploads and media tree
 * management without delegating to a child process or app-owned shell logic.
 */
 
#ifndef PHAROS_NATIVE_DYNAMIC_MEDIA_H
#define PHAROS_NATIVE_DYNAMIC_MEDIA_H
 
#include "native_connection.h"
#include "native_http_request.h"
 
#include <stddef.h>
 
/** @name Media serving helpers
 * @{
 */
 
/**
 * @brief Determines whether a request path targets a known static asset.
 *
 * Paths beginning with @c /static/, @c /media/, or matching a
 * well-known JSON endpoint (e.g. @c /manifest.json) are considered
 * static assets that can be served directly from the artifact directory.
 *
 * @param path  Normalised request path (query string stripped).
 * @return Non-zero when the path is a known static asset, 0 otherwise.
 */
int native_dynamic_media_is_static_path(const char *path);
 
/**
 * @brief Serves a static asset from the artifact directory.
 *
 * Resolves the file path, determines the content type, and writes
 * the full HTTP response to @p connection.
 *
 * @param connection  Connection to write the response to.
 * @param artifact_dir  App artifact root directory.
 * @param path  Normalised request path.
 * @param request  Parsed request (used for conditional GET).
 * @return HTTP status code written, or a negative value on error.
 */
int native_dynamic_media_serve_asset(
  NativeConnection *connection,
  const char *artifact_dir,
  const char *path,
  const HttpRequest *request
);
 
/**
 * @brief Resolves a request path to a file-system path inside the artifact directory.
 *
 * Returns NULL when the path does not map to a valid asset file.
 *
 * @param artifact_dir  App artifact root directory.
 * @param path  Normalised request path.
 * @return Newly allocated file-system path, or NULL.  Caller must free.
 */
char *native_dynamic_media_resolve_path(
  const char *artifact_dir,
  const char *path
);
 
/** @} */
 
/** @name Media mutation helpers
 * @{
 */
 
/**
 * @brief Sanitises a raw upload filename into a safe filesystem name.
 *
 * Strips directory components, replaces unsafe characters with @c _,
 * and removes leading/trailing dots, dashes, and underscores.
 *
 * @param raw_name  Raw filename from the upload (may be NULL).
 * @return Newly allocated safe filename, or an empty string on failure.
 *         Caller must free.
 */
char *safe_upload_filename_dup(const char *raw_name);
 
/**
 * @brief Resolves a media URL into an on-disk path inside an app artifact directory.
 *
 * @param artifact_dir  Artifact directory that owns the media tree.
 * @param media_url  Media URL beginning with @c /media/.
 * @return Newly allocated disk path, or NULL when the URL is outside the managed tree.
 *         Caller must free.
 */
char *media_disk_path_dup(const char *artifact_dir, const char *media_url);
 
/**
 * @brief Ensures a managed media subtree exists for an entity type by reading
 *        the media policy fixture at {artifact_dir}/data/framework/media-policy-v1.json.
 *
 * Loads the fixture, finds the entry matching @p entity_type, substitutes
 * @p entity_slug into the @c base_path_template, and creates the base
 * directory and all declared subdirectories.
 *
 * @param artifact_dir  App artifact root directory.
 * @param entity_type   Entity type key to look up in the fixture (e.g. "business").
 * @param entity_slug   Entity slug to substitute into the path template.
 * @return 0 on success, or a non-zero status code on failure.
 */
int ensure_media_subtree(const char *artifact_dir, const char *entity_type, const char *entity_slug);
 
/**
 * @brief Ensures the managed business media subtree exists under an app artifact.
 *
 * Creates the directory structure for a business's media by delegating to
 * @c ensure_media_subtree() with the @c "business" entity type, reading
 * the directory layout from the media policy fixture.
 *
 * @param artifact_dir  App artifact root directory.
 * @param business_slug  Business slug identifying the subtree.
 * @return 0 on success, or a non-zero status code on failure.
 */
int ensure_business_media_tree(const char *artifact_dir, const char *business_slug);
 
/**
 * @brief Removes a managed business media file from an app artifact when it exists.
 *
 * Only removes files whose URL begins with @c /media/businesses/.
 * Silently succeeds when the file does not exist or the URL is not
 * a recognised business media path.
 *
 * @param artifact_dir  App artifact root directory.
 * @param media_url  Media URL of the file to remove.
 * @return 0 on success or when nothing to remove, non-zero on failure.
 */
int remove_media_url_file(const char *artifact_dir, const char *media_url);
 
/**
 * @brief Extracts a multipart upload into the app artifact media tree and returns the resulting media URL.
 *
 * Reads the request body from @p body_path, locates the multipart part
 * for @p field_name, sanitises the filename, writes the file to
 * @p target_url_dir inside @p artifact_dir, and returns the public media URL.
 *
 * @param artifact_dir  App artifact root directory.
 * @param content_type  Full Content-Type header of the request.
 * @param body_path  Path to the request body file on disk.
 * @param field_name  Form field name of the file input.
 * @param target_url_dir  Target URL directory under @c /media/ (e.g. @c /media/businesses/lotus-studio).
 * @param fallback_filename  Fallback filename when the upload provides none.
 * @return Newly allocated media URL string, or NULL on failure.  Caller must free.
 */
char *store_uploaded_media(
  const char *artifact_dir,
  const char *content_type,
  const char *body_path,
  const char *field_name,
  const char *target_url_dir,
  const char *fallback_filename
);
 
/** @} */
 
#endif