native_dynamic_relational.h

Go to the documentation of this file.

/**
 * @file
 * @brief Declares Pharos-owned native relational runtime helpers for dynamic apps.
 */
 
#ifndef PHAROS_NATIVE_DYNAMIC_RELATIONAL_H
#define PHAROS_NATIVE_DYNAMIC_RELATIONAL_H
 
#include "native_runtime_types.h"
 
/**
 * @brief Carries request-local relational bridge state for one native request.
 */
typedef struct {
  int enabled;               /**< Non-zero when relational sync is active for the request. */
  char *before_signature;    /**< File signature captured after export and before request mutation. */
} NativeDynamicRelationalRequestSync;
 
/**
 * @brief Clears heap-owned fields in a request-local relational sync record.
 *
 * @param sync Sync record to clear.
 */
void native_dynamic_relational_request_sync_free(NativeDynamicRelationalRequestSync *sync);
 
/**
 * @brief Returns the configured relational backend when it is recognized.
 *
 * @param app_root App root directory.
 * @param runtime_conf_path Runtime config path.
 * @return Newly allocated backend string, or NULL when no supported backend is configured.
 */
char *native_dynamic_relational_backend_dup(const char *app_root, const char *runtime_conf_path);
 
/**
 * @brief Returns the effective sqlite database path for a dynamic app.
 *
 * @param app_root App root directory.
 * @param runtime_conf_path Runtime config path.
 * @param app_id App identifier used for the default sqlite path.
 * @return Newly allocated sqlite path, or NULL on failure.
 */
char *native_dynamic_relational_sqlite_path_dup(
  const char *app_root,
  const char *runtime_conf_path,
  const char *app_id
);
 
/**
 * @brief Returns whether sqlite runtime prerequisites are satisfied.
 *
 * @param app_root App root directory.
 * @param runtime_conf_path Runtime config path.
 * @param app_id App identifier used for the default sqlite path.
 * @return Non-zero when sqlite runtime work can proceed, otherwise 0.
 */
int native_dynamic_relational_sqlite_runtime_ready(
  const char *app_root,
  const char *runtime_conf_path,
  const char *app_id
);
 
/**
 * @brief Returns whether PostgreSQL runtime prerequisites are satisfied.
 *
 * @param app_root App root directory.
 * @param runtime_conf_path Runtime config path.
 * @return Non-zero when PostgreSQL runtime work can proceed, otherwise 0.
 */
int native_dynamic_relational_postgresql_runtime_ready(
  const char *app_root,
  const char *runtime_conf_path
);
 
/**
 * @brief Prepares the sqlite schema, seed data, and migration ledger for one dynamic app.
 *
 * @param app_root App root directory.
 * @param runtime_conf_path Runtime config path.
 * @param app_id App identifier used for the default sqlite path.
 * @return 0 on success, otherwise a non-zero native status code.
 */
int native_dynamic_relational_sqlite_runtime_prepare(
  const char *app_root,
  const char *runtime_conf_path,
  const char *app_id
);
 
/**
 * @brief Prepares the PostgreSQL schema, seed data, and migration ledger for one dynamic app.
 *
 * @param app_root App root directory.
 * @param runtime_conf_path Runtime config path.
 * @return 0 on success, otherwise a non-zero native status code.
 */
int native_dynamic_relational_postgresql_runtime_prepare(
  const char *app_root,
  const char *runtime_conf_path
);
 
/**
 * @brief Exports canonical runtime state JSON from the configured relational backend.
 *
 * @param app_root App root directory.
 * @param runtime_conf_path Runtime config path.
 * @param app_id App identifier used for sqlite path resolution.
 * @return Newly allocated compact JSON string, or NULL on failure.
 */
char *native_dynamic_relational_runtime_export_json_dup(
  const char *app_root,
  const char *runtime_conf_path,
  const char *app_id
);
 
/**
 * @brief Returns the current audit-event count from the configured relational backend.
 *
 * @param app_root App root directory.
 * @param runtime_conf_path Runtime config path.
 * @param app_id App identifier used for sqlite path resolution.
 * @return Newly allocated count text, or NULL on failure.
 */
char *native_dynamic_relational_runtime_audit_count_dup(
  const char *app_root,
  const char *runtime_conf_path,
  const char *app_id
);
 
/**
 * @brief Imports canonical runtime state JSON into the configured relational backend.
 *
 * @param app_root App root directory.
 * @param runtime_conf_path Runtime config path.
 * @param app_id App identifier used for sqlite path resolution.
 * @param state_path Canonical state JSON path.
 * @param expected_audit_count Optional optimistic concurrency guard.
 * @return 0 on success, otherwise a non-zero native status code.
 */
int native_dynamic_relational_runtime_import_state(
  const char *app_root,
  const char *runtime_conf_path,
  const char *app_id,
  const char *state_path,
  const char *expected_audit_count
);
 
/**
 * @brief Computes a stable signature for one file path.
 *
 * @param path File path to hash.
 * @return Newly allocated signature text, or NULL on failure.
 */
char *native_dynamic_relational_file_signature_dup(const char *path);
 
/**
 * @brief Exports relational state into the app state file before request handling when enabled.
 *
 * @param app App runtime being served.
 * @param sync Output sync record to populate.
 * @return 0 on success, otherwise a non-zero native status code.
 */
int native_dynamic_relational_prepare_request_state(
  const AppRuntime *app,
  NativeDynamicRelationalRequestSync *sync
);
 
/**
 * @brief Imports the app state file back into the relational backend when it changed.
 *
 * @param app App runtime being served.
 * @param sync Request sync record populated by prepare_request_state.
 * @return 0 on success, otherwise a non-zero native status code.
 */
int native_dynamic_relational_sync_back_if_changed(
  const AppRuntime *app,
  const NativeDynamicRelationalRequestSync *sync
);
 
#endif