Download stream client - stream client

Aliran klien

Ini adalah perpustakaan yang ringan, hanya header, berbasis boost yang menyediakan primitif jaringan sisi klien untuk dengan mudah mengatur dan mengimplementasikan transmisi data dengan titik akhir jarak jauh.

Perpustakaan ini:

Terinspirasi oleh dan dibangun di sekitar boost.asio.
Memberikan konstruksi tingkat tinggi sebagai konektor dan kumpulan koneksi.
Mendukung protokol TCP / UDP / SSL / HTTP / HTTPS .
Menggunakan soket dengan antarmuka yang sama seperti Boost :: asio :: IP Ones.
Mengizinkan waktu tunggu/batas waktu transparan untuk semua operasi.
Membutuhkan Boost 1.65+ atau 1.66+ Jika Anda berencana untuk menggunakan protokol HTTP.

Mengapa

Jika Anda menulis perangkat lunak di C ++, yang berkomunikasi dengan layanan lain sebagai klien, Anda mungkin sudah datang -ecross dengan masalah - perlu mengimplementasikan lapisan konektivitas untuk menyediakan transportasi jaringan ke semua layanan terkait. Inilah yang tepat untuk dipecahkan perpustakaan ini.

Cara menggunakan

Soket

Soket diimplementasikan di atas boost::asio::basic_socket dan menyediakan kelas dengan kontrol waktu tunggu, jadi dalam kebanyakan kasus itu cukup untuk hanya menelepon () / menerima () / write_some () / read_some () dengan tenggat waktu atau batas waktu. Data yang disediakan untuk operasi I/O harus dibungkus menjadi boost::asio::buffer . Pada dasarnya klien-klien ini adalah boost::asio::ip dan memiliki antarmuka yang sama.

Kelas Stream Klien:

stream_client::tcp_client - Klien Soket Stream TCP Plain. Mendukung kirim () / rekecive () untuk transfer seluruh buffer yang diterima bersama dengan write_some () / read_some () untuk mentransfer setidaknya sesuatu.
stream_client::udp_client - klien soket UDP biasa. Dukungan hanya mengirim () / menerima () tanpa pengakuan sesuai spesifikasi UDP.
stream_client::ssl::ssl_client - klien TCP yang dienkripsi SSL. Memiliki fungsi yang sama seperti tcp_client Plus SSL Handshake dan Kontrol Konteks.
stream_client::http::http_client - klien http. Wraps tcp_client dengan boost::beast::http::parser dan boost::beast::http::serializer dan memiliki fungsi () untuk membuat panggilan permintaan-respons.
stream_client::http::https_client - klien https. Sama seperti http_client tetapi menggunakan klien ssl_client di bawahnya.

Contoh

 const boost::asio::ip::tcp::endpoint endpoint (boost::asio::ip::address::from_string( " 127.0.0.1 " ), 12345);
const std::chrono::milliseconds connect_timeout ( 1000 );
const std::chrono::milliseconds io_timeout ( 100 );

// this makes connected socket and may take up to connect_timeout time
stream_client::tcp_client client (endpoint, connect_timeout, io_timeout);

// send() operation will transmit all contents of send_data or throw an error;
// also it will throw boost::asio::error::timed_out after io_timeout.
const std::string send_data = " test data " ;
client.send(boost::asio::buffer(send_data.data(), send_data.size()));

// receive() operation will read send_data.size() size or throw an error;
// also it will throw boost::asio::error::timed_out after io_timeout.
std::string recv_data (send_data.size(), '');
client.receive(boost::asio::buffer(&recv_data[ 0 ], send_data.size()));

// there are also non-throw overloads to these functions which
// will set boost::system::error_code instead of exception;

DNS Resolver

Resolver diimplementasikan di sekitar ide yang sama - buat sinkronisasi, waktu resolver DNS, oleh karena itu ia menggunakan boost::asio::ip::basic_resolver untuk melakukan resolusi aktual dalam batas waktu yang ditentukan.

Ini adalah templat kelas dengan satu parameter - protokol hasil, juga Anda dapat menentukan jenis titik akhir IP yang Anda minati - IPv4, IPv6 atau keduanya. Resolusi yang dilakukan dengan panggilan Resolve () yang memiliki tanda tangan yang sama dengan operasi soket - Anda bebas untuk menentukan batas waktu/batas waktu atau menggunakan satu default.

Kelas Resolver:

stream_client::resolver::tcp_resolver - resolver yang mengembalikan iterator titik akhir TCP.
stream_client::resolver::udp_resolver - resolver yang mengembalikan iterator titik akhir UDP.

Contoh

 const std::chrono::milliseconds resolve_timeout ( 5000 );

stream_client::resolver::tcp_resolver resolver ( " localhost " , " 12345 " ,
                                               resolve_timeout,
                                               stream_client::resolver::ip_family::ipv4);

// resolve() guaranteed to return at least one endpoint or will throw an error;
// it will throw boost::asio::error::timed_out after resolve_timeout.
auto endpoints_it = resolver.resolve();

