{"id":19933021,"url":"https://github.com/kontena/kontena-websocket-client","last_synced_at":"2025-05-03T11:33:13.909Z","repository":{"id":56880440,"uuid":"97710235","full_name":"kontena/kontena-websocket-client","owner":"kontena","description":"Ruby websocket client library","archived":false,"fork":false,"pushed_at":"2019-01-10T04:54:26.000Z","size":116,"stargazers_count":2,"open_issues_count":13,"forks_count":10,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-18T09:02:11.052Z","etag":null,"topics":["kontena","ruby","websockets"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kontena.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-19T11:47:36.000Z","updated_at":"2020-09-03T02:14:51.000Z","dependencies_parsed_at":"2022-08-20T13:00:34.579Z","dependency_job_id":null,"html_url":"https://github.com/kontena/kontena-websocket-client","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontena%2Fkontena-websocket-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontena%2Fkontena-websocket-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontena%2Fkontena-websocket-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontena%2Fkontena-websocket-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kontena","download_url":"https://codeload.github.com/kontena/kontena-websocket-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252185497,"owners_count":21708159,"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":["kontena","ruby","websockets"],"created_at":"2024-11-12T23:12:21.925Z","updated_at":"2025-05-03T11:33:13.249Z","avatar_url":"https://github.com/kontena.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/kontena/kontena-websocket-client.svg?branch=master)](https://travis-ci.org/kontena/kontena-websocket-client)\n[![Gem Version](https://badge.fury.io/rb/kontena-websocket-client.svg)](https://badge.fury.io/rb/kontena-websocket-client)\n[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/kontena/kontena-websocket-client/master)\n\n# Kontena::Websocket::Client\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'kontena-websocket-client'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install kontena-websocket-client\n\n## Usage\n\nThe high-level `Kontena::Websocket::Client#connect` API uses a synchronous programming model instead of the event-based `on(:event) do ...` model used by the browser WebSockets API:\n\n* The `connect` class method yields the connected `Kontena::Websocket::Client` object\n* The `read` method yields received websocket messages and returns once the websocket is closed\n* The `send` and `close` methods can be called from the `connect` block, the `read` block, or a different thread\n* Any of these functions can also raise `Kontena::Websocket::Error`\n\n```ruby\nrequire 'kontena-websocket-client'\n\ndef websocket_connect\n  Kontena::Websocket::Client.connect(url, options...) do |client|\n    on_open\n\n    client.send(...)\n    client.close(1000)\n\n    client.read do |message|\n      on_message(message)\n    end\n\n    on_close(client.close_code, client.close_reason) # client closed connection\n  end\nrescue Kontena::Websocket::CloseError =\u003e exc\n  on_close(exc.code, exc.reason) # server closed connection\nrescue Kontena::Websocket::Error =\u003e exc\n  on_error(exc)\nend\n```\n### Environment variables\n\nThe library uses the following environment variables:\n\n* `SSL_CERT_FILE`: Default value for `ssl_params: { ca_file: ... }`\n* `SSL_CERT_PATH`: Default value for `ssl_params: { ca_path: ... }`\n\n### Threadsafe\n\nThe `Kontena::Websocket::Client` is threadsafe: while a single read thread is blocking on `read`, other threads may safely call `send`, `ping` and `close`.\n\nThe `read` block may also call `send`, `ping` and `close`.\nDo not call `read` from multiple threads, or the websocket messages may get corrupted.\n\nThe library uses an internal `Mutex` to protect the internal `Websocket::Driver` state, and prevent socket read/write reordering/corruption.\n\nXXX: The `on_pong` callback is called with the mutex held; do not call any client methods from the `on_pong` block.\n\n### Timeouts\n\nThe `Kontena::Websocket::Client` uses timeouts (given in `options`) to deal with network errors and not leave the client hanging. Timeouts will raise a descriptive `Kontena::Websocket::TimeoutError` from either the `connect`, `read` or `send/close` methods.\n\n* `connect_timeout` is used for both TCP, SSL `connect` operations\n* `open_timeout` is used for the websocket `open` handshake\n* `write_timeout` is used for each socket `write` operation\n* `ping_timeout` is used for each websocket `ping` request\n\nThe `Kontena::Websocket::Client` supports keepalive pings, where the `read` method will send a websocket ping request every `ping_interval` seconds, and raise a `Kontena::Websocket::TimeoutError` if it does not receive a websocket pong response within `ping_timeout` seconds.\n\n### SSL Validation\n\nThe `Kontena::Websocket::Client` validates `wss://` server SSL certificates by default, using the OpenSSL APIs to provide useful `Kontena::Websocket::SSLVerifyError` messages. It also provides methods to inspect and validate the server SSL certificates, even when not using strict SSL validation.\n\nExample code and resulting messages:\n\n```ruby\nbegin\n  ssl_cert = ws.ssl_cert!\nrescue Kontena::Websocket::SSLVerifyError =\u003e ssl_error\n  ssl_cert = ssl_error.cert\nelse\n  ssl_error = nil\nend\n\nif ssl_cert \u0026\u0026 ssl_error\n  $logger.warn \"Connected to #{url} with ssl errors: #{ssl_error} (subject #{ssl_cert.subject}, issuer #{ssl_cert.issuer})\"\nelsif ssl_error\n  $logger.warn \"Connected to #{url} with ssl errors: #{ssl_error}\"\nelsif ssl_cert \u0026\u0026 !ws.ssl_verify?\n  $logger.warn \"Connected to #{url} without ssl verify: #{ssl_cert.subject} (issuer #{ssl_cert.issuer})\"\nelsif ssl_cert\n  $logger.info \"Connected to #{url} with ssl verify: #{ssl_cert.subject} (issuer #{ssl_cert.issuer})\"\nelse\n  $logger.info \"Connected to #{url} without ssl\"\nend\n```\n\n* `ERROR -- websocket-echo-client: certificate verify failed: self signed certificate`\n* `WARN -- websocket-echo-client: Connected to wss://localhost:9293 with ssl errors: certificate verify failed: self signed certificate (subject /CN=kontena.test, issuer /CN=kontena.test)`\n* `WARN -- websocket-echo-client: Connected to wss://echo.websocket.org without ssl verify: /OU=Domain Control Validated/CN=*.websocket.org (issuer /C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc./OU=http://certs.godaddy.com/repository//CN=Go Daddy Secure Certificate Authority - G2)`\n* `INFO -- websocket-echo-client: Connected to wss://echo.websocket.org with ssl verify: /OU=Domain Control Validated/CN=*.websocket.org (issuer /C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc./OU=http://certs.godaddy.com/repository//CN=Go Daddy Secure Certificate Authority - G2)`\n* `INFO -- websocket-echo-client: Connected to ws://echo.websocket.org without ssl`\n\n### Examples\n\nUse `bundle exec ./examples/...` to run the examples.\n\n#### [Websocket Echo Client](./examples/websocket-echo-client.rb)\n\nConnect to a websocket server, displaying the server SSL certificate. Send lines from `stdin`, and write messages to `stdout`. Close on `EOF`.\n\n```\nI, [2017-07-21T17:06:48.353944 #17507]  INFO -- : Connecting to wss://echo.websocket.org...\nI, [2017-07-21T17:06:49.329616 #17507]  INFO -- : Connected to wss://echo.websocket.org with ssl verify: /OU=Domain Control Validated/CN=*.websocket.org (issuer /C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc./OU=http://certs.godaddy.com/repository//CN=Go Daddy Secure Certificate Authority - G2)\nhello\nD, [2017-07-21T17:06:50.447423 #17507] DEBUG -- : websocket write: \"hello\\n\"\nD, [2017-07-21T17:06:50.578683 #17507] DEBUG -- : websocket read: \"hello\\n\"\nhello\nD, [2017-07-21T17:06:51.135395 #17507] DEBUG -- : websocket close: EOF\nI, [2017-07-21T17:06:51.375279 #17507]  INFO -- : Client closed connection with code 1000: EOF\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/kontena/kontena-websocket-client.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkontena%2Fkontena-websocket-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkontena%2Fkontena-websocket-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkontena%2Fkontena-websocket-client/lists"}