native_dynamic_dispatch.c

Go to the documentation of this file.

/**
 * @file
 * @brief Route dispatch for in-process dynamic-app request handling.
 *
 * Reads the app's route fixture JSON, matches an incoming request path
 * against declared routes, and extracts parameterised segments.
 */
 
#include "native_dynamic_dispatch.h"
 
#include "native_dispatch_table.h"
#include "native_yyjson_helpers.h"
#include "native_support.h"
 
#include <stdlib.h>
#include <string.h>
 
/* ------------------------------------------------------------------ */
/* Route fixture path resolution                                       */
/* ------------------------------------------------------------------ */
 
/**
 * @brief Attempts to locate the route fixture path from the artifact directory.
 *
 * Reads the finalized artifact-local app manifest from @p artifact_dir and
 * extracts the route_fixture path.  Falls back to the app-root fixture
 * path when the manifest stores a relative value.
 *
 * @param artifact_dir  App artifact directory containing the manifest.
 * @return Newly allocated route fixture path, or NULL.  Caller must free.
 */
/**
 * @brief Builds the conventional packaged-app route fixture path.
 *
 * Packaged app artifacts place the checked route fixture at
 * @c fixtures/route-fixture.json under the artifact root.
 *
 * @param artifact_dir  App artifact directory.
 * @return Newly allocated path, or NULL on allocation failure.
 */
static char *construct_packaged_route_fixture_path(const char *artifact_dir) {
  char *fixtures_dir;
  char *result;
 
  if (artifact_dir == NULL || artifact_dir[0] == '\0') {
    return NULL;
  }
 
  fixtures_dir = path_join(artifact_dir, "fixtures");
  if (fixtures_dir == NULL) {
    return NULL;
  }
  result = path_join(fixtures_dir, "route-fixture.json");
  free(fixtures_dir);
  return result;
}
 
/**
 * @brief Builds the framework-data route fixture fallback path.
 *
 * Dynamic-app artifact layouts may also publish route fixtures under
 * @c data/framework/framework-<app_id>-route-fixture-v1.json.
 *
 * @param artifact_dir  App artifact directory.
 * @param app_id        App identifier used in the framework fixture name.
 * @return Newly allocated path, or NULL on allocation failure.
 */
static char *construct_direct_route_fixture_path(const char *artifact_dir, const char *app_id) {
  char *dir = NULL;
  char *filename = NULL;
  char *result = NULL;
  size_t filename_len;
 
  if (artifact_dir == NULL || app_id == NULL || app_id[0] == '\0') {
    return NULL;
  }
 
  dir = path_join(artifact_dir, "data/framework");
  if (dir == NULL) {
    return NULL;
  }
 
  /* Build filename: framework-<app_id>-route-fixture-v1.json */
  filename_len = strlen("framework-") + strlen(app_id) + strlen("-route-fixture-v1.json") + 1;
  filename = (char *)malloc(filename_len);
  if (filename == NULL) {
    free(dir);
    return NULL;
  }
  snprintf(filename, filename_len, "framework-%s-route-fixture-v1.json", app_id);
 
  result = path_join(dir, filename);
  free(dir);
  free(filename);
  return result;
}
 
