native_dynamic_relational.h File Reference

Declares Pharos-owned native relational runtime helpers for dynamic apps. More...

#include "native_runtime_types.h"

Go to the source code of this file.

Data Structures
struct	NativeDynamicRelationalRequestSync
	Carries request-local relational bridge state for one native request. More...

Functions
void	native_dynamic_relational_request_sync_free (NativeDynamicRelationalRequestSync *sync)
	Clears heap-owned fields in a request-local relational sync record.
char *	native_dynamic_relational_backend_dup (const char *app_root, const char *runtime_conf_path)
	Returns the configured relational backend when it is recognized.
char *	native_dynamic_relational_sqlite_path_dup (const char *app_root, const char *runtime_conf_path, const char *app_id)
	Returns the effective sqlite database path for a dynamic app.
int	native_dynamic_relational_sqlite_runtime_ready (const char *app_root, const char *runtime_conf_path, const char *app_id)
	Returns whether sqlite runtime prerequisites are satisfied.
int	native_dynamic_relational_postgresql_runtime_ready (const char *app_root, const char *runtime_conf_path)
	Returns whether PostgreSQL runtime prerequisites are satisfied.
int	native_dynamic_relational_sqlite_runtime_prepare (const char *app_root, const char *runtime_conf_path, const char *app_id)
	Prepares the sqlite schema, seed data, and migration ledger for one dynamic app.
int	native_dynamic_relational_postgresql_runtime_prepare (const char *app_root, const char *runtime_conf_path)
	Prepares the PostgreSQL schema, seed data, and migration ledger for one dynamic app.
char *	native_dynamic_relational_runtime_export_json_dup (const char *app_root, const char *runtime_conf_path, const char *app_id)
	Exports canonical runtime state JSON from the configured relational backend.
char *	native_dynamic_relational_runtime_audit_count_dup (const char *app_root, const char *runtime_conf_path, const char *app_id)
	Returns the current audit-event count from the configured relational backend.
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)
	Imports canonical runtime state JSON into the configured relational backend.
char *	native_dynamic_relational_file_signature_dup (const char *path)
	Computes a stable signature for one file path.
int	native_dynamic_relational_prepare_request_state (const AppRuntime *app, NativeDynamicRelationalRequestSync *sync)
	Exports relational state into the app state file before request handling when enabled.
int	native_dynamic_relational_sync_back_if_changed (const AppRuntime *app, const NativeDynamicRelationalRequestSync *sync)
	Imports the app state file back into the relational backend when it changed.

Detailed Description

Declares Pharos-owned native relational runtime helpers for dynamic apps.

Definition in file native_dynamic_relational.h.

Function Documentation

native_dynamic_relational_backend_dup()

char * native_dynamic_relational_backend_dup	(	const char *	app_root,
		const char *	runtime_conf_path )

Returns the configured relational backend when it is recognized.

Parameters

app_root	App root directory.
runtime_conf_path	Runtime config path.

Returns

Newly allocated backend string, or NULL when no supported backend is configured.

Definition at line 679 of file native_dynamic_relational.c.

References native_dynamic_config_merged_value_dup(), and streq().

Referenced by handle_dynamic_relational_backend_command(), native_dynamic_relational_postgresql_runtime_prepare(), native_dynamic_relational_postgresql_runtime_ready(), native_dynamic_relational_prepare_request_state(), native_dynamic_relational_runtime_audit_count_dup(), native_dynamic_relational_runtime_export_json_dup(), native_dynamic_relational_runtime_import_state(), native_dynamic_relational_sqlite_runtime_prepare(), native_dynamic_relational_sqlite_runtime_ready(), and persist_app_state_text_runtime_local().

native_dynamic_relational_file_signature_dup()

char * native_dynamic_relational_file_signature_dup

(

const char *

path

)

Computes a stable signature for one file path.

Parameters

path	File path to hash.

Returns

Newly allocated signature text, or NULL on failure.

Definition at line 1220 of file native_dynamic_relational.c.

References path_exists(), and read_file_bytes_dup_runtime().

Referenced by native_dynamic_relational_prepare_request_state(), and native_dynamic_relational_sync_back_if_changed().

native_dynamic_relational_postgresql_runtime_prepare()

int native_dynamic_relational_postgresql_runtime_prepare	(	const char *	app_root,
		const char *	runtime_conf_path )

Prepares the PostgreSQL schema, seed data, and migration ledger for one dynamic app.

Parameters

app_root	App root directory.
runtime_conf_path	Runtime config path.

Returns

0 on success, otherwise a non-zero native status code.

Definition at line 752 of file native_dynamic_relational.c.

References free_postgresql_runtime_config_runtime_local(), load_postgresql_runtime_config_runtime_local(), migration_backend_record_runtime_local(), migration_expected_checksum_dup_runtime_local(), migration_fixture_path_dup_runtime_local(), native_dynamic_relational_backend_dup(), native_json_doc_free(), native_json_doc_load_file(), native_json_obj_get(), native_json_obj_get_array(), native_json_obj_get_long_default(), native_json_obj_get_string_dup(), postgresql_apply_file_list_runtime_local(), run_postgresql_sql_capture_runtime_local(), sql_literal_escape_dup_runtime_local(), streq(), yyjson_arr_iter_init(), yyjson_arr_iter_next(), yyjson_arr_size(), and yyjson_doc_get_root().

