matssocket library

MatsSocket Dart/Flutter client library

This is the Dart client library for MatsSocket. It handles both VM, Node and Web platforms (using conditional imports and dynamic resolving for the few platform specifics, notably the WebSocket implementation), and is compatible with Flutter. It runs on all platforms (VM, Node, Web) with all compiler targets (Kernel, Source, Exe, JS, Wasm).

MatsSocket is a WebSocket-based client-server solution which bridges the asynchronous message based nature of Mats3 all the way out to your end user client applications, featuring bidirectional communication. It consists of a small MatsSocketServer API which is implemented on top of the Mats3 API and JSR 356 Java API for WebSockets (which most Servlet Containers implement), as well as client libraries - for which there currently exists JavaScript and Dart/Flutter implementations.

Dependencies: logging for all targets, and web and http for the JS targets (Node and Web).

MatsSocket code is at GitHub, with the Dart client library residing in the matssocket-client-dart subproject.

There are a few examples in the example directory, and the integration tests exercises all features of the MatsSocket client.

For Development of the library itself, see README-development.md.

Classes

AuthorizationRequiredEvent
Event sent to AuthorizationExpiredCallback when a new authorization is required.
ConnectionEvent
Event object for MatsSocket.addConnectionEventListener.
ConnectResult
Result from the PreConnectOperation, containing an Function abortFunction to abort the operation, and a Future<int> responseStatusCode.
DebugDto
Meta-information for the call, availability depends on the allowed debug options for the authenticated user, and which information is requested in client. Notice that Client side and Server side might have wildly differing ideas of what the time is, which means that timestamps comparison between Server and Client must be evaluated with massive interpretation.
ErrorEvent
The Event object supplied to listeners added via {@link MatsSocket#addErrorEventListener()}.
InitiationProcessedEvent
(Metrics) Information about Client-to-Server SENDs and REQUESTs (aka Client Initiations), including experienced round-trip times for both Received acknowledgement, and for Requests, the Request-to-Reply time.
LogLineDto
MatsSocket
MatsSocketCloseEvent
Event given to listeners registered via MatsSocket.addSessionClosedEventListener.
MatsSocketEnvelopeDto
MatsSocketPlatform
Interface to communicate with the platform that the mats socket runs on.
MessageEvent
Message Event - the event emitted for a {@link MatsSocket#request() Requests}'s Promise resolve() and reject() (i.e. then() and catch()), and to a {@link MatsSocket#terminator() Terminator}'s resolveCallback and rejectCallback functions for replies due to {@link MatsSocket#requestReplyTo() requestReplyTo}, and for Server initiated Sends (to Terminators), and for the event to a {@link MatsSocket#endpoint() Endpoint} upon a Server initiated Request, and for the event sent to a {@link MatsSocket#subscribe() Subscription}.
PingPong
(Metric) A "holding struct" for pings and their experienced round-trip times - you may "subscribe" to ping results using MatsSocket.addPingPongListener, and you may get the latest pings from the property MatsSocket.pings.
ReceivedEvent
Message Received on Server event: "acknowledge" or "negative acknowledge" - these are the events which the returned Promise of a send(..) is settled with (i.e. then() and catch()), and which MatsSocket.request's receivedCallback function are invoked with.
SubscriptionEvent
Information about how a subscription went on the server side. If you do two subscriptions to the same Topic, you will still only get one such message - thus if you want one for each, you'd better add two listeners too, before doing any of the subscribes.
WebSocket

Enums

AuthorizationRequiredEventType
Type of AuthorizationRequiredEvent.
CloseCodes
An Enumeration of status codes for a web socket close that are defined in the specification.
ConnectionEventType
The event types of ConnectionEvent - four of the event types are state-transitions into different states of ConnectionState.
ConnectionState
States for MatsSocket.state.
DebugOption
Copied directly from AuthenticationPlugin.java: Types of debug information you can request, read more at {@link MatsSocket#debug} and {@link MessageEvent#debug}.
InitiationProcessedEventType
Type of InitiationProcessedEvent - the type of the initiation of a flow, which also determines which fields of the InitiationProcessedEvent are set.
MatsSocketCloseCodes
WebSocket CloseCodes used in MatsSocket, and for what. Using both standard codes, and MatsSocket-specific/defined codes.
MessageEventType
Types of {@link MessageEvent}.
MessageType
All Message Types (aka MatsSocket Envelope Types) used in the wire-protocol of MatsSocket.
ReceivedEventType
Types of ReceivedEvent.
SubscriptionEventType
Type of {@link SubscriptionEvent}.

Typedefs

AuthorizationExpiredCallback = dynamic Function(AuthorizationRequiredEvent)
Signature for callback of AuthorizationRequiredEvent.
CloseHandler = void Function(WebSocket, int?, String?, dynamic)
Handler for close event, with WebSocket closeCode and reason, and the native event, if any.
ConnectionEventListener = dynamic Function(ConnectionEvent)
Method signature for listeners wishing to accept ConnectionEvent
EndpointMessageHandler = Future Function(MessageEvent)
ErrorEventListener = dynamic Function(ErrorEvent)
ErrorHandler = void Function(WebSocket, dynamic)
Handler for the error event, will be passed the native event as an argument, if any.
InitiationProcessedEventListener = dynamic Function(InitiationProcessedEvent)
MessageEventHandler = dynamic Function(MessageEvent)
MessageHandler = void Function(WebSocket, String?, dynamic)
Handler for messages, this will get the message string, and the native event, if any.
OpenHandler = void Function(WebSocket, dynamic)
Handler for the open event, will be passed the native event as an argument, if any.
OutOfBandClose = dynamic Function(Uri webSocketUri, String sessionId)
Function that will be invoked upon closing the session, as an extra way to say to the server that the session is closing. This is beneficial if the WebSocket for some reason has gone down, as the server then can clean up the otherwise lingering session.
PingPongListener = dynamic Function(PingPong)
PreConnectOperation = ConnectResult Function(Uri webSocketUri, String authorization)
Function that performs a pre-connection operation (typically an HTTP GET) before opening the WebSocket, if the feature is enabled using MatsSocket.preConnectOperation, read doc there.
SessionClosedEventListener = dynamic Function(MatsSocketCloseEvent)
SubscriptionEventListener = dynamic Function(SubscriptionEvent)