database.h File Reference

Go to the source code of this file.

Data Structures
struct	database_session_stats_t
	The useful part of database session stats is in participants, host_ready, migrating: together they describe what is pending, who owns it, and how much data is valid. Keep the object with its parent operation and use the parent cleanup path. More...

Macros
#define	DISCOVERY_DATABASE_SESSION_STRING_BUFFER_SIZE   64

Typedefs
typedef sqlite3	discovery_database_t
	Discovery database handle (sqlite3 wrapper).

Functions
asciichat_error_t	database_session_transport_set (sqlite3 *db, const uint8_t session_id[16], const void *metadata, size_t length)
asciichat_error_t	database_session_transport_get (sqlite3 *db, const uint8_t session_id[16], void *metadata, size_t capacity, size_t *length)
asciichat_error_t	database_init (const char *db_path, sqlite3 **db)
	Initialize database and create schema.
void	database_close (sqlite3 *db)
	Close database.
asciichat_error_t	database_session_create (sqlite3 *db, const acip_session_create_t *req, const acds_config_t *config, acip_session_created_t *resp)
	Create new session.
asciichat_error_t	database_session_create_keys (sqlite3 *db, const acip_session_create_t *req, const uint8_t(*keys)[32], size_t count, const acds_config_t *config, acip_session_created_t *resp)
asciichat_error_t	database_session_create_keys_with_transport (sqlite3 *db, const acip_session_create_t *req, const uint8_t(*keys)[32], size_t count, const acds_config_t *config, acip_session_created_t *resp, const void *metadata, size_t metadata_length)
asciichat_error_t	database_session_lookup (sqlite3 *db, const char *session_string, const acds_config_t *config, acip_session_info_t *resp)
	Lookup session by string.
asciichat_error_t	database_session_join (sqlite3 *db, const acip_session_join_t *req, const acds_config_t *config, acip_session_joined_t *resp)
	Join existing session.
asciichat_error_t	database_session_leave (sqlite3 *db, const uint8_t session_id[16], const uint8_t participant_id[16])
	Leave session.
session_entry_t *	database_session_find_by_id (sqlite3 *db, const uint8_t session_id[16])
	Find session by session_id.
session_entry_t *	database_session_find_by_string (sqlite3 *db, const char *session_string)
	Find session by session_string.
void	database_session_cleanup_expired (sqlite3 *db)
	Clean up inactive sessions.
asciichat_error_t	database_session_update_host (sqlite3 *db, const uint8_t session_id[16], const uint8_t host_participant_id[16], const char *host_address, uint16_t host_port, uint8_t connection_type)
	Update session host (discovery mode).
asciichat_error_t	database_session_clear_host (sqlite3 *db, const uint8_t session_id[16])
	Clear session host (discovery mode - host migration).
asciichat_error_t	database_session_start_migration (sqlite3 *db, const uint8_t session_id[16])
	Start host migration (discovery mode).
bool	database_session_is_migration_ready (sqlite3 *db, const uint8_t session_id[16], uint64_t migration_window_ms)
	Check if migration window has completed.
asciichat_error_t	database_session_add_key (sqlite3 *db, const char *session_string, const uint8_t identity_pubkey[32], uint32_t key_version)
	Add a key to a session.
asciichat_error_t	database_session_revoke_key (sqlite3 *db, const char *session_string, const uint8_t identity_pubkey[32])
	Revoke a key from a session.
bool	database_session_verify_key (sqlite3 *db, const char *session_string, const uint8_t identity_pubkey[32])
	Check if a key is valid for a session (exists and not revoked).
asciichat_error_t	database_session_get_keys (sqlite3 *db, const char *session_string, uint8_t(*keys_out)[32], size_t max_keys, size_t *count_out)
	Get all active keys for a session.
asciichat_error_t	database_stats_session_count (sqlite3 *db, int64_t *count_out)
	Get total number of active sessions.
asciichat_error_t	database_stats_unique_clients (sqlite3 *db, int64_t *count_out)
	Get total number of unique clients/participants.
asciichat_error_t	database_stats_snapshot (sqlite3 *db, database_session_stats_t *rows, size_t capacity, size_t *row_count, uint64_t *sessions, uint64_t *participants)
asciichat_error_t	database_session_update_host_with_transport (sqlite3 *db, const uint8_t session[16], const uint8_t host[16], const char *address, uint16_t port, uint8_t type, const void *metadata, size_t length)

Macro Definition Documentation

DISCOVERY_DATABASE_SESSION_STRING_BUFFER_SIZE

#define DISCOVERY_DATABASE_SESSION_STRING_BUFFER_SIZE   64

Definition at line 13 of file database.h.

Typedef Documentation

discovery_database_t

typedef sqlite3 discovery_database_t

Discovery database handle (sqlite3 wrapper).

Definition at line 33 of file database.h.

Function Documentation

database_close()

void database_close

(

sqlite3 *

db

)

Close database.

Parameters

db	Database handle to close

Definition at line 305 of file discovery/database.c.

                                 {
  ASCII_OTEL_SCOPE(DATABASE_CLOSE);
  if (!db) {
    return;
  }
  sqlite3_close(db);
  log_debug("Database closed");
}

References ASCII_OTEL_SCOPE, and log_debug.

Referenced by acds_server_shutdown().

database_init()

asciichat_error_t database_init	(	const char *	db_path,
		sqlite3 **	db )

Initialize database and create schema.

Parameters

db_path	Path to SQLite database file
db	Output database handle

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 188 of file discovery/database.c.

                                                                   {
  ASCII_OTEL_SCOPE(DATABASE_INIT);
  if (!db_path || !db) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "db_path or db is NULL");
  }
 
  log_info("Opening database: %s", db_path);
 
  // Signaling workers share this connection; macOS SQLite defaults to multi-thread mode.
  int rc = sqlite3_open_v2(db_path, db, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_FULLMUTEX, NULL);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    const char *err = sqlite3_errmsg(*db);
    sqlite3_close(*db);
    *db = NULL;
    return SET_ERRNO(ERROR_CONFIG, "Failed to open database: %s", err);
  }
 
  const gotel_query_catalog_t query_catalog = {database_queries, DATABASE_QUERY_COUNT, database_query_get};
  ascii_otel_sqlite_catalog(*db, &query_catalog);
  // Enable Write-Ahead Logging for concurrent reads
  char *err_msg = NULL;
  rc = sqlite3_exec(*db, database_queries[DATABASE_QUERY_EnableWAL].sql, NULL, NULL, &err_msg);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    log_warn("Failed to enable WAL mode: %s", err_msg ? err_msg : "unknown error");
    sqlite3_free(err_msg);
  }
 
  // Enable foreign key constraints
  rc = sqlite3_exec(*db, database_queries[DATABASE_QUERY_EnableForeignKeys].sql, NULL, NULL, &err_msg);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    log_error("Failed to enable foreign keys: %s", err_msg ? err_msg : "unknown error");
    sqlite3_free(err_msg);
    sqlite3_close(*db);
    *db = NULL;
    return SET_ERRNO(ERROR_CONFIG, "Failed to enable foreign keys");
  }
 
  // Create schema
  const database_query_id_t schema[] = {DATABASE_QUERY_SchemaSessions,
                                        DATABASE_QUERY_SchemaParticipants,
                                        DATABASE_QUERY_SchemaRateEvents,
                                        DATABASE_QUERY_SchemaIdxSessionsId,
                                        DATABASE_QUERY_SchemaIdxSessionsActivity,
                                        DATABASE_QUERY_SchemaIdxParticipantsSession,
                                        DATABASE_QUERY_SchemaIdxRateEvents};
  for (size_t i = 0; i < sizeof(schema) / sizeof(schema[0]); ++i) {
    rc = sqlite3_exec(*db, database_queries[schema[i]].sql, NULL, NULL, &err_msg);
    if (rc != SQLITE_OK)
      break;
  }
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    log_error("Failed to create schema: %s", err_msg ? err_msg : "unknown error");
    sqlite3_free(err_msg);
    sqlite3_close(*db);
    *db = NULL;
    return SET_ERRNO(ERROR_CONFIG, "Failed to create database schema");
  }
 
  rc = sqlite3_exec(*db, database_queries[DATABASE_QUERY_SchemaSessionTransports].sql, NULL, NULL, NULL);
  if (rc == SQLITE_OK)
    rc = sqlite3_exec(*db, database_queries[DATABASE_QUERY_SchemaSessionTransportHosts].sql, NULL, NULL, NULL);
  if (rc == SQLITE_OK)
    rc = sqlite3_exec(*db, database_queries[DATABASE_QUERY_SchemaClearTransportsTrigger].sql, NULL, NULL, NULL);
  if (rc != SQLITE_OK) {
    sqlite3_close(*db);
    *db = NULL;
    return SET_ERRNO(ERROR_CONFIG, "Cannot create discovery transport metadata table");
  }
 
  // Idempotent, transactional migration from the untyped key table. A policy
  // row is also the migration marker: reopening must never restore revoked keys.
  sqlite3_stmt *legacy_table = NULL;
  rc = ascii_otel_sqlite_prepare(*db, database_queries[DATABASE_QUERY_HasLegacySessionKeys].sql, &legacy_table);
  bool has_legacy_keys = false;
  if (rc == SQLITE_OK) {
    rc = sqlite3_step(legacy_table);
    has_legacy_keys = rc == SQLITE_ROW;
    if (rc == SQLITE_ROW || rc == SQLITE_DONE)
      rc = SQLITE_OK;
  }
  sqlite3_finalize(legacy_table);
  const database_query_id_t migration_schema[] = {DATABASE_QUERY_BeginTransaction, DATABASE_QUERY_SchemaKeyPolicy,
                                                  DATABASE_QUERY_SchemaIdentityKeys};
  for (size_t i = 0; rc == SQLITE_OK && i < sizeof(migration_schema) / sizeof(migration_schema[0]); ++i)
    rc = sqlite3_exec(*db, database_queries[migration_schema[i]].sql, NULL, NULL, &err_msg);
  if (rc == SQLITE_OK && has_legacy_keys) {
    // Read legacy keys only during migration; new databases do not create the
    // superseded table or its indexes. Existing tables remain intact.
    const char *legacy_import = database_queries[DATABASE_QUERY_ImportLegacySessionKeys].sql;
    rc = sqlite3_exec(*db, legacy_import, NULL, NULL, &err_msg);
  }
  const database_query_id_t migration_backfill[] = {DATABASE_QUERY_BackfillSessionIdentityKeys,
                                                    DATABASE_QUERY_BackfillSessionKeyPolicy,
                                                    DATABASE_QUERY_CommitTransaction};
  for (size_t i = 0; rc == SQLITE_OK && i < sizeof(migration_backfill) / sizeof(migration_backfill[0]); ++i)
    rc = sqlite3_exec(*db, database_queries[migration_backfill[i]].sql, NULL, NULL, &err_msg);
  if (rc != SQLITE_OK) {
    log_error("Failed to migrate session keys: %s", err_msg ? err_msg : "unknown error");
    sqlite3_free(err_msg);
    sqlite3_exec(*db, database_queries[DATABASE_QUERY_RollbackTransaction].sql, NULL, NULL, NULL);
    sqlite3_close(*db);
    *db = NULL;
    return SET_ERRNO(ERROR_CONFIG, "Failed to migrate session keys");
  }
 
  log_info("Database initialized successfully (SQLite as single source of truth)");
  return ASCIICHAT_OK;
}