Referenced by handle_dynamic_postgresql_runtime_prepare_command(), and native_dynamic_relational_prepare_request_state().

native_dynamic_relational_postgresql_runtime_ready()

int native_dynamic_relational_postgresql_runtime_ready	(	const char *	app_root,
		const char *	runtime_conf_path )

Returns whether PostgreSQL runtime prerequisites are satisfied.

Parameters

app_root	App root directory.
runtime_conf_path	Runtime config path.

Returns

Non-zero when PostgreSQL runtime work can proceed, otherwise 0.

Definition at line 733 of file native_dynamic_relational.c.

References free_native_libpq_api_runtime_local(), free_postgresql_runtime_config_runtime_local(), load_native_libpq_api_runtime_local(), load_postgresql_runtime_config_runtime_local(), native_dynamic_relational_backend_dup(), and streq().

Referenced by handle_dynamic_postgresql_runtime_ready_command(), and native_dynamic_relational_prepare_request_state().

native_dynamic_relational_prepare_request_state()

int native_dynamic_relational_prepare_request_state	(	const AppRuntime *	app,
		NativeDynamicRelationalRequestSync *	sync )

Exports relational state into the app state file before request handling when enabled.

Parameters

app	App runtime being served.
sync	Output sync record to populate.

Returns

0 on success, otherwise a non-zero native status code.

Definition at line 1248 of file native_dynamic_relational.c.

References AppRuntime::app_id, AppRuntime::app_root, NativeDynamicRelationalRequestSync::before_signature, NativeDynamicRelationalRequestSync::enabled, ensure_directory(), native_dynamic_relational_backend_dup(), native_dynamic_relational_file_signature_dup(), native_dynamic_relational_postgresql_runtime_prepare(), native_dynamic_relational_postgresql_runtime_ready(), native_dynamic_relational_request_sync_free(), native_dynamic_relational_runtime_export_json_dup(), native_dynamic_relational_sqlite_runtime_prepare(), native_dynamic_relational_sqlite_runtime_ready(), path_dirname(), AppRuntime::runtime_conf_path, AppRuntime::state_path, streq(), and write_text_file().

Referenced by native_dynamic_runtime_handle_request().

native_dynamic_relational_request_sync_free()

void native_dynamic_relational_request_sync_free

(

NativeDynamicRelationalRequestSync *

sync

)

Clears heap-owned fields in a request-local relational sync record.

Parameters

sync	Sync record to clear.

Definition at line 670 of file native_dynamic_relational.c.

References NativeDynamicRelationalRequestSync::before_signature, and NativeDynamicRelationalRequestSync::enabled.

Referenced by native_dynamic_relational_prepare_request_state(), and native_dynamic_runtime_handle_request().

native_dynamic_relational_runtime_audit_count_dup()

char * native_dynamic_relational_runtime_audit_count_dup	(	const char *	app_root,
		const char *	runtime_conf_path,
		const char *	app_id )

Returns the current audit-event count from the configured relational backend.

Parameters

app_root	App root directory.
runtime_conf_path	Runtime config path.
app_id	App identifier used for sqlite path resolution.

Returns

Newly allocated count text, or NULL on failure.

Definition at line 1107 of file native_dynamic_relational.c.

References free_postgresql_runtime_config_runtime_local(), load_postgresql_runtime_config_runtime_local(), native_dynamic_relational_backend_dup(), native_dynamic_relational_sqlite_path_dup(), run_postgresql_sql_capture_runtime_local(), sqlite_exec_first_value_dup_runtime_local(), and streq().

Referenced by handle_dynamic_relational_runtime_audit_count_command(), and native_dynamic_relational_runtime_import_state().

native_dynamic_relational_runtime_export_json_dup()

char * native_dynamic_relational_runtime_export_json_dup	(	const char *	app_root,
		const char *	runtime_conf_path,
		const char *	app_id )

Exports canonical runtime state JSON from the configured relational backend.

Parameters

app_root	App root directory.
runtime_conf_path	Runtime config path.
app_id	App identifier used for sqlite path resolution.

Returns

Newly allocated compact JSON string, or NULL on failure.

Definition at line 1065 of file native_dynamic_relational.c.

References free_postgresql_runtime_config_runtime_local(), load_postgresql_runtime_config_runtime_local(), native_dynamic_relational_backend_dup(), native_dynamic_relational_sqlite_path_dup(), read_file_text(), run_postgresql_sql_capture_runtime_local(), runtime_state_export_postgresql_path_dup_runtime_local(), runtime_state_export_sqlite_path_dup_runtime_local(), sqlite_exec_first_value_dup_runtime_local(), and streq().

Referenced by handle_dynamic_relational_runtime_export_json_command(), native_dynamic_relational_prepare_request_state(), and persist_app_state_text_runtime_local().

native_dynamic_relational_runtime_import_state()

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 )

Imports canonical runtime state JSON into the configured relational backend.

