WebSocketClient.qm.dox.h

// -*- mode: c++; indent-tabs-mode: nil -*-
 
/*  WebSocketClient.qm Copyright 2013 - 2023 Qore Technologies, s.r.o.
 
    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:
 
    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
 
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
*/
 
// minimum required Qore version
 
// require type definitions everywhere
 
// enable all warnings
 
// do not require "$" signs for vars, assume local variable scope
 
 
 
 
 
namespace WebSocketClient {
const WsSchemes = {
    "ws": {
        "ssl": False,
    },
    "wss": {
        "ssl": True,
    },
};
 
const WSC_Process = 0;
 
const WSC_Continue = 1;
 
const WSC_Break = 2;
 
const WsDefaultPort = 80;
 
const EVENT_WS_DATA = "ws-data-event";
 
const EVENT_WS_PING = "ws-ping-event";
 
const EVENT_WS_PONG = "ws-pong-event";
 
const EVENT_WS_CLOSED = "ws-closed-event";
 
 
const MESSAGE_WS_DATA = "data";
 
 
const MESSAGE_WS_RAW = "raw";
 
 
const MESSAGE_WS_PING = "ping";
 
 
const MESSAGE_WS_PONG = "pong";
 
 
class WebSocketClient {
 
public:
protected:
        Mutex m();
        HTTPClient hc;
        int stop = 0;
        Counter c();
        code callback;
        code raw_callback;
        code pong_callback;
        *code log;
        *code errlog;
        *code debuglog;
        timeout timeout_ms = DefaultTimeout;
        int tid;
        int cid = -1;
        *code yield;
        string url;
 
        static Sequence seq();
 
public:
 
        const DefaultTimeout = 15s;
 
        const Version = "1.6";
 
        const DefaultUserAgent = sprintf("Qore-WebSocketClient/%s", WebSocketClient::Version);
 
 
    constructor(code cb, hash<auto> opts);
 
 
    destructor();
 
 
    string getUrl();
 
 
    string getSafeUrl();
 
 
    int getConnectionId();
 
 
    hash<auto> getSchemes();
 
 
 
    hash<auto> connect(*hash<auto> opts, *reference<hash<auto>> info);
 
 
    bool isOpen();
 
 
    disconnect(int cmd = WSCC_GoingAway);
 
 
 
    nothing clearWarningQueue();
 
 
 
    nothing setWarningQueue(int warning_ms, int warning_bs, Queue queue, auto arg, timeout min_ms = 1s);
 
 
 
    hash<auto> getUsageInfo();
 
 
 
    clearStats();
 
 
 
    setEventQueue(Qore::Thread::Queue queue, auto arg, *bool with_data);
 
 
 
    setEventQueue();
 
 
protected:
     disconnectUnlocked(int cmd = WSCC_GoingAway);
public:
 
 
protected:
     eventLoop(code callback);
public:
 
 
protected:
     receivedPong(*data msg);
public:
 
 
protected:
     handlePing(hash<auto> h);
public:
 
 
protected:
     logInfo(string fmt);
public:
 
 
protected:
     logError(string fmt);
public:
 
 
protected:
     logDebug(string fmt);
public:
 
 
protected:
     sendClose(int code, *string txtmsg);
public:
 
 
protected:
     hash<auto> connectUnlocked(*hash<auto> hdr0, *reference<hash<auto>> info);
public:
 
 
 
    ping(*data msg);
 
 
 
    pong(*data msg);
 
 
 
    send(string str);
 
 
 
    send(binary bin);
 
 
    send(data msg, int op, bool fin);
 
};
 
 
class WebSocketConnectionObject : public ConnectionProvider::AbstractConnectionWithInfo {
 
public:
        const ConnectionScheme = <ConnectionSchemeInfo>{
            "cls": Class::forName("WebSocketConnectionObject"),
            "options": HttpConnection::ConnectionScheme.options,
        };
 
 
    constructor(string name, string description, string url, hash<auto> attributes = {}, hash<auto> options = {})
 ;
 
 
    string getType();
 
 
 