References ascii_otel_metric(), ASCII_OTEL_SCOPE, ascii_otel_sqlite_catalog(), ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_BackfillSessionIdentityKeys, DATABASE_QUERY_BackfillSessionKeyPolicy, DATABASE_QUERY_BeginTransaction, DATABASE_QUERY_CommitTransaction, DATABASE_QUERY_COUNT, DATABASE_QUERY_EnableForeignKeys, DATABASE_QUERY_EnableWAL, DATABASE_QUERY_HasLegacySessionKeys, DATABASE_QUERY_ImportLegacySessionKeys, DATABASE_QUERY_RollbackTransaction, DATABASE_QUERY_SchemaClearTransportsTrigger, DATABASE_QUERY_SchemaIdentityKeys, DATABASE_QUERY_SchemaIdxParticipantsSession, DATABASE_QUERY_SchemaIdxRateEvents, DATABASE_QUERY_SchemaIdxSessionsActivity, DATABASE_QUERY_SchemaIdxSessionsId, DATABASE_QUERY_SchemaKeyPolicy, DATABASE_QUERY_SchemaParticipants, DATABASE_QUERY_SchemaRateEvents, DATABASE_QUERY_SchemaSessions, DATABASE_QUERY_SchemaSessionTransportHosts, DATABASE_QUERY_SchemaSessionTransports, ERROR_CONFIG, ERROR_INVALID_PARAM, log_error, log_info, log_warn, and SET_ERRNO.

Referenced by acds_server_init().

database_session_add_key()

asciichat_error_t database_session_add_key	(	sqlite3 *	db,
		const char *	session_string,
		const uint8_t	identity_pubkey[32],
		uint32_t	key_version )

Add a key to a session.

Parameters

db	Database handle
session_string	Session string
identity_pubkey	Ed25519 public key (32 bytes)
key_version	Key version for tracking rotation

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 1389 of file discovery/database.c.

                                                                 {
  ASCII_OTEL_SCOPE(DATABASE_ADD_KEY);
  if (!db || !session_string || !identity_pubkey || sodium_is_zero(identity_pubkey, 32)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for add_key");
  }
 
  const char *sql = database_queries[DATABASE_QUERY_AddSessionKey].sql;
 
  sqlite3_stmt *stmt = NULL;
  if (ascii_otel_sqlite_prepare(db, sql, &stmt) != SQLITE_OK) {
    return SET_ERRNO(ERROR_CONFIG, "Failed to prepare add_key statement: %s", sqlite3_errmsg(db));
  }
 
  if ((sqlite3_bind_text(stmt, sqlite3_bind_parameter_index(stmt, ":session_string"), session_string, -1,
                         SQLITE_STATIC) != SQLITE_OK) ||
      (sqlite3_bind_blob(stmt, sqlite3_bind_parameter_index(stmt, ":identity_pubkey"), identity_pubkey, 32,
                         SQLITE_STATIC) != SQLITE_OK) ||
      (sqlite3_bind_int(stmt, sqlite3_bind_parameter_index(stmt, ":key_version"), key_version) != SQLITE_OK) ||
      (sqlite3_bind_int64(stmt, sqlite3_bind_parameter_index(stmt, ":added_at"), database_get_current_time_ms()) !=
       SQLITE_OK)) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
  }
 
  int rc = sqlite3_step(stmt);
  sqlite3_finalize(stmt);
 
  if (rc != SQLITE_DONE) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    return SET_ERRNO(ERROR_CONFIG, "Failed to add session key: %s", sqlite3_errmsg(db));
  }
 
  log_debug("Added key to session %s (version=%u)", session_string, key_version);
  return ASCIICHAT_OK;
}

References ascii_otel_metric(), ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_AddSessionKey, ED25519_PUBLIC_KEY_SIZE, ERROR_CONFIG, ERROR_INVALID_PARAM, log_debug, and SET_ERRNO.

database_session_cleanup_expired()

void database_session_cleanup_expired

(

sqlite3 *

db

)

Clean up inactive sessions.

Removes sessions that have been inactive for more than 3 hours. Inactivity is measured by last_activity_at (updated on join/leave/host updates). Called periodically by background cleanup thread.

Parameters

db	Database handle

Definition at line 1140 of file discovery/database.c.

                                                   {
  ASCII_OTEL_SCOPE(DATABASE_SESSION_CLEANUP_EXPIRED);
  if (!db) {
    return;
  }
 
  uint64_t now = database_get_current_time_ms();
  // 3 hours in milliseconds
  uint64_t inactivity_threshold = 3ULL * SEC_PER_HOUR * MS_PER_SEC_INT;
  uint64_t cutoff_time = now - inactivity_threshold;
 
  // Log sessions about to be deleted
  const char *log_sql = database_queries[DATABASE_QUERY_FindExpiredSessions].sql;
  sqlite3_stmt *stmt = NULL;
  if (ascii_otel_sqlite_prepare(db, log_sql, &stmt) == SQLITE_OK) {
    if ((sqlite3_bind_int64(stmt, sqlite3_bind_parameter_index(stmt, ":cutoff_time"), (sqlite3_int64)cutoff_time) !=
         SQLITE_OK)) {
      sqlite3_finalize(stmt);
      log_error("Failed to bind SQLite query parameters");
      return;
    }
    while (sqlite3_step(stmt) == SQLITE_ROW) {
      const char *session_string = (const char *)sqlite3_column_text(stmt, 0);
      uint64_t last_activity = (uint64_t)sqlite3_column_int64(stmt, 1);
      uint64_t inactive_ms = now - last_activity;
      uint64_t inactive_hours = inactive_ms / (SEC_PER_HOUR * MS_PER_SEC_INT);
      log_info("Session %s inactive for %lu hours, deleting", session_string ? session_string : "<unknown>",
               inactive_hours);
    }
    sqlite3_finalize(stmt);
  }
 
  // Delete inactive sessions (CASCADE deletes participants)
  const char *del_sql = database_queries[DATABASE_QUERY_DeleteExpiredSessions].sql;
  if (ascii_otel_sqlite_prepare(db, del_sql, &stmt) == SQLITE_OK) {
    if ((sqlite3_bind_int64(stmt, sqlite3_bind_parameter_index(stmt, ":cutoff_time"), (sqlite3_int64)cutoff_time) !=
         SQLITE_OK)) {
      sqlite3_finalize(stmt);
      log_error("Failed to bind SQLite query parameters");
      return;
    }
    sqlite3_step(stmt);
    int deleted = sqlite3_changes(db);
    sqlite3_finalize(stmt);
 
    if (deleted > 0) {
      stats_counter_add(stats_runtime_scope(), STATS_COUNTER_SESSION_EXPIRATIONS, (uint64_t)deleted);
      log_info("Cleaned up %d inactive sessions (>3 hours)", deleted);
    }
  }
}

References ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), DATABASE_QUERY_DeleteExpiredSessions, DATABASE_QUERY_FindExpiredSessions, log_error, log_info, MS_PER_SEC_INT, SEC_PER_HOUR, stats_counter_add(), STATS_COUNTER_SESSION_EXPIRATIONS, and stats_runtime_scope().

database_session_clear_host()

asciichat_error_t database_session_clear_host	(	sqlite3 *	db,
		const uint8_t	session_id[16] )

Clear session host (discovery mode - host migration).

Called when the current host disconnects or fails. Clears host fields so remaining participants can negotiate a new host.

Parameters

db	Database handle
session_id	Session UUID

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 1252 of file discovery/database.c.

                                                                                                      {
  ASCII_OTEL_SCOPE(DATABASE_SESSION_CLEAR_HOST);
  if (!db || !session_id) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "db or session_id is NULL");
  }
 
  const char *sql = database_queries[DATABASE_QUERY_ClearHost].sql;
 
  sqlite3_stmt *stmt = NULL;
  int rc = ascii_otel_sqlite_prepare(db, sql, &stmt);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    return SET_ERRNO(ERROR_CONFIG, "Failed to prepare host clear: %s", sqlite3_errmsg(db));
  }
 
  if ((sqlite3_bind_blob(stmt, sqlite3_bind_parameter_index(stmt, ":session_id"), session_id, 16, SQLITE_STATIC) !=
       SQLITE_OK)) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
  }
 
  rc = sqlite3_step(stmt);
  if (rc == SQLITE_DONE && !sqlite3_stmt_readonly(stmt))
    ascii_otel_metric(ASCII_OTEL_METRIC_DB_ROWS, sqlite3_changes(db));
  sqlite3_finalize(stmt);
 
  if (rc != SQLITE_DONE) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    return SET_ERRNO(ERROR_CONFIG, "Failed to clear host: %s", sqlite3_errmsg(db));
  }
 
  int changes = sqlite3_changes(db);
  if (changes == 0) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Session not found for host clear");
  }
 
  log_info("Session host cleared (session=%02x%02x...) - ready for migration", session_id[0], session_id[1]);
 
  return ASCIICHAT_OK;
}

References ascii_otel_metric(), ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_ClearHost, ERROR_CONFIG, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, log_info, session_id, SESSION_ID_SIZE, and SET_ERRNO.

database_session_create()

asciichat_error_t database_session_create	(	sqlite3 *	db,
		const acip_session_create_t *	req,
		const acds_config_t *	config,
		acip_session_created_t *	resp )

Create new session.

Parameters

db	Database handle
req	Session creation request
config	ACDS server configuration
resp	Session creation response (output)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 434 of file discovery/database.c.

                                                                        {
  if (!req)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing create request");
  return database_session_create_keys(db, req, (const uint8_t (*)[32]) & req->identity_pubkey, 1, config, resp);
}

References acip_session_create_t, acip_session_created_t, database_session_create_keys(), ERROR_INVALID_PARAM, and SET_ERRNO.

database_session_create_keys()

asciichat_error_t database_session_create_keys	(	sqlite3 *	db,
		const acip_session_create_t *	req,
		const uint8_t(*)	keys[32],
		size_t	count,
		const acds_config_t *	config,
		acip_session_created_t *	resp )

Create an explicit Ed25519 key set atomically. More than one key opts into allowlisted joins; count=1 preserves the legacy admission policy. The caller must verify each create proof before calling this persistence API.

Definition at line 512 of file discovery/database.c.

                                                                             {
  return database_session_create_keys_with_transport(db, req, keys, count, config, resp, NULL, 0);
}

References acip_session_create_t, acip_session_created_t, and database_session_create_keys_with_transport().

Referenced by database_session_create().

database_session_create_keys_with_transport()

asciichat_error_t database_session_create_keys_with_transport	(	sqlite3 *	db,
		const acip_session_create_t *	req,
		const uint8_t(*)	keys[32],
		size_t	count,
		const acds_config_t *	config,
		acip_session_created_t *	resp,
		const void *	metadata,
		size_t	metadata_length )

Persist advertised transports in the same transaction as the session and key set.

Definition at line 496 of file discovery/database.c.

                                                                                                            {
  if (!db)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing database");
  // SQLite serializes statements, but a shared connection also needs to keep
  // other client threads out of this multi-statement savepoint.
  sqlite3_mutex *mutex = sqlite3_db_mutex(db);
  sqlite3_mutex_enter(mutex);
  asciichat_error_t result =
      database_session_create_keys_locked(db, req, keys, count, config, resp, metadata, metadata_length);
  sqlite3_mutex_leave(mutex);
  return result;
}

References acip_session_create_t, acip_session_created_t, ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by database_session_create_keys().

database_session_find_by_id()

session_entry_t * database_session_find_by_id	(	sqlite3 *	db,
		const uint8_t	session_id[16] )

Find session by session_id.

Allocates and returns a session_entry_t. Caller must free with session_entry_destroy().

Parameters

db	Database handle
session_id	Session UUID to find

Returns

Allocated session entry (caller owns), or NULL if not found

Definition at line 1078 of file discovery/database.c.

                                                                                                     {
  if (!db || !session_id) {
    return NULL;
  }
 
  const char *sql = database_queries[DATABASE_QUERY_GetSessionById].sql;
 
  sqlite3_stmt *stmt = NULL;
  if (ascii_otel_sqlite_prepare(db, sql, &stmt) != SQLITE_OK) {
    return NULL;
  }
 
  if ((sqlite3_bind_blob(stmt, sqlite3_bind_parameter_index(stmt, ":session_id"), session_id, 16, SQLITE_STATIC) !=
       SQLITE_OK)) {
    sqlite3_finalize(stmt);
    log_error("Failed to bind SQLite query parameters");
    return NULL;
  }
 
  session_entry_t *session = NULL;
  if (sqlite3_step(stmt) == SQLITE_ROW) {
    session = load_session_from_row(stmt);
    if (session) {
      load_session_participants(db, session);
    }
  }
 
  sqlite3_finalize(stmt);
  return session;
}

References ascii_otel_sqlite_prepare(), DATABASE_QUERY_GetSessionById, log_error, session_id, and SESSION_ID_SIZE.

Referenced by acds_send_current_host(), signaling_broadcast(), signaling_relay_ice(), and signaling_relay_sdp().

database_session_find_by_string()

session_entry_t * database_session_find_by_string	(	sqlite3 *	db,
		const char *	session_string )

Find session by session_string.

Allocates and returns a session_entry_t. Caller must free with session_entry_destroy().

Parameters

db	Database handle
session_string	Session string to find

Returns

Allocated session entry (caller owns), or NULL if not found

Definition at line 1109 of file discovery/database.c.

                                                                                          {
  if (!db || !session_string) {
    return NULL;
  }
 
  const char *sql = database_queries[DATABASE_QUERY_GetSessionByString].sql;
 
  sqlite3_stmt *stmt = NULL;
  if (ascii_otel_sqlite_prepare(db, sql, &stmt) != SQLITE_OK) {
    return NULL;
  }
 
  if ((sqlite3_bind_text(stmt, sqlite3_bind_parameter_index(stmt, ":session_string"), session_string, -1,
                         SQLITE_STATIC) != SQLITE_OK)) {
    sqlite3_finalize(stmt);
    log_error("Failed to bind SQLite query parameters");
    return NULL;
  }
 
  session_entry_t *session = NULL;
  if (sqlite3_step(stmt) == SQLITE_ROW) {
    session = load_session_from_row(stmt);
    if (session) {
      load_session_participants(db, session);
    }
  }
 
  sqlite3_finalize(stmt);
  return session;
}

References ascii_otel_sqlite_prepare(), DATABASE_QUERY_GetSessionByString, and log_error.

Referenced by database_session_join().

database_session_get_keys()

