74a4dc2533
- Add cli_options_t structure for extensible command line options - Implement port override in create_default_config_event() - Update main() with robust CLI parsing and validation - Add comprehensive help text documenting first-time only behavior - Ensure CLI options only affect initial configuration event creation - Maintain event-based configuration architecture for ongoing operation - Include comprehensive error handling and input validation - Add documentation in CLI_PORT_OVERRIDE_IMPLEMENTATION.md Tested: First-time startup uses CLI port, subsequent startups use database config
145 lines
4.7 KiB
Markdown
145 lines
4.7 KiB
Markdown
# 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
|
|
|
|
```c
|
|
typedef struct {
|
|
int port_override; // -1 = not set, >0 = port value
|
|
// Future CLI options can be added here
|
|
} cli_options_t;
|
|
```
|
|
|
|
### Command Line Usage
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
./c_relay_x86 -p 9090
|
|
```
|
|
**Result**: ✅ Relay starts on port 9090, configuration stored in database
|
|
|
|
### Test 2: Subsequent startup ignores CLI options
|
|
```bash
|
|
./c_relay_x86 -p 7777
|
|
```
|
|
**Result**: ✅ Relay starts on port 9090 (from database), ignores `-p 7777`
|
|
|
|
### Test 3: Error handling
|
|
```bash
|
|
./c_relay_x86 -p invalid_port
|
|
./c_relay_x86 -p
|
|
```
|
|
**Result**: ✅ Proper error messages and help text displayed
|
|
|
|
### Test 4: Help text
|
|
```bash
|
|
./c_relay_x86 --help
|
|
```
|
|
**Result**: ✅ Displays updated help with `-p, --port PORT` option
|
|
|
|
## Database Verification
|
|
|
|
The port setting is correctly stored in the database:
|
|
```sql
|
|
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:
|
|
|
|
```c
|
|
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. |