{"id":19584727,"url":"https://github.com/oracle-samples/websocket-client-template","last_synced_at":"2025-04-27T11:32:18.605Z","repository":{"id":238912393,"uuid":"794731174","full_name":"oracle-samples/websocket-client-template","owner":"oracle-samples","description":null,"archived":false,"fork":false,"pushed_at":"2024-08-19T22:01:03.000Z","size":1688,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-08-20T02:13:29.326Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/oracle-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-01T20:42:21.000Z","updated_at":"2024-08-19T22:01:07.000Z","dependencies_parsed_at":"2024-05-21T00:39:21.727Z","dependency_job_id":"0019ded7-3576-4b57-9dad-4c53db7eac28","html_url":"https://github.com/oracle-samples/websocket-client-template","commit_stats":null,"previous_names":["oracle-samples/websocket-client-template"],"tags_count":0,"template":false,"template_full_name":"oracle/template-repo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle-samples%2Fwebsocket-client-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle-samples%2Fwebsocket-client-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle-samples%2Fwebsocket-client-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle-samples%2Fwebsocket-client-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oracle-samples","download_url":"https://codeload.github.com/oracle-samples/websocket-client-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251129595,"owners_count":21540677,"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":[],"created_at":"2024-11-11T07:49:29.796Z","updated_at":"2025-04-27T11:32:18.136Z","avatar_url":"https://github.com/oracle-samples.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WebSocket Client template\n\n\u003cp\u003e\n  \u003cem\u003eThis is a websocket client template for the AsyncAPI generator\u003c/em\u003e\n\u003c/p\u003e\n\n[![AsyncAPI logo](./assets/github-repobanner-generic.png)](https://www.asyncapi.com)  \n\n\n\n\u003c!-- toc is generated with GitHub Actions do not remove toc markers --\u003e\n\n\u003c!-- toc --\u003e\n\n- [Overview](#overview)\n- [Technical requirements](#technical-requirements)\n- [Documentation](#documentation)\n- [Supported protocols](#supported-protocols)\n- [How to use the template](#how-to-use-the-template)\n  * [Data Streaming Client](#data-streaming-client)\n- [Template configuration](#template-configuration)\n- [Development](#development)\n- [Contributing](#contributing)\n- [Security](#security)\n- [License](#license)\n\n\u003c!-- tocstop --\u003e\n\n## Overview\n\nThis template generates the following resources related to using WebSockets protocol with a data streaming service:\n\n- Client application source code to connect and receive data from a data streaming service via dedicated websocket channel\n- Client application build environment and dependency management depending on the client application language\n- Client resource property files depending on the client application language\n\n## Technical requirements\n\nThe AsyncAPI Generator is a Node.js application. Therefore, this template also depends on Node.js. The generator's technical requirements are:\n\n- Node.js v18.12.0+\n- npm v8.19.0+\n\nInstall both using [official installer](https://nodejs.org/en/download/).\n\nAfter that you can install the [AsyncAPI Generator](https://github.com/asyncapi/generator) globally to use its CLI:\n\n```bash\nnpm install -g @asyncapi/generator\n```\n\n## Documentation\n\nThis is a very early version of the template and limited specification features are supported:\n\nProperty name | Reason | Fallback | Default\n---|---|---|---\n`servers.*.url` | Template doesn't support variables in the server url. | - | -\n`bindings` | Template doesn't fully use [websockets](https://github.com/asyncapi/bindings/tree/master/websockets) bindings.| - | -\n`operationId` | Operation ID must be set for every operation to generate proper functions as there is no fallback in place | - | -\n\n## Supported protocols\n\n[WebSocket](https://en.wikipedia.org/wiki/WebSocket)\n\n## How to use the template\n\nThis template must be used with the AsyncAPI Generator. You can find all available options [here](https://github.com/asyncapi/generator/).\n\n### Data Streaming Client\n\nIn case of one-way data streaming use case, A client program establishes the websocket connection with the specified service and starts to receive data in a streaming fashion. In this usage case, a single channel is assumed in the service configuration and only subscribe operation is supported for the channel. To generate the data streaming client, run the asyncapi generator against a websocket client API specification such as the one included (test/streaming.yaml):\n\n```bash\n# Install dependecies and the AsyncAPI Generator\nnpm install\nnpm install -g @asyncapi/generator\n\n###\n### How to run the code generation,\n### @note: you need to customize the asyncapi yaml document with your actual server settings.\n\ncd /localdir/websocket-client-template/\nag test/streaming.yaml . -o output -p server=localhost -p authorization=basic \n\nor\n\nag test/streaming.yaml /localdir/websocket-client-template -o output -p server=localhost -p authorization=basic\n\n\n###\n### How to start the generated client\n### @note: this is for the nodejs client, for other programming languages, check details in the client language section\n\n# Go to the generated output folder, and install needed packages for client\ncd output\nnpm install\n\n##\n## Start the client\n##\n\n# Optional: You can set environment variables for username/password or the location of certificate/key. Otherwise, follow the instructions to provide required information\n# For WS, use ASYNCAPI_WS_CLIENT_USERNAME and ASYNCAPI_WS_CLIENT_PASSWORD to specify the username and password accordingly. \n# For WSS, use ASYNCAPI_WS_CLIENT_CERT, ASYNCAPI_WS_CLIENT_KEY, and ASYNCAPI_WS_CA_CERT to specify the location of client certificate, client private key, or CA certificate.\n# Find more details in the authorization section. \n\n# Excute the client and follow the instructions\nnode client.js\n```\n\n## Template configuration\n\nYou can configure this template by passing different parameters in the Generator CLI: `-p PARAM1_NAME=PARAM1_VALUE -p PARAM2_NAME=PARAM2_VALUE`\n\n| Name | Description | Required | Default | Allowed Values | Example\n|---|---|---|---|---|---|\n|server|The server you want to use in the code.|Yes| - | Name of the server from the list of servers under Servers object | `localhost`|\n|language|The programming language of the client application you want to generate.|No| javascript | javascript/python/java/golang/all | `all`|\n|authorization|The authorization method you want to use. Use basic or digest if the server is behind a proxy.|No| certificate | basic/digest/certificate | `basic`|\n\n### Language Support\n- JavaScript\n  - use \"-p language=javascript\" option explicitly or ignore this option in the client code generation command line. By default, the javascipt client will be generated.\n  - once the client code is generated \u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; cd output \u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; npm install \u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; node client.js \u003cbr\u003e\n\n- Python\n  - use \"-p language=python\" option in the client code generation command line.\n  - once the client code is generated \u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; cd output \u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; pip install -r requirements.txt\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; python client.py \u003cbr\u003e\n\n- Java\n  - use \"-p language=java\" option in the client code generation command line.\n  - once the client code is generated \u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; cd output \u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; mvn package\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; java -jar target/AsyncapiWebSocketClientEndpoint-1.0.jar \u003cbr\u003e\n  - Requirement \u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; Java 1.8+ \u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; Maven 3.9.x+ \u003cbr\u003e\n\n- Go\n  - use \"-p language=Go\" option in the client code generation command line.\n  - once the client code is generated \u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; cd output \u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; go build\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; ./client \u003cbr\u003e\n  - Requirement \u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; go1.22.2+ \u003cbr\u003e\n\n- all\n  - use \"-p language=all\" option in the client code generation command line to generate  clients in all supported languages.  \n  - follow above instructions to build and run the clients\u003cbr\u003e\n\n\n### Authentication and Authorization Support\n- Basic Authentication and Authorization \u003cbr\u003e\nuse \"-p authorization=basic\" option in the code generation command line to use the basicAuth mode in the generated client. The client will ask for the user credentials (username/password) or check for the environmeent variables ASYNCAPI_WS_CLIENT_USERNAME and ASYNCAPI_WS_CLIENT_PASSWORD. The generated client will then construct a basicAuth header field in the websocket connection request. \u003cbr\u003e\u003cbr\u003e\n\n- Digest Authentication and Authorization \u003cbr\u003e\nuse \"-p authorization=digest\" option in the code generation command line to use the digeestAuth mode in the generated client. The client will ask for the user credentials (username/password) or check for the environmeent variables ASYNCAPI_WS_CLIENT_USERNAME and ASYNCAPI_WS_CLIENT_PASSWORD. The client will then construct a digestAuth header field in the websocket connection request. \u003cbr\u003e\u003cbr\u003e\n\n- x-Certificate Authentication and Authorization \u003cbr\u003e\nuse \"-p authorization=certificate\" option in the code generation command line to use the certificate mode in the generated client. The generated client will ask for the locations of the certificate/key files. The client will then construct the sslContext needed with the given certificate/key files for the websocket connection request. \u003cbr\u003e\u003cbr\u003e\n\n\nWhen reverse proxy is used in the setup, only basicAuth or digestAuth are supported as authorization mode with the data streaming service. If the reverse proxy is in secure mode, you may also need to provide the client certificate information in order to authenticate with the reverse proxy.\n\n## Development\n\nThe most straightforward command to use this template is:\n```bash\nag test/streaming.yaml . -o output -p server=localhost -p language=python\n```\n\nFor local development, you need different variations of this command. First of all, you need to know about the following important CLI flags:\n- `--install` enforces reinstallation of the template.\n\nThere are two ways you can work on template development:\n- Use global Generator and template from your local sources:\n  ```bash\n  # assumption is that you run this command from the root of your template\n  ag test/streaming.yaml ./ -o output -p server=localhost -p authorization=digest -p language=python\n  ```\n- Use Generator from sources and template also from local sources. This approach enables more debugging options with awesome `console.log` in the Generator sources or even the Parser located in `node_modules` of the Generator:\n  ```bash\n  # assumption is that you run this command from the root of your template\n  # assumption is that generator sources are cloned on the same level as the template\n  ../generator/cli.js test/streaming.yaml ./ -o output -p server=localhost\n  ```\n\n## Contributing\n\nThis project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md)\n\n## Security\n\nPlease consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process\n\n## License\n\nYou may not use the identified files except in compliance with the\nApache License, Version 2.0 (the \"License.\")\n\nYou may obtain a copy of the License at\nhttp://www.apache.org/licenses/LICENSE-2.0.  A copy of the license is\nalso reproduced in [LICENSE.txt](./LICENSE.txt)\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\nimplied.\n\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle-samples%2Fwebsocket-client-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foracle-samples%2Fwebsocket-client-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle-samples%2Fwebsocket-client-template/lists"}