5.9 KiB

Raw Permalink Blame History

NOSTR WebSocket Library Export Guide

This guide explains how to use the NOSTR WebSocket library in other C projects.

Library Structure

The NOSTR WebSocket library consists of these key files for export:

Core Files (Required)

nostr_websocket_tls.h - Header with all function declarations and constants
nostr_websocket_openssl.c - Main implementation using OpenSSL for SSL/TLS
../cjson/cJSON.h and ../cjson/cJSON.c - JSON parsing (lightweight)

Dependencies

OpenSSL - For SSL/TLS support (wss:// connections) - libssl, libcrypto
Standard C libraries - socket, networking, etc.

Quick Integration

1. Copy Files to Your Project

# Copy the library files
cp nostr_websocket_tls.h your_project/
cp nostr_websocket_openssl.c your_project/
cp ../cjson/cJSON.h your_project/
cp ../cjson/cJSON.c your_project/

2. Install OpenSSL Dependency

# Ubuntu/Debian
sudo apt-get install libssl-dev

# CentOS/RHEL/Fedora
sudo yum install openssl-devel
# or
sudo dnf install openssl-devel

# macOS (via Homebrew)
brew install openssl

3. Compile Your Project

gcc -o my_nostr_app my_app.c nostr_websocket_openssl.c cJSON.c \
    -lssl -lcrypto -lm

Basic Usage Example

#include "nostr_websocket_tls.h"
#include "cJSON.h"
#include <stdio.h>

int main() {
    // Connect to relay
    nostr_ws_client_t* client = nostr_ws_connect("wss://relay.damus.io");
    if (!client) {
        printf("Failed to connect\n");
        return 1;
    }
    
    // Create subscription filter
    cJSON* filter = cJSON_CreateObject();
    cJSON* kinds = cJSON_CreateArray();
    cJSON_AddItemToArray(kinds, cJSON_CreateNumber(1)); // Text notes
    cJSON_AddItemToObject(filter, "kinds", kinds);
    cJSON_AddItemToObject(filter, "limit", cJSON_CreateNumber(10));
    
    // Send REQ message
    nostr_relay_send_req(client, "my-sub", filter);
    
    // Receive messages
    char buffer[8192];
    while (1) {
        int len = nostr_ws_receive(client, buffer, sizeof(buffer), 1000);
        if (len > 0) {
            printf("Received: %s\n", buffer);
            
            // Parse message type
            char* msg_type;
            cJSON* parsed;
            if (nostr_parse_relay_message(buffer, &msg_type, &parsed) == 0) {
                if (strcmp(msg_type, "EOSE") == 0) {
                    printf("End of subscription\n");
                    free(msg_type);
                    cJSON_Delete(parsed);
                    break;
                }
                free(msg_type);
                cJSON_Delete(parsed);
            }
        }
    }
    
    // Cleanup
    nostr_ws_close(client);
    cJSON_Delete(filter);
    return 0;
}

API Reference

Connection Management

nostr_ws_connect(url) - Connect to relay (ws:// or wss://)
nostr_ws_close(client) - Close connection and cleanup
nostr_ws_get_state(client) - Get connection state

Messaging

nostr_ws_send_text(client, message) - Send raw text message
nostr_ws_receive(client, buffer, size, timeout) - Receive message
nostr_ws_ping(client) - Send ping frame

NOSTR Protocol Helpers

nostr_relay_send_req(client, sub_id, filters) - Send REQ message
nostr_relay_send_event(client, event) - Send EVENT message
nostr_relay_send_close(client, sub_id) - Send CLOSE message
nostr_parse_relay_message(message, type, json) - Parse relay message

Error Handling

nostr_ws_strerror(error_code) - Get error string
Return codes: NOSTR_WS_SUCCESS, NOSTR_WS_ERROR_*

Advanced Configuration

Custom Timeouts

nostr_ws_set_timeout(client, 30000); // 30 second timeout

Multiple Transports

The library supports both TCP (ws://) and TLS (wss://) automatically based on URL scheme.

Cross-Platform Notes

Linux/Unix

Works out of the box with standard development tools
Requires: gcc, OpenSSL development headers (libssl-dev)

Windows Support

Would need Winsock2 adaptations in transport layer
OpenSSL is widely available on Windows

Embedded Systems

Lightweight design suitable for embedded use
Memory usage: ~4KB per client + message buffers
No dynamic allocations in hot paths
OpenSSL provides optimized implementations for various architectures

Library Design Benefits

Modular Architecture

Clean separation between WebSocket protocol and NOSTR logic
Transport layer abstraction (easy to add new transports)
No global state - multiple clients supported

Performance Optimized

Minimal memory allocations
Efficient SSL buffer handling
Fast WebSocket frame parsing

Production Ready

Proper error handling throughout
Resource cleanup on all code paths
Thread-safe design (no shared state)

Migration from Other Libraries

From libwebsockets

// Old libwebsockets code:
// lws_client_connect_info info = {...};
// wsi = lws_client_connect(context, &info);

// New NOSTR WebSocket library:
client = nostr_ws_connect("wss://relay.example.com");

From raw sockets

The library handles all WebSocket protocol details, SSL/TLS, and NOSTR message formatting automatically.

Support

Based on WebSocket RFC 6455
Implements NOSTR WebSocket conventions
SSL/TLS via industry-standard OpenSSL library
Tested with major NOSTR relays

Migration Notes

If you were previously using the mbedTLS version of this library:

Code Changes Required

Update #include to reference nostr_websocket_openssl.c instead of nostr_websocket_mbedtls.c
Change linking flags from -lmbedtls -lmbedx509 -lmbedcrypto to -lssl -lcrypto
Install OpenSSL development headers instead of mbedTLS

API Compatibility

All function signatures remain identical
No changes to your application code required
Same performance characteristics and behavior

This library provides a clean, efficient way to integrate NOSTR WebSocket functionality into any C project with minimal dependencies and maximum portability.

5.9 KiB Raw Permalink Blame History