static char *resolve_route_fixture_path(const char *artifact_dir, const char *app_id) {
  char *manifest_path = NULL;
  char *manifest_text = NULL;
  char *route_fixture = NULL;
  char *app_root = NULL;
 
  if (artifact_dir == NULL) {
    return NULL;
  }
 
  /* Read the finalized artifact-local app manifest. */
  manifest_path = path_join(artifact_dir, "pharos.app.json");
  if (manifest_path == NULL || !path_exists(manifest_path)) {
    free(manifest_path);
  } else {
    manifest_text = read_file_text(manifest_path);
    free(manifest_path);
  }
 
  /* Extract route_fixture from the app manifest JSON */
  if (manifest_text != NULL) {
    yyjson_doc *doc = native_json_doc_load_text(manifest_text);
    yyjson_val *root;
    yyjson_val *fixtures;
    free(manifest_text);
    if (doc != NULL) {
      root = yyjson_doc_get_root(doc);
      fixtures = native_json_obj_get(root, "fixtures");
      if (fixtures != NULL) {
        route_fixture = native_json_obj_get_string_dup(fixtures, "route_fixture");
      }
      if (route_fixture == NULL) {
        route_fixture = native_json_obj_get_string_dup(root, "route_fixture");
      }
      app_root = native_json_obj_get_string_dup(root, "app_root");
      native_json_doc_free(doc);
    }
  }
 
  if (route_fixture != NULL) {
    char *resolved;
    /* Resolve relative route fixture path against the artifact directory. */
    if (route_fixture[0] != '/') {
      resolved = path_join(artifact_dir, route_fixture);
    } else {
      resolved = route_fixture;
      route_fixture = NULL;
    }
    free(route_fixture);
    free(app_root);
    if (resolved != NULL && path_exists(resolved)) {
      return resolved;
    }
    /* Manifest resolved path does not exist on disk; fall through to
     * direct construction below. */
    free(resolved);
  } else {
    free(app_root);
  }
 
  {
    char *packaged_route_fixture = construct_packaged_route_fixture_path(artifact_dir);
    if (packaged_route_fixture != NULL && path_exists(packaged_route_fixture)) {
      return packaged_route_fixture;
    }
    free(packaged_route_fixture);
  }
 
  /* Fallback: construct the framework-data route fixture path directly from
   * the app_id without relying on the manifest.  This handles cases where
   * the manifest is present but the route_fixture value resolves to a
   * non-existent path or where the artifact uses the framework-data layout. */
  {
    char *framework_route_fixture = construct_direct_route_fixture_path(artifact_dir, app_id);
    if (framework_route_fixture != NULL && path_exists(framework_route_fixture)) {
      return framework_route_fixture;
    }
    free(framework_route_fixture);
  }
 
  return NULL;
}
 
/* ------------------------------------------------------------------ */
/* Pattern matching                                                    */
/* ------------------------------------------------------------------ */
 
/**
 * @brief Counts the number of path segments in a pattern or path.
 */
static int count_segments(const char *path) {
  int count = 0;
  const char *cursor;
 
  if (path == NULL || path[0] == '\0') {
    return 0;
  }
 
  cursor = path;
  if (*cursor == '/') {
    cursor++;
  }
  while (*cursor != '\0') {
    count++;
    while (*cursor != '\0' && *cursor != '/') {
      cursor++;
    }
    if (*cursor == '/') {
      cursor++;
    }
  }
  return count;
}
 
/**
 * @brief Extracts the N-th segment (0-indexed) from a path.
 *
 * @return Pointer into the original string (not allocated), or NULL.
 */
static const char *get_segment(const char *path, int index) {
  const char *cursor;
  int current = 0;
 
  if (path == NULL || path[0] == '\0') {
    return NULL;
  }
 
  cursor = path;
  if (*cursor == '/') {
    cursor++;
  }
 
  while (*cursor != '\0' && current < index) {
    while (*cursor != '\0' && *cursor != '/') {
      cursor++;
    }
    if (*cursor == '/') {
      cursor++;
    }
    current++;
  }
 
  if (current != index || *cursor == '\0') {
    return NULL;
  }
  return cursor;
}
 
/**
 * @brief Returns the length of a segment starting at @p start.
 */
static size_t segment_length(const char *start) {
  const char *end = start;
  while (*end != '\0' && *end != '/') {
    end++;
  }
  return (size_t)(end - start);
}
 
/**
 * @brief Scores a route pattern by match specificity.
 *
 * Higher scores mean a more specific route. Exact literal segments outrank
 * parameter segments, and parameter segments outrank wildcards. This lets the
 * dispatcher prefer a static route like @c /appointments/diagnose/ over a
 * broader parameterized route like @c /appointments/:appointment_id/ when both
 * patterns match the same request path.
 *
 * @param pattern Route pattern from the fixture.
 * @return Specificity score, or @c -1 when the pattern is missing.
 */
static int route_pattern_specificity_score(const char *pattern) {
  int segment_count = 0;
  int score = 0;
  int index = 0;
 
  if (pattern == NULL) {
    return -1;
  }
 
  segment_count = count_segments(pattern);
  for (index = 0; index < segment_count; index++) {
    const char *segment = get_segment(pattern, index);
    size_t segment_len = 0;
    if (segment == NULL) {
      continue;
    }
    segment_len = segment_length(segment);
    score += 1;
    if (segment_len == 1 && segment[0] == '*') {
      continue;
    }
    if (segment_len > 0 && segment[0] == ':') {
      score += 10;
      continue;
    }
    score += 100;
  }
  return score;
}
 
