5.2 KiB

Raw 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_mbedtls.c - Main implementation using mbedTLS for SSL/TLS
../cjson/cJSON.h and ../cjson/cJSON.c - JSON parsing (lightweight)

Dependencies

mbedTLS - For SSL/TLS support (wss:// connections)
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_mbedtls.c your_project/
cp ../cjson/cJSON.h your_project/
cp ../cjson/cJSON.c your_project/

2. Install mbedTLS Dependency

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

# Or build from source (see mbedTLS documentation)

3. Compile Your Project

gcc -o my_nostr_app my_app.c nostr_websocket_mbedtls.c cJSON.c \
    -lmbedtls -lmbedx509 -lmbedcrypto -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, mbedTLS development headers

Potential Windows Support

Would need Winsock2 adaptations in transport layer
mbedTLS is cross-platform compatible

Embedded Systems

Lightweight design suitable for embedded use
Memory usage: ~4KB per client + message buffers
No dynamic allocations in hot paths

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 proven mbedTLS library
Tested with major NOSTR relays

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

5.2 KiB Raw Blame History