Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/plugfox/ws
WS: A compact, highly efficient WebSocket library. Easily establish, manage, and reconnect WebSocket connections in real-time apps.
https://github.com/plugfox/ws
cross-platform dart flutter library package pub socket websocket ws
Last synced: 12 days ago
JSON representation
WS: A compact, highly efficient WebSocket library. Easily establish, manage, and reconnect WebSocket connections in real-time apps.
- Host: GitHub
- URL: https://github.com/plugfox/ws
- Owner: PlugFox
- License: mit
- Created: 2023-05-02T12:00:10.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-08-30T15:19:22.000Z (2 months ago)
- Last Synced: 2024-10-12T05:43:14.790Z (27 days ago)
- Topics: cross-platform, dart, flutter, library, package, pub, socket, websocket, ws
- Language: Dart
- Homepage: https://pub.dev/packages/ws
- Size: 2.22 MB
- Stars: 39
- Watchers: 1
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# WS: Cross-platform WebSocket client
[](https://pub.dev/packages/ws)
[](https://github.com/PlugFox/ws/actions)
[](https://codecov.io/gh/PlugFox/ws)
[](https://opensource.org/licenses/MIT)
[](https://pub.dev/packages/linter)
[](https://github.com/plugfox/ws/)
The `ws` package provides a cross-platform WebSocket client for both Dart and Flutter applications. It allows you to connect to a WebSocket server, send and receive messages, and handle the connection state changes.
---
## Installation
Add the following dependency to your `pubspec.yaml` file:
```yaml
dependencies:
ws:
```
## Properties
- `reconnectTimeout`: A read-only property that returns the reconnect timeout. The default value is 5 seconds.
- `state`: A read-only property that returns the current WebSocket connection state.
- `stateChanges`: A read-only property that returns a stream of WebSocket connection state changes.
- `stream`: A read-only property that returns a stream of message events handled by the WebSocket.
- `metrics`: A read-only property that returns a `WebSocketMetrics` object with metrics about the WebSocket connection.
## Methods
- `connect(String url)`: Connects to the WebSocket server specified by the URL argument.
- `disconnect([int? code = 1000, String? reason = 'NORMAL_CLOSURE'])`: Closes the WebSocket connection. You can optionally pass a numeric code and a reason string to the method to send close information to the remote peer.
- `add(Object data)`: Sends data on the WebSocket connection. The data can be either a String or a List of integers holding bytes.
- `close([int? code = 1000, String? reason = 'NORMAL_CLOSURE'])`: Permanently stops the WebSocket connection and frees all resources. After calling this method, the WebSocket client is no longer usable.
## Options
The `WebSocketOptions` class provides a configurable set of options for setting up a WebSocket connection on both VM (Virtual Machine) and JS (JavaScript) platforms. This class supports a variety of settings including connection retry strategies, subprotocols, timeouts, message interceptors, and platform-specific configurations.
To use `WebSocketOptions`, instantiate it directly with the desired configuration for your platform. Use the `.vm()` factory for VM platform settings and `.js()` factory for JS platform settings. The `.selector()` factory can be used to construct options depending on the current platform, allowing for flexible configuration across different environments.
### Common Options
Common configuration options applicable across VM and JS platforms:
| Option | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connectionRetryInterval` | Specifies the [Backoff full jitter strategy](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) for reconnecting. Allows tweaks for the reconnect backoff algorithm (min delay, max delay). If not specified, reconnecting is disabled. |
| `protocols` | Specifies the subprotocols the client is willing to speak. |
| `timeout` | Specifies the maximum time to wait for the connection to be established. Defaults to 30 seconds if not specified. |
| `afterConnect` | Specifies the callback function to be called after the connection is established, but before the client is allowed to send user messages. |
| `interceptors` | Specifies the interceptors for WebSocket messages. |
### VM Platform Options
Specific to VM (Mobile, Desktop, Server, Console) platform. Not to be used on the web platform.
- Includes all common options.
- `headers`: Specifies additional HTTP headers for setting up the connection. Certain headers are controlled by the WebSocket connection process and will be ignored if passed.
- `compression`: If provided, configures the WebSocket to negotiate with the specified `CompressionOptions`.
- `customClient`: Allows specifying a custom `HttpClient`.
- `userAgent`: Allows specifying a custom `UserAgent`.
### JS Platform Options
Specific to JS (Browser) platform. Not to be used on the VM platform.
- Includes all common options.
- `useBlobForBinary`: Specifies if `Uint8List` should be sent as `Blob` or as typed data. Defaults to sending as typed data.
## Example
[Example of using the ws library](https://pub.dev/packages/ws/example) to connect to a WebSocket server
## Reconnection
The `ws` package provides a cross-platform WebSocket client that supports automatic reconnection in case of connection loss. The client automatically tries to reconnect to the server when the connection is lost. To handle reconnection-related events, you can register listeners for the `stateChanges` stream, which notifies you about changes in the connection state. When the connection is closed, the client tries to reconnect with a delay, which increases exponentially with each unsuccessful attempt to prevent overloading the server.
## Metrics
The `ws` package provides a cross-platform WebSocket client that supports metrics. The client automatically collects metrics about the number of sent and received messages, as well as the number of sent and received bytes. To get the metrics, you can use the `metrics` property, which returns a `WebSocketMetrics` object. The metrics are updated on demand, so you can get the latest values at any time.
## JSON
The `ws` package provides a cross-platform WebSocket client that supports JSON. The client automatically decodes incoming messages from JSON to Dart objects. To get the decoded messages, you can use the `client.stream.json` property, which returns a `Stream>` of decoded messages.
## Features and Roadmap
- ✅ Cross-platform WebSocket client for Dart and Flutter
- ✅ Support for secure WebSocket connections `wss://`
- ✅ Specifying custom protocols
- ✅ Connection state changes
- ✅ Reconnection to new URL
- ✅ Concurrency
- ✅ Backoff [full jitter strategy](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) for reconnection attempts
- ✅ Handy stream of messages with automatic JSON decoding
- ✅ Metrics & TX/RX bytes and counters
- ✅ Platform-specific options
- ✅ Connection timeout
- ✅ Creating Web Socket client from custom implementation
- ✅ Fake client for testing
- ✅ Custom exceptions
- ✅ 90% test coverage
- ✅ First message after connection/reconnection
- ✅ Interceptors (middlewares)
## More resources
- [RFC 6455: The WebSocket Protocol](https://tools.ietf.org/html/rfc6455)
- [WebSocket API on MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
- [Dart HTML WebSocket library](https://api.dart.dev/stable/dart-html/WebSocket-class.html)
- [Dart IO WebSocket library](https://api.dart.dev/stable/dart-io/WebSocket-class.html)
## Coverage
[](https://codecov.io/gh/PlugFox/ws/branch/master)
## Changelog
Refer to the [Changelog](https://github.com/PlugFox/ws/blob/master/CHANGELOG.md) to get all release notes.
## Maintainers
[Matiunin Mikhail aka Plague Fox](https://plugfox.dev)
## Funding
If you want to support the development of our library, there are several ways you can do it:
- [Buy me a coffee](https://www.buymeacoffee.com/plugfox)
- [Support on Patreon](https://www.patreon.com/plugfox)
- [Subscribe through Boosty](https://boosty.to/plugfox)
We appreciate any form of support, whether it's a financial donation or just a star on GitHub. It helps us to continue developing and improving our library. Thank you for your support!
## License
[MIT](https://opensource.org/licenses/MIT)
## Tags
web, socket, ws, wss, WebSocket, cross, platform
```
```