/**
 * @brief Tests whether a pattern matches a concrete path.
 *
 * Supports:
 *  - Exact segment matches (e.g. @c /accounts/login/ )
 *  - Parameterised segments prefixed with @c : (e.g. @c /businesses/:slug/ )
 *  - Wildcard segment @c * (matches any single segment)
 */
static int pattern_matches(const char *pattern, const char *path) {
  int pat_segs;
  int path_segs;
  int i;
 
  if (pattern == NULL || path == NULL) {
    return 0;
  }
 
  pat_segs = count_segments(pattern);
  path_segs = count_segments(path);
 
  if (pat_segs != path_segs) {
    return 0;
  }
 
  for (i = 0; i < pat_segs; i++) {
    const char *pat_seg = get_segment(pattern, i);
    const char *path_seg = get_segment(path, i);
    size_t pat_len;
    size_t path_len;
 
    if (pat_seg == NULL || path_seg == NULL) {
      return 0;
    }
 
    pat_len = segment_length(pat_seg);
    path_len = segment_length(path_seg);
 
    /* Parameterised segment: matches any non-empty segment */
    if (pat_len > 0 && pat_seg[0] == ':') {
      if (path_len == 0) {
        return 0;
      }
      continue;
    }
 
    /* Wildcard segment: matches any single segment */
    if (pat_len == 1 && pat_seg[0] == '*') {
      continue;
    }
 
    /* Exact match */
    if (pat_len != path_len) {
      return 0;
    }
    if (strncmp(pat_seg, path_seg, pat_len) != 0) {
      return 0;
    }
  }
 
  return 1;
}
 
/* ------------------------------------------------------------------ */
/* Public API                                                          */
/* ------------------------------------------------------------------ */
 
int native_dynamic_dispatch_match(
  const char *route_fixture_path,
  const char *method,
  const char *path,
  NativeDynamicRouteMatch **match_out
) {
  yyjson_doc *doc = NULL;
  yyjson_val *root = NULL;
  yyjson_val *routes = NULL;
  NativeDynamicRouteMatch *best_match = NULL;
  NativeDynamicRouteMatch *fallback_match = NULL;
  const char *preferred_kind = NULL;
  int best_score = -1;
  int fallback_score = -1;
  size_t route_count;
  size_t i;
 
  if (match_out != NULL) {
    *match_out = NULL;
  }
 
  if (route_fixture_path == NULL || path == NULL || match_out == NULL) {
    return -1;
  }
 
  if (method != NULL) {
    if (strcmp(method, "GET") == 0 || strcmp(method, "HEAD") == 0 || strcmp(method, "OPTIONS") == 0) {
      preferred_kind = "page";
    } else if (strcmp(method, "POST") == 0 || strcmp(method, "PUT") == 0 || strcmp(method, "PATCH") == 0 || strcmp(method, "DELETE") == 0) {
      preferred_kind = "action";
    }
  }
 
  doc = native_json_doc_load_file(route_fixture_path);
  if (doc == NULL) {
    return -1;
  }
 
  root = yyjson_doc_get_root(doc);
  routes = native_json_obj_get_array(root, "routes");
  if (routes == NULL) {
    native_json_doc_free(doc);
    return 1; /* no routes found */
  }
 
  route_count = yyjson_arr_size(routes);
  for (i = 0; i < route_count; i++) {
    yyjson_val *route = yyjson_arr_get(routes, i);
    char *route_path = NULL;
    const char *route_id = NULL;
    const char *kind = NULL;
    NativeDynamicRouteMatch *match = NULL;
    int score = -1;
 
    if (route == NULL) {
      continue;
    }
 
    route_path = native_json_obj_get_string_dup(route, "path");
    if (route_path == NULL) {
      continue;
    }
 
    if (!pattern_matches(route_path, path)) {
      free(route_path);
      continue;
    }
 
    match = (NativeDynamicRouteMatch *)calloc(1, sizeof(NativeDynamicRouteMatch));
    if (match == NULL) {
      free(route_path);
      native_dynamic_dispatch_free_match(fallback_match);
      native_json_doc_free(doc);
      return -1;
    }
 
    route_id = yyjson_get_str(native_json_obj_get(route, "route_id"));
    kind = yyjson_get_str(native_json_obj_get(route, "kind"));
 
    match->route_id = strdup(route_id != NULL ? route_id : "");
    match->path = route_path; /* transferred ownership */
    match->kind = strdup(kind != NULL ? kind : "page");
    match->page_id = native_json_obj_get_string_dup(route, "page_id");
    match->action_id = native_json_obj_get_string_dup(route, "action_id");
    match->layout_id = native_json_obj_get_string_dup(route, "layout_id");
    match->auth_gate = native_json_obj_get_string_dup(route, "auth_gate");
    match->policy_gate = native_json_obj_get_string_dup(route, "policy_gate");
 
    score = route_pattern_specificity_score(route_path);
 
    if (preferred_kind == NULL || (kind != NULL && strcmp(kind, preferred_kind) == 0)) {
      if (best_match == NULL || score > best_score) {
        native_dynamic_dispatch_free_match(best_match);
        best_match = match;
        best_score = score;
      } else {
        native_dynamic_dispatch_free_match(match);
      }
      continue;
    }
 
    if (fallback_match == NULL || score > fallback_score) {
      native_dynamic_dispatch_free_match(fallback_match);
      fallback_match = match;
      fallback_score = score;
    } else {
      native_dynamic_dispatch_free_match(match);
    }
  }
 
  native_json_doc_free(doc);
  if (best_match != NULL) {
    native_dynamic_dispatch_free_match(fallback_match);
    *match_out = best_match;
    return 0;
  }
  if (fallback_match != NULL) {
    *match_out = fallback_match;
    return 0;
  }
  return 1; /* no match */
}
 
