status.h File Reference

📊 Status screen display and management for server/discovery service modes More...

Go to the source code of this file.

Data Structures
struct	ui_status_t
	Status information for server/discovery service modes. More...

Macros
#define	TUI_STATUS_SESSION_STRING_BUFFER_SIZE   64
#define	TUI_STATUS_IPV4_ADDRESS_BUFFER_SIZE   256
#define	TUI_STATUS_IPV6_ADDRESS_BUFFER_SIZE   256

Functions
void	ui_status_render_header (frame_buffer_t *buffer, terminal_size_t size, void *status)
const char *	ui_status_log_controls (void)
asciichat_error_t	ui_status_gather (network_server_t *server, const char *session_string, const char *ipv4_address, const char *ipv6_address, uint16_t port, time_t start_time, const char *mode_name, bool session_is_mdns_only, ui_status_t *out_status)
	Gather current status information.
void	ui_status_display (const ui_status_t *status)
	Display status screen.
bool	ui_status_display_interactive (const ui_status_t *status)
	Display status screen with interactive keyboard support.
void	ui_status_update (network_server_t *server, const char *session_string, const char *ipv4_address, const char *ipv6_address, uint16_t port, time_t start_time, const char *mode_name, bool session_is_mdns_only, uint64_t *last_update_ns)
	Periodically update status display with live logs at FPS rate.
void	ui_status_log_init (void)
	Initialize status screen log capture system.
void	ui_status_log_destroy (void)
	Cleanup status screen log capture system.
void	ui_status_log_append (const char *message)
	Append a log message to status screen buffer.
void	ui_status_log_clear (void)
	Clear all log messages from status screen buffer.

Detailed Description

📊 Status screen display and management for server/discovery service modes

Manages periodic display of status information including:

• Session string (memorable 3-word string)
• Bind addresses (IPv4 and IPv6)
• Connected client/server count
• Server uptime

The status screen is updated periodically from the TCP server accept loop via callback and can be disabled with –no-status-screen flag.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

February 2026

Definition in file status.h.

Macro Definition Documentation

TUI_STATUS_IPV4_ADDRESS_BUFFER_SIZE

#define TUI_STATUS_IPV4_ADDRESS_BUFFER_SIZE   256

Definition at line 23 of file status.h.

TUI_STATUS_IPV6_ADDRESS_BUFFER_SIZE

#define TUI_STATUS_IPV6_ADDRESS_BUFFER_SIZE   256

Definition at line 24 of file status.h.

TUI_STATUS_SESSION_STRING_BUFFER_SIZE

#define TUI_STATUS_SESSION_STRING_BUFFER_SIZE   64

Definition at line 22 of file status.h.

Function Documentation

ui_status_display()

void ui_status_display

(

const ui_status_t *

status

)

Display status screen.

Outputs formatted status to stdout. Uses ANSI escape codes for clean display that doesn't interfere with logging output.

Parameters

status

Status information

Definition at line 106 of file status.c.

                                                  {
  if (!status) {
    return;
  }
 
  // Only render the status screen if:
  // 1. Terminal is interactive (default behavior), OR
  // 2. User explicitly set --status-screen on command line (force it regardless of terminal)
  // In non-interactive mode without explicit flag, logs flow to stdout/stderr normally
  if (!terminal_is_interactive() && !GET_OPTION(status_screen_explicitly_set)) {
    return;
  }
 
  // Redirect status screen to stderr when stdout is piped (not a TTY).
  // This keeps stdout clean for frame data while status goes to stderr.
  // Uses platform_isatty() so non-desktop platforms (iOS, WASM) can override.
  if (!platform_isatty(STDOUT_FILENO)) {
    terminal_screen_set_output_fd(STDERR_FILENO);
  }
 
  // If --grep pattern was provided, enter interactive grep mode with it pre-populated
  // Only do this once (check if not already entering)
  static bool grep_mode_entered = false;
  if (!grep_mode_entered && grep_get_last_pattern() && grep_get_last_pattern()[0] != '\0') {
    log_search_enter_mode();
    grep_mode_entered = true;
  }
 
  // Use terminal_screen abstraction for rendering
  ui_status_t rendered = *status;
  if (!rendered.detail)
    rendered.detail = ui_status_log_controls();
  terminal_screen_config_t config = {
      .screen = UI_SCREEN_STATUS,
      .output_fd = platform_isatty(STDOUT_FILENO) ? STDOUT_FILENO : STDERR_FILENO,
      .user_data_size = sizeof(*status),
      .minimum_cols = 20,
      .fixed_header_lines = 4,
      .render_header = ui_status_render_header,
      .user_data = &rendered,
      .show_logs = true,
  };
 
  terminal_screen_render(&config);
}

