First commit on a late git install

2025-08-09 10:23:28 -04:00
commit ca6b4754f9
88 changed files with 18219 additions and 0 deletions
--- a/nostr_websocket/README.md
+++ b/nostr_websocket/README.md
@@ -0,0 +1,139 @@
+# 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 mbedTLS
+- ✅ **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_mbedtls.c`** - Main implementation (mbedTLS backend)
+- **`../cjson/cJSON.h/c`** - JSON parsing support
+
+### Dependencies
+- **mbedTLS** - For SSL/TLS support
+- **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 in `../websocket_experiment/` and represents the production-ready, stable version suitable for integration into other projects.
+
+Key improvements made during development:
+- Fixed critical WebSocket frame parsing bugs
+- Optimized SSL/TLS performance
+- Reduced memory allocations
+- Enhanced error handling
+- Added comprehensive documentation
+
+## 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.