stream client

تيار العميل

هذه مكتبة خفيفة الوزن ، رأسًا على عقب ، توفر بدايات الشبكة من جانب العميل لتنظيم وتنفيذ نقل البيانات بسهولة مع نقاط النهاية عن بُعد.

هذه المكتبة:

مستوحاة من وبنيت حول boost.asio.
يوفر بنيات عالية المستوى كموصل ومجموعة اتصال.
يدعم بروتوكولات TCP / UDP / SSL / HTTP / HTTPS .
يستخدم مآخذ مع نفس الواجهة مثل Boost :: Asio :: IP منها.
يتيح مهلة الشفافة/السيطرة على الموعد النهائي لجميع العمليات.
يتطلب Boost 1.65+ أو 1.66+ إذا كنت تخطط لاستخدام بروتوكول HTTP.

لماذا

إذا كنت تكتب برامج على C ++ ، والتي تتواصل مع الخدمات الأخرى كعميل ، فمن المحتمل أن تكون قد حصلت بالفعل على Across مع المشكلة - تحتاج إلى تطبيق طبقة الاتصال لتوفير نقل الشبكة لجميع الخدمات ذات الصلة. هذا هو بالضبط ما هدف هذه المكتبة لحلها.

كيفية استخدام

مآخذ

يتم تنفيذ المقابس أعلى boost::asio::basic_socket وتزويد الفصول بالتحكم في المهلة ، لذلك في معظم الحالات ، يكفي الاتصال فقط () / تلقي () / write_some () / read_some () مع موعد نهائي أو مهلة. يجب أن يتم لف البيانات المقدمة لعمليات الإدخال/الإخراج في boost::asio::buffer . في الأساس ، فإن هؤلاء العملاء هم boost::asio::ip Sockets ولديهم نفس الواجهة.

فئات تدفقات العميل:

stream_client::tcp_client - عميل مقبس دفق TCP عادي. يدعم Send () / REGNECIVE () لنقله المقبول من المخزن المؤقت بالكامل جنبا إلى جنب مع write_some () / read_some () لنقل شيء ما على الأقل.
stream_client::udp_client - عميل مقبس UDP عادي. يدعم فقط Send () / receed () دون أي إقرار حسب مواصفات UDP.
stream_client::ssl::ssl_client - عميل TCP - SSL -incrypted. لديك نفس الوظائف مثل tcp_client Plus SSL المصافحة والتحكم في السياق.
stream_client::http::http_client - عميل http. يلف tcp_client مع boost::beast::http::parser and boost::beast::http::serializer و eash () وظيفة لإجراء مكالمات استجابة الطلب.
stream_client::http::https_client - عميل https. مثل http_client ولكن يستخدم عميل ssl_client أسفله.

مثال

 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 حول نفس الفكرة - اجعل Sync و DNS Resolver ، وبالتالي يستخدم boost::asio::ip::basic_resolver لأداء الدقة الفعلية داخل مهلة محددة.

هذا هو قالب الفصل مع بروتوكول واحد - نتيجة ، يمكنك أيضًا تحديد نوع نقاط نهاية IP التي تهتم بها - IPv4 أو IPv6 أو كليهما. الدقة التي تم تنفيذها باستخدام Colling () والتي لها توقيع مماثل كعمليات مآخذ - أنت حر في تحديد المهلة/الموعد النهائي أو استخدام واحد افتراضي.

فصول الحلول:

stream_client::resolver::tcp_resolver - RESOLVER الذي يعيد ITERATAR لنقاط نهاية TCP.
stream_client::resolver::udp_resolver - Resolver الذي يعيد Iterator لنقاط نهاية UDP.

مثال

 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>

الموصل

يستخدم Connector Resolver لأداء دقة DNS وتحديث قائمة نقاط النهاية ويستخدمها إذا تم طلبها مع New_Session () ، لإنشاء مأخذ توصيل جديد للبروتوكول المحدد. يتم لف أعمال حل DNS في خيط الخلفية التي تسببت عند الإنشاء أو إذا كان هناك خطأ في فتح مقبس جديد.

نقطة النهاية الهدف لفتح مقبس جديد تم اختياره عشوائيًا من نتائج DNS ، مما يجعله موصل متوازن لمضيف عن بعد. أيضًا ، يتيح الموصل تحديد مهلة منفصلة للدقة والاتصال وتشغيل مآخذ مآخذ جديدة.

فصول الموصل:

stream_client::connector::tcp_connector - TCP Connector ، للحصول على stream_client::tcp_client Sockets.
stream_client::connector::udp_connector - موصل UDP ، للحصول على stream_client::udp_client sockets.
stream_client::connector::ssl_connector - TCP Connector ، للحصول على stream_client::ssl::ssl_client Sockets.
stream_client::connector::http_connector - http connector ، للحصول على stream_client::http::http_client sockets.
stream_client::connector::https_connector - موصل https ، للحصول على stream_client::http::https_client sockets.

مثال

 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()));

تجمع الاتصال

يمثل حاوية مشغولة بمآخذ مفتوح. يستخدم الموصل لفتح مآخذ جديدة في خيط الخلفية الذي يتم تشغيله بمجرد وجود أماكن شاغرة في المسبح. يمكن للمستخدم الاتصال بـ get_session () للحصول على مقبس من التجمع وإرجاعها () لإعادته.