References ui_status_t::detail, GET_OPTION, grep_get_last_pattern(), log_search_enter_mode(), terminal_screen_render(), terminal_screen_set_output_fd(), UI_SCREEN_STATUS, ui_status_log_controls(), and ui_status_render_header().

Referenced by ui_status_update().

ui_status_display_interactive()

bool ui_status_display_interactive

(

const ui_status_t *

status

)

Display status screen with interactive keyboard support.

Renders status screen and handles keyboard input:

• Escape cancels grep if active, otherwise exits status screen
• Other keys handled by interactive grep if active

Parameters

status

Status information

Returns

true if status screen should continue, false if user pressed Escape to exit

Display status screen with interactive keyboard support.

Definition at line 156 of file status.c.

                                                              {
  if (!status) {
    return true;
  }
 
  // Only render the status screen if:
  // 1. Terminal is interactive (default behavior), OR
  // 2. User explicitly set --status-screen on command line (force it regardless of terminal)
  // In non-interactive mode without explicit flag, logs flow to stdout/stderr normally
  if (!terminal_is_interactive() && !GET_OPTION(status_screen_explicitly_set)) {
    return true;
  }
 
  // If --grep pattern was provided, enter interactive grep mode with it pre-populated
  static bool grep_mode_entered = false;
  if (!grep_mode_entered && grep_get_last_pattern() && grep_get_last_pattern()[0] != '\0') {
    log_search_enter_mode();
    grep_mode_entered = true;
  }
 
  // Status may use stderr when stdout is redirected. Check the descriptors
  // used by this screen instead of requiring stdout to be a terminal.
  int output_fd = platform_isatty(STDOUT_FILENO) ? STDOUT_FILENO : STDERR_FILENO;
  bool keyboard_enabled = false;
  if (platform_isatty(STDIN_FILENO) && platform_isatty(output_fd) && keyboard_init() == ASCIICHAT_OK) {
    keyboard_enabled = true;
  }
 
  // Use terminal_screen abstraction for rendering
  ui_status_t rendered = *status;
  if (!rendered.detail)
    rendered.detail = ui_status_log_controls();
  terminal_screen_config_t config = {
      .screen = UI_SCREEN_STATUS,
      .output_fd = output_fd,
      .user_data_size = sizeof(*status),
      .minimum_cols = 20,
      .fixed_header_lines = 4,
      .render_header = ui_status_render_header,
      .user_data = &rendered,
      .show_logs = true,
  };
 
  terminal_screen_render(&config);
 
  // Poll keyboard for Escape to exit or for interactive grep
  bool should_exit_status = false;
  if (keyboard_enabled) {
    keyboard_key_t key = ui_input_read_key(UI_SCREEN_STATUS);
    if (ui_errno_stacks_handle_key(key)) {
      return true;
    } else if (key == KEY_BACKTICK) {
      ui_errno_stacks_toggle();
    } else if (key == KEY_ESCAPE) {
      // Escape key: cancel grep if active, otherwise exit status screen
      if (log_search_is_active()) {
        log_search_exit_mode(false); // Cancel grep without applying
      } else {
        should_exit_status = true; // Exit status screen
      }
    } else if (key != KEY_NONE && log_search_should_handle(key)) {
      log_search_handle_key(key);
    }
  }
 
  // Keyboard ownership lasts until session shutdown, including between status frames.
 
  return !should_exit_status; // Return false if user wants to exit
}

