nostr_core_lib/nostr_websocket

NOSTR WebSocket Library

A production-ready, lightweight WebSocket client library specifically designed for the NOSTR protocol. This library provides a clean C API for connecting to NOSTR relays over both TCP (ws://) and TLS (wss://) connections.

Features

• ✅ WebSocket RFC 6455 Compliant - Full WebSocket protocol implementation
• ✅ SSL/TLS Support - Secure wss:// connections via OpenSSL
• ✅ NOSTR Protocol - Built-in support for REQ, EVENT, CLOSE messages
• ✅ Production Ready - Optimized performance and error handling
• ✅ Lightweight - Minimal dependencies and memory footprint
• ✅ Cross-Platform - Linux/Unix support, Windows adaptable
• ✅ Thread Safe - No global state, multiple clients supported

Quick Start

1. Build the Test Program

make

2. Run the Test

make test
# or directly:
./test_5_events_clean

3. Basic Usage

#include "nostr_websocket_tls.h"

// Connect to a NOSTR relay
nostr_ws_client_t* client = nostr_ws_connect("wss://relay.damus.io");

// Create and send a subscription
cJSON* filter = cJSON_CreateObject();
cJSON_AddItemToObject(filter, "limit", cJSON_CreateNumber(10));
nostr_relay_send_req(client, "my-sub", filter);

// Receive messages
char buffer[8192];
int len = nostr_ws_receive(client, buffer, sizeof(buffer), 1000);
if (len > 0) {
    printf("Received: %s\n", buffer);
}

// Cleanup
nostr_ws_close(client);
cJSON_Delete(filter);

Library Structure

Core Components

• nostr_websocket_tls.h - Public API header
• nostr_websocket_openssl.c - Main implementation (OpenSSL backend)
• ../cjson/cJSON.h/c - JSON parsing support

Dependencies

• OpenSSL - For SSL/TLS support (libssl, libcrypto)
• Standard C libraries - POSIX sockets, etc.

Installation in Other Projects

See EXPORT_GUIDE.md for detailed instructions on integrating this library into your C projects.

API Reference

Connection Management

nostr_ws_client_t* nostr_ws_connect(const char* url);
int nostr_ws_close(nostr_ws_client_t* client);
nostr_ws_state_t nostr_ws_get_state(nostr_ws_client_t* client);

Messaging

int nostr_ws_send_text(nostr_ws_client_t* client, const char* message);
int nostr_ws_receive(nostr_ws_client_t* client, char* buffer, size_t size, int timeout_ms);
int nostr_ws_ping(nostr_ws_client_t* client);

NOSTR Protocol Helpers

int nostr_relay_send_req(nostr_ws_client_t* client, const char* sub_id, cJSON* filters);
int nostr_relay_send_event(nostr_ws_client_t* client, cJSON* event);
int nostr_relay_send_close(nostr_ws_client_t* client, const char* sub_id);
int nostr_parse_relay_message(const char* message, char** type, cJSON** json);

Error Handling

const char* nostr_ws_strerror(int error_code);

Performance Characteristics

• Memory Usage: ~4KB per client + message buffers
• Latency: Optimized SSL buffer handling, minimal delays
• Throughput: Efficient WebSocket frame parsing
• Scalability: Multiple concurrent clients supported

Tested Relays

This library has been successfully tested with:

• wss://relay.damus.io
• wss://nostr.mom
• wss://relay.nostr.band
• ws://localhost:7777 (local relays)

Build Options

make          # Build test programs
make test     # Run WebSocket test
make clean    # Clean build artifacts
make info     # Show library information
make help     # Show help

Development History

This library evolved from the experimental WebSocket implementation and represents the production-ready, stable version suitable for integration into other projects.

Key improvements made during development:

• Migrated from mbedTLS to OpenSSL - Better compatibility and performance
• Fixed critical WebSocket frame parsing bugs
• Optimized SSL/TLS performance
• Reduced memory allocations
• Enhanced error handling
• Added comprehensive documentation
• Improved build system integration

License

This library is part of the C NOSTR project and follows the same license terms.

Contributing

For issues, improvements, or questions about the NOSTR WebSocket library, please refer to the main project documentation.