void native_dynamic_dispatch_free_match(NativeDynamicRouteMatch *match) {
  if (match == NULL) {
    return;
  }
  free(match->route_id);
  free(match->path);
  free(match->kind);
  free(match->page_id);
  free(match->action_id);
  free(match->layout_id);
  free(match->auth_gate);
  free(match->policy_gate);
  free(match);
}
 
char *native_dynamic_dispatch_response_file(
  const char *artifact_dir,
  const char *method,
  const char *path
) {
  (void)method;
  /* Delegate to the existing dispatch table helper which already knows
   * how to resolve API routes against the dispatch-table.json. */
  /* Note: native_dispatch_response_file_for_request is declared in
   * native_dispatch_table.h but the current implementation only matches
   * paths starting with "/api/".  For the dynamic runtime we expand this
   * to also check the full dispatch table for non-API paths. */
  return native_dispatch_response_file_for_request(artifact_dir, method, path);
}
 
char *native_dynamic_dispatch_extract_param(
  const char *pattern,
  const char *path,
  const char *param_name
) {
  int pat_segs;
  int path_segs;
  int i;
  char param_marker[256];
 
  if (pattern == NULL || path == NULL || param_name == NULL) {
    return NULL;
  }
 
  /* Build the expected parameter token, e.g. ":business_slug" */
  if (snprintf(param_marker, sizeof(param_marker), ":%s", param_name) >= (int)sizeof(param_marker)) {
    return NULL;
  }
 
  pat_segs = count_segments(pattern);
  path_segs = count_segments(path);
 
  if (pat_segs != path_segs) {
    return NULL;
  }
 
  for (i = 0; i < pat_segs; i++) {
    const char *pat_seg = get_segment(pattern, i);
    const char *path_seg = get_segment(path, i);
    size_t pat_len;
    size_t seg_len;
 
    if (pat_seg == NULL || path_seg == NULL) {
      return NULL;
    }
 
    pat_len = segment_length(pat_seg);
    seg_len = segment_length(path_seg);
 
    if (pat_len > 0 && strncmp(pat_seg, param_marker, pat_len) == 0 && pat_len == strlen(param_marker)) {
      return dup_range(path_seg, seg_len);
    }
  }
 
  return NULL;
}
 
char *native_dynamic_dispatch_resolve_route_fixture(const char *artifact_dir, const char *app_id) {
  return resolve_route_fixture_path(artifact_dir, app_id);
}