References ASCIICHAT_OK, ui_status_t::detail, GET_OPTION, grep_get_last_pattern(), KEY_BACKTICK, KEY_ESCAPE, KEY_NONE, keyboard_init(), log_search_enter_mode(), log_search_exit_mode(), log_search_handle_key(), log_search_is_active(), log_search_should_handle(), terminal_screen_render(), ui_errno_stacks_handle_key(), ui_errno_stacks_toggle(), ui_input_read_key(), UI_SCREEN_STATUS, ui_status_log_controls(), and ui_status_render_header().

ui_status_gather()

asciichat_error_t ui_status_gather	(	network_server_t *	server,
		const char *	session_string,
		const char *	ipv4_address,
		const char *	ipv6_address,
		uint16_t	port,
		time_t	start_time,
		const char *	mode_name,
		bool	session_is_mdns_only,
		ui_status_t *	out_status )

Gather current status information.

Collects current status information including connected count, bind addresses, and session string.

Parameters

	server	Initialized TCP server structure
	session_string	Memorable session string
	ipv4_address	IPv4 bind address (can be NULL or empty)
	ipv6_address	IPv6 bind address (can be NULL or empty)
	port	TCP listen port
	start_time	Server start time
	mode_name	Mode name for display (e.g., "Server")
	session_is_mdns_only	Whether session is mDNS-only or ACDS
[out]	out_status	Output status structure

Returns

ASCIICHAT_OK on success

