c-relay/CLI_PORT_OVERRIDE_IMPLEMENTATION.md

CLI Port Override Implementation

Overview

This document describes the implementation of the -p <port> command line option for the C Nostr Relay, which allows overriding the default relay port during first-time startup only.

Design Principles

1. First-time startup only: Command line options only affect the initial configuration event creation
2. Event-based persistence: After first startup, all configuration is managed through database events
3. Proper encapsulation: All configuration logic is contained within config.c
4. Extensible design: The CLI options structure can easily accommodate future command line options

Implementation Details

Files Modified

src/config.h

• Added cli_options_t structure to encapsulate command line options
• Updated first_time_startup_sequence() function signature

src/config.c

• Updated first_time_startup_sequence() to accept CLI options parameter
• Updated create_default_config_event() to accept CLI options parameter
• Implemented port override logic in DEFAULT_CONFIG_VALUES array processing

src/default_config_event.h

• Updated function signature for create_default_config_event()
• Added proper header include for cli_options_t definition

src/main.c

• Added command line parsing for -p <port> and --port <port>
• Updated help text to document the new option
• Added proper error handling for invalid port values
• Updated function call to pass CLI options to configuration system

CLI Options Structure

typedef struct {
    int port_override;  // -1 = not set, >0 = port value
    // Future CLI options can be added here
} cli_options_t;

Command Line Usage

# First-time startup with port override
./c_relay_x86 -p 9090
./c_relay_x86 --port 9090

# Show help (includes new option)
./c_relay_x86 --help

# Show version
./c_relay_x86 --version

Error Handling

The implementation includes robust error handling for:

• Missing port argument: ./c_relay_x86 -p
• Invalid port format: ./c_relay_x86 -p invalid_port
• Out-of-range ports: ./c_relay_x86 -p 0 or ./c_relay_x86 -p 99999

Behavior Verification

First-Time Startup

When no database exists:

1. Command line is parsed and -p <port> is processed
2. CLI options are passed to first_time_startup_sequence()
3. Port override is applied in create_default_config_event()
4. Configuration event is created with overridden port value
5. Relay starts on the specified port
6. Port setting is persisted in database for future startups

Subsequent Startups

When database already exists:

1. Command line is still parsed (for consistency)
2. Existing relay path is taken
3. Configuration is loaded from database events
4. CLI options are ignored
5. Relay starts on port from database configuration

Testing Results

Test 1: First-time startup with port override

./c_relay_x86 -p 9090

Result: ✅ Relay starts on port 9090, configuration stored in database

Test 2: Subsequent startup ignores CLI options

./c_relay_x86 -p 7777

Result: ✅ Relay starts on port 9090 (from database), ignores -p 7777

Test 3: Error handling

./c_relay_x86 -p invalid_port
./c_relay_x86 -p

Result: ✅ Proper error messages and help text displayed

Test 4: Help text

./c_relay_x86 --help

Result: ✅ Displays updated help with -p, --port PORT option

Database Verification

The port setting is correctly stored in the database:

SELECT json_extract(tags, '$') FROM events WHERE kind = 33334;

Shows the overridden port value in the configuration event tags.

Future Extensions

The cli_options_t structure is designed to be easily extended:

typedef struct {
    int port_override;        // -1 = not set, >0 = port value
    char* description_override; // Future: relay description override
    int max_connections_override; // Future: connection limit override
    // Add more options as needed
} cli_options_t;

Key Design Benefits

1. Separation of Concerns: Main function handles CLI parsing, config system handles application
2. First-time Only: Prevents confusion about configuration precedence
3. Event-based Architecture: Maintains consistency with the relay's event-based configuration system
4. Extensible: Easy to add new command line options in the future
5. Robust: Comprehensive error handling and validation
6. Documented: Clear help text explains behavior to users

Summary

The -p <port> command line option implementation successfully provides a way to override the default relay port during first-time startup while maintaining the event-based configuration architecture for ongoing operation. The implementation is robust, well-tested, and ready for production use.