native_dynamic_dispatch.h

Go to the documentation of this file.

/**
 * @file
 * @brief Route dispatch for in-process dynamic-app request handling.
 *
 * This module reads the app's route fixture JSON and matches an incoming
 * request path against the declared routes.  It supports both exact
 * segment matches and parameterised segment patterns (e.g.
 * @c /businesses/:business_slug/).
 *
 * The dispatch layer also resolves the response artifact file for
 * API-style routes that have pre-built static responses in the
 * dispatch table.
 *
 * @see native_dynamic_runtime.h for the higher-level entry point.
 */
 
#ifndef PHAROS_NATIVE_DYNAMIC_DISPATCH_H
#define PHAROS_NATIVE_DYNAMIC_DISPATCH_H
 
#include "native_runtime_types.h"
#include "native_http_request.h"
#include "native_connection.h"
 
/**
 * @brief Describes one matched route from the route fixture.
 */
typedef struct {
  char *route_id;     /**< Unique route identifier from the fixture. */
  char *path;         /**< Route path pattern (may contain parameter segments). */
  char *kind;         /**< Route kind: @c "page" or @c "action". */
  char *page_id;      /**< Page identifier (for page routes), or NULL. */
  char *action_id;    /**< Action identifier (for action routes), or NULL. */
  char *layout_id;    /**< Layout identifier, or NULL. */
  char *auth_gate;    /**< Auth gate constraint, or NULL. */
  char *policy_gate;  /**< Policy gate constraint, or NULL. */
} NativeDynamicRouteMatch;
 
/** @name Dispatch helpers
 * @{
 */
 
/**
 * @brief Matches a request path against the route fixture for an app.
 *
 * Reads @p route_fixture_path and walks the route list looking for a
 * match.  Parameterised segments (prefixed with @c : ) match any
 * non-empty segment in the corresponding position.
 *
 * @param route_fixture_path  File-system path to the route fixture JSON.
 * @param method  HTTP method (GET, POST, etc.).
 * @param path    Normalised request path (query string already stripped).
 * @param match_out  Destination for the allocated match record.  Caller
 *                   must free with @c native_dynamic_dispatch_free_match().
 * @return 0 when a match is found, 1 when no route matches, or a
 *         negative value on I/O or parse failure.
 */
int native_dynamic_dispatch_match(
  const char *route_fixture_path,
  const char *method,
  const char *path,
  NativeDynamicRouteMatch **match_out
);
 
/**
 * @brief Frees a route match returned by @c native_dynamic_dispatch_match().
 * @param match  Match record to free, or NULL.
 */
void native_dynamic_dispatch_free_match(NativeDynamicRouteMatch *match);
 
/**
 * @brief Resolves the response artifact file for a matched page route.
 *
 * Looks up the dispatch table in @p artifact_dir and returns the
 * pre-built response file for routes whose paths are served as
 * static responses.  Returns NULL when no static response file
 * exists for the route.
 *
 * @param artifact_dir  App artifact directory.
 * @param method  HTTP method.
 * @param path    Normalised request path.
 * @return Newly allocated file path, or NULL.  Caller must free.
 */
char *native_dynamic_dispatch_response_file(
  const char *artifact_dir,
  const char *method,
  const char *path
);
 
/**
 * @brief Resolves the route fixture path from the artifact directory.
 *
 * Reads the manifest from @p artifact_dir and returns the file-system
 * path to the route fixture JSON.
 *
 * @param artifact_dir  App artifact directory.
 * @return Newly allocated route fixture path, or NULL.  Caller must free.
 */
char *native_dynamic_dispatch_resolve_route_fixture(
  const char *artifact_dir,
  const char *app_id
);
 
/**
 * @brief Returns the URL path parameter value extracted from a matched route.
 *
 * Given a route pattern like @c /businesses/:business_slug/ and a
 * concrete path @c /businesses/foo-bar/, this returns @c "foo-bar".
 *
 * @param pattern  Route pattern from the fixture.
 * @param path     Concrete request path.
 * @param param_name  Name of the parameter segment (without the colon).
 * @return Newly allocated parameter value, or NULL if not found.
 *         Caller must free.
 */
char *native_dynamic_dispatch_extract_param(
  const char *pattern,
  const char *path,
  const char *param_name
);
 
/** @} */
 
#endif