-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #8 from chandleg/stage
Stage
- Loading branch information
Showing
16 changed files
with
792 additions
and
178 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| # API Manual | ||
|
|
||
| ## Installation | ||
|
|
||
| The library requires the Boost Beast and Jsoncpp libraries to handle WebSocket communications and JSON data manipulation respectively. Install these dependencies using CMake if they are not already present on your system. | ||
|
|
||
| ### Required Libraries | ||
| - **Boost Beast** (version >= 1.76.0): Used for WebSocket implementation. Available at [boost.org](https://www.boost.org/). | ||
| - **Jsoncpp**: Used for JSON parsing and serialization. Known for its performance and ease of use in C++ environments. | ||
|
|
||
| ## Examples | ||
| Two simple examples are provided demonstrating the Library in a simple raw C and a C++ classed implementation. Compile the examples using: | ||
| ```bash | ||
| - mkdir build && cd build | ||
| - cmake .. | ||
| - make | ||
| - ./example_client_simple or ./example_client_classed | ||
| ``` | ||
|
|
||
| ## Classes | ||
| ### Connection | ||
| The `Connection` class manages WebSocket connections using Boost Beast. It handles asynchronous read, write, and connection management activities necessary for real-time communication. | ||
|
|
||
| #### Constructor | ||
| - `Connection(net::io_context& ioc)`: Initializes a new connection with a given I/O context. This context is used to handle all I/O operations for the WebSocket. | ||
|
|
||
| #### Methods | ||
| - `std::thread launch_socket(const char *host, const char *port)`: Starts the WebSocket connection on a separate thread. | ||
| - `void stop()`: Stops the WebSocket connection and cleans up resources. | ||
| - `void subscribe(std::string channel, socketCallback callback)`: Subscribes to a specific channel with a callback to handle incoming messages. | ||
| - `void unsubscribe(std::string channel)`: Unsubscribes from a specific channel. | ||
| - `void publish(std::string channel, std::string data)`: Publishes data to a specific channel. | ||
| - `void message_processing()`: Handles the internal message processing in its thread. | ||
|
|
||
| #### Callbacks | ||
| - `socketCallback`: A function type that handles incoming messages. Takes an event as `std::string` and data as `Json::Value`. | ||
|
|
||
| #### Members | ||
| - `websocket::stream<beast::tcp_stream> ws_`: WebSocket stream for the connection. | ||
| - `beast::flat_buffer buffer_`: Buffer used for reading WebSocket messages. | ||
|
|
||
| ### SocketClusterClient | ||
|
|
||
| The `SocketClusterClient` class manages multiple WebSocket connections and provides methods to create and retrieve these connections. | ||
|
|
||
| #### Constructor | ||
| - `SocketClusterClient()`: Initializes a new client capable of handling WebSocket connections. | ||
|
|
||
| #### Methods | ||
| - `std::shared_ptr<Connection> createConnection(const char *url, const char *port)`: Creates and returns a new connection to the specified URL and port. | ||
| - `std::list<std::shared_ptr<Connection>>& getConnections()`: Returns a list of all active connections. | ||
|
|
||
| #### Members | ||
| - `std::list<std::shared_ptr<Connection>> m_connections`: List storing all managed connections. | ||
|
|
||
|
|
||
| ## Errors & Exceptions | ||
| - `1000 - Normal Closure` : Connection closed successfully. | ||
| - `1001 - Going Away` : Server or client is shutting down. | ||
| - `1002 - Protocol Error` : Protocol violation detected. | ||
| - `1003 - Unsupported Data` : The endpoint received data of a type it cannot accept. | ||
| - `1006 - Abnormal Closure` : Connection closed abnormally without a status code. | ||
|
|
||
|
|
||
| ## Example Usage of SocketClusterClient Library | ||
|
|
||
| This example demonstrates how to use the `SocketClusterClient` and `Connection` classes to connect to a WebSocket server, subscribe to a channel, and handle incoming messages. | ||
|
|
||
| ```cpp | ||
| #include <iostream> | ||
| #include "SocketClusterClient.h" | ||
|
|
||
| // Define a callback function to handle messages received on the WebSocket | ||
| void handleMessage(std::string event, Json::Value data) { | ||
| std::cout << "Event: " << event << "\nMessage received: " << data.toStyledString() << std::endl; | ||
| } | ||
|
|
||
| int main() { | ||
| // Create a client instance | ||
| SocketClusterClient client; | ||
|
|
||
| // Create a new WebSocket connection to the desired host and port | ||
| auto connection = client.createConnection("ws://example.com", "80"); | ||
|
|
||
| // Subscribe to a channel with the defined callback | ||
| connection->subscribe("exampleChannel", handleMessage); | ||
|
|
||
| // Publish to a channel | ||
| connection->publish("exampleChannel", "Hello World!"); | ||
|
|
||
| return 0; | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,30 @@ | ||
| # socketcluster-client-cpp | ||
| # Socket Cluster C++ Client | ||
|
|
||
| This repository hosts a [SocketCluster](https://socketcluster.io/) C++ Client designed to facilitate communication between C++ applications and SocketCluster servers. This client supports real-time, scalable, bi-directional communication, making it ideal for applications requiring high performance and efficient data exchange. | ||
| S | ||
| This client is developed using the [Boost Beast](https://github.com/boostorg/beast) and [jsoncpp](https://github.com/open-source-parsers/jsoncpp) libraries in C++. | ||
|
|
||
| ## Features | ||
|
|
||
| - **Real-Time Communication**: Enables real-time connectivity with SocketCluster servers. | ||
| - **Bi-Directional Communication**: Supports both sending and receiving messages efficiently. | ||
| - **Scalability**: Designed to handle high-load scenarios, making it suitable for large-scale deployments. | ||
| - **WebSocket Support**: Utilizes WebSockets for low-latency communication. | ||
|
|
||
|
|
||
| ## Getting Starting | ||
| A detailed list of the libraries API can be found [here](API.md). | ||
|
|
||
| ## Security / SSL | ||
| #### Tokens | ||
| To address the threat of unauthenticated connections, we will utilize SocketCluster's built-in JWT-based authentication mechanism. Each JWT is uniquely signed using a server-specific authKey, ensuring secure and verified connections right from the initial handshake. Follow the guide [here](https://socketcluster.io/docs/authentication/) to enable JWTs with SocketCluster. | ||
| #### WSS | ||
| To allow development and production runs a flag can be set to enable SSL assuming the SocketCluster server has been configured to accept SSL connections. To best achieve this a flag can be set in the client to put the data transfer into the secure mode. | ||
| ```cpp | ||
| #define SOCKETCLUSTER_SLL 1 | ||
| ``` | ||
| ## Performance | ||
| The maximum output and input rates have not been tested yet. This document will be updated with statistics after tests have been run. **Both example programs have been profiled and show no memory leaks.** | ||
| The SocketCluster server has been thoroughly tested in an [academic paper](https://arxiv.org/pdf/1409.3367.pdf). This client library aims to match the results listed. |
Oops, something went wrong.