    *hash<auto> getRuntimeOptions();
 
 
protected:
     hash<PingInfo> pingIntern(hash<PingInfo> rv);
public:
 
 
 
protected:
     WebSocketClient getImpl(bool connect = True, *hash<auto> rtopts);
public:
 
 
 
    DataProvider::AbstractDataProvider getDataProvider();
 
 
 
    bool hasDataProvider();
 
 
protected:
     setChildCapabilities();
public:
 
 
protected:
     hash<ConnectionSchemeInfo> getConnectionSchemeInfoImpl();
public:
 
};
 
 
class WebSocketClientDataProviderBase : public DataProvider::AbstractDataProvider {
 
public:
        const ProviderInfo = <DataProviderInfo>{
            "supports_children": True,
            "supports_observable": True,
            "supports_messages": MSG_Async,
            "children_can_support_apis": True,
            "constructor_options": ConstructorOptions,
            "desc": "Allows sending and receiving WebSocket messages to and from a WebSocket server",
        };
 
        const ConstructorOptions = {
            "connect_timeout": <DataProviderOptionInfo>{
                "type": AbstractDataProviderTypeMap."int",
                "desc": "connection timeout to use in milliseconds",
            },
            "data": <DataProviderOptionInfo>{
                "type": AbstractDataProviderTypeMap."string",
                "desc": "data serialization to use:\n"
%ifndef NoJson
                    " - `json`: JSON serialization (default)\n"
%endif
%ifndef NoYaml
                    " - `yaml`: YAML serialization\n"
%endif
                    " - `none`: no serialization; raw messages\n",
                "default_value":
%ifndef NoJson
                    "json"
%else
                    "none"
%endif
                    ,
            },
            "headers": <DataProviderOptionInfo>{
                "type": AbstractDataProviderTypeMap."hash",
                "desc": "headers to add in each outgoing request",
            },
            "http_version": <DataProviderOptionInfo>{
                "type": AbstractDataProviderTypeMap."string",
                "desc": "HTTP version to use (`1.0` or `1.1`, defaults to `1.1`)",
                "default_value": "1.1",
            },
            "max_redirects": <DataProviderOptionInfo>{
                "type": AbstractDataProviderTypeMap."int",
                "desc": "maximum redirects to support",
            },
            "proxy": <DataProviderOptionInfo>{
                "type": AbstractDataProviderTypeMap."string",
                "desc": "proxy URL to use",
            },
            "report_pings": <DataProviderOptionInfo>{
                "type": AbstractDataProviderTypeMap."bool",
                "desc": "Raise events for ping message from clients",
                "default_value": False,
            },
            "timeout": <DataProviderOptionInfo>{
                "type": AbstractDataProviderTypeMap."int",
                "desc": "transfer timeout to use in milliseconds",
            },
            "url": <DataProviderOptionInfo>{
                "type": AbstractDataProviderTypeMap."string",
                "desc": "A URL for a WebSocket connection",
                "required": True,
            },
        };
 
        const ApiClasses = {
            "wait-for-message": Class::forName("WebSocketClientWaitForMessageDataProvider"),
        };
 
        const SerializationMap = ...;
 
 
protected:
        WebSocketClient client;
 
        string serialization;
 
        bool report_pings;
 
        Mutex m();
 
        WebSocketClientWaitForMessageDataProvider child;
 
        Queue q;
 
public:
 