Definition at line 71 of file status.c.

                                                                                       {
  if (!server || !out_status || !mode_name) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  memset(out_status, 0, sizeof(*out_status));
 
  // Copy session string
  if (session_string) {
    SAFE_STRNCPY(out_status->session_string, session_string, sizeof(out_status->session_string));
  }
 
  // Format IPv4 address
  out_status->ipv4_bound = (ipv4_address && ipv4_address[0] != '\0');
  if (out_status->ipv4_bound) {
    snprintf(out_status->ipv4_address, sizeof(out_status->ipv4_address), "%s:%u", ipv4_address, port);
  }
 
  // Format IPv6 address
  out_status->ipv6_bound = (ipv6_address && ipv6_address[0] != '\0');
  if (out_status->ipv6_bound) {
    snprintf(out_status->ipv6_address, sizeof(out_status->ipv6_address), "[%s]:%u", ipv6_address, port);
  }
 
  out_status->port = port;
  out_status->start_time = start_time;
  out_status->mode_name = mode_name;
  out_status->session_is_mdns_only = session_is_mdns_only;
  out_status->connected_count = network_server_connection_count(server);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ui_status_t::connected_count, ERROR_INVALID_PARAM, ui_status_t::ipv4_address, ui_status_t::ipv4_bound, ui_status_t::ipv6_address, ui_status_t::ipv6_bound, ui_status_t::mode_name, network_server_connection_count(), ui_status_t::port, SAFE_STRNCPY, ui_status_t::session_is_mdns_only, ui_status_t::session_string, SET_ERRNO, and ui_status_t::start_time.

Referenced by ui_status_update().

ui_status_log_append()

void ui_status_log_append

(

const char *

message

)

Append a log message to status screen buffer.

Thread-safe. Called from logging system to capture messages.

Parameters

message

Log message text (already formatted with colors)

ui_status_log_clear()

void ui_status_log_clear

(

void

)

Clear all log messages from status screen buffer.

Thread-safe. Resets buffer to empty state, discarding all captured logs. Used to clear initialization logs before status screen starts rendering.

Definition at line 62 of file status.c.

                               {
  // Delegate to terminal_screen log abstraction
  terminal_screen_log_clear();
}

References terminal_screen_log_clear().

ui_status_log_controls()

const char * ui_status_log_controls

(

void

)

Shared controls line shown by every interactive log viewer.

Definition at line 34 of file status.c.

                                         {
  static _Thread_local char controls[512];
  snprintf(controls, sizeof(controls),
           "%s / %s: close | %s: search logs | %s: keyboard controls | %s / %s: one log | "
           "%s / %s: page | %s / %s: oldest/newest",
           colored_string(LOG_COLOR_WARN, "q"), colored_string(LOG_COLOR_WARN, "Esc"), "/",
           colored_string(LOG_COLOR_WARN, "?"), colored_string(LOG_COLOR_WARN, "Up"),
           colored_string(LOG_COLOR_WARN, "Down"), colored_string(LOG_COLOR_WARN, "PageUp"),
           colored_string(LOG_COLOR_WARN, "PageDown"), colored_string(LOG_COLOR_WARN, "Home"),
           colored_string(LOG_COLOR_WARN, "End"));
  return controls;
}

References colored_string(), and LOG_COLOR_WARN.

Referenced by ui_session_logs_render(), ui_status_display(), and ui_status_display_interactive().

ui_status_log_destroy()

void ui_status_log_destroy

(

void

)

Cleanup status screen log capture system.

Call when shutting down. Frees internal log buffer.

Definition at line 55 of file status.c.

                                 {
  // Unregister from logger before destroying
  log_clear_session_log_buffer();
  // Cleanup the shared terminal screen log buffer
  terminal_screen_log_destroy();
}

References log_clear_session_log_buffer(), and terminal_screen_log_destroy().

Referenced by session_server_like_run().

ui_status_log_init()

void ui_status_log_init

(

void

)

Initialize status screen log capture system.

Must be called before using status screen. Creates internal log buffer.

Definition at line 47 of file status.c.

                              {
  // Initialize the shared terminal screen log buffer
  session_log_buffer_t *buf = terminal_screen_log_init();
  if (buf) {
    log_set_session_log_buffer(buf);
  }
}

References log_set_session_log_buffer(), and terminal_screen_log_init().

Referenced by session_server_like_run().

ui_status_render_header()

void ui_status_render_header	(	frame_buffer_t *	buf,
		terminal_size_t	term_size,
		void *	user_data )

The same four-line status header in every host.

Server status presentation shared by native and browser sessions.

Definition at line 34 of file session_status.c.

                                                                                              {
  const ui_status_t *status = (const ui_status_t *)user_data;
  if (!status) {
    return;
  }
 
  // Calculate uptime
  time_t now = time(NULL);
  time_t uptime_secs = now - status->start_time;
  int uptime_hours = uptime_secs / SEC_PER_HOUR;
  int uptime_mins = (uptime_secs % SEC_PER_HOUR) / SEC_PER_MIN;
  int uptime_secs_rem = uptime_secs % 60;
 
  // Line 1: Top border
  bool unicode = terminal_should_use_utf8(GET_OPTION(force_utf8));
  bool colors = !GET_OPTION(strip_ansi) &&
                terminal_should_color_output(frame_buffer_get_screen_output_fd(), options_terminal_settings());
  frame_buffer_render_divider(buf, term_size.cols - 1, unicode, colors);
 
  // The bundled browser font does not contain the emoji used in native status titles.
#ifdef __EMSCRIPTEN__
  bool status_icons = false;
#else
  bool status_icons = unicode;
#endif
 
  // Line 2: Title + Stats (centered)
  char status_line[TUI_SESSION_STATUS_STATUS_LINE_BUFFER_SIZE];
  char status_line_truncated[TUI_SESSION_STATUS_STATUS_LINE_TRUNCATED_BUFFER_SIZE];
  char status_line_colored[TUI_SESSION_STATUS_STATUS_LINE_COLORED_BUFFER_SIZE];
  char uptime_str[TUI_SESSION_STATUS_UPTIME_BUFFER_SIZE];
  format_uptime_hms(uptime_hours, uptime_mins, uptime_secs_rem, uptime_str, sizeof(uptime_str));
  bool generic_log_header = status->detail && strstr(status->detail, "keyboard controls") != NULL;
  if (generic_log_header)
    snprintf(status_line, sizeof(status_line), status_icons ? "ascii-chat | ⏱️ %s" : "ascii-chat | uptime %s",
             uptime_str);
  else if (status->detail)
    snprintf(status_line, sizeof(status_line), status_icons ? "ascii-chat %s | ⏱️ %s" : "ascii-chat %s | uptime %s",
             status->mode_name, uptime_str);
  else
    snprintf(status_line, sizeof(status_line),
             status_icons ? "ascii-chat %s | 👥 %zu | ⏱️ %s" : "ascii-chat %s | clients %zu | uptime %s",
             status->mode_name, status->connected_count, uptime_str);
 
  // Truncate if needed (ANSI-aware)
  truncate_with_ellipsis(status_line, status_line_truncated, sizeof(status_line_truncated), term_size.cols - 2);
  snprintf(status_line_colored, sizeof(status_line_colored), "\033[1m%s\033[0m",
           colored_string(LOG_COLOR_DEBUG, status_line_truncated));
 
  int padding = display_center_horizontal(status_line_truncated, term_size.cols);
  for (int i = 0; i < padding; i++) {
    frame_buffer_printf(buf, " ");
  }
  frame_buffer_printf(buf, "%s\n", status_line_colored);
 
  // Line 3: Session + Addresses (centered)
  char addr_line[TUI_SESSION_STATUS_ADDR_LINE_BUFFER_SIZE] = {0};
  char addr_line_truncated[TUI_SESSION_STATUS_ADDR_LINE_TRUNCATED_BUFFER_SIZE];
  int pos = 0;
  if (status->session_string[0] != '\0') {
    pos += snprintf(addr_line + pos, sizeof(addr_line) - pos, unicode ? "🔗 %s" : "Session %s", status->session_string);
  }
  if (status->ipv4_bound && pos < (int)sizeof(addr_line) - 30) {
    if (pos > 0) {
      pos += snprintf(addr_line + pos, sizeof(addr_line) - pos, " | ");
    }
    // Extract IP and get type
    char ipv4_only[TUI_SESSION_STATUS_IPV4_ONLY_BUFFER_SIZE];
    if (extract_ip_from_address(status->ipv4_address, ipv4_only, sizeof(ipv4_only)) == 0) {
      const char *type = get_ip_type_string(ipv4_only);
      pos += snprintf(addr_line + pos, sizeof(addr_line) - pos, "%s (%s)", status->ipv4_address, type);
    } else {
      pos += snprintf(addr_line + pos, sizeof(addr_line) - pos, "%s", status->ipv4_address);
    }
  }
  if (status->ipv6_bound && pos < (int)sizeof(addr_line) - 30) {
    if (pos > 0) {
      pos += snprintf(addr_line + pos, sizeof(addr_line) - pos, " | ");
    }
    // Extract IP and get type
    char ipv6_only[TUI_SESSION_STATUS_IPV6_ONLY_BUFFER_SIZE];
    if (extract_ip_from_address(status->ipv6_address, ipv6_only, sizeof(ipv6_only)) == 0) {
      const char *type = get_ip_type_string(ipv6_only);
      snprintf(addr_line + pos, sizeof(addr_line) - pos, "%s (%s)", status->ipv6_address, type);
    } else {
      snprintf(addr_line + pos, sizeof(addr_line) - pos, "%s", status->ipv6_address);
    }
  }
 
  if (status->detail)
    SAFE_STRNCPY(addr_line, status->detail, sizeof(addr_line));
 
  // Truncate if needed (ANSI-aware)
  truncate_with_ellipsis(addr_line, addr_line_truncated, sizeof(addr_line_truncated), term_size.cols - 2);
 
  int addr_padding = display_center_horizontal(addr_line_truncated, term_size.cols);
  for (int i = 0; i < addr_padding; i++) {
    frame_buffer_printf(buf, " ");
  }
  frame_buffer_printf(buf, "%s\n", addr_line_truncated);
 
  // Line 4: Bottom border
  frame_buffer_render_divider(buf, term_size.cols - 1, unicode, colors);
}

References colored_string(), colors, ui_status_t::connected_count, ui_status_t::detail, display_center_horizontal(), extract_ip_from_address(), format_uptime_hms(), frame_buffer_get_screen_output_fd(), frame_buffer_printf(), frame_buffer_render_divider(), get_ip_type_string(), GET_OPTION, ui_status_t::ipv4_address, ui_status_t::ipv4_bound, ui_status_t::ipv6_address, ui_status_t::ipv6_bound, LOG_COLOR_DEBUG, ui_status_t::mode_name, options_terminal_settings, SAFE_STRNCPY, SEC_PER_HOUR, SEC_PER_MIN, ui_status_t::session_string, ui_status_t::start_time, truncate_with_ellipsis(), TUI_SESSION_STATUS_ADDR_LINE_BUFFER_SIZE, TUI_SESSION_STATUS_ADDR_LINE_TRUNCATED_BUFFER_SIZE, TUI_SESSION_STATUS_IPV4_ONLY_BUFFER_SIZE, TUI_SESSION_STATUS_IPV6_ONLY_BUFFER_SIZE, TUI_SESSION_STATUS_STATUS_LINE_BUFFER_SIZE, TUI_SESSION_STATUS_STATUS_LINE_COLORED_BUFFER_SIZE, TUI_SESSION_STATUS_STATUS_LINE_TRUNCATED_BUFFER_SIZE, and TUI_SESSION_STATUS_UPTIME_BUFFER_SIZE.

Referenced by ui_session_logs_render(), ui_status_display(), and ui_status_display_interactive().

ui_status_update()

void ui_status_update	(	network_server_t *	server,
		const char *	session_string,
		const char *	ipv4_address,
		const char *	ipv6_address,
		uint16_t	port,
		time_t	start_time,
		const char *	mode_name,
		bool	session_is_mdns_only,
		uint64_t *	last_update_ns )

Periodically update status display with live logs at FPS rate.

Gathers and displays status with live log feed if enough time has passed since last update (based on GET_OPTION(fps)). Updates at 60 Hz by default.

Parameters

	server	Initialized TCP server structure
	session_string	Memorable session string
	ipv4_address	IPv4 bind address (can be NULL or empty)
	ipv6_address	IPv6 bind address (can be NULL or empty)
	port	TCP listen port
	start_time	Server start time
	mode_name	Mode name for display (e.g., "Server")
	session_is_mdns_only	Whether session is mDNS-only or ACDS
[in,out]	last_update_ns	Last update time in microseconds (from platform_get_monotonic_time_us)

Definition at line 226 of file status.c.

                                                                           {
  if (!server || !last_update_ns) {
    return;
  }
 
  // Update at FPS rate (60 Hz = 16.67ms by default)
  uint32_t fps = GET_OPTION(fps);
  if (fps == 0) {
    fps = 60; // Default
  }
 
  // Calculate frame interval in microseconds
  uint64_t frame_interval_us = US_PER_SEC_INT / fps;
 
  // Get current time in microseconds using platform abstraction
  uint64_t now_us = platform_get_monotonic_time_us();
 
  // Check if enough time has passed
  if ((now_us - *last_update_ns) < frame_interval_us) {
    return; // Too soon, skip frame
  }
 
  ui_status_t status;
  if (ui_status_gather(server, session_string, ipv4_address, ipv6_address, port, start_time, mode_name,
                       session_is_mdns_only, &status) == ASCIICHAT_OK) {
    ui_status_display(&status);
    *last_update_ns = now_us;
  }
}

References ASCIICHAT_OK, GET_OPTION, platform_get_monotonic_time_us(), ui_status_display(), ui_status_gather(), and US_PER_SEC_INT.