// returned iterator is an instance of boost::asio::ip::basic_resolver::iterator<Protocol>

Konektor

Connector menggunakan resolver untuk melakukan resolusi DNS dan memperbarui daftar titik akhir dan menggunakannya jika diminta dengan new_session () , untuk membuat soket baru dari protokol yang ditentukan. Pekerjaan resolver DNS dibungkus ke dalam utas latar belakang yang dipicu pada pembuatan atau jika ada kesalahan dalam membuka soket baru.

Target Endpoint untuk membuka soket baru yang dipilih secara acak dari hasil DNS, yang membuatnya konektor seimbang ke host jarak jauh. Juga, konektor memungkinkan menentukan batas waktu terpisah untuk resolusi, koneksi, dan operasi I/O soket baru.

Kelas Konektor:

stream_client::connector::tcp_connector - TCP Connector, untuk mendapatkan soket stream_client::tcp_client .
stream_client::connector::udp_connector - Konektor UDP, untuk mendapatkan soket stream_client::udp_client .
stream_client::connector::ssl_connector - TCP Connector, untuk mendapatkan soket stream_client::ssl::ssl_client .
stream_client::connector::http_connector - http connector, untuk mendapatkan stream_client::http::http_client sockets.
stream_client::connector::https_connector - konektor https, untuk mendapatkan stream_client::http::https_client soket.

Contoh

 const std::chrono::milliseconds resolve_timeout ( 5000 );
const std::chrono::milliseconds connect_timeout ( 1000 );
const std::chrono::milliseconds io_timeout ( 100 );

// this will return immediately, starting background thread for name resolution
stream_client::connector::tcp_connector connector ( " localhost " , " 12345 " ,
                                                  resolve_timeout, connect_timeout, io_timeout,
                                                  stream_client::resolver::ip_family::ipv4);

// this will acquire new socket or throw;
// it will throw boost::asio::error::timed_out after connect_timeout
std::unique_ptr<stream_client::tcp_client> client = connector.new_session();

// use the client
const std::string send_data = " test data " ;
std::string recv_data (send_data.size(), '');
client-> send (boost::asio::buffer(send_data.data(), send_data.size()));
client-> receive (boost::asio::buffer(&recv_data[ 0 ], send_data.size()));

Kumpulan koneksi

Mewakili wadah yang ditempati dengan soket yang dibuka. Menggunakan Connector untuk membuka soket baru di utas latar belakang yang dipicu setelah ada tempat kosong di kolam renang. Pengguna dapat menghubungi get_session () untuk mendapatkan soket dari kumpulan dan return_session () untuk mengembalikannya.

Ada dua strategi untuk mengisi ulang kolam:

serakah ( stream_client::connector::greedy_strategy ). Jika ada tempat kosong, ia akan mencoba mengisinya dengan sesi baru secara bersamaan. Ini adalah yang default.
konservatif ( stream_client::connector::conservative_strategy ). Akan mencoba mengisi hingga 2/3 tempat kosong dalam jajak pendapat. Jika gagal akan kembali untuk beberapa waktu dan coba lagi nanti. Juga, setelah kegagalan itu hanya akan membuat satu sesi baru.

Keduanya didefinisikan dalam hal stream_client::connector::pool_strategy Interface, jadi Anda bebas untuk mengimplementasikan yang baru.

Keterbatasan:

Soket yang sudah ada di kolam tidak diperiksa atau dipelihara dengan cara apa pun. Oleh karena itu, kolam tidak menjamin bahwa semua soket dibuka pada titik waktu yang sewenang -wenang karena kompleksitas cek tersebut untuk semua protokol yang didukung.
Tidak ada yang spesifik dilakukan dengan soket setelah mereka kembali dalam return_session () . Karena itu, jika mereka memiliki atau akan memiliki data yang tertunda untuk dibaca, itu akan tetap di sana sampai membaca.

Mempertimbangkan ini, strategi terbaik untuk menggunakan kumpulan koneksi adalah:

Buatnya, tentukan semua waktu tunggu yang Anda butuhkan.
Setelah dibuat, gunakan get_session () untuk mendapatkan soket yang dibuka.
Melakukan operasi I/O yang dibutuhkan di soket.
Jika 2-3 berhasil, kembalikan kembali dengan return_session () , selain itu ulang titik 2.

Penting untuk membuang soket pada kegagalan dan tidak menggunakannya kembali, atau manajemen permintaan-respons akan menjadi buruk.

Kolam koneksi:

stream_client::connector::tcp_pool - kumpulan soket stream_client::tcp_client .
stream_client::connector::udp_pool - kumpulan soket stream_client::udp_client .
stream_client::connector::ssl_pool - kumpulan stream_client::ssl::ssl_client .
stream_client::connector::http_pool - kumpulan stream_client::http::http_client sockets.
stream_client::connector::https_pool - kumpulan stream_client::http::https_client sockets.

Ada juga alias untuk kumpulan yang sama tetapi menggunakan strategi koneksi konservatif:

