native_dynamic_runtime.h

Go to the documentation of this file.

/**
 * @file
 * @brief In-process dynamic-app request handler for the Pharos native runtime.
 *
 * This module owns the primary entry point for serving dynamic-app requests
 * directly inside the Pharos binary process.  It replaces the earlier
 * architecture where every dynamic-app request spawned a child process via
 * @c spawn_app_request().
 *
 * The handler is responsible for:
 *  - loading the route fixture for the target app,
 *  - matching the incoming request path against declared routes,
 *  - serving static assets from the artifact directory,
 *  - delegating page and action routes to the dispatch layer, and
 *  - writing the final HTTP response back through the connection.
 *
 * @see native_dynamic_dispatch.h for the route-matching layer.
 * @see native_dynamic_request_fields.h for request field extraction helpers.
 */
 
#ifndef PHAROS_NATIVE_DYNAMIC_RUNTIME_H
#define PHAROS_NATIVE_DYNAMIC_RUNTIME_H
 
#include "native_runtime_types.h"
#include "native_connection.h"
#include "native_http_request.h"
 
/** @name Dynamic runtime entry points
 * @{
 */
 
/**
 * @brief Serves one dynamic-app request entirely in-process.
 *
 * This is the canonical entry point that replaces the former
 * @c spawn_app_request() path for apps whose @c host_profile is
 * @c "dynamic-app".  The function reads the app's route fixture,
 * resolves the appropriate handler, and writes the HTTP response
 * directly to @p connection.
 *
 * Static-only and non-dynamic host profiles continue to use their
 * existing code paths; this function is called only for dynamic-app
 * requests.
 *
 * @param app   Finalized app runtime metadata (artifact dir, state, etc.).
 * @param request  Parsed HTTP request record.
 * @param connection  Connection to write the response to.
 * @return 0 on success, or a non-zero native status code on failure.
 */
int native_dynamic_runtime_handle_request(
  const AppRuntime *app,
  const HttpRequest *request,
  NativeConnection *connection
);
 
/**
 * @brief Returns the canonical host profile string that this module handles.
 *
 * Useful for callers that need to decide which request path to use
 * without duplicating the profile name string.
 *
 * @return Pointer to a string literal; never NULL.
 */
const char *native_dynamic_runtime_host_profile(void);
 
/** @} */
 
#endif