asciichat_error_t database_session_get_keys	(	sqlite3 *	db,
		const char *	session_string,
		uint8_t(*)	keys_out[32],
		size_t	max_keys,
		size_t *	count_out )

Get all active keys for a session.

Parameters

db	Database handle
session_string	Session string
keys_out	Output array for keys (caller must provide buffer)
max_keys	Maximum number of keys to retrieve
count_out	Output: number of keys retrieved

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 1492 of file discovery/database.c.

                                                                                {
  ASCII_OTEL_SCOPE(DATABASE_GET_KEYS);
  if (!db || !session_string || !keys_out || !count_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for get_keys");
  }
 
  const char *sql = database_queries[DATABASE_QUERY_GetSessionKeys].sql;
 
  sqlite3_stmt *stmt = NULL;
  if (ascii_otel_sqlite_prepare(db, sql, &stmt) != SQLITE_OK) {
    return SET_ERRNO(ERROR_CONFIG, "Failed to prepare get_keys statement: %s", sqlite3_errmsg(db));
  }
 
  if ((sqlite3_bind_text(stmt, sqlite3_bind_parameter_index(stmt, ":session_string"), session_string, -1,
                         SQLITE_STATIC) != SQLITE_OK)) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
  }
 
  size_t count = 0;
  while (sqlite3_step(stmt) == SQLITE_ROW && count < max_keys) {
    const void *blob = sqlite3_column_blob(stmt, 0);
    if (blob && sqlite3_column_bytes(stmt, 0) == 32) {
      memcpy(keys_out[count], blob, ED25519_PUBLIC_KEY_SIZE);
      count++;
    }
  }
 
  sqlite3_finalize(stmt);
  *count_out = count;
 
  log_debug("Retrieved %zu keys for session %s", count, session_string);
  return ASCIICHAT_OK;
}

References ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_GetSessionKeys, ED25519_PUBLIC_KEY_SIZE, ERROR_CONFIG, ERROR_INVALID_PARAM, log_debug, and SET_ERRNO.

database_session_is_migration_ready()

bool database_session_is_migration_ready	(	sqlite3 *	db,
		const uint8_t	session_id[16],
		uint64_t	migration_window_ms )

Check if migration window has completed.

Called periodically to check if migration collection window timeout has expired. Returns the session if migration is ready for host election.

Parameters

db	Database handle
session_id	Session UUID
migration_window_ms	Collection window duration in milliseconds

Returns

true if collection window has completed, false otherwise

Definition at line 1343 of file discovery/database.c.

                                                                       {
  ASCII_OTEL_SCOPE(DATABASE_MIGRATION_READY);
  if (!db || !session_id) {
    return false;
  }
 
  uint64_t now_ns = time_get_realtime_ns();
  const char *sql = database_queries[DATABASE_QUERY_GetMigrationState].sql;
 
  sqlite3_stmt *stmt = NULL;
  if (ascii_otel_sqlite_prepare(db, sql, &stmt) != SQLITE_OK) {
    return false;
  }
 
  if ((sqlite3_bind_blob(stmt, sqlite3_bind_parameter_index(stmt, ":session_id"), session_id, 16, SQLITE_STATIC) !=
       SQLITE_OK)) {
    sqlite3_finalize(stmt);
    log_error("Failed to bind SQLite query parameters");
    return false;
  }
 
  bool ready = false;
  if (sqlite3_step(stmt) == SQLITE_ROW) {
    int in_migration = sqlite3_column_int(stmt, 0);
    uint64_t migration_start_ns = (uint64_t)sqlite3_column_int64(stmt, 1);
 
    if (in_migration) {
      uint64_t elapsed_ns = now_ns - migration_start_ns;
      uint64_t migration_window_ns = migration_window_ms * NS_PER_MS_INT;
      if (elapsed_ns >= migration_window_ns) {
        ready = true;
        log_debug("Migration window complete (session=%02x%02x..., elapsed=%lu ns, window=%lu ns)", session_id[0],
                  session_id[1], elapsed_ns, migration_window_ns);
      }
    }
  }
 
  sqlite3_finalize(stmt);
  return ready;
}

References ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), DATABASE_QUERY_GetMigrationState, log_debug, log_error, NS_PER_MS_INT, session_id, and SESSION_ID_SIZE.

Referenced by database_session_update_host().

database_session_join()

asciichat_error_t database_session_join	(	sqlite3 *	db,
		const acip_session_join_t *	req,
		const acds_config_t *	config,
		acip_session_joined_t *	resp )

Join existing session.

Parameters

db	Database handle
req	Join request
config	ACDS server configuration (for TURN credentials)
resp	Join response (output)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 834 of file discovery/database.c.

                                                                     {
  ASCII_OTEL_SCOPE(DATABASE_SESSION_JOIN);
  if (!db || !req || !config || !resp) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "db, req, config, or resp is NULL");
  }
 
  memset(resp, 0, sizeof(*resp));
  resp->success = 0;
 
  if (req->session_string_len == 0 || req->session_string_len >= sizeof(req->session_string) ||
      memchr(req->session_string, '\0', (size_t)req->session_string_len) ||
      req->session_string[req->session_string_len] != '\0' ||
      (req->has_password && !memchr(req->password, '\0', sizeof(req->password))))
    return SET_ERRNO(ERROR_INVALID_PARAM, "Malformed join request");
 
  // Extract session string
  char session_string[ACIP_MAX_SESSION_STRING_LEN] = {0};
  size_t len = req->session_string_len < (ACIP_MAX_SESSION_STRING_LEN - 1) ? req->session_string_len
                                                                           : (ACIP_MAX_SESSION_STRING_LEN - 1);
  memcpy(session_string, req->session_string, len);
  session_string[len] = '\0';
 
  // Find session
  session_entry_t *session = database_session_find_by_string(db, session_string);
  if (!session) {
    ascii_otel_metric(ASCII_OTEL_METRIC_LOOKUP_MISS, 1);
    resp->error_code = ACIP_ERROR_SESSION_NOT_FOUND;
    SAFE_STRNCPY(resp->error_message, "Session not found", sizeof(resp->error_message));
    log_warn("Session join failed: %s (not found)", session_string);
    return ASCIICHAT_OK;
  }
 
  // Reject unauthorized identities before spending Argon2 resources or revealing
  // a password result. This preliminary check is repeated in the transaction.
  sqlite3_mutex *mutex = sqlite3_db_mutex(db);
  sqlite3_mutex_enter(mutex);
  asciichat_error_t result = database_session_authorize_join(db, req, config, session_string, resp);
  sqlite3_mutex_leave(mutex);
  if (result != ASCIICHAT_OK || resp->error_code != ACIP_ERROR_NONE) {
    session_entry_destroy(session);
    return result;
  }
 
  // Check if session is full
  if (session->current_participants >= session->max_participants) {
    session_entry_destroy(session);
    resp->error_code = ACIP_ERROR_SESSION_FULL;
    SAFE_STRNCPY(resp->error_message, "Session is full", sizeof(resp->error_message));
    log_warn("Session join failed: %s (full)", session_string);
    return ASCIICHAT_OK;
  }
 
  // Verify password if required
  if (session->has_password && req->has_password) {
    if (!verify_password(req->password, session->password_hash)) {
      session_entry_destroy(session);
      resp->error_code = ACIP_ERROR_INVALID_PASSWORD;
      SAFE_STRNCPY(resp->error_message, "Invalid password", sizeof(resp->error_message));
      log_warn("Session join failed: %s (invalid password)", session_string);
      return ASCIICHAT_OK;
    }
  } else if (session->has_password && !req->has_password) {
    session_entry_destroy(session);
    resp->error_code = ACIP_ERROR_INVALID_PASSWORD;
    SAFE_STRNCPY(resp->error_message, "Password required", sizeof(resp->error_message));
    log_warn("Session join failed: %s (password required)", session_string);
    return ASCIICHAT_OK;
  }
 
  // The immutable snapshot records which session/password was verified. The
  // commit helper reloads mutable state after BEGIN and never hashes under lock.
  session_entry_t *joined = NULL;
  sqlite3_mutex_enter(mutex);
  result = database_session_join_commit(db, req, config, session, resp, &joined);
  sqlite3_mutex_leave(mutex);
  session_entry_destroy(session);
  if (joined)
    database_session_join_response(joined, config, resp);
  return result;
}

References ACIP_ERROR_INVALID_PASSWORD, ACIP_ERROR_NONE, ACIP_ERROR_SESSION_FULL, ACIP_ERROR_SESSION_NOT_FOUND, ACIP_MAX_SESSION_STRING_LEN, acip_session_join_t, acip_session_joined_t, ascii_otel_metric(), ASCII_OTEL_SCOPE, ASCIICHAT_OK, session_entry::current_participants, database_session_find_by_string(), ERROR_INVALID_PARAM, session_entry::has_password, log_warn, session_entry::max_participants, session_entry::password_hash, SAFE_STRNCPY, session_entry_destroy(), and SET_ERRNO.