stream_client::connector::tcp_conservative_pool
stream_client::connector::udp_conservative_pool
stream_client::connector::ssl_conservative_pool
stream_client::connector::http_conservative_pool
stream_client::connector::https_conservative_pool

Contoh

 const std::chrono::milliseconds resolve_timeout ( 5000 );
const std::chrono::milliseconds connect_timeout ( 1000 );
const std::chrono::milliseconds io_timeout ( 100 );

auto connector_pool =
    std::make_shared<stream_client::connector::tcp_pool>( " localhost " , " 12345 " ,
                                                         resolve_timeout, connect_timeout, io_timeout,
                                                         stream_client::resolver::ip_family::ipv4);
const size_t threads_num = 10 ;
std::vector<std::thread> threads;
const std::string send_data = " test data " ;
std::mutex stdout_mutex;

for ( size_t i = 0 ; i < threads_num; ++i) {
    threads. emplace_back ([&send_data, &stdout_mutex, connector_pool]() {
        std::string recv_data (send_data. size (), '  ' );

        auto client = connector_pool-> get_session ();
        // both these calls will throw exception on error or timeout
        client-> send ( boost::asio::buffer (send_data. data (), send_data. size ()));
        client-> receive ( boost::asio::buffer (&recv_data[ 0 ], send_data. size ()));
        // if there was no exception, return it
        connector_pool-> return_session ( std::move (client));

        const std::lock_guard<std::mutex> lk (stdout_mutex);
        std::cout << std::this_thread::get_id () << " : " << recv_data << std::endl;
    });
}

for ( auto & t : threads) {
    t. join ();
}

Logging

Perpustakaan menggunakan antarmuka Logger dasar yang diimplementasikan secara internal. Anda dapat memodifikasi level logger menggunakan stream_client::set_log_level() atau stream_client::get_log_level() fungsi.

Level -level ini didukung:

 enum class log_level : int
{
    trace = 0 ,
    debug,
    info,
    warning,
    error,
};

Secara Default Library mencetak pesan ke stdout dengan pemformatan yang layak. Jika Anda ingin menimpa perilaku ini, Anda dapat mengatur logger Anda sendiri melalui:

 void stream_client::set_logger (std::shared_ptr<stream_client::log_interface> logger);

void stream_client::set_logger (stream_client::log_level level, stream_client::log_func_type log_func);

Yang memungkinkan untuk menimpa instance Logger menggunakan panggilan balik dengan tanda tangan yang tepat. Tipe ini didefinisikan sebagai:

 class log_interface
{
public:
    virtual void set_level (log_level level) noexcept = 0;
    virtual log_level get_level () const noexcept = 0;
    virtual void message (log_level level, const std::string& location, const std::string& message) const = 0;
};

using log_func_type = std::function< void (log_level level, const std::string& location, const std::string& message)>;

Untuk informasi lebih lanjut, silakan lihat di dalam Logger.hpp.

Cara membangun

Perpustakaan ini seharusnya agak multi-platform, namun, diuji dan terutama digunakan pada Ubuntu dan MacOS.
Lebih suka bangunan di luar sumber.

Ketergantungan Ubuntu

sudo apt update
sudo apt install build-essential cmake libboost-dev libboost-system-dev libssl-dev

Ketergantungan MacOS

brew install cmake pkg-config icu4c openssl boost

Untuk membangun:

cmake -H. -Bbuild
cmake --build ./build

Untuk menginstal (sudo mungkin diperlukan):

cmake -H. -Bbuild -DSTREAMCLIENT_BUILD_TESTING=OFF -DSTREAMCLIENT_BUILD_DOCS=OFF -DSTREAMCLIENT_BUILD_EXAMPLES=OFF
cmake --build ./build --target install

Atau tes:

cmake -H. -Bbuild -DSTREAMCLIENT_BUILD_TESTING=ON -DSTREAMCLIENT_BUILD_DOCS=OFF -DSTREAMCLIENT_BUILD_EXAMPLES=OFF
cmake --build ./build
cmake -E chdir ./build ctest --output-on-failure

Semua perintah ini menganggap Anda berada di folder root stream-client

Opsi CMake

Cmake_build_type - tipe build. RelWithDebInfo secara default.
Build_shared_libs - Bangun perpustakaan bersama atau statis. ON secara default.
Streamclient_build_testing - membangun tes atau tidak. OFF secara default
Streamclient_build_examples - Bangun contoh perpustakaan atau tidak. OFF secara default.
Streamclient_build_docs - Bangun dokumen referensi html (sphinx). OFF secara default.
OpenSSL_USE_STATIC_LIBS - tautan secara statis atau dinamis terhadap OpenSSL yang ditemukan. Jika build_shared_libs OFF maka opsi ini diatur.
OpenSSL_ROOT_DIR - Folder tempat mencari openssl. Ditetapkan oleh PKG-Config of Brew secara default.

Lisensi

Dikembangkan di Tinkoff.ru pada tahun 2020.
Didistribusikan di bawah lisensi Apache 2.0 Lisensi. Anda juga dapat memperoleh lisensi ini di https://www.apache.org/licenses/license-2.0.