{"id":13548411,"url":"https://github.com/felangel/web_socket_client","last_synced_at":"2025-04-12T17:44:21.829Z","repository":{"id":64766528,"uuid":"577405994","full_name":"felangel/web_socket_client","owner":"felangel","description":"A simple WebSocket client for Dart which includes automatic reconnection logic.","archived":false,"fork":false,"pushed_at":"2025-03-22T18:35:29.000Z","size":62,"stargazers_count":171,"open_issues_count":3,"forks_count":40,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-03T23:09:07.723Z","etag":null,"topics":["dart","dart-package","web-socket","websocket","websocket-client"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/web_socket_client","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/felangel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-12T17:01:46.000Z","updated_at":"2025-03-23T21:42:13.000Z","dependencies_parsed_at":"2024-04-27T20:34:42.834Z","dependency_job_id":"61a22f36-41b8-43bb-9b2e-c9b4801e4dde","html_url":"https://github.com/felangel/web_socket_client","commit_stats":{"total_commits":34,"total_committers":9,"mean_commits":"3.7777777777777777","dds":"0.32352941176470584","last_synced_commit":"679b8c45813fc977fa48ccd48054b6924d389dbb"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felangel%2Fweb_socket_client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felangel%2Fweb_socket_client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felangel%2Fweb_socket_client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felangel%2Fweb_socket_client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/felangel","download_url":"https://codeload.github.com/felangel/web_socket_client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248609373,"owners_count":21132899,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dart","dart-package","web-socket","websocket","websocket-client"],"created_at":"2024-08-01T12:01:09.980Z","updated_at":"2025-04-12T17:44:21.807Z","avatar_url":"https://github.com/felangel.png","language":"Dart","readme":"# WebSocket Client\n\n[![build][build_badge]][build_link] [![coverage][coverage_badge]][build_link]\n[![pub package][pub_badge]][pub_link]\n[![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link]\n[![License: MIT][license_badge]][license_link]\n\nA simple `WebSocket` client for Dart which includes automatic reconnection\nlogic.\n\n## Quick Start 🚀\n\n```dart\n// Create a WebSocket client.\nfinal socket = WebSocket(Uri.parse('ws://localhost:8080'));\n\n// Listen to messages from the server.\nsocket.messages.listen((message) {\n  // Handle incoming messages.\n});\n\n// Send a message to the server.\nsocket.send('ping');\n\n// Close the connection.\nsocket.close();\n```\n\n## Establishing a Connection 🔌\n\nThe `WebSocket` client will attempt to establish a connection immediately upon\ninitialization. By default, a timeout will occur if establishing a connection\nexceeds 60 seconds but a custom `timeout` duration can be provided:\n\n```dart\nfinal uri = Uri.parse('ws://localhost:8080');\n\n// Trigger a timeout if establishing a connection exceeds 10s.\nfinal timeout = Duration(seconds: 10);\nfinal socket = WebSocket(uri, timeout: timeout);\n```\n\n## Reconnecting 🔄\n\nIf the `WebSocket` client is not able to establish a connection, it will\nautomatically attempt to reconnect using the provided `Backoff` strategy. By\ndefault, a `BinaryExponentialBackoff` is used but a custom `backoff` can be\nprovided.\n\nThere are three built-in backoff strategies but a custom backoff strategy can be\nwritten by implementing the `Backoff` interface.\n\n**ConstantBackoff**\n\nThis backoff strategy will make the `WebSocket` client wait a constant amount of\ntime between reconnection attempts.\n\n```dart\n// Wait a constant 1s between reconnection attempts.\n// [1, 1, 1, ...]\nconst backoff = ConstantBackoff(Duration(seconds: 1));\nfinal socket = WebSocket(uri, backoff: backoff);\n```\n\n**LinearBackoff**\n\nThis backoff strategy will make the `WebSocket` client wait a linearly\nincreasing amount of time until an optional maximum duration is reached.\n\n```dart\n// Initially wait 0s and increase the wait time by 1s until a maximum of 5s is reached.\n// [0, 1, 2, 3, 4, 5, 5, 5, ...]\nconst backoff = LinearBackoff(\n  initial: Duration(seconds: 0),\n  increment: Duration(seconds: 1),\n  maximum: Duration(seconds: 5),\n);\nfinal socket = WebSocket(uri, backoff: backoff);\n```\n\n**BinaryExponentialBackoff**\n\nThis backoff strategy will make the `WebSocket` client wait an exponentially\nincreasing amount of time until a maximum step is reached.\n\n```dart\n// Initially wait 1s and double the wait time until a maximum step of of 3 is reached.\n// [1, 2, 4, 4, 4, ...]\nconst backoff = BinaryExponentialBackoff(\n  initial: Duration(seconds: 1),\n  maximumStep: 3\n);\nfinal socket = WebSocket(uri, backoff: backoff);\n```\n\n## Monitoring the Connection ⚡️\n\nThe `WebSocket` client exposes a `connection` object which can be used to query\nthe connection state at any given time as well as listen to real-time changes in\nthe connection state.\n\n```dart\nfinal uri = Uri.parse('ws://localhost:8080');\nfinal socket = WebSocket(uri);\n\n// Listen to changes in the connection state.\nsocket.connection.listen((state) {\n  // Handle changes in the connection state.\n});\n\n// Query the current connection state.\nfinal connectionState = socket.connection.state;\n```\n\nThe connection state can be one of the following:\n\n- **connecting**: the connection has not yet been established.\n- **connected**: the connection is established and communication is possible.\n- **reconnecting**: the connection was lost and is in the process of being\n  re-established.\n- **reconnected**: the connection was lost and has been re-established.\n- **disconnecting**: the connection is going through the closing handshake or\n  the `close` method has been invoked.\n- **disconnected**: the WebSocket connection has been closed or could not be\n  established.\n\n_\\* The disconnected connection state contains nullable fields for the close\ncode, close reason, error, and stack trace._\n\n## Sending Messages 📤\n\nOnce a `WebSocket` connection has been established, messages can be sent to the\nserver via `send`:\n\n```dart\nfinal socket = WebSocket(Uri.parse('ws://localhost:8080'));\n\n// Wait until a connection has been established.\nawait socket.connection.firstWhere((state) =\u003e state is Connected);\n\n// Send a message to the server.\nsocket.send('ping');\n```\n\n## Receiving Messages 📥\n\nListen for incoming messages from the server via the `messages` stream:\n\n```dart\nfinal socket = WebSocket(Uri.parse('ws://localhost:8080'));\n\n// Listen for incoming messages.\nsocket.messages.listen((message) {\n  // Handle the incoming message.\n});\n```\n\n## Protobuf 💬\n\nIf you're using `web_socket_client` on the web with Protobuf, you might\nwant to use `binaryType` when initializing the `WebSocket` class.\n`binaryType` is only applicable on the web and is not used on desktop or mobile platforms.\n\n```dart\nfinal socket = WebSocket(Uri.parse('ws://localhost:8080'), binaryType: 'arraybuffer');\n```\n\nSee https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/binaryType for more info.\n\n## Closing the Connection 🚫\n\nOnce a `WebSocket` connection is established, it will automatically attempt to\nreconnect if the connection is disrupted. Calling `close()` will update the\nconnection state to `disconnecting`, perform the closing handshake, and set the\nstate to `disconnected`. At this point, the `WebSocket` client will not attempt\nto reconnect and a new `WebSocket` client instance will need to be created in\norder to establish a new connection.\n\n```dart\nfinal socket = WebSocket(Uri.parse('ws://localhost:8080'));\n\n// Later, close the connection with an optional code and reason.\nsocket.close(1000, 'CLOSE_NORMAL');\n```\n\n[build_badge]: https://github.com/felangel/web_socket_client/actions/workflows/main.yaml/badge.svg\n[build_link]: https://github.com/felangel/web_socket_client/actions/workflows/main.yaml\n[coverage_badge]: https://raw.githubusercontent.com/felangel/web_socket_client/main/coverage_badge.svg\n[license_badge]: https://img.shields.io/badge/license-MIT-blue.svg\n[license_link]: https://opensource.org/licenses/MIT\n[pub_badge]: https://img.shields.io/pub/v/web_socket_client.svg\n[pub_link]: https://pub.dartlang.org/packages/web_socket_client\n[very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg\n[very_good_analysis_link]: https://pub.dev/packages/very_good_analysis\n","funding_links":[],"categories":["Dart"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelangel%2Fweb_socket_client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffelangel%2Fweb_socket_client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelangel%2Fweb_socket_client/lists"}