database_session_leave()

asciichat_error_t database_session_leave	(	sqlite3 *	db,
		const uint8_t	session_id[16],
		const uint8_t	participant_id[16] )

Leave session.

Parameters

db	Database handle
session_id	Session UUID
participant_id	Participant UUID

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 916 of file discovery/database.c.

                                                                                        {
  ASCII_OTEL_SCOPE(DATABASE_SESSION_LEAVE);
  if (!db || !session_id || !participant_id) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "db, session_id, or participant_id is NULL");
  }
 
  // Look up session_string from session_id
  char session_string[SESSION_STRING_BUFFER_SIZE] = {0};
  const char *lookup_sql = database_queries[DATABASE_QUERY_LookupSessionString].sql;
  sqlite3_stmt *stmt = NULL;
  int rc = ascii_otel_sqlite_prepare(db, lookup_sql, &stmt);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    return SET_ERRNO(ERROR_CONFIG, "Failed to prepare session lookup: %s", sqlite3_errmsg(db));
  }
 
  int session_id_index = sqlite3_bind_parameter_index(stmt, ":session_id");
  rc = session_id_index ? sqlite3_bind_blob(stmt, session_id_index, session_id, SESSION_ID_SIZE, SQLITE_STATIC)
                        : SQLITE_RANGE;
  if (rc != SQLITE_OK) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_CONFIG, "Failed to bind session lookup parameter");
  }
  rc = sqlite3_step(stmt);
  if (rc == SQLITE_DONE && !sqlite3_stmt_readonly(stmt))
    ascii_otel_metric(ASCII_OTEL_METRIC_DB_ROWS, sqlite3_changes(db));
  if (rc != SQLITE_ROW) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_INVALID_STATE, "Session not found");
  }
 
  const char *str = (const char *)sqlite3_column_text(stmt, 0);
  if (str) {
    SAFE_STRNCPY(session_string, str, sizeof(session_string));
  }
  sqlite3_finalize(stmt);
 
  if (session_string[0] == '\0') {
    return SET_ERRNO(ERROR_INVALID_STATE, "Session string is empty");
  }
 
  // Begin transaction
  char *err_msg = NULL;
  rc = sqlite3_exec(db, database_queries[DATABASE_QUERY_BeginTransaction].sql, NULL, NULL, &err_msg);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    log_error("Failed to begin transaction: %s", err_msg ? err_msg : "unknown");
    sqlite3_free(err_msg);
    return SET_ERRNO(ERROR_CONFIG, "Failed to begin transaction");
  }
 
  // Delete participant
  const char *del_sql = database_queries[DATABASE_QUERY_DeleteParticipant].sql;
  rc = ascii_otel_sqlite_prepare(db, del_sql, &stmt);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    sqlite3_exec(db, database_queries[DATABASE_QUERY_RollbackTransaction].sql, NULL, NULL, NULL);
    return SET_ERRNO(ERROR_CONFIG, "Failed to prepare participant delete: %s", sqlite3_errmsg(db));
  }
 
  if ((sqlite3_bind_blob(stmt, sqlite3_bind_parameter_index(stmt, ":participant_id"), participant_id, 16,
                         SQLITE_STATIC) != SQLITE_OK) ||
      (sqlite3_bind_text(stmt, sqlite3_bind_parameter_index(stmt, ":session_string"), session_string, -1,
                         SQLITE_STATIC) != SQLITE_OK)) {
    sqlite3_finalize(stmt);
    sqlite3_exec(db, database_queries[DATABASE_QUERY_RollbackTransaction].sql, NULL, NULL, NULL);
    return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
  }
  rc = sqlite3_step(stmt);
  if (rc == SQLITE_DONE && !sqlite3_stmt_readonly(stmt))
    ascii_otel_metric(ASCII_OTEL_METRIC_DB_ROWS, sqlite3_changes(db));
  sqlite3_finalize(stmt);
 
  if (rc != SQLITE_DONE) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    sqlite3_exec(db, database_queries[DATABASE_QUERY_RollbackTransaction].sql, NULL, NULL, NULL);
    return SET_ERRNO(ERROR_CONFIG, "Failed to delete participant: %s", sqlite3_errmsg(db));
  }
 
  int changes = sqlite3_changes(db);
  if (changes == 0) {
    sqlite3_exec(db, database_queries[DATABASE_QUERY_RollbackTransaction].sql, NULL, NULL, NULL);
    return SET_ERRNO(ERROR_INVALID_STATE, "Participant not in session");
  }
 
  uint64_t now = database_get_current_time_ms();
 
  // Decrement participant count and update last activity
  const char *update_sql = database_queries[DATABASE_QUERY_DecrementParticipants].sql;
  rc = ascii_otel_sqlite_prepare(db, update_sql, &stmt);
  if (rc == SQLITE_OK) {
    if ((sqlite3_bind_int64(stmt, sqlite3_bind_parameter_index(stmt, ":last_activity_at"), (sqlite3_int64)now) !=
         SQLITE_OK) ||
        (sqlite3_bind_text(stmt, sqlite3_bind_parameter_index(stmt, ":session_string"), session_string, -1,
                           SQLITE_STATIC) != SQLITE_OK)) {
      sqlite3_finalize(stmt);
      sqlite3_exec(db, database_queries[DATABASE_QUERY_RollbackTransaction].sql, NULL, NULL, NULL);
      return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
    }
    sqlite3_step(stmt);
    sqlite3_finalize(stmt);
  }
 
  // Check if session is now empty and delete if so
  const char *check_sql = database_queries[DATABASE_QUERY_GetParticipantCount].sql;
  rc = ascii_otel_sqlite_prepare(db, check_sql, &stmt);
  if (rc == SQLITE_OK) {
    if ((sqlite3_bind_text(stmt, sqlite3_bind_parameter_index(stmt, ":session_string"), session_string, -1,
                           SQLITE_STATIC) != SQLITE_OK)) {
      sqlite3_finalize(stmt);
      sqlite3_exec(db, database_queries[DATABASE_QUERY_RollbackTransaction].sql, NULL, NULL, NULL);
      return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
    }
    if (sqlite3_step(stmt) == SQLITE_ROW) {
      int count = sqlite3_column_int(stmt, 0);
 
      if (count <= 0) {
        log_info("Session %s has no participants, deleting", session_string);
        sqlite3_finalize(stmt);
 
        // Delete empty session
        const char *del_session_sql = database_queries[DATABASE_QUERY_DeleteSession].sql;
        rc = ascii_otel_sqlite_prepare(db, del_session_sql, &stmt);
        if (rc == SQLITE_OK) {
          if ((sqlite3_bind_text(stmt, sqlite3_bind_parameter_index(stmt, ":session_string"), session_string, -1,
                                 SQLITE_STATIC) != SQLITE_OK)) {
            sqlite3_finalize(stmt);
            sqlite3_exec(db, database_queries[DATABASE_QUERY_RollbackTransaction].sql, NULL, NULL, NULL);
            return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
          }
          sqlite3_step(stmt);
          sqlite3_finalize(stmt);
        }
        stmt = NULL;
      } else {
        log_info("Participant left session %s (participants=%d remaining)", session_string, count);
      }
    }
    if (stmt) {
      sqlite3_finalize(stmt);
    }
  }
 
  // Commit transaction
  rc = sqlite3_exec(db, database_queries[DATABASE_QUERY_CommitTransaction].sql, NULL, NULL, &err_msg);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    log_error("Failed to commit transaction: %s", err_msg ? err_msg : "unknown");
    sqlite3_free(err_msg);
    sqlite3_exec(db, database_queries[DATABASE_QUERY_RollbackTransaction].sql, NULL, NULL, NULL);
    return SET_ERRNO(ERROR_CONFIG, "Failed to commit transaction");
  }
 
  return ASCIICHAT_OK;
}

References ascii_otel_metric(), ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_BeginTransaction, DATABASE_QUERY_CommitTransaction, DATABASE_QUERY_DecrementParticipants, DATABASE_QUERY_DeleteParticipant, DATABASE_QUERY_DeleteSession, DATABASE_QUERY_GetParticipantCount, DATABASE_QUERY_LookupSessionString, DATABASE_QUERY_RollbackTransaction, ERROR_CONFIG, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, log_error, log_info, participant_id, SAFE_STRNCPY, session_id, SESSION_ID_SIZE, SESSION_STRING_BUFFER_SIZE, and SET_ERRNO.

database_session_lookup()

asciichat_error_t database_session_lookup	(	sqlite3 *	db,
		const char *	session_string,
		const acds_config_t *	config,
		acip_session_info_t *	resp )