Parameters

app_root	App root directory.
runtime_conf_path	Runtime config path.
app_id	App identifier used for sqlite path resolution.
state_path	Canonical state JSON path.
expected_audit_count	Optional optimistic concurrency guard.

Returns

0 on success, otherwise a non-zero native status code.

Definition at line 1153 of file native_dynamic_relational.c.

References free_postgresql_runtime_config_runtime_local(), load_postgresql_runtime_config_runtime_local(), native_dynamic_relational_backend_dup(), native_dynamic_relational_runtime_audit_count_dup(), native_dynamic_relational_sqlite_path_dup(), read_file_text(), run_postgresql_sql_capture_runtime_local(), runtime_state_import_postgresql_path_dup_runtime_local(), runtime_state_import_sqlite_path_dup_runtime_local(), runtime_state_placeholder_sql_dup_runtime_local(), sql_literal_escape_dup_runtime_local(), sqlite_exec_runtime_local(), and streq().

Referenced by handle_dynamic_relational_runtime_import_state_command(), native_dynamic_relational_sync_back_if_changed(), and persist_app_state_text_runtime_local().

native_dynamic_relational_sqlite_path_dup()

char * native_dynamic_relational_sqlite_path_dup	(	const char *	app_root,
		const char *	runtime_conf_path,
		const char *	app_id )

Returns the effective sqlite database path for a dynamic app.

Parameters

app_root	App root directory.
runtime_conf_path	Runtime config path.
app_id	App identifier used for the default sqlite path.

Returns

Newly allocated sqlite path, or NULL on failure.

Definition at line 688 of file native_dynamic_relational.c.

References native_dynamic_config_merged_value_dup().

Referenced by handle_dynamic_relational_sqlite_path_command(), native_dynamic_relational_runtime_audit_count_dup(), native_dynamic_relational_runtime_export_json_dup(), native_dynamic_relational_runtime_import_state(), native_dynamic_relational_sqlite_runtime_prepare(), and native_dynamic_relational_sqlite_runtime_ready().

native_dynamic_relational_sqlite_runtime_prepare()

int native_dynamic_relational_sqlite_runtime_prepare	(	const char *	app_root,
		const char *	runtime_conf_path,
		const char *	app_id )

Prepares the sqlite schema, seed data, and migration ledger for one dynamic app.

Parameters

app_root	App root directory.
runtime_conf_path	Runtime config path.
app_id	App identifier used for the default sqlite path.

Returns

0 on success, otherwise a non-zero native status code.

Definition at line 914 of file native_dynamic_relational.c.

References ensure_directory(), migration_backend_record_runtime_local(), migration_expected_checksum_dup_runtime_local(), migration_fixture_path_dup_runtime_local(), native_dynamic_relational_backend_dup(), native_dynamic_relational_sqlite_path_dup(), native_json_doc_free(), native_json_doc_load_file(), native_json_obj_get(), native_json_obj_get_array(), native_json_obj_get_long_default(), native_json_obj_get_string_dup(), path_dirname(), sql_literal_escape_dup_runtime_local(), sqlite_apply_file_list_runtime_local(), sqlite_exec_first_value_dup_runtime_local(), sqlite_exec_runtime_local(), streq(), yyjson_arr_iter_init(), yyjson_arr_iter_next(), yyjson_arr_size(), and yyjson_doc_get_root().

Referenced by handle_dynamic_sqlite_runtime_prepare_command(), and native_dynamic_relational_prepare_request_state().

native_dynamic_relational_sqlite_runtime_ready()

int native_dynamic_relational_sqlite_runtime_ready	(	const char *	app_root,
		const char *	runtime_conf_path,
		const char *	app_id )

Returns whether sqlite runtime prerequisites are satisfied.

Parameters

app_root	App root directory.
runtime_conf_path	Runtime config path.
app_id	App identifier used for the default sqlite path.

Returns

Non-zero when sqlite runtime work can proceed, otherwise 0.

Definition at line 709 of file native_dynamic_relational.c.

References ensure_directory(), native_dynamic_relational_backend_dup(), native_dynamic_relational_sqlite_path_dup(), path_dirname(), path_exists(), and streq().

Referenced by handle_dynamic_sqlite_runtime_ready_command(), and native_dynamic_relational_prepare_request_state().

native_dynamic_relational_sync_back_if_changed()

int native_dynamic_relational_sync_back_if_changed	(	const AppRuntime *	app,
		const NativeDynamicRelationalRequestSync *	sync )

Imports the app state file back into the relational backend when it changed.

Parameters

app	App runtime being served.
sync	Request sync record populated by prepare_request_state.

Returns

0 on success, otherwise a non-zero native status code.

Definition at line 1316 of file native_dynamic_relational.c.

References AppRuntime::app_id, AppRuntime::app_root, NativeDynamicRelationalRequestSync::before_signature, NativeDynamicRelationalRequestSync::enabled, native_dynamic_relational_file_signature_dup(), native_dynamic_relational_runtime_import_state(), AppRuntime::runtime_conf_path, AppRuntime::state_path, and streq().

Referenced by native_dynamic_runtime_handle_request().