# 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
```bash
make
```

### 2. Run the Test
```bash
make test
# or directly:
./test_5_events_clean
```

### 3. Basic Usage
```c
#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`](EXPORT_GUIDE.md) for detailed instructions on integrating this library into your C projects.

## API Reference

### Connection Management
```c
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
```c
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
```c
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
```c
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

```bash
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.