    constructor(*hash<auto> options);
 
 
    destructor();
 
 
    string getName();
 
 
    register(WebSocketClientWaitForMessageDataProvider child);
 
 
    deregister();
 
 
    Queue getQueue();
 
 
 
protected:
     *list<string> getChildProviderNamesImpl();
public:
 
 
 
protected:
     *AbstractDataProvider getChildProviderImpl(string name);
public:
 
 
protected:
     start();
public:
 
 
 
protected:
     hash<string, hash<DataProviderMessageInfo>> getEventTypesImpl();
public:
 
 
 
protected:
     hash<string, hash<DataProviderMessageInfo>> getMessageTypesImpl();
public:
 
 
 
protected:
     sendMessageImpl(string message_id, auto msg, *hash<auto> send_message_options);
public:
 
 
protected:
     event(*data msg);
public:
 
 
protected:
     pong(*data msg);
public:
 
 
    auto deserializeMessage(data msg);
 
 
    data serializeMessage(auto msg);
 
 
      static hash<auto> getOptionsFromTemplate(hash<auto> template_options, *hash<auto> options);
 
protected:
     unsupportedSerialization();
public:
 
 
    abstract notifyObservers(string msg_id, hash<auto> event);
};
 
 
class WebSocketClientDataProvider : public WebSocketClientDataProviderBase, public DataProvider::Observable {
 
public:
        const ProviderInfo = <DataProviderInfo>{
            "type": "WebSocketClientDataProvider",
        } + WebSocketClientDataProviderBase::ProviderInfo;
 
    constructor(*hash<auto> options) ;
 
 
    constructor(hash<auto> template_options, *hash<auto> options) ;
 
 
protected:
     hash<DataProviderInfo> getStaticInfoImpl();
public:
 
};
 
 
class WebSocketClientDelayedDataProvider : public WebSocketClientDataProviderBase, public DataProvider::DelayedObservable {
 
public:
        const ProviderInfo = <DataProviderInfo>{
            "type": "WebSocketClientDelayedDataProvider",
        } + WebSocketClientDataProviderBase::ProviderInfo;
 
    constructor(*hash<auto> options) ;
 
 
    constructor(hash<auto> template_options, *hash<auto> options) ;
 
 
 
    observersReady();
 
 
protected:
     hash<DataProviderInfo> getStaticInfoImpl();
public:
 
};
 
class WebSocketClientEventDataType : public HashDataType {
 
public:
    constructor();
 
};
 
class WebSocketClientWaitForMessageDataProvider : public AbstractDataProvider {
 
public:
        const ProviderInfo = <DataProviderInfo>{
            "type": "WebSocketClientWaitForMessageDataProvider",
            "supports_request": True,
            "desc": "Waits for a WebSocket message to be received from the server within a timeout period and "
                "returns the message if one is received in the timeout perdiod, or an exception is thrown",
        };
 
        const RequestType = new WebSocketClientWaitForMessageRequestDataType();
 
        const ResponseType = AbstractDataProviderTypeMap."any";
 
protected:
        WebSocketClientDataProviderBase base;
 
public:
 
    constructor(WebSocketClientDataProviderBase base);
 
 
    destructor();
 
 
    string getName();
 
 
 
protected:
     auto doRequestImpl(auto req, *hash<auto> request_options);
public:
 
 
 
protected:
     *AbstractDataProviderType getRequestTypeImpl();
public:
 
 
 
protected:
     *AbstractDataProviderType getResponseTypeImpl();
public:
 
 
    hash<DataProviderInfo> getStaticInfoImpl();
 
};
 
class WebSocketClientWaitForMessageRequestDataType : public HashDataType {
 
public:
        const Fields = {
            "timeout": {
                "type": IntType,
                "desc": "The number of milliseconds to wait for an incoming message; after this point, if no "
                    "WebSocket message has been received, an exception will be thrown",
                "required": True,
                "default_value": 10000,
            },
        };
 
    constructor();
 
};
 
class WebSocketClientDataProviderFactory : public AbstractDataProviderFactory {
 
public:
protected:
        static Class cls = new Class("WebSocketClientDelayedDataProvider");
 
        const FactoryInfo = <DataProviderFactoryInfo>{
            "name": "wsclient",
            "desc": "WebSocket client data provider factory",
            "children_can_support_observers": True,
            "children_can_support_messages": True,
        };
 
public:
 
 
protected:
     hash<DataProviderFactoryInfo> getInfoImpl();
public:
 
 
 
protected:
     hash<DataProviderInfo> getProviderInfoImpl();
public:
 
 
protected:
     Class getClassImpl();
public:
 
};
};