Lookup session by string.

Parameters

db	Database handle
session_string	Session string to look up
config	ACDS server configuration (for policy flags)
resp	Session info response (output)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 518 of file discovery/database.c.

                                                                     {
  ASCII_OTEL_SCOPE(DATABASE_SESSION_LOOKUP);
  if (!db || !session_string || !config || !resp) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "db, session_string, config, or resp is NULL");
  }
 
  memset(resp, 0, sizeof(*resp));
 
  const char *sql = database_queries[DATABASE_QUERY_LookupSession].sql;
 
  sqlite3_stmt *stmt = NULL;
  int rc = ascii_otel_sqlite_prepare(db, sql, &stmt);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    return SET_ERRNO(ERROR_CONFIG, "Failed to prepare session lookup: %s", sqlite3_errmsg(db));
  }
 
  if ((sqlite3_bind_text(stmt, sqlite3_bind_parameter_index(stmt, ":session_string"), session_string, -1,
                         SQLITE_STATIC) != SQLITE_OK)) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
  }
 
  rc = sqlite3_step(stmt);
  if (rc == SQLITE_DONE && !sqlite3_stmt_readonly(stmt))
    ascii_otel_metric(ASCII_OTEL_METRIC_DB_ROWS, sqlite3_changes(db));
  if (rc != SQLITE_ROW) {
    sqlite3_finalize(stmt);
    resp->found = 0;
    log_debug("Session lookup failed: %s (not found)", session_string);
    return ASCIICHAT_OK;
  }
 
  // Load session data
  resp->found = 1;
 
  const void *blob = sqlite3_column_blob(stmt, 1);
  if (blob) {
    memcpy(resp->session_id, blob, SESSION_ID_SIZE);
  }
 
  blob = sqlite3_column_blob(stmt, 2);
  if (blob) {
    memcpy(resp->host_pubkey, blob, ED25519_PUBLIC_KEY_SIZE);
  }
 
  resp->max_participants = (uint8_t)sqlite3_column_int(stmt, 4);
  resp->current_participants = (uint8_t)sqlite3_column_int(stmt, 5);
  resp->capabilities = (uint8_t)sqlite3_column_int(stmt, 6);
  resp->has_password = sqlite3_column_int(stmt, 7) != 0;
  resp->session_type = (uint8_t)sqlite3_column_int(stmt, 9);
  resp->created_at = (uint64_t)sqlite3_column_int64(stmt, 12);
  resp->expires_at = (uint64_t)sqlite3_column_int64(stmt, 13);
 
  // ACDS policy flags
  resp->require_server_verify = config->require_server_verify ? 1 : 0;
  resp->require_client_verify = config->require_client_verify ? 1 : 0;
 
  sqlite3_finalize(stmt);
 
  log_debug("Session lookup: %s (found, participants=%d/%d)", session_string, resp->current_participants,
            resp->max_participants);
 
  return ASCIICHAT_OK;
}

References acip_session_info_t, ascii_otel_metric(), ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_LookupSession, ED25519_PUBLIC_KEY_SIZE, ERROR_CONFIG, ERROR_INVALID_PARAM, log_debug, acds_config_t::require_client_verify, acds_config_t::require_server_verify, SESSION_ID_SIZE, and SET_ERRNO.

database_session_revoke_key()

asciichat_error_t database_session_revoke_key	(	sqlite3 *	db,
		const char *	session_string,
		const uint8_t	identity_pubkey[32] )

Revoke a key from a session.

Parameters

db	Database handle
session_string	Session string
identity_pubkey	Ed25519 public key to revoke (32 bytes)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 1428 of file discovery/database.c.

                                                                                                      {
  ASCII_OTEL_SCOPE(DATABASE_REVOKE_KEY);
  if (!db || !session_string || !identity_pubkey) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for revoke_key");
  }
 
  const char *sql = database_queries[DATABASE_QUERY_RevokeSessionKey].sql;
 
  sqlite3_stmt *stmt = NULL;
  if (ascii_otel_sqlite_prepare(db, sql, &stmt) != SQLITE_OK) {
    return SET_ERRNO(ERROR_CONFIG, "Failed to prepare revoke_key statement: %s", sqlite3_errmsg(db));
  }
 
  if ((sqlite3_bind_text(stmt, sqlite3_bind_parameter_index(stmt, ":session_string"), session_string, -1,
                         SQLITE_STATIC) != SQLITE_OK) ||
      (sqlite3_bind_blob(stmt, sqlite3_bind_parameter_index(stmt, ":identity_pubkey"), identity_pubkey, 32,
                         SQLITE_STATIC) != SQLITE_OK)) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
  }
 
  int rc = sqlite3_step(stmt);
  sqlite3_finalize(stmt);
 
  if (rc != SQLITE_DONE) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    return SET_ERRNO(ERROR_CONFIG, "Failed to revoke session key: %s", sqlite3_errmsg(db));
  }
 
  log_debug("Revoked key from session %s", session_string);
  return ASCIICHAT_OK;
}

References ascii_otel_metric(), ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_RevokeSessionKey, ED25519_PUBLIC_KEY_SIZE, ERROR_CONFIG, ERROR_INVALID_PARAM, log_debug, and SET_ERRNO.

database_session_start_migration()

asciichat_error_t database_session_start_migration	(	sqlite3 *	db,
		const uint8_t	session_id[16] )

Start host migration (discovery mode).

Called when the current host disconnects. Marks session as in_migration and starts a collection window for HOST_LOST candidates.

Parameters

db	Database handle
session_id	Session UUID

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 1295 of file discovery/database.c.

                                                                                                           {
  ASCII_OTEL_SCOPE(DATABASE_SESSION_START_MIGRATION);
  if (!db || !session_id) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "db or session_id is NULL");
  }
 
  uint64_t now_ns = time_get_realtime_ns();
 
  const char *sql = database_queries[DATABASE_QUERY_StartMigration].sql;
 
  sqlite3_stmt *stmt = NULL;
  int rc = ascii_otel_sqlite_prepare(db, sql, &stmt);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    return SET_ERRNO(ERROR_CONFIG, "Failed to prepare migration start: %s", sqlite3_errmsg(db));
  }
 
  if ((sqlite3_bind_int64(stmt, sqlite3_bind_parameter_index(stmt, ":migration_start_ns"), (sqlite3_int64)now_ns) !=
       SQLITE_OK) ||
      (sqlite3_bind_blob(stmt, sqlite3_bind_parameter_index(stmt, ":session_id"), session_id, 16, SQLITE_STATIC) !=
       SQLITE_OK)) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
  }
 
  rc = sqlite3_step(stmt);
  if (rc == SQLITE_DONE && !sqlite3_stmt_readonly(stmt))
    ascii_otel_metric(ASCII_OTEL_METRIC_DB_ROWS, sqlite3_changes(db));
  sqlite3_finalize(stmt);
 
  if (rc != SQLITE_DONE) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    return SET_ERRNO(ERROR_CONFIG, "Failed to start migration: %s", sqlite3_errmsg(db));
  }
 
  int changes = sqlite3_changes(db);
  if (changes == 0) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Session not found for migration start");
  }
 
  log_info("Session migration started (session=%02x%02x..., start_ns=%" PRIu64 ")", session_id[0], session_id[1],
           now_ns);
 
  return ASCIICHAT_OK;
}

References ascii_otel_metric(), ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_StartMigration, ERROR_CONFIG, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, log_info, session_id, SESSION_ID_SIZE, and SET_ERRNO.

database_session_transport_get()

asciichat_error_t database_session_transport_get	(	sqlite3 *	db,
		const uint8_t	session_id[16],
		void *	metadata,
		size_t	capacity,
		size_t *	length )

Definition at line 1660 of file discovery/database.c.

                                                                                  {
  if (!db || !session_id || !metadata || !length)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid discovery transport metadata output");
  *length = 0;
  sqlite3_stmt *statement = NULL;
  int rc = ascii_otel_sqlite_prepare(db, database_queries[DATABASE_QUERY_GetSessionTransports].sql, &statement);
  if (rc == SQLITE_OK)
    rc = sqlite3_bind_blob(statement, sqlite3_bind_parameter_index(statement, ":session_id"), session_id,
                           SESSION_ID_SIZE, SQLITE_TRANSIENT);
  if (rc == SQLITE_OK)
    rc = sqlite3_step(statement);
  asciichat_error_t result = ASCIICHAT_OK;
  if (rc == SQLITE_ROW) {
    int bytes = sqlite3_column_bytes(statement, 0);
    if (bytes < 10 || (size_t)bytes > capacity)
      result = SET_ERRNO(ERROR_NETWORK_SIZE, "Invalid stored discovery transport metadata size");
    else {
      memcpy(metadata, sqlite3_column_blob(statement, 0), (size_t)bytes);
      *length = (size_t)bytes;
    }
  } else if (rc != SQLITE_DONE) {
    result = SET_ERRNO(ERROR_CONFIG, "Cannot read discovery transport metadata");
  }
  sqlite3_finalize(statement);
  return result;
}

References ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_GetSessionTransports, ERROR_CONFIG, ERROR_INVALID_PARAM, ERROR_NETWORK_SIZE, session_id, SESSION_ID_SIZE, and SET_ERRNO.

database_session_transport_set()

asciichat_error_t database_session_transport_set	(	sqlite3 *	db,
		const uint8_t	session_id[16],
		const void *	metadata,
		size_t	length )

Definition at line 1642 of file discovery/database.c.

                                                                                      {
  if (!db || !session_id || !metadata || length < 10 || length > 521)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid discovery transport metadata");
  sqlite3_stmt *statement = NULL;
  int rc = ascii_otel_sqlite_prepare(db, database_queries[DATABASE_QUERY_SetSessionTransports].sql, &statement);
  if (rc == SQLITE_OK)
    rc = sqlite3_bind_blob(statement, sqlite3_bind_parameter_index(statement, ":session_id"), session_id,
                           SESSION_ID_SIZE, SQLITE_TRANSIENT);
  if (rc == SQLITE_OK)
    rc = sqlite3_bind_blob(statement, sqlite3_bind_parameter_index(statement, ":metadata"), metadata, (int)length,
                           SQLITE_TRANSIENT);
  if (rc == SQLITE_OK)
    rc = sqlite3_step(statement);
  sqlite3_finalize(statement);
  return rc == SQLITE_DONE ? ASCIICHAT_OK : SET_ERRNO(ERROR_CONFIG, "Cannot store discovery transport metadata");
}

References ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_SetSessionTransports, ERROR_CONFIG, ERROR_INVALID_PARAM, session_id, SESSION_ID_SIZE, and SET_ERRNO.

Referenced by database_session_update_host_with_transport().

database_session_update_host()

asciichat_error_t database_session_update_host	(	sqlite3 *	db,
		const uint8_t	session_id[16],
		const uint8_t	host_participant_id[16],
		const char *	host_address,
		uint16_t	host_port,
		uint8_t	connection_type )

Update session host (discovery mode).

Called when a participant announces they are hosting. Updates the session's host fields so new joiners know where to connect.

Parameters

db	Database handle
session_id	Session UUID
host_participant_id	Host's participant UUID
host_address	Host's reachable address
host_port	Host's port
connection_type	How to reach host (ACIP_CONNECTION_TYPE_*)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 1192 of file discovery/database.c.

                                                                                                                      {
  ASCII_OTEL_SCOPE(DATABASE_SESSION_UPDATE_HOST);
  if (!db || !session_id || !host_participant_id) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "db, session_id, or host_participant_id is NULL");
  }
 
  bool migrating = database_session_is_migration_ready(db, session_id, 0);
  uint64_t now = database_get_current_time_ms();
 
  const char *sql = database_queries[DATABASE_QUERY_UpdateHost].sql;
 
  sqlite3_stmt *stmt = NULL;
  int rc = ascii_otel_sqlite_prepare(db, sql, &stmt);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    return SET_ERRNO(ERROR_CONFIG, "Failed to prepare host update: %s", sqlite3_errmsg(db));
  }
 
  if ((sqlite3_bind_blob(stmt, sqlite3_bind_parameter_index(stmt, ":host_participant_id"), host_participant_id, 16,
                         SQLITE_STATIC) != SQLITE_OK) ||
      (sqlite3_bind_text(stmt, sqlite3_bind_parameter_index(stmt, ":host_address"), host_address ? host_address : "",
                         -1, SQLITE_STATIC) != SQLITE_OK) ||
      (sqlite3_bind_int(stmt, sqlite3_bind_parameter_index(stmt, ":host_port"), host_port) != SQLITE_OK) ||
      (sqlite3_bind_int(stmt, sqlite3_bind_parameter_index(stmt, ":host_connection_type"), connection_type) !=
       SQLITE_OK) ||
      (sqlite3_bind_int64(stmt, sqlite3_bind_parameter_index(stmt, ":last_activity_at"), (sqlite3_int64)now) !=
       SQLITE_OK) ||
      (sqlite3_bind_blob(stmt, sqlite3_bind_parameter_index(stmt, ":session_id"), session_id, 16, SQLITE_STATIC) !=
       SQLITE_OK)) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
  }
 
  rc = sqlite3_step(stmt);
  if (rc == SQLITE_DONE && !sqlite3_stmt_readonly(stmt))
    ascii_otel_metric(ASCII_OTEL_METRIC_DB_ROWS, sqlite3_changes(db));
  sqlite3_finalize(stmt);
 
  if (rc != SQLITE_DONE) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    return SET_ERRNO(ERROR_CONFIG, "Failed to update host: %s", sqlite3_errmsg(db));
  }
 
  int changes = sqlite3_changes(db);
  if (changes == 0) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Session not found for host update");
  }
 
  log_info("Session host updated: participant=%02x%02x..., address=%s:%u, type=%d", host_participant_id[0],
           host_participant_id[1], host_address ? host_address : "(none)", host_port, connection_type);
 
  if (migrating)
    stats_counter_add(stats_runtime_scope(), STATS_COUNTER_HOST_MIGRATIONS, 1);
  return ASCIICHAT_OK;
}

References ascii_otel_metric(), ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_UpdateHost, database_session_is_migration_ready(), ERROR_CONFIG, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, log_info, session_id, SESSION_ID_SIZE, SET_ERRNO, stats_counter_add(), STATS_COUNTER_HOST_MIGRATIONS, and stats_runtime_scope().

Referenced by database_session_update_host_with_transport().

database_session_update_host_with_transport()

asciichat_error_t database_session_update_host_with_transport	(	sqlite3 *	db,
		const uint8_t	session[16],
		const uint8_t	host[16],
		const char *	address,
		uint16_t	port,
		uint8_t	type,
		const void *	metadata,
		size_t	length )

Definition at line 1691 of file discovery/database.c.

                                                                             {
  if (!db || !session || !host || (!metadata && length) || (length && (length < 10 || length > 521)))
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid host transport update");
  // Savepoints belong to the shared connection, so exclude other client
  // threads until this entire refresh has committed or rolled back.
  sqlite3_mutex *mutex = sqlite3_db_mutex(db);
  sqlite3_mutex_enter(mutex);
  if (sqlite3_exec(db, database_queries[DATABASE_QUERY_BeginHostTransportRefresh].sql, NULL, NULL, NULL) != SQLITE_OK) {
    sqlite3_mutex_leave(mutex);
    return SET_ERRNO(ERROR_CONFIG, "Cannot begin host transport update");
  }
  asciichat_error_t result = database_session_update_host(db, session, host, address, port, type);
  if (result == ASCIICHAT_OK && length)
    result = database_session_transport_set(db, session, metadata, length);
  if (result == ASCIICHAT_OK && length) {
    sqlite3_stmt *statement = NULL;
    int rc = ascii_otel_sqlite_prepare(db, database_queries[DATABASE_QUERY_SetSessionTransportHost].sql, &statement);
    if (rc == SQLITE_OK)
      rc = sqlite3_bind_blob(statement, sqlite3_bind_parameter_index(statement, ":session_id"), session,
                             SESSION_ID_SIZE, SQLITE_TRANSIENT);
    if (rc == SQLITE_OK)
      rc = sqlite3_bind_blob(statement, sqlite3_bind_parameter_index(statement, ":host_id"), host, SESSION_ID_SIZE,
                             SQLITE_TRANSIENT);
    if (rc == SQLITE_OK)
      rc = sqlite3_step(statement);
    sqlite3_finalize(statement);
    if (rc != SQLITE_DONE)
      result = SET_ERRNO(ERROR_CONFIG, "Cannot bind transports to the new host");
  }
  if (result == ASCIICHAT_OK &&
      sqlite3_exec(db, database_queries[DATABASE_QUERY_CommitHostTransportRefresh].sql, NULL, NULL, NULL) != SQLITE_OK)
    result = SET_ERRNO(ERROR_CONFIG, "Cannot commit host transport update");
  if (result != ASCIICHAT_OK) {
    sqlite3_exec(db, database_queries[DATABASE_QUERY_RollbackHostTransportRefresh].sql, NULL, NULL, NULL);
    sqlite3_exec(db, database_queries[DATABASE_QUERY_CommitHostTransportRefresh].sql, NULL, NULL, NULL);
  }
  sqlite3_mutex_leave(mutex);
  return result;
}

References ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_BeginHostTransportRefresh, DATABASE_QUERY_CommitHostTransportRefresh, DATABASE_QUERY_RollbackHostTransportRefresh, DATABASE_QUERY_SetSessionTransportHost, database_session_transport_set(), database_session_update_host(), ERROR_CONFIG, ERROR_INVALID_PARAM, SESSION_ID_SIZE, and SET_ERRNO.

database_session_verify_key()

bool database_session_verify_key	(	sqlite3 *	db,
		const char *	session_string,
		const uint8_t	identity_pubkey[32] )

Check if a key is valid for a session (exists and not revoked).

Parameters

db	Database handle
session_string	Session string
identity_pubkey	Ed25519 public key to check (32 bytes)

Returns

true if key is valid, false otherwise

Definition at line 1463 of file discovery/database.c.

                                                                                         {
  ASCII_OTEL_SCOPE(DATABASE_VERIFY_KEY);
  if (!db || !session_string || !identity_pubkey) {
    return false;
  }
 
  const char *sql = database_queries[DATABASE_QUERY_VerifySessionKey].sql;
 
  sqlite3_stmt *stmt = NULL;
  if (ascii_otel_sqlite_prepare(db, sql, &stmt) != SQLITE_OK) {
    return false;
  }
 
  if ((sqlite3_bind_text(stmt, sqlite3_bind_parameter_index(stmt, ":session_string"), session_string, -1,
                         SQLITE_STATIC) != SQLITE_OK) ||
      (sqlite3_bind_blob(stmt, sqlite3_bind_parameter_index(stmt, ":identity_pubkey"), identity_pubkey, 32,
                         SQLITE_STATIC) != SQLITE_OK)) {
    sqlite3_finalize(stmt);
    log_error("Failed to bind SQLite query parameters");
    return false;
  }
 
  bool valid = (sqlite3_step(stmt) == SQLITE_ROW);
  sqlite3_finalize(stmt);
 
  return valid;
}

References ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), DATABASE_QUERY_VerifySessionKey, ED25519_PUBLIC_KEY_SIZE, log_error, and valid.

database_stats_session_count()

asciichat_error_t database_stats_session_count	(	sqlite3 *	db,
		int64_t *	count_out )

Get total number of active sessions.

Parameters

db	Database handle
count_out	Output: number of active sessions

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 1532 of file discovery/database.c.

                                                                                {
  ASCII_OTEL_SCOPE(DATABASE_SESSION_COUNT);
  if (!db || !count_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "db or count_out is NULL");
  }
 
  const char *query = database_queries[DATABASE_QUERY_CountSessions].sql;
  sqlite3_stmt *stmt;
  int rc = ascii_otel_sqlite_prepare(db, query, &stmt);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    return SET_ERRNO(ERROR_CONFIG, "Failed to prepare statement: %s", sqlite3_errmsg(db));
  }
 
  time_t now = time(NULL);
  if ((sqlite3_bind_int64(stmt, sqlite3_bind_parameter_index(stmt, ":now"), (sqlite3_int64)now) != SQLITE_OK)) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
  }
 
  int64_t count = 0;
  rc = sqlite3_step(stmt);
  if (rc == SQLITE_DONE && !sqlite3_stmt_readonly(stmt))
    ascii_otel_metric(ASCII_OTEL_METRIC_DB_ROWS, sqlite3_changes(db));
  if (rc == SQLITE_ROW) {
    count = sqlite3_column_int64(stmt, 0);
  } else if (rc != SQLITE_DONE) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_CONFIG, "Failed to execute query: %s", sqlite3_errmsg(db));
  }
 
  sqlite3_finalize(stmt);
  *count_out = count;
 
  log_debug("Active session count: %lld", (long long)count);
  return ASCIICHAT_OK;
}

References ascii_otel_metric(), ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_CountSessions, ERROR_CONFIG, ERROR_INVALID_PARAM, log_debug, and SET_ERRNO.

database_stats_snapshot()

asciichat_error_t database_stats_snapshot	(	sqlite3 *	db,
		database_session_stats_t *	rows,
		size_t	capacity,
		size_t *	row_count,
		uint64_t *	sessions,
		uint64_t *	participants )

Definition at line 1604 of file discovery/database.c.

                                                                                                         {
  ASCII_OTEL_SCOPE(DATABASE_STATS_SNAPSHOT);
  if (!db || (!rows && capacity) || !row_count || !sessions || !participants)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid database stats snapshot");
  *row_count = 0;
  *sessions = *participants = 0;
  sqlite3_stmt *stmt = NULL;
  const char *sql = database_queries[DATABASE_QUERY_GetStatsSnapshot].sql;
  if (ascii_otel_sqlite_prepare(db, sql, &stmt) != SQLITE_OK)
    return SET_ERRNO(ERROR_CONFIG, "Cannot query active session statistics");
  if ((sqlite3_bind_int64(stmt, sqlite3_bind_parameter_index(stmt, ":now"),
                          (sqlite3_int64)(time_get_realtime_ns() / NS_PER_MS_INT)) != SQLITE_OK)) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_CONFIG, "Failed to bind SQLite query parameters");
  }
  int result;
  while ((result = sqlite3_step(stmt)) == SQLITE_ROW) {
    (*sessions)++;
    int count = sqlite3_column_int(stmt, 1);
    if (count > 0)
      *participants += (uint64_t)count;
    if (*row_count < capacity) {
      database_session_stats_t *row = &rows[(*row_count)++];
      snprintf(row->session_string, sizeof(row->session_string), "%s", (const char *)sqlite3_column_text(stmt, 0));
      row->participants = count > 0 ? (uint32_t)count : 0;
      row->host_ready = sqlite3_column_int(stmt, 2) != 0;
      row->migrating = sqlite3_column_int(stmt, 3) != 0;
    }
  }
  sqlite3_finalize(stmt);
  if (result != SQLITE_DONE)
    return SET_ERRNO(ERROR_CONFIG, "Active session statistics query failed");
  stats_gauge_set(stats_runtime_scope(), STATS_GAUGE_SESSIONS_ACTIVE, *sessions);
  stats_gauge_set(stats_runtime_scope(), STATS_GAUGE_PARTICIPANTS_ACTIVE, *participants);
  return ASCIICHAT_OK;
}

References ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_GetStatsSnapshot, ERROR_CONFIG, ERROR_INVALID_PARAM, database_session_stats_t::host_ready, database_session_stats_t::migrating, NS_PER_MS_INT, database_session_stats_t::participants, database_session_stats_t::session_string, SET_ERRNO, STATS_GAUGE_PARTICIPANTS_ACTIVE, STATS_GAUGE_SESSIONS_ACTIVE, stats_gauge_set(), and stats_runtime_scope().

database_stats_unique_clients()

asciichat_error_t database_stats_unique_clients	(	sqlite3 *	db,
		int64_t *	count_out )

Get total number of unique clients/participants.

Parameters

db	Database handle
count_out	Output: number of unique participants

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 1571 of file discovery/database.c.

                                                                                 {
  ASCII_OTEL_SCOPE(DATABASE_UNIQUE_CLIENTS);
  if (!db || !count_out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "db or count_out is NULL");
  }
 
  const char *query = database_queries[DATABASE_QUERY_CountUniqueClients].sql;
  sqlite3_stmt *stmt;
  int rc = ascii_otel_sqlite_prepare(db, query, &stmt);
  if (rc != SQLITE_OK) {
    if (rc == SQLITE_BUSY || rc == SQLITE_LOCKED)
      ascii_otel_metric(ASCII_OTEL_METRIC_DB_BUSY, 1);
    return SET_ERRNO(ERROR_CONFIG, "Failed to prepare statement: %s", sqlite3_errmsg(db));
  }
 
  int64_t count = 0;
  rc = sqlite3_step(stmt);
  if (rc == SQLITE_DONE && !sqlite3_stmt_readonly(stmt))
    ascii_otel_metric(ASCII_OTEL_METRIC_DB_ROWS, sqlite3_changes(db));
  if (rc == SQLITE_ROW) {
    count = sqlite3_column_int64(stmt, 0);
  } else if (rc != SQLITE_DONE) {
    sqlite3_finalize(stmt);
    return SET_ERRNO(ERROR_CONFIG, "Failed to execute query: %s", sqlite3_errmsg(db));
  }
 
  sqlite3_finalize(stmt);
  *count_out = count;
 
  log_debug("Unique clients count: %lld", (long long)count);
  return ASCIICHAT_OK;
}

References ascii_otel_metric(), ASCII_OTEL_SCOPE, ascii_otel_sqlite_prepare(), ASCIICHAT_OK, DATABASE_QUERY_CountUniqueClients, ERROR_CONFIG, ERROR_INVALID_PARAM, log_debug, and SET_ERRNO.