هناك استراتيجيتان لإعادة ملء التجمع:

الجشع ( stream_client::connector::greedy_strategy ). إذا كانت هناك أماكن شاغرة ، فستحاول ملء جلسات جديدة في وقت واحد. هذا هو الافتراضي.
المحافظ ( stream_client::connector::conservative_strategy ). سأحاول ملء ما يصل إلى 2/3 من الأماكن الشاغرة في الاستطلاع. إذا فشل سيعود لبعض الوقت وإعادة المحاولة لاحقًا. أيضًا ، بعد الإخفاقات ، سيخلق جلسة واحدة فقط.

يتم تعريف كلاهما من حيث stream_client::connector::pool_strategy ، لذلك أنت حر في تنفيذ واحدة جديدة.

القيود:

لا يتم فحص أو الحفاظ على مآخذ موجودة بالفعل في حمام السباحة بأي شكل من الأشكال. وبالتالي ، لا يضمن المجمع فتح جميع المقابس في وقت تعسفي في الوقت المناسب بسبب تعقيد هذه الشيكات لجميع البروتوكولات المدعومة.
لا شيء محدد مع مآخذ عند عودتهم داخل Return_session () . لذلك ، إذا كان لديهم أو سيكون لديهم بيانات معلقة للقراءة ، فسيبقى هناك حتى القراءة.

بالنظر إلى ذلك ، فإن أفضل استراتيجية لاستخدام مجموعة اتصال هي:

قم بإنشائها ، وتحديد جميع المهام كما تحتاج.
بمجرد إنشائها ، استخدم get_session () للحصول على مقبس مفتوح.
هل هناك حاجة إلى عمليات الإدخال/الإخراج على المقبس.
إذا نجحت 2-3 ، أعدها مرة أخرى مع return_session () ، وإلا نروي النقطة 2.

من المهم التخلص من المقابس عند الفشل وعدم إعادة استخدامها ، أو ستصبح إدارة الاستجابة للطلب سيئة.

تجمعات الاتصال:

stream_client::connector::tcp_pool - POOW of stream_client::tcp_client SOCKETS.
stream_client::connector::udp_pool - POOW of stream_client::udp_client SOCKETS.
stream_client::connector::ssl_pool - POOW stream_client::ssl::ssl_client Sockets.
stream_client::connector::http_pool - Pool of stream_client::http::http_client sockets.
stream_client::connector::https_pool - Pool of stream_client::http::https_client sockets.

هناك أيضًا أسماء مستعارة لنفس التجمعات ولكن باستخدام استراتيجية إعادة الاتصال المحافظة:

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

مثال

 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 ();
}

قطع الأشجار

تستخدم المكتبة واجهة المسجل الأساسية التي يتم تنفيذها داخليًا. يمكنك تعديل مستوى المسجل باستخدام stream_client::set_log_level() أو stream_client::get_log_level() .

هذه المستويات مدعومة:

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

بشكل افتراضي ، يطبع المكتبة الرسائل إلى stdout بتنسيق لائق. إذا كنت ترغب في الكتابة فوق هذا السلوك ، يمكنك تعيين المسجل الخاص بك عبر:

 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);

مما يسمح إما بكتابة مسجل فوق استخدام رد الاتصال بالتوقيع المناسب. تعرّف هذه الأنواع على النحو التالي:

 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)>;

لمزيد من المعلومات ، يرجى النظر داخل logger.hpp.

كيفية البناء

من المفترض أن تكون هذه المكتبة متعددة المنصات إلى حد ما ، ومع ذلك ، فقد تم اختبارها واستخدامها بشكل رئيسي على Ubuntu و MacOS.
تفضل المبنى خارج المصدر.

تبعيات أوبونتو

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

تبعيات ماكوس

brew install cmake pkg-config icu4c openssl boost

للبناء:

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

للتثبيت (قد تكون هناك حاجة إلى sudo):

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

أو الاختبار:

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

تفترض كل هذه الأوامر أنك في مجلد جذر الدفق-العميل

خيارات cmake

cmake_build_type - نوع البناء. RelWithDebInfo افتراضيا.
build_shared_libs - إنشاء مكتبة مشتركة أو ثابتة. بشكل ON .
StreamClient_build_testing - بناء اختبارات أم لا. OFF افتراضي
StreamClient_build_examples - إنشاء أمثلة مكتبة أم لا. OFF افتراضي.
StreamClient_build_docs - بناء مستندات مرجعية HTML (sphinx). OFF افتراضي.
Openssl_use_static_libs - ارتباط بشكل ثابت أو ديناميكي ضد OpenSSL. إذا تم OFF build_shared_libs ، فسيتم تعيين هذه الخيارات.
OpenSSL_ROOT_DIR - مجلد حيث يبحث عن OpenSSL. تم تعيينه بواسطة PKG-Config من Brew افتراضيًا.

رخصة

تم تطويره في Tinkoff.ru في عام 2020.
Dividiped بموجب ترخيص Apache 2.0 . يمكنك أيضًا الحصول على هذا الترخيص على https://www.apache.org